feat: signed plugin index with validation and publish pipeline

The catalog the Punktfunk plugin store fetches. Served straight out of this
repository over Gitea's anonymous raw endpoint:

  https://git.unom.io/unom/punktfunk-plugin-index/raw/branch/main/v1/index.json
  https://git.unom.io/unom/punktfunk-plugin-index/raw/branch/main/v1/index.json.sig

Hosts verify the ed25519 signature against a compiled-in public key and only
then parse. Verified that the raw endpoint serves blobs byte-for-byte, which
the signature depends on; .gitattributes pins LF so a Windows checkout cannot
break it from the other direction.

Entries pin one exact version plus that version's registry tarball integrity
hash -- no ranges, no "latest". A plugin author publishing a new version
changes nothing for users; the new version becomes installable only when a
reviewer works the checklist and lands a new pinned entry here. That data
shape is what makes "verified on every release" enforceable rather than a
promise.

Seeded with the two first-party plugins, both integrity hashes confirmed
against the live registry:
  - @punktfunk/plugin-rom-manager 0.3.1 (linux, windows)
  - @punktfunk/plugin-playnite    0.1.1 (windows)

Tooling (bun + TypeScript, node builtins only):
  - validate: every field rule the host enforces, plus a live registry
    cross-check that the pinned version exists and its dist.integrity matches
    the pin. Strict on unknown keys, since the host silently drops entries
    that fail validation -- a `min_host` typo would otherwise ship as a
    missing version floor with no error anywhere.
  - sign / verify / keygen: ed25519 over the exact bytes of index.json.
    keygen never prints the private key; verify defaults to the host-pinned
    public key so an index can be audited with no arguments.

CI splits by trust: pull requests run validate only and hold no secrets, so a
fork PR can never reach the signing key or a token that can write to main.
Publishing from main validates, signs, self-verifies, then commits the
signature back. The loop guard is a paths-ignore filter on v1/index.json.sig,
with a [skip ci] marker as a second line of defence; ed25519 determinism means
an unchanged index re-signs to identical bytes and commits nothing at all.

CI signs after the merge, so there is a brief window where index.json is newer
than its signature. It fails closed -- hosts reject the document and keep
their last good cached catalog -- and is documented as such in the README.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tools/keygen.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+/**
+ * Generate an ed25519 signing keypair for the index.
+ *
+ * Prints the PUBLIC key in the exact form the host pins (`ed25519:<base64>` of
+ * the raw 32 bytes) and writes the PRIVATE key as a PKCS#8 PEM.
+ *
+ * The private key is NEVER printed to stdout -- it only ever reaches a file
+ * with 0600 permissions, so it cannot leak into a terminal scrollback, a CI
+ * log, or a shell history via a pipe.
+ *
+ * Usage:
+ *   bun tools/keygen.ts [--out path/to/key.pem] [--force]
+ *
+ * Then: store the PEM contents in the INDEX_SIGNING_KEY CI secret, add the
+ * public key to a host key slot, and destroy every other copy of the PEM.
+ */
+import { generateKeyPairSync } from "node:crypto";
+import { existsSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { encodePublicKey } from "./keys.ts";
+
+function die(message: string): never {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+let out = "index-signing-key.pem";
+let force = false;
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]!;
+  if (arg === "--out") {
+    const next = args[++i];
+    if (!next) die("--out needs a path");
+    out = next;
+  } else if (arg.startsWith("--out=")) {
+    out = arg.slice("--out=".length);
+  } else if (arg === "--force") {
+    force = true;
+  } else {
+    die(`unknown argument ${arg}`);
+  }
+}
+
+const outPath = resolve(out);
+if (existsSync(outPath) && !force) {
+  die(
+    `${outPath} already exists. Refusing to overwrite a private key -- ` +
+      "move it aside first, or pass --force if you are certain it is disposable.",
+  );
+}
+
+const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+
+const pem = privateKey.export({ type: "pkcs8", format: "pem" }) as string;
+// mode 0600 on create; also set explicitly in case of a pre-existing file.
+writeFileSync(outPath, pem, { mode: 0o600 });
+
+console.log(`private key -> ${outPath} (mode 0600, NOT printed, do not commit)`);
+console.log("");
+console.log("public key (pin this in the host):");
+console.log("");
+console.log(`  ${encodePublicKey(publicKey)}`);
+console.log("");
+console.log("Next steps:");
+console.log("  1. Put the PEM contents in the INDEX_SIGNING_KEY repository secret.");
+console.log("  2. Add the public key above to a host key slot (the host pins two,");
+console.log("     so you can roll to a new key before retiring the old one).");
+console.log("  3. Destroy every copy of the PEM outside the secret store.");

