@nimbus-dev/sdk 1.1.2

package/src/crypto/canonical-json.ts

@@ -0,0 +1,73 @@
+/**
+ * Deterministic JSON canonicalization for extension manifests.
+ *
+ * Used as the input to Ed25519 manifest signing (T2 PR 2 / I16). The signed
+ * bytes are the manifest with the `signature` field stripped, re-serialized
+ * via the rules below. Signing and verifying both call into this module so
+ * the byte sequences match exactly.
+ *
+ * Rules:
+ * - Object keys sorted in lexicographic UTF-16 code-unit order (JS `Array.sort` default).
+ * - String VALUES Unicode-normalized to NFC so semantically-equal strings
+ *   yield identical bytes regardless of how the source editor encoded them.
+ *   Object KEYS are NOT normalized — the publisher signs them byte-for-byte
+ *   as serialized.
+ * - Integer numbers only (manifests have no floating-point fields).
+ * - No whitespace; UTF-8 encoded.
+ * - Recursion capped at MAX_DEPTH (32) — real manifests have depth ≤ 4; the
+ *   cap defends against a maliciously crafted manifest blowing the stack.
+ *
+ * Preconditions: callers pass values produced by `JSON.parse`. That domain
+ * guarantees no cycles, no undefined / function / symbol values, no NaN /
+ * Infinity. The thrown error classes below are defensive for callers that
+ * violate the precondition (e.g. constructing the input in-memory).
+ */
+
+export class NonIntegerNumberInManifest extends Error {
+  override readonly name = "NonIntegerNumberInManifest";
+}
+export class UnsupportedManifestValueType extends Error {
+  override readonly name = "UnsupportedManifestValueType";
+}
+export class ManifestNestedTooDeep extends Error {
+  override readonly name = "ManifestNestedTooDeep";
+}
+
+const MAX_DEPTH = 32;
+
+export function canonicalize(value: unknown, depth = 0): string {
+  if (depth > MAX_DEPTH) throw new ManifestNestedTooDeep();
+  if (value === null) return "null";
+  if (value === true) return "true";
+  if (value === false) return "false";
+  if (typeof value === "string") {
+    return JSON.stringify(value.normalize("NFC"));
+  }
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) throw new NonIntegerNumberInManifest();
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalize(v, depth + 1)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).sort((a, b) => {
+      if (a < b) return -1;
+      if (a > b) return 1;
+      return 0;
+    });
+    return (
+      "{" +
+      keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k], depth + 1)}`).join(",") +
+      "}"
+    );
+  }
+  throw new UnsupportedManifestValueType();
+}
+
+export function canonicalizeManifest(manifest: object): Uint8Array {
+  const clone: Record<string, unknown> = { ...(manifest as Record<string, unknown>) };
+  delete clone["signature"];
+  return new TextEncoder().encode(canonicalize(clone));
+}

package/src/crypto/jwt.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import crypto from "node:crypto";
+
+import { base64UrlJson, signJwt } from "./jwt";
+
+function decode(segment: string): Record<string, unknown> {
+  return JSON.parse(Buffer.from(segment, "base64url").toString("utf8")) as Record<string, unknown>;
+}
+
+describe("base64UrlJson", () => {
+  test("round-trips a JSON value through base64url", () => {
+    const enc = base64UrlJson({ a: 1, b: "x" });
+    expect(decode(enc)).toEqual({ a: 1, b: "x" });
+    // base64url uses no +,/,= characters
+    expect(enc).not.toMatch(/[+/=]/);
+  });
+});
+
+describe("signJwt", () => {
+  test("RS256 (no dsaEncoding) produces a DER signature verifiable under the RSA key", () => {
+    const { privateKey, publicKey } = crypto.generateKeyPairSync("rsa", { modulusLength: 2048 });
+    const pem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    const token = signJwt({
+      header: { alg: "RS256", typ: "JWT" },
+      payload: { iss: "a" },
+      privateKeyPem: pem,
+    });
+    const [h, p, sig] = token.split(".");
+    expect(decode(h as string)).toEqual({ alg: "RS256", typ: "JWT" });
+    expect(decode(p as string)).toEqual({ iss: "a" });
+    const ok = crypto.verify(
+      "sha256",
+      Buffer.from(`${h}.${p}`, "utf8"),
+      crypto.createPublicKey(publicKey.export({ type: "spki", format: "pem" }).toString()),
+      Buffer.from(sig as string, "base64url"), // NOSONAR S4325: sig is string|undefined from the JWT split under noUncheckedIndexedAccess
+    );
+    expect(ok).toBe(true);
+  });
+
+  test("ES256 (ieee-p1363) produces a raw r||s signature verifiable under the EC key", () => {
+    const { privateKey, publicKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+    const pem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    const token = signJwt({
+      header: { alg: "ES256", kid: "K", typ: "JWT" },
+      payload: { iss: "b" },
+      privateKeyPem: pem,
+      dsaEncoding: "ieee-p1363",
+    });
+    const [h, p, sig] = token.split(".");
+    expect(token.split(".")).toHaveLength(3);
+    const ok = crypto.verify(
+      "sha256",
+      Buffer.from(`${h}.${p}`, "utf8"),
+      {
+        key: crypto.createPublicKey(publicKey.export({ type: "spki", format: "pem" }).toString()),
+        dsaEncoding: "ieee-p1363",
+      },
+      Buffer.from(sig as string, "base64url"), // NOSONAR S4325: sig is string|undefined from the JWT split under noUncheckedIndexedAccess
+    );
+    expect(ok).toBe(true);
+  });
+});

package/src/crypto/jwt.ts

@@ -0,0 +1,45 @@
+/**
+ * Compact JWS (JWT) signing primitive shared by connector auth flows.
+ *
+ * A first-party connector that authenticates with a signed JWT must sign in
+ * TWO places that cannot import each other across the package boundary — the
+ * gateway-side sync handler and the connector's own MCP server. Hosting the
+ * signer here (the SDK, which both may import) keeps a single source of truth.
+ *
+ * Uses `node:crypto` only — no runtime dependency, so the SDK stays dep-free.
+ */
+
+import crypto from "node:crypto";
+
+/** base64url-encode the JSON serialization of `value` (a JWT header/payload). */
+export function base64UrlJson(value: unknown): string {
+  return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+
+export interface SignJwtOptions {
+  readonly header: Record<string, unknown>;
+  readonly payload: Record<string, unknown>;
+  /** Full PEM text of the signing private key (`-----BEGIN PRIVATE KEY----- …`). */
+  readonly privateKeyPem: string;
+  /**
+   * ECDSA (e.g. ES256) requires `"ieee-p1363"` — the raw `r||s` encoding JWS
+   * mandates. Omit for RSA (e.g. RS256), which uses PKCS#1 v1.5 / DER.
+   */
+  readonly dsaEncoding?: "ieee-p1363" | "der";
+}
+
+/**
+ * Sign a compact JWS — `base64url(header).base64url(payload).base64url(sig)` —
+ * over SHA-256. The digest name is passed explicitly ("sha256") rather than
+ * `null` so the signer works on Bun's BoringSSL, which has no default digest.
+ */
+export function signJwt(opts: SignJwtOptions): string {
+  const signingInput = `${base64UrlJson(opts.header)}.${base64UrlJson(opts.payload)}`;
+  const data = Buffer.from(signingInput, "utf8");
+  const key = crypto.createPrivateKey(opts.privateKeyPem);
+  const signature =
+    opts.dsaEncoding === undefined
+      ? crypto.sign("sha256", data, key)
+      : crypto.sign("sha256", data, { key, dsaEncoding: opts.dsaEncoding });
+  return `${signingInput}.${signature.toString("base64url")}`;
+}

package/src/crypto/service-account-token.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "bun:test";
+import crypto from "node:crypto";
+
+import {
+  type FetchLike,
+  mintGoogleAccessToken,
+  parseServiceAccountJson,
+  signServiceAccountAssertion,
+} from "./service-account-token";
+
+function generateRsa(): { privateKey: string; publicKey: string } {
+  const { privateKey, publicKey } = crypto.generateKeyPairSync("rsa", { modulusLength: 2048 });
+  return {
+    privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
+  };
+}
+
+function decode(segment: string): Record<string, unknown> {
+  return JSON.parse(Buffer.from(segment, "base64url").toString("utf8")) as Record<string, unknown>;
+}
+
+const NOW_MS = 1_700_000_000_000;
+
+describe("parseServiceAccountJson", () => {
+  test("parses the fields and defaults the token uri", () => {
+    const sa = parseServiceAccountJson(
+      JSON.stringify({ client_email: "a@b.com", private_key: "k" }),
+    );
+    expect(sa).not.toBeNull();
+    expect(sa?.clientEmail).toBe("a@b.com");
+    expect(sa?.privateKey).toBe("k");
+    expect(sa?.tokenUri).toBe("https://oauth2.googleapis.com/token");
+  });
+
+  test("honours an explicit token_uri", () => {
+    const sa = parseServiceAccountJson(
+      JSON.stringify({ client_email: "a@b.com", private_key: "k", token_uri: "https://custom/t" }),
+    );
+    expect(sa?.tokenUri).toBe("https://custom/t");
+  });
+
+  test("returns null on malformed JSON, non-object, or missing fields", () => {
+    expect(parseServiceAccountJson("{not json")).toBeNull();
+    expect(parseServiceAccountJson("42")).toBeNull();
+    expect(parseServiceAccountJson("null")).toBeNull();
+    expect(parseServiceAccountJson(JSON.stringify({ private_key: "k" }))).toBeNull();
+    expect(parseServiceAccountJson(JSON.stringify({ client_email: "a@b.com" }))).toBeNull();
+  });
+});
+
+describe("signServiceAccountAssertion", () => {
+  const { privateKey, publicKey } = generateRsa();
+  const sa = {
+    clientEmail: "sa@example.iam.gserviceaccount.com",
+    privateKey,
+    tokenUri: "https://oauth2.googleapis.com/token",
+  };
+
+  test("RS256 header, iss/scope/aud claims, and a 1-hour exp", () => {
+    const [h, p] = signServiceAccountAssertion(sa, NOW_MS).split(".");
+    expect(decode(h as string)).toEqual({ alg: "RS256", typ: "JWT" });
+    const payload = decode(p as string);
+    const nowSec = Math.floor(NOW_MS / 1000);
+    expect(payload["iss"]).toBe(sa.clientEmail);
+    expect(payload["scope"]).toBe("https://www.googleapis.com/auth/cloud-platform");
+    expect(payload["aud"]).toBe(sa.tokenUri);
+    expect(payload["iat"]).toBe(nowSec);
+    expect(payload["exp"]).toBe(nowSec + 3600);
+  });
+
+  test("honours a custom scope", () => {
+    const payload = decode(
+      signServiceAccountAssertion(
+        sa,
+        NOW_MS,
+        "https://www.googleapis.com/auth/devstorage.read_only",
+      ).split(".")[1] as string,
+    );
+    expect(payload["scope"]).toBe("https://www.googleapis.com/auth/devstorage.read_only");
+  });
+
+  test("signature verifies under RS256", () => {
+    const [h, p, sig] = signServiceAccountAssertion(sa, NOW_MS).split(".");
+    const ok = crypto.verify(
+      "sha256",
+      Buffer.from(`${h}.${p}`, "utf8"),
+      crypto.createPublicKey(publicKey),
+      Buffer.from(sig as string, "base64url"), // NOSONAR S4325: sig is string|undefined from the JWT split under noUncheckedIndexedAccess
+    );
+    expect(ok).toBe(true);
+  });
+});
+
+describe("mintGoogleAccessToken", () => {
+  const { privateKey } = generateRsa();
+  const sa = {
+    clientEmail: "sa@example.iam.gserviceaccount.com",
+    privateKey,
+    tokenUri: "https://oauth2.googleapis.com/token",
+  };
+
+  test("exchanges the assertion for an access token", async () => {
+    let posted: { url: string; body: string } | null = null;
+    const fetchFn: FetchLike = async (input, init) => {
+      posted = { url: String(input), body: String(init?.body) };
+      return new Response(JSON.stringify({ access_token: "ya29.test", expires_in: 3599 }), {
+        status: 200,
+      });
+    };
+    const token = await mintGoogleAccessToken(sa, fetchFn, NOW_MS);
+    expect(token).toBe("ya29.test");
+    const sent = posted as unknown as { url: string; body: string };
+    expect(sent.url).toBe(sa.tokenUri);
+    expect(sent.body).toContain("grant_type=urn");
+    expect(sent.body).toContain("assertion=");
+  });
+
+  test("returns null on non-ok, non-JSON, or missing access_token", async () => {
+    const bad: FetchLike = async () => new Response("denied", { status: 400 });
+    expect(await mintGoogleAccessToken(sa, bad, NOW_MS)).toBeNull();
+    const notJson: FetchLike = async () => new Response("<html>", { status: 200 });
+    expect(await mintGoogleAccessToken(sa, notJson, NOW_MS)).toBeNull();
+    const noToken: FetchLike = async () =>
+      new Response(JSON.stringify({ token_type: "Bearer" }), { status: 200 });
+    expect(await mintGoogleAccessToken(sa, noToken, NOW_MS)).toBeNull();
+  });
+});

package/src/crypto/service-account-token.ts

@@ -0,0 +1,116 @@
+/**
+ * Google service-account OAuth2 access tokens via the JWT-bearer grant.
+ *
+ * Google Cloud REST APIs (App Distribution, BigQuery, …) accept a short-lived
+ * OAuth2 access token. This mints one from a service-account key (the JSON the
+ * developer downloads) by signing an RS256 JWT assertion and exchanging it at
+ * the token endpoint — no `googleapis` dependency. Shared so the gateway sync
+ * and a connector's MCP server sign identically without duplicating the flow.
+ *
+ * See: https://developers.google.com/identity/protocols/oauth2/service-account
+ */
+
+import { signJwt } from "./jwt";
+
+const SCOPE_CLOUD_PLATFORM = "https://www.googleapis.com/auth/cloud-platform";
+const DEFAULT_TOKEN_URI = "https://oauth2.googleapis.com/token";
+/** Google caps SA assertion lifetime at 1 hour. */
+const ASSERTION_TTL_SECONDS = 3600;
+const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+
+export interface GoogleServiceAccount {
+  readonly clientEmail: string;
+  readonly privateKey: string;
+  readonly tokenUri: string;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/**
+ * Parse a service-account key JSON string into the fields the JWT-bearer flow
+ * needs. Returns null on malformed JSON or a missing `client_email` /
+ * `private_key`; `token_uri` defaults to Google's endpoint when absent.
+ */
+export function parseServiceAccountJson(json: string): GoogleServiceAccount | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json) as unknown;
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const obj = parsed as Record<string, unknown>;
+  const clientEmail = asString(obj["client_email"]);
+  const privateKey = asString(obj["private_key"]);
+  if (clientEmail === undefined || privateKey === undefined) {
+    return null;
+  }
+  return {
+    clientEmail,
+    privateKey,
+    tokenUri: asString(obj["token_uri"]) ?? DEFAULT_TOKEN_URI,
+  };
+}
+
+/**
+ * Sign an RS256 JWT assertion for the JWT-bearer grant. `nowMs` is injectable
+ * so tests can assert deterministic `iat`/`exp`; `scope` defaults to
+ * `cloud-platform`.
+ */
+export function signServiceAccountAssertion(
+  sa: GoogleServiceAccount,
+  nowMs: number = Date.now(),
+  scope: string = SCOPE_CLOUD_PLATFORM,
+): string {
+  const nowSec = Math.floor(nowMs / 1000);
+  return signJwt({
+    header: { alg: "RS256", typ: "JWT" },
+    payload: {
+      iss: sa.clientEmail,
+      scope,
+      aud: sa.tokenUri,
+      iat: nowSec,
+      exp: nowSec + ASSERTION_TTL_SECONDS,
+    },
+    privateKeyPem: sa.privateKey,
+  });
+}
+
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Exchange a service-account assertion for an OAuth2 access token. `fetchFn` and
+ * `nowMs` are injectable for tests; the live path uses the global `fetch`.
+ * Returns null when the token endpoint declines the assertion.
+ */
+export async function mintGoogleAccessToken(
+  sa: GoogleServiceAccount,
+  fetchFn: FetchLike = globalThis.fetch as FetchLike,
+  nowMs: number = Date.now(),
+  scope: string = SCOPE_CLOUD_PLATFORM,
+): Promise<string | null> {
+  const assertion = signServiceAccountAssertion(sa, nowMs, scope);
+  const body = new URLSearchParams({ grant_type: JWT_BEARER_GRANT, assertion }).toString();
+  const res = await fetchFn(sa.tokenUri, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body,
+  });
+  if (!res.ok) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = (await res.json()) as unknown;
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  return asString((parsed as Record<string, unknown>)["access_token"]) ?? null;
+}

package/src/crypto/verify-signature.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  decodeBase64,
+  encodeBase64,
+  errorToHardDisableReason,
+  generateEd25519Keypair,
+  PublisherKeyMismatch,
+  SignatureInvalid,
+  SignatureInvalidFormat,
+  signManifest,
+  verifyManifestSignature,
+} from "./verify-signature.ts";
+
+type Manifest = {
+  publisher?: { id: string; key: string };
+  signature?: string;
+  [k: string]: unknown;
+};
+
+async function signedManifest(): Promise<{
+  manifest: Manifest;
+  pubkey: Uint8Array;
+  privkey: Uint8Array;
+}> {
+  const { privkey, pubkey } = generateEd25519Keypair();
+  const manifest: Manifest = {
+    id: "com.example.demo",
+    version: "1.0.0",
+    publisher: { id: "demo", key: encodeBase64(pubkey) },
+  };
+  manifest.signature = await signManifest(manifest, privkey);
+  return { manifest, pubkey, privkey };
+}
+
+describe("base64 round-trip", () => {
+  test("encode then decode is identity", () => {
+    const bytes = new Uint8Array([0, 1, 2, 250, 255]);
+    expect(Array.from(decodeBase64(encodeBase64(bytes)))).toEqual(Array.from(bytes));
+  });
+});
+
+describe("verifyManifestSignature", () => {
+  test("accepts a correctly signed manifest", async () => {
+    const { manifest, pubkey } = await signedManifest();
+    await expect(verifyManifestSignature(manifest, pubkey)).resolves.toBeUndefined();
+  });
+  test("throws SignatureInvalid when a field is tampered after signing", async () => {
+    const { manifest, pubkey } = await signedManifest();
+    manifest["version"] = "9.9.9";
+    await expect(verifyManifestSignature(manifest, pubkey)).rejects.toBeInstanceOf(
+      SignatureInvalid,
+    );
+  });
+  test("throws PublisherKeyMismatch when resolved key differs from declared", async () => {
+    const { manifest } = await signedManifest();
+    const other = generateEd25519Keypair().pubkey;
+    await expect(verifyManifestSignature(manifest, other)).rejects.toBeInstanceOf(
+      PublisherKeyMismatch,
+    );
+  });
+  test("throws SignatureInvalidFormat for a wrong-length resolved pubkey", async () => {
+    const { manifest } = await signedManifest();
+    await expect(verifyManifestSignature(manifest, new Uint8Array(31))).rejects.toBeInstanceOf(
+      SignatureInvalidFormat,
+    );
+  });
+  test("throws SignatureInvalidFormat for a wrong-length declared pubkey", async () => {
+    const { manifest, pubkey } = await signedManifest();
+    manifest.publisher = { id: "demo", key: encodeBase64(new Uint8Array(31)) };
+    await expect(verifyManifestSignature(manifest, pubkey)).rejects.toBeInstanceOf(
+      SignatureInvalidFormat,
+    );
+  });
+  test("throws SignatureInvalidFormat for a wrong-length signature", async () => {
+    const { manifest, pubkey } = await signedManifest();
+    manifest.signature = encodeBase64(new Uint8Array(63));
+    await expect(verifyManifestSignature(manifest, pubkey)).rejects.toBeInstanceOf(
+      SignatureInvalidFormat,
+    );
+  });
+  test("throws when manifest is unsigned (no publisher / no signature)", async () => {
+    const { pubkey } = await signedManifest();
+    await expect(verifyManifestSignature({ id: "x" }, pubkey)).rejects.toThrow(/unsigned manifest/);
+  });
+  test("throws when publisher is present but signature is missing", async () => {
+    const pubkey = generateEd25519Keypair().pubkey;
+    await expect(
+      verifyManifestSignature(
+        { id: "x", publisher: { id: "p", key: encodeBase64(pubkey) } },
+        pubkey,
+      ),
+    ).rejects.toThrow(/unsigned manifest/);
+  });
+  test("throws when signature is present but publisher is missing", async () => {
+    const pubkey = generateEd25519Keypair().pubkey;
+    await expect(verifyManifestSignature({ id: "x", signature: "AA==" }, pubkey)).rejects.toThrow(
+      /unsigned manifest/,
+    );
+  });
+});
+
+describe("signManifest", () => {
+  test("throws SignatureInvalidFormat for a non-32-byte private key", async () => {
+    await expect(signManifest({ id: "x" }, new Uint8Array(16))).rejects.toBeInstanceOf(
+      SignatureInvalidFormat,
+    );
+  });
+});
+
+describe("errorToHardDisableReason", () => {
+  test("maps each error class to its reason", () => {
+    expect(errorToHardDisableReason(new PublisherKeyMismatch())).toBe("publisher_key_mismatch");
+    expect(errorToHardDisableReason(new SignatureInvalidFormat())).toBe("signature_malformed");
+    expect(errorToHardDisableReason(new SignatureInvalid())).toBe("signature_failed");
+    expect(errorToHardDisableReason(new Error("unknown"))).toBe("signature_failed");
+  });
+});

package/src/crypto/verify-signature.ts

@@ -0,0 +1,138 @@
+/**
+ * Ed25519 sign + verify primitives for extension manifest signatures.
+ * Connector authors use this to sign manifests; the gateway uses it to verify
+ * at install + every startup (I16 wiring sites).
+ */
+
+import { canonicalizeManifest } from "./canonical-json";
+
+export class PublisherKeyMismatch extends Error {
+  override readonly name = "PublisherKeyMismatch";
+}
+export class SignatureInvalidFormat extends Error {
+  override readonly name = "SignatureInvalidFormat";
+}
+export class SignatureInvalid extends Error {
+  override readonly name = "SignatureInvalid";
+}
+
+export type SignatureDisableReason =
+  | "publisher_key_missing"
+  | "publisher_key_mismatch"
+  | "signature_failed"
+  | "signature_malformed";
+
+export function encodeBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64");
+}
+
+export function decodeBase64(s: string): Uint8Array {
+  return new Uint8Array(Buffer.from(s, "base64"));
+}
+
+function constantTimeBytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  }
+  return diff === 0;
+}
+
+type SignedManifestShape = {
+  publisher?: { id: string; key: string };
+  signature?: string;
+  [k: string]: unknown;
+};
+
+/**
+ * Verify `manifest.signature` against the canonical bytes of the manifest
+ * (with `signature` stripped), the declared `manifest.publisher.key`, and
+ * the externally-resolved `resolvedPubkey`. Throws on any mismatch.
+ *
+ * Caller must check `manifest.publisher !== undefined` first — this function
+ * does not gate the unsigned case.
+ */
+export async function verifyManifestSignature(
+  manifest: SignedManifestShape,
+  resolvedPubkey: Uint8Array,
+): Promise<void> {
+  if (manifest.publisher === undefined || manifest.signature === undefined) {
+    throw new Error(
+      "verifyManifestSignature called on unsigned manifest — caller must check first",
+    );
+  }
+  if (resolvedPubkey.length !== 32) throw new SignatureInvalidFormat();
+  const declaredPubkey = decodeBase64(manifest.publisher.key);
+  if (declaredPubkey.length !== 32) throw new SignatureInvalidFormat();
+  if (!constantTimeBytesEqual(declaredPubkey, resolvedPubkey)) {
+    throw new PublisherKeyMismatch();
+  }
+  const sig = decodeBase64(manifest.signature);
+  if (sig.length !== 64) throw new SignatureInvalidFormat();
+  const canonical = canonicalizeManifest(manifest);
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    new Uint8Array(resolvedPubkey),
+    { name: "Ed25519" },
+    false,
+    ["verify"],
+  );
+  const ok = await crypto.subtle.verify(
+    "Ed25519",
+    cryptoKey,
+    new Uint8Array(sig),
+    new Uint8Array(canonical),
+  );
+  if (!ok) throw new SignatureInvalid();
+}
+
+/**
+ * Deterministically sign a manifest's canonical bytes with `privkey` (32-byte
+ * Ed25519 seed). Returns the 64-byte signature as base64. Any existing
+ * `signature` field on the manifest is ignored (stripped by
+ * `canonicalizeManifest`).
+ */
+export async function signManifest(
+  manifest: SignedManifestShape,
+  privkey: Uint8Array,
+): Promise<string> {
+  if (privkey.length !== 32) throw new SignatureInvalidFormat();
+  const d = Buffer.from(privkey).toString("base64url");
+  const cryptoKey = await crypto.subtle.importKey(
+    "jwk",
+    { kty: "OKP", crv: "Ed25519", d },
+    { name: "Ed25519" },
+    false,
+    ["sign"],
+  );
+  const canonical = canonicalizeManifest(manifest);
+  const sig = await crypto.subtle.sign("Ed25519", cryptoKey, new Uint8Array(canonical));
+  return encodeBase64(new Uint8Array(sig));
+}
+
+/**
+ * Generate a fresh Ed25519 keypair via WebCrypto and export both halves as
+ * raw 32-byte arrays. Used by `nimbus extension keygen` and by every test
+ * fixture (no committed crypto material — see spec §6.3).
+ */
+export function generateEd25519Keypair(): { privkey: Uint8Array; pubkey: Uint8Array } {
+  const nodeCrypto: typeof import("node:crypto") = require("node:crypto");
+  const { privateKey, publicKey } = nodeCrypto.generateKeyPairSync("ed25519");
+  const privJwk = privateKey.export({ format: "jwk" }) as { d: string };
+  const pubJwk = publicKey.export({ format: "jwk" }) as { x: string };
+  const privkey = new Uint8Array(Buffer.from(privJwk.d, "base64url"));
+  const pubkey = new Uint8Array(Buffer.from(pubJwk.x, "base64url"));
+  return { privkey, pubkey };
+}
+
+/**
+ * Map a verification error class to the `SignatureDisableReason` string the
+ * `SignatureDisabledRegistry` (hard-disable.ts) records.
+ */
+export function errorToHardDisableReason(err: unknown): SignatureDisableReason {
+  if (err instanceof PublisherKeyMismatch) return "publisher_key_mismatch";
+  if (err instanceof SignatureInvalidFormat) return "signature_malformed";
+  if (err instanceof SignatureInvalid) return "signature_failed";
+  return "signature_failed";
+}