tools/keys.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared ed25519 key helpers.
+ *
+ * The host pins public keys in the exact string form `ed25519:<base64>`, where
+ * the base64 payload is the RAW 32-byte ed25519 public key -- NOT a DER/SPKI
+ * blob and NOT a PEM. node:crypto only exports SPKI, so we slice the raw key
+ * out of it (and splice it back in on the way in).
+ *
+ * An ed25519 SPKI DER is always exactly 44 bytes:
+ *   30 2a 30 05 06 03 2b 65 70 03 21 00 || <32-byte raw key>
+ * so the prefix is a fixed 12-byte constant.
+ */
+import { createPublicKey, type KeyObject } from "node:crypto";
+
+/** Fixed 12-byte DER prefix of an ed25519 SubjectPublicKeyInfo. */
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export const PUBKEY_PREFIX = "ed25519:";
+
+/**
+ * The public key currently compiled into the Punktfunk host (slot 1).
+ * `verify` defaults to this so a signed index can be checked with no arguments.
+ */
+export const DEFAULT_PUBLIC_KEY =
+  "ed25519:n/KgBQSSDZqvyGHa8PkHWHZtV1zRXLk0BdQUi4/BD/w=";
+
+/** Encode a node KeyObject public key as the host's `ed25519:<base64>` form. */
+export function encodePublicKey(key: KeyObject): string {
+  const spki = key.export({ type: "spki", format: "der" });
+  if (spki.length !== 44 || !spki.subarray(0, 12).equals(SPKI_PREFIX)) {
+    throw new Error(
+      `not an ed25519 public key (unexpected SPKI: ${spki.length} bytes)`,
+    );
+  }
+  return PUBKEY_PREFIX + spki.subarray(12).toString("base64");
+}
+
+/** Parse the host's `ed25519:<base64>` form into a usable KeyObject. */
+export function decodePublicKey(text: string): KeyObject {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith(PUBKEY_PREFIX)) {
+    throw new Error(`public key must start with "${PUBKEY_PREFIX}"`);
+  }
+  const b64 = trimmed.slice(PUBKEY_PREFIX.length);
+  if (!/^[A-Za-z0-9+/]{43}=$/.test(b64)) {
+    throw new Error(
+      "public key payload must be base64 of exactly 32 raw bytes",
+    );
+  }
+  const raw = Buffer.from(b64, "base64");
+  if (raw.length !== 32) {
+    throw new Error(`public key must be 32 raw bytes, got ${raw.length}`);
+  }
+  return createPublicKey({
+    key: Buffer.concat([SPKI_PREFIX, raw]),
+    format: "der",
+    type: "spki",
+  });
+}

tools/sign.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env bun
+/**
+ * Sign v1/index.json with an ed25519 private key.
+ *
+ * The signature is over the EXACT BYTES of index.json -- no canonicalisation,
+ * no re-serialisation. Whatever is committed is what gets signed and what the
+ * host hashes, so any whitespace change invalidates the signature (validate.ts
+ * enforces canonical formatting to keep that from happening by accident).
+ *
+ * Output is base64 of the raw 64-byte signature, written to v1/index.json.sig.
+ *
+ * Key input, in precedence order:
+ *   --key <path>            PKCS#8 PEM file
+ *   $INDEX_SIGNING_KEY_FILE PKCS#8 PEM file
+ *   $INDEX_SIGNING_KEY      PKCS#8 PEM contents (this is what CI uses)
+ *
+ * Usage:
+ *   bun tools/sign.ts [--key path/to/key.pem] [path/to/index.json]
+ */
+import { createPrivateKey, createPublicKey, sign } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { encodePublicKey } from "./keys.ts";
+
+function die(message: string): never {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+let keyPath: string | undefined;
+const positional: string[] = [];
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]!;
+  if (arg === "--key") {
+    keyPath = args[++i];
+    if (!keyPath) die("--key needs a path");
+  } else if (arg.startsWith("--key=")) {
+    keyPath = arg.slice("--key=".length);
+  } else if (arg.startsWith("--")) {
+    die(`unknown flag ${arg}`);
+  } else {
+    positional.push(arg);
+  }
+}
+
+keyPath ??= process.env.INDEX_SIGNING_KEY_FILE;
+
+let pem: string;
+let source: string;
+if (keyPath) {
+  source = keyPath;
+  try {
+    pem = readFileSync(keyPath, "utf8");
+  } catch (err) {
+    die(`cannot read key file ${keyPath}: ${(err as Error).message}`);
+  }
+} else if (process.env.INDEX_SIGNING_KEY) {
+  source = "$INDEX_SIGNING_KEY";
+  pem = process.env.INDEX_SIGNING_KEY;
+} else {
+  die(
+    "no signing key. Pass --key <pkcs8.pem>, or set INDEX_SIGNING_KEY_FILE (path) " +
+      "or INDEX_SIGNING_KEY (PEM contents).",
+  );
+}
+
+// Tolerate secrets stores that mangle newlines into literal \n.
+if (!pem.includes("\n") && pem.includes("\\n")) pem = pem.replace(/\\n/g, "\n");
+
+let key;
+try {
+  key = createPrivateKey({ key: pem, format: "pem" });
+} catch (err) {
+  die(`${source} is not a readable PKCS#8 PEM private key: ${(err as Error).message}`);
+}
+if (key.asymmetricKeyType !== "ed25519") {
+  die(`${source} is a ${key.asymmetricKeyType ?? "unknown"} key; an ed25519 key is required`);
+}
+
+const file = resolve(positional[0] ?? "v1/index.json");
+const sigFile = `${file}.sig`;
+
+let data: Buffer;
+try {
+  data = readFileSync(file);
+} catch (err) {
+  die(`cannot read ${file}: ${(err as Error).message}`);
+}
+
+// ed25519 is a pure signature scheme: the digest argument MUST be null.
+const signature = sign(null, data, key);
+if (signature.length !== 64) {
+  die(`expected a 64-byte ed25519 signature, got ${signature.length}`);
+}
+
+writeFileSync(sigFile, `${signature.toString("base64")}\n`);
+
+// Report the public key so the operator can eyeball WHICH key just signed --
+// the most likely deploy mistake is signing with a key the host does not pin.
+const publicKey = encodePublicKey(createPublicKey(key));
+console.log(`signed  ${file} (${data.length} bytes)`);
+console.log(`wrote   ${sigFile}`);
+console.log(`key     ${publicKey}`);
+console.log("\nThe host must pin that public key in one of its two key slots.");

tools/validate.ts

@@ -0,0 +1,691 @@
+#!/usr/bin/env bun
+/**
+ * Validate v1/index.json.
+ *
+ * Two layers:
+ *   1. Shape/rule validation of every field, matching what the host parser
+ *      accepts. The host SILENTLY DROPS an entry that fails validation, so a
+ *      typo here would ship as "the plugin just isn't in the store" with no
+ *      error anywhere. This validator is the only place that failure is loud.
+ *   2. Live registry cross-check: the pinned version must exist upstream and
+ *      its dist.integrity must equal the pinned integrity. This is the check
+ *      that makes the pin meaningful -- an entry whose hash does not match the
+ *      registry is either stale or an attack.
+ *
+ * Usage:
+ *   bun tools/validate.ts [--offline] [--fix] [path/to/index.json]
+ *
+ *   --offline  skip layer 2 (no network). CI must NOT use this.
+ *   --fix      rewrite the file in canonical formatting instead of erroring.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// error collection
+// ---------------------------------------------------------------------------
+
+interface Problem {
+  path: string;
+  message: string;
+}
+
+const problems: Problem[] = [];
+
+function fail(path: string, message: string): void {
+  problems.push({ path, message });
+}
+
+// ---------------------------------------------------------------------------
+// primitive checks
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Reject any key we do not know about. Deliberately strict: the host ignores
+ * unknown keys, so a snake_case slip like `min_host` would parse "fine" and
+ * silently lose its meaning. Catching it here is the whole point.
+ */
+function checkKeys(
+  path: string,
+  obj: Record<string, unknown>,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): void {
+  const known = new Set([...required, ...optional]);
+  for (const key of Object.keys(obj)) {
+    if (!known.has(key)) {
+      const hint = [...known].find(
+        (k) => k.toLowerCase().replace(/[_-]/g, "") ===
+          key.toLowerCase().replace(/[_-]/g, ""),
+      );
+      fail(
+        `${path}.${key}`,
+        `unknown key${hint ? ` -- did you mean "${hint}"? (keys are camelCase)` : ""}`,
+      );
+    }
+  }
+  for (const key of required) {
+    if (!(key in obj)) fail(`${path}.${key}`, "missing required key");
+  }
+}
+
+function requireString(
+  path: string,
+  value: unknown,
+  opts: { min?: number; max?: number } = {},
+): string | undefined {
+  if (typeof value !== "string") {
+    fail(path, `must be a string, got ${value === undefined ? "nothing" : typeof value}`);
+    return undefined;
+  }
+  const { min = 1, max } = opts;
+  if (value.length < min) {
+    fail(path, `must be at least ${min} character${min === 1 ? "" : "s"}`);
+    return undefined;
+  }
+  if (max !== undefined && value.length > max) {
+    fail(path, `must be at most ${max} characters (got ${value.length})`);
+    return undefined;
+  }
+  return value;
+}
+
+function requireHttpsUrl(path: string, value: unknown): string | undefined {
+  const s = requireString(path, value, { max: 2048 });
+  if (s === undefined) return undefined;
+  let url: URL;
+  try {
+    url = new URL(s);
+  } catch {
+    fail(path, `not a valid URL: ${JSON.stringify(s)}`);
+    return undefined;
+  }
+  if (url.protocol !== "https:") {
+    fail(path, `must be https, got ${url.protocol.replace(":", "")}`);
+    return undefined;
+  }
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// semver
+// ---------------------------------------------------------------------------
+
+/** Official semver.org recommended regex, anchored. Exact versions only. */
+const EXACT_SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+function requireExactVersion(path: string, value: unknown): string | undefined {
+  const s = requireString(path, value, { max: 256 });
+  if (s === undefined) return undefined;
+  if (!EXACT_SEMVER.test(s)) {
+    const looksLikeRange = /[\^~*<>=|\s]|\.x$/i.test(s);
+    fail(
+      path,
+      looksLikeRange
+        ? `must be an EXACT semver version, not a range: ${JSON.stringify(s)}`
+        : `not a valid semver version: ${JSON.stringify(s)}`,
+    );
+    return undefined;
+  }
+  return s;
+}
+
+const PRE_IDENT = /^(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)$/;
+const BUILD_IDENT = /^[0-9a-zA-Z-]+$/;
+
+/**
+ * Check that a string parses as a Rust `semver::VersionReq`.
+ *
+ * Mirrors the grammar of the `semver` crate: comma-separated comparators, each
+ * an optional operator (= > >= < <= ~ ^) followed by a possibly-partial version
+ * (major[.minor[.patch]]) with optional pre-release and build metadata, or a
+ * wildcard (* / x / X). Numeric parts reject leading zeros and must fit u64,
+ * exactly as the crate does.
+ *
+ * Where this differs from the crate it is STRICTER, never looser -- so anything
+ * accepted here is guaranteed to parse host-side.
+ */
+function parseVersionReq(text: string): string | null {
+  if (text.trim() === "") return "must not be empty";
+
+  const parts = text.split(",");
+  for (const rawPart of parts) {
+    const part = rawPart.trim();
+    if (part === "") return "empty comparator (stray or trailing comma)";
+
+    const m = /^(=|>=|<=|>|<|~|\^)?\s*(.*)$/.exec(part);
+    if (!m) return `cannot parse comparator ${JSON.stringify(part)}`;
+    const [, , versionText = ""] = m;
+    if (versionText === "") {
+      return `comparator ${JSON.stringify(part)} has an operator but no version`;
+    }
+
+    // Split off build metadata, then pre-release.
+    let rest = versionText;
+    let build: string | undefined;
+    const plus = rest.indexOf("+");
+    if (plus !== -1) {
+      build = rest.slice(plus + 1);
+      rest = rest.slice(0, plus);
+    }
+    let pre: string | undefined;
+    const dash = rest.indexOf("-");
+    if (dash !== -1) {
+      pre = rest.slice(dash + 1);
+      rest = rest.slice(0, dash);
+    }
+
+    const nums = rest.split(".");
+    if (nums.length > 3) {
+      return `too many version segments in ${JSON.stringify(versionText)}`;
+    }
+
+    let sawWildcard = false;
+    for (const seg of nums) {
+      if (seg === "*" || seg === "x" || seg === "X") {
+        sawWildcard = true;
+        continue;
+      }
+      if (sawWildcard) {
+        return `${JSON.stringify(versionText)}: a numeric segment cannot follow a wildcard`;
+      }
+      if (seg === "") return `empty version segment in ${JSON.stringify(versionText)}`;
+      if (!/^\d+$/.test(seg)) {
+        return `version segment ${JSON.stringify(seg)} is not a number`;
+      }
+      if (seg.length > 1 && seg.startsWith("0")) {
+        return `version segment ${JSON.stringify(seg)} has a leading zero`;
+      }
+      if (BigInt(seg) > 18446744073709551615n) {
+        return `version segment ${JSON.stringify(seg)} does not fit in u64`;
+      }
+    }
+
+    if (sawWildcard && (pre !== undefined || build !== undefined)) {
+      return `${JSON.stringify(versionText)}: wildcards cannot carry pre-release or build metadata`;
+    }
+    if (pre !== undefined) {
+      if (pre === "") return `empty pre-release in ${JSON.stringify(versionText)}`;
+      for (const id of pre.split(".")) {
+        if (!PRE_IDENT.test(id)) {
+          return `invalid pre-release identifier ${JSON.stringify(id)}`;
+        }
+      }
+    }
+    if (build !== undefined) {
+      if (build === "") return `empty build metadata in ${JSON.stringify(versionText)}`;
+      for (const id of build.split(".")) {
+        if (!BUILD_IDENT.test(id)) {
+          return `invalid build identifier ${JSON.stringify(id)}`;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// entry-level validation
+// ---------------------------------------------------------------------------
+
+const ID_RE = /^[a-z][a-z0-9-]*$/;
+const ICON_RE = /^[a-z0-9-]{1,48}$/;
+/** npm scoped name. Scoped is mandatory: the scope is what maps to a registry. */
+const PKG_RE = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+const INTEGRITY_RE = /^sha512-[A-Za-z0-9+/]+={0,2}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const RFC3339_UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+const PLATFORMS = ["linux", "windows", "macos"] as const;
+
+const PLUGIN_REQUIRED = [
+  "id",
+  "pkg",
+  "registry",
+  "title",
+  "description",
+  "icon",
+  "author",
+  "homepage",
+  "license",
+  "version",
+  "integrity",
+  "verification",
+] as const;
+const PLUGIN_OPTIONAL = ["minHost", "platforms"] as const;
+
+interface CheckTarget {
+  path: string;
+  pkg: string;
+  registry: string;
+  version: string;
+  integrity: string;
+}
+
+/** Returns a registry cross-check job if the entry had enough valid fields. */
+function validatePlugin(
+  path: string,
+  entry: unknown,
+  seenIds: Map<string, string>,
+  seenPkgs: Map<string, string>,
+): CheckTarget | undefined {
+  if (!isPlainObject(entry)) {
+    fail(path, "must be an object");
+    return undefined;
+  }
+  checkKeys(path, entry, PLUGIN_REQUIRED, PLUGIN_OPTIONAL);
+
+  // id
+  const id = requireString(`${path}.id`, entry.id, { max: 64 });
+  if (id !== undefined) {
+    if (!ID_RE.test(id)) {
+      fail(
+        `${path}.id`,
+        `must match ^[a-z][a-z0-9-]*$ (lowercase, starts with a letter): ${JSON.stringify(id)}`,
+      );
+    } else {
+      const prior = seenIds.get(id);
+      if (prior) fail(`${path}.id`, `duplicate id ${JSON.stringify(id)}, already used by ${prior}`);
+      else seenIds.set(id, path);
+    }
+  }
+
+  // pkg
+  const pkg = requireString(`${path}.pkg`, entry.pkg, { max: 214 });
+  if (pkg !== undefined && !PKG_RE.test(pkg)) {
+    fail(
+      `${path}.pkg`,
+      pkg.startsWith("@")
+        ? `not a valid npm package name: ${JSON.stringify(pkg)}`
+        : `must be a SCOPED package name (@scope/name), got ${JSON.stringify(pkg)}`,
+    );
+  } else if (pkg !== undefined) {
+    const prior = seenPkgs.get(pkg);
+    if (prior) fail(`${path}.pkg`, `duplicate package ${JSON.stringify(pkg)}, already listed at ${prior}`);
+    else seenPkgs.set(pkg, path);
+  }
+
+  // registry
+  const registry = requireHttpsUrl(`${path}.registry`, entry.registry);
+  if (registry !== undefined && !registry.endsWith("/")) {
+    fail(
+      `${path}.registry`,
+      "must end with a trailing slash so the package name can be appended safely",
+    );
+  }
+
+  // plain text fields
+  requireString(`${path}.title`, entry.title, { max: 64 });
+  requireString(`${path}.description`, entry.description, { max: 280 });
+  requireString(`${path}.author`, entry.author, { max: 64 });
+  requireString(`${path}.license`, entry.license, { max: 64 });
+
+  const icon = requireString(`${path}.icon`, entry.icon, { max: 48 });
+  if (icon !== undefined && !ICON_RE.test(icon)) {
+    fail(
+      `${path}.icon`,
+      `must be a lucide icon name matching ^[a-z0-9-]{1,48}$ (kebab-case, e.g. "gamepad-2"): ${JSON.stringify(icon)}`,
+    );
+  }
+
+  requireHttpsUrl(`${path}.homepage`, entry.homepage);
+
+  const version = requireExactVersion(`${path}.version`, entry.version);
+
+  // integrity
+  const integrity = requireString(`${path}.integrity`, entry.integrity, { max: 200 });
+  if (integrity !== undefined) {
+    if (!INTEGRITY_RE.test(integrity)) {
+      fail(
+        `${path}.integrity`,
+        `must be a Subresource Integrity string of the form "sha512-<base64>": ${JSON.stringify(integrity)}`,
+      );
+    } else {
+      const raw = Buffer.from(integrity.slice("sha512-".length), "base64");
+      if (raw.length !== 64) {
+        fail(
+          `${path}.integrity`,
+          `sha512 digest must decode to 64 bytes, got ${raw.length}`,
+        );
+      }
+    }
+  }
+
+  // verification
+  if (!isPlainObject(entry.verification)) {
+    if ("verification" in entry) fail(`${path}.verification`, "must be an object");
+  } else {
+    checkKeys(`${path}.verification`, entry.verification, ["reviewedAt"]);
+    const reviewedAt = requireString(
+      `${path}.verification.reviewedAt`,
+      entry.verification.reviewedAt,
+      { max: 10 },
+    );
+    if (reviewedAt !== undefined) {
+      if (!DATE_RE.test(reviewedAt)) {
+        fail(`${path}.verification.reviewedAt`, `must be YYYY-MM-DD, got ${JSON.stringify(reviewedAt)}`);
+      } else {
+        const parsed = new Date(`${reviewedAt}T00:00:00Z`);
+        if (Number.isNaN(parsed.getTime()) || !parsed.toISOString().startsWith(reviewedAt)) {
+          fail(`${path}.verification.reviewedAt`, `not a real calendar date: ${reviewedAt}`);
+        } else if (parsed.getTime() > Date.now() + 24 * 60 * 60 * 1000) {
+          fail(`${path}.verification.reviewedAt`, `is in the future: ${reviewedAt}`);
+        }
+      }
+    }
+  }
+
+  // minHost (optional)
+  if (entry.minHost !== undefined) requireExactVersion(`${path}.minHost`, entry.minHost);
+
+  // platforms (optional)
+  if (entry.platforms !== undefined) {
+    if (!Array.isArray(entry.platforms)) {
+      fail(`${path}.platforms`, "must be an array");
+    } else {
+      const seen = new Set<string>();
+      entry.platforms.forEach((p, i) => {
+        if (typeof p !== "string" || !(PLATFORMS as readonly string[]).includes(p)) {
+          fail(
+            `${path}.platforms[${i}]`,
+            `must be one of ${PLATFORMS.join(" | ")}, got ${JSON.stringify(p)}`,
+          );
+          return;
+        }
+        if (seen.has(p)) fail(`${path}.platforms[${i}]`, `duplicate platform ${JSON.stringify(p)}`);
+        seen.add(p);
+      });
+    }
+  }
+
+  if (pkg && registry && version && integrity && INTEGRITY_RE.test(integrity)) {
+    return { path, pkg, registry, version, integrity };
+  }
+  return undefined;
+}
+
+function validateSecurity(path: string, entry: unknown): { pkg?: string; req?: string } {
+  if (!isPlainObject(entry)) {
+    fail(path, "must be an object");
+    return {};
+  }
+  checkKeys(path, entry, ["pkg", "versions", "reason"], ["url"]);
+
+  const pkg = requireString(`${path}.pkg`, entry.pkg, { max: 214 });
+  if (pkg !== undefined && !PKG_RE.test(pkg)) {
+    fail(`${path}.pkg`, `must be a scoped npm package name, got ${JSON.stringify(pkg)}`);
+  }
+
+  const versions = requireString(`${path}.versions`, entry.versions, { max: 256 });
+  if (versions !== undefined) {
+    const err = parseVersionReq(versions);
+    if (err) {
+      fail(`${path}.versions`, `not a valid semver requirement (${err}): ${JSON.stringify(versions)}`);
+    } else if (versions.trim() === "*") {
+      // Guard rail: `*` revokes every version ever published. If that is really
+      // intended, say so explicitly with a bounded range.
+      fail(
+        `${path}.versions`,
+        'refusing a bare "*" revocation -- it would revoke every version of the package; use an explicit bound',
+      );
+    }
+  }
+
+  requireString(`${path}.reason`, entry.reason, { max: 280 });
+  if (entry.url !== undefined) requireHttpsUrl(`${path}.url`, entry.url);
+
+  return { pkg, req: versions };
+}
+
+// ---------------------------------------------------------------------------
+// live registry cross-check
+// ---------------------------------------------------------------------------
+
+/**
+ * npm packument URL for a scoped package. The scope separator is percent-
+ * encoded but the leading `@` is left literal -- this is the form Gitea's npm
+ * API is known to answer.
+ */
+function packumentUrl(registry: string, pkg: string): string {
+  return registry + pkg.replace("/", "%2f");
+}
+
+async function crossCheck(target: CheckTarget): Promise<void> {
+  const url = packumentUrl(target.registry, target.pkg);
+  let body: unknown;
+  try {
+    const res = await fetch(url, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(20_000),
+    });
+    if (!res.ok) {
+      fail(target.path, `registry lookup failed: HTTP ${res.status} ${res.statusText} for ${url}`);
+      return;
+    }
+    body = await res.json();
+  } catch (err) {
+    fail(target.path, `registry lookup failed for ${url}: ${(err as Error).message}`);
+    return;
+  }
+
+  if (!isPlainObject(body) || !isPlainObject(body.versions)) {
+    fail(target.path, `registry returned no "versions" map for ${target.pkg}`);
+    return;
+  }
+  const meta = body.versions[target.version];
+  if (meta === undefined) {
+    const available = Object.keys(body.versions).slice(-8).join(", ");
+    fail(
+      target.path,
+      `version ${target.version} of ${target.pkg} does not exist in the registry (latest seen: ${available || "none"})`,
+    );
+    return;
+  }
+  if (!isPlainObject(meta) || !isPlainObject(meta.dist)) {
+    fail(target.path, `registry entry for ${target.pkg}@${target.version} has no "dist" block`);
+    return;
+  }
+  const upstream = meta.dist.integrity;
+  if (typeof upstream !== "string" || upstream === "") {
+    fail(
+      target.path,
+      `registry entry for ${target.pkg}@${target.version} has no dist.integrity -- cannot pin this package`,
+    );
+    return;
+  }
+  if (upstream !== target.integrity) {
+    fail(
+      target.path,
+      `INTEGRITY MISMATCH for ${target.pkg}@${target.version}\n` +
+        `      pinned here: ${target.integrity}\n` +
+        `      registry:    ${upstream}\n` +
+        "      The pinned hash must be copied verbatim from the registry. If the registry\n" +
+        "      changed for a version that was already published, stop and investigate.",
+    );
+    return;
+  }
+  console.log(`  ok  ${target.pkg}@${target.version} integrity matches registry`);
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const offline = args.includes("--offline");
+const fixFormat = args.includes("--fix");
+const positional = args.filter((a) => !a.startsWith("--"));
+const file = resolve(positional[0] ?? "v1/index.json");
+
+let text: string;
+try {
+  text = readFileSync(file, "utf8");
+} catch (err) {
+  console.error(`error: cannot read ${file}: ${(err as Error).message}`);
+  process.exit(1);
+}
+
+let doc: unknown;
+try {
+  doc = JSON.parse(text);
+} catch (err) {
+  console.error(`${file}: not valid JSON: ${(err as Error).message}`);
+  process.exit(1);
+}
+
+// Canonical formatting. The signature covers the exact bytes of this file, so
+// keeping it byte-stable makes review diffs minimal and re-signing predictable.
+const canonical = `${JSON.stringify(doc, null, 2)}\n`;
+if (text !== canonical) {
+  if (fixFormat) {
+    writeFileSync(file, canonical);
+    console.log(`fixed formatting of ${file}`);
+    text = canonical;
+  } else {
+    fail(
+      "<file>",
+      "not in canonical formatting (2-space indent, trailing newline). Run: bun run validate -- --fix",
+    );
+  }
+}
+
+if (!isPlainObject(doc)) {
+  console.error(`${file}: top level must be a JSON object`);
+  process.exit(1);
+}
+
+checkKeys("$", doc, ["schema", "name", "generated", "plugins", "security"]);
+
+if (doc.schema !== 1) {
+  fail("$.schema", `must be exactly 1 (number), got ${JSON.stringify(doc.schema)}`);
+}
+requireString("$.name", doc.name, { max: 64 });
+
+const generated = requireString("$.generated", doc.generated, { max: 40 });
+if (generated !== undefined) {
+  if (!RFC3339_UTC_RE.test(generated)) {
+    fail("$.generated", `must be an RFC 3339 UTC timestamp like 2026-07-20T18:00:00Z, got ${JSON.stringify(generated)}`);
+  } else if (Number.isNaN(new Date(generated).getTime())) {
+    fail("$.generated", `not a real timestamp: ${generated}`);
+  }
+}
+
+const targets: CheckTarget[] = [];
+const pinned = new Map<string, string>(); // pkg -> pinned version
+
+if (!Array.isArray(doc.plugins)) {
+  fail("$.plugins", "must be an array");
+} else {
+  const seenIds = new Map<string, string>();
+  const seenPkgs = new Map<string, string>();
+  doc.plugins.forEach((entry, i) => {
+    const target = validatePlugin(`$.plugins[${i}]`, entry, seenIds, seenPkgs);
+    if (target) {
+      targets.push(target);
+      pinned.set(target.pkg, target.version);
+    }
+  });
+}
+
+if (!Array.isArray(doc.security)) {
+  fail("$.security", "must be an array");
+} else {
+  doc.security.forEach((entry, i) => {
+    const path = `$.security[${i}]`;
+    const { pkg, req } = validateSecurity(path, entry);
+    // Self-consistency: never ship a catalog that pins a version it also revokes.
+    if (pkg && req && pinned.has(pkg)) {
+      const version = pinned.get(pkg)!;
+      if (satisfiesSimple(version, req)) {
+        fail(
+          path,
+          `revokes ${pkg} ${req}, which matches the version pinned in $.plugins (${version}) -- bump the pin or narrow the revocation`,
+        );
+      }
+    }
+  });
+}
+
+/**
+ * Minimal "does this exact version satisfy this requirement" check, used only
+ * for the self-consistency guard above. Handles the comparator forms we allow;
+ * on anything it cannot decide it returns false (no false alarms).
+ */
+function satisfiesSimple(version: string, req: string): boolean {
+  const v = parseExact(version);
+  if (!v) return false;
+  return req.split(",").every((rawPart) => {
+    const part = rawPart.trim();
+    const m = /^(=|>=|<=|>|<|~|\^)?\s*(.*)$/.exec(part);
+    if (!m) return false;
+    const op = m[1] ?? "^";
+    const bare = (m[2] ?? "").split("+")[0]!;
+    if (/[*xX]/.test(bare)) return true;
+    const parts = bare.split("-")[0]!.split(".").map((n) => Number(n));
+    const [major = 0, minor, patch] = parts;
+    const lower: [number, number, number] = [major, minor ?? 0, patch ?? 0];
+    const cmp = compare(v, lower);
+    switch (op) {
+      case "=":
+        return cmp === 0;
+      case ">":
+        return cmp > 0;
+      case ">=":
+        return cmp >= 0;
+      case "<":
+        return cmp < 0;
+      case "<=":
+        return cmp <= 0;
+      case "~": {
+        if (cmp < 0) return false;
+        if (minor === undefined) return v[0] === major;
+        return v[0] === major && v[1] === minor;
+      }
+      case "^": {
+        if (cmp < 0) return false;
+        if (major > 0) return v[0] === major;
+        if (minor === undefined || minor > 0) return v[0] === 0 && v[1] === (minor ?? 0);
+        return v[0] === 0 && v[1] === 0 && v[2] === (patch ?? 0);
+      }
+      default:
+        return false;
+    }
+  });
+}
+
+function parseExact(version: string): [number, number, number] | null {
+  const m = EXACT_SEMVER.exec(version);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function compare(a: [number, number, number], b: [number, number, number]): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i]! !== b[i]!) return a[i]! < b[i]! ? -1 : 1;
+  }
+  return 0;
+}
+
+// Layer 2: live registry.
+if (problems.length === 0 && !offline) {
+  console.log(`checking ${targets.length} pinned package(s) against their registries...`);
+  await Promise.all(targets.map(crossCheck));
+} else if (offline) {
+  console.log("skipping live registry cross-check (--offline)");
+}
+
+if (problems.length > 0) {
+  console.error(`\n${file}: ${problems.length} problem(s):\n`);
+  for (const p of problems) console.error(`  ${p.path}\n      ${p.message}\n`);
+  process.exit(1);
+}
+
+const pluginCount = Array.isArray(doc.plugins) ? doc.plugins.length : 0;
+const securityCount = Array.isArray(doc.security) ? doc.security.length : 0;
+console.log(
+  `\nOK: ${file} is valid -- ${pluginCount} plugin(s), ${securityCount} security advisory(ies).`,
+);

tools/verify.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+/**
+ * Verify v1/index.json.sig against v1/index.json.
+ *
+ * This is exactly what the host does before it will parse a single byte of the
+ * catalog, so a green run here means a host that pins the same key will accept
+ * the index. Used as a post-sign self-check in CI, and by anyone auditing.
+ *
+ * Public key, in precedence order:
+ *   --pub ed25519:<base64>   (or a path to a file containing that string)
+ *   $INDEX_PUBLIC_KEY
+ *   the key currently pinned in the host (see tools/keys.ts)
+ *
+ * Usage:
+ *   bun tools/verify.ts [--pub ed25519:...] [path/to/index.json]
+ */
+import { verify } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { DEFAULT_PUBLIC_KEY, PUBKEY_PREFIX, decodePublicKey } from "./keys.ts";
+
+function die(message: string): never {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+let pubArg: string | undefined;
+const positional: string[] = [];
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]!;
+  if (arg === "--pub") {
+    pubArg = args[++i];
+    if (!pubArg) die("--pub needs a value");
+  } else if (arg.startsWith("--pub=")) {
+    pubArg = arg.slice("--pub=".length);
+  } else if (arg.startsWith("--")) {
+    die(`unknown flag ${arg}`);
+  } else {
+    positional.push(arg);
+  }
+}
+
+let source = "host-pinned default";
+let pubText = DEFAULT_PUBLIC_KEY;
+if (pubArg) {
+  // Accept either the literal ed25519:... string or a file containing it.
+  if (!pubArg.startsWith(PUBKEY_PREFIX) && existsSync(pubArg)) {
+    source = pubArg;
+    pubText = readFileSync(pubArg, "utf8").trim();
+  } else {
+    source = "--pub";
+    pubText = pubArg;
+  }
+} else if (process.env.INDEX_PUBLIC_KEY) {
+  source = "$INDEX_PUBLIC_KEY";
+  pubText = process.env.INDEX_PUBLIC_KEY;
+}
+
+let publicKey;
+try {
+  publicKey = decodePublicKey(pubText);
+} catch (err) {
+  die(`bad public key from ${source}: ${(err as Error).message}`);
+}
+
+const file = resolve(positional[0] ?? "v1/index.json");
+const sigFile = `${file}.sig`;
+
+let data: Buffer;
+try {
+  data = readFileSync(file);
+} catch (err) {
+  die(`cannot read ${file}: ${(err as Error).message}`);
+}
+
+let sigText: string;
+try {
+  sigText = readFileSync(sigFile, "utf8");
+} catch (err) {
+  die(`cannot read ${sigFile}: ${(err as Error).message}`);
+}
+
+// Whitespace-tolerant on read, matching the host.
+const b64 = sigText.replace(/\s+/g, "");
+if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) {
+  die(`${sigFile} is not valid base64`);
+}
+const signature = Buffer.from(b64, "base64");
+if (signature.length !== 64) {
+  die(`${sigFile} must decode to a 64-byte ed25519 signature, got ${signature.length} bytes`);
+}
+
+if (!verify(null, data, publicKey, signature)) {
+  console.error(`FAILED: signature in ${sigFile} does not match ${file}`);
+  console.error(`  key used: ${pubText.trim()} (from ${source})`);
+  console.error(
+    "\n  Either the index was modified after signing, or it was signed with a\n" +
+      "  different key than the one being checked. Re-run `bun run sign`, and\n" +
+      "  confirm the signing key matches a slot the host pins.",
+  );
+  process.exit(1);
+}
+
+console.log(`OK: ${sigFile} is a valid signature over ${file} (${data.length} bytes)`);
+console.log(`    key: ${pubText.trim()} (from ${source})`);