@nimbus-dev/sdk 1.1.2

package/src/contract-tests.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  assertNoRowDataTools,
+  ExtensionContractError,
+  ROW_DATA_TOOL_SEGMENTS,
+  runContractTests,
+} from "./contract-tests.ts";
+import type { ExtensionManifest } from "./types.ts";
+
+const base = (): ExtensionManifest => ({
+  id: "demo.ext",
+  displayName: "Demo",
+  version: "0.1.0",
+  description: "Demo extension",
+  author: "nimbus",
+  entrypoint: "dist/index.js",
+  runtime: "bun",
+  permissions: ["read"],
+  hitlRequired: [],
+  minNimbusVersion: "0.1.0",
+});
+
+describe("runContractTests", () => {
+  test("accepts a minimal valid manifest", async () => {
+    await expect(runContractTests(base())).resolves.toBeUndefined();
+  });
+
+  test("rejects invalid permission", async () => {
+    const m = base();
+    m.permissions = ["read", "admin"] as ExtensionManifest["permissions"];
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+});
+
+describe("runContractTests — v1 additions", () => {
+  test("v1 contract passes against a minimal extension manifest", async () => {
+    await expect(
+      runContractTests({
+        id: "ext.v1-smoke",
+        displayName: "V1 Smoke",
+        version: "0.1.0",
+        description: "Smoke test extension",
+        author: "Nimbus",
+        entrypoint: "index.ts",
+        runtime: "bun",
+        permissions: [],
+        hitlRequired: [],
+        minNimbusVersion: "0.1.0",
+      }),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe("runContractTests — missing required fields", () => {
+  test("rejects manifest with empty id", async () => {
+    const m = base();
+    m.id = "";
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+
+  test("rejects manifest with empty displayName", async () => {
+    const m = base();
+    m.displayName = "";
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+
+  test("rejects manifest with empty version", async () => {
+    const m = base();
+    m.version = "";
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+
+  test("rejects manifest with empty description", async () => {
+    const m = base();
+    m.description = "";
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+
+  test("rejects manifest with empty author", async () => {
+    const m = base();
+    m.author = "";
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+
+  test("rejects manifest with empty entrypoint", async () => {
+    const m = base();
+    m.entrypoint = "";
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+});
+
+describe("runContractTests — runtime validation", () => {
+  test("rejects manifest with unsupported runtime", async () => {
+    const m = base();
+    m.runtime = "deno" as ExtensionManifest["runtime"];
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+});
+
+describe("runContractTests — permissions validation", () => {
+  test("rejects manifest when permissions is not an array", async () => {
+    const m = base();
+    m.permissions = "read" as unknown as ExtensionManifest["permissions"];
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+});
+
+describe("runContractTests — hitlRequired validation", () => {
+  test("rejects manifest when hitlRequired is not an array", async () => {
+    const m = base();
+    m.hitlRequired = "write" as unknown as ExtensionManifest["hitlRequired"];
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+
+  test("rejects manifest with invalid hitlRequired entry", async () => {
+    const m = base();
+    m.hitlRequired = ["admin"] as unknown as ExtensionManifest["hitlRequired"];
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+});
+
+describe("runContractTests — minNimbusVersion validation", () => {
+  test("rejects manifest with empty minNimbusVersion", async () => {
+    const m = base();
+    m.minNimbusVersion = "";
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+
+  test("rejects manifest with non-semver minNimbusVersion", async () => {
+    const m = base();
+    m.minNimbusVersion = "latest";
+    await expect(runContractTests(m)).rejects.toBeInstanceOf(ExtensionContractError);
+  });
+});
+
+describe("assertNoRowDataTools — Tier-3 no-row-data contract", () => {
+  test("accepts a metadata-only warehouse surface", () => {
+    expect(() =>
+      assertNoRowDataTools([
+        { name: "bigquery_list" },
+        { name: "bigquery_get" },
+        { name: "bigquery_search" },
+        { name: "bigquery_list_datasets" },
+        { name: "bigquery_get_table_schema" },
+        { name: "athena_list_databases" },
+        { name: "cloudwatch_list_log_groups" },
+        { name: "vertexai_get_model" },
+        { name: "great_expectations_list_suites" },
+      ]),
+    ).not.toThrow();
+  });
+
+  test("does NOT false-positive on the 'bigquery' service prefix (single token, not 'query')", () => {
+    expect(() => assertNoRowDataTools([{ name: "bigquery_get" }])).not.toThrow();
+    // The denylisted segment IS present as its own token, though:
+    expect(ROW_DATA_TOOL_SEGMENTS.has("query")).toBe(true);
+  });
+
+  test("accepts an empty tool surface", () => {
+    expect(() => assertNoRowDataTools([])).not.toThrow();
+  });
+
+  test.each([
+    "bigquery_run_query",
+    "bigquery_get_rows",
+    "athena_query_results",
+    "dynamodb_scan",
+    "bigquery_head",
+    "bigquery_preview_rows",
+    "warehouse_sample",
+    "table_select",
+    "cloudwatch_get_log_records",
+    "cloudwatch_get_log_events",
+    "cloudwatch_filter_log_events",
+    "bigquery_export_table",
+    "snowflake_download",
+    "sheet_get_cell",
+  ])("rejects row/cell/result fetcher %p", (name) => {
+    expect(() => assertNoRowDataTools([{ name }])).toThrow(ExtensionContractError);
+  });
+
+  test("error names every offending tool", () => {
+    try {
+      assertNoRowDataTools([
+        { name: "bigquery_list" },
+        { name: "bigquery_run_query" },
+        { name: "bigquery_get_rows" },
+      ]);
+      throw new Error("expected assertNoRowDataTools to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(ExtensionContractError);
+      const msg = (err as ExtensionContractError).message;
+      expect(msg).toContain("bigquery_run_query");
+      expect(msg).toContain("bigquery_get_rows");
+      expect(msg).not.toContain("bigquery_list (");
+    }
+  });
+
+  test("ignores blank tool names", () => {
+    expect(() => assertNoRowDataTools([{ name: "" }, { name: "   " }])).not.toThrow();
+  });
+});

package/src/contract-tests.ts

@@ -0,0 +1,220 @@
+import { type AuditLogger, createScopedAuditLogger } from "./audit-logger";
+import { type HitlRequest, isHitlRequest } from "./hitl-request";
+import type { ExtensionManifest } from "./types";
+
+export class ExtensionContractError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ExtensionContractError";
+  }
+}
+
+const PERMS = new Set<ExtensionManifest["permissions"][number]>(["read", "write", "delete"]);
+const HITL = new Set<ExtensionManifest["hitlRequired"][number]>(["write", "delete"]);
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.trim() !== "";
+}
+
+function validateRequiredStrings(manifest: ExtensionManifest): string[] {
+  const errors: string[] = [];
+  if (!isNonEmptyString(manifest.id)) {
+    errors.push("manifest.id is required");
+  }
+  if (!isNonEmptyString(manifest.displayName)) {
+    errors.push("manifest.displayName is required");
+  }
+  if (!isNonEmptyString(manifest.version)) {
+    errors.push("manifest.version is required");
+  }
+  if (!isNonEmptyString(manifest.description)) {
+    errors.push("manifest.description is required");
+  }
+  if (!isNonEmptyString(manifest.author)) {
+    errors.push("manifest.author is required");
+  }
+  if (!isNonEmptyString(manifest.entrypoint)) {
+    errors.push("manifest.entrypoint is required");
+  }
+  return errors;
+}
+
+function validateRuntime(manifest: ExtensionManifest): string[] {
+  if (manifest.runtime === "bun" || manifest.runtime === "node") {
+    return [];
+  }
+  return ['manifest.runtime must be "bun" or "node"'];
+}
+
+function validatePermissions(manifest: ExtensionManifest): string[] {
+  const errors: string[] = [];
+  if (!Array.isArray(manifest.permissions)) {
+    errors.push("manifest.permissions must be an array");
+    return errors;
+  }
+  for (const p of manifest.permissions) {
+    if (!PERMS.has(p)) {
+      errors.push(`invalid manifest.permissions entry: ${String(p)}`);
+    }
+  }
+  return errors;
+}
+
+function validateHitlRequired(manifest: ExtensionManifest): string[] {
+  const errors: string[] = [];
+  if (Array.isArray(manifest.hitlRequired)) {
+    for (const h of manifest.hitlRequired) {
+      if (!HITL.has(h)) {
+        errors.push(`invalid manifest.hitlRequired entry: ${String(h)}`);
+      }
+    }
+  } else {
+    errors.push("manifest.hitlRequired must be an array");
+  }
+  return errors;
+}
+
+function validateMinNimbusVersion(manifest: ExtensionManifest): string[] {
+  if (!isNonEmptyString(manifest.minNimbusVersion)) {
+    return ["manifest.minNimbusVersion is required"];
+  }
+  if (!/^\d+\.\d+\.\d+/.test(manifest.minNimbusVersion.trim())) {
+    return ["manifest.minNimbusVersion must start with semver x.y.z"];
+  }
+  return [];
+}
+
+function assertV1AuditLoggerShape(logger: AuditLogger, extensionId: string): void {
+  const ret = logger.log("test.action", {});
+  if (typeof ret.then !== "function") {
+    throw new ExtensionContractError(
+      `AuditLogger.log must return a Promise (extension ${extensionId})`,
+    );
+  }
+}
+
+function assertV1HitlRequestGuard(): void {
+  const good: HitlRequest = { actionId: "x", summary: "y" };
+  if (!isHitlRequest(good)) {
+    throw new ExtensionContractError("isHitlRequest must accept a valid HitlRequest");
+  }
+  if (isHitlRequest({})) {
+    throw new ExtensionContractError("isHitlRequest must reject an empty object");
+  }
+  if (isHitlRequest({ actionId: "", summary: "y" })) {
+    throw new ExtensionContractError("isHitlRequest must reject empty actionId");
+  }
+}
+
+/**
+ * Tool-name segments that indicate a tool fetches actual ROW / CELL / query-result
+ * data (including log EVENTS) — as opposed to schema/metadata. Used by
+ * {@link assertNoRowDataTools}.
+ *
+ * The service prefix of a tool name must be a single token (e.g. `bigquery_list`,
+ * not `big_query_list`) so that, for example, `bigquery` never splits into a
+ * spurious `query` segment.
+ */
+export const ROW_DATA_TOOL_SEGMENTS: ReadonlySet<string> = new Set<string>([
+  "query",
+  "queries",
+  "row",
+  "rows",
+  "cell",
+  "cells",
+  "record",
+  "records",
+  "event",
+  "events",
+  "result",
+  "results",
+  "tabledata",
+  "scan",
+  "sample",
+  "samples",
+  "select",
+  "values",
+  "preview",
+  "head",
+  "dump",
+  "export",
+  "download",
+]);
+
+/** A registered MCP tool, reduced to the fields the no-row-data check inspects. */
+export interface RowDataToolCandidate {
+  readonly name: string;
+  readonly description?: string;
+}
+
+function toolNameSegments(name: string): string[] {
+  return name
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Tier-3 "no-row-data" contract assertion. A warehouse / logging / query connector
+ * must expose ONLY schema/metadata tools (list / get / search over datasets, tables,
+ * schemas, jobs, log groups, models, expectation suites …) and MUST NOT register any
+ * tool that pulls actual row / cell / query-result data into the local index.
+ *
+ * Enforcement is structural at the connector surface (NOT a runtime Gateway
+ * invariant): if the connector never registers a row/cell tool there is nothing to
+ * block at runtime. This assertion is the executable backstop — call it from the
+ * connector's contract test with its registered tool surface so that a future edit
+ * adding a `<svc>_run_query` / `<svc>_get_rows` / `<svc>_sample` / `<svc>_scan` tool
+ * fails CI. A connector that genuinely needs a live-gated row tool is a discrete
+ * `I17` design discussion, out of scope for the no-row-data tier.
+ *
+ * The check is name-based (tool descriptions are not scanned, to avoid false
+ * positives like "does not fetch rows"). Each tool name is split on non-alphanumeric
+ * boundaries and rejected if any segment is in {@link ROW_DATA_TOOL_SEGMENTS}.
+ *
+ * @throws {ExtensionContractError} if any tool name looks like a row/cell fetcher.
+ */
+export function assertNoRowDataTools(
+  tools: ReadonlyArray<RowDataToolCandidate>,
+  context = "connector",
+): void {
+  const offenders: string[] = [];
+  for (const tool of tools) {
+    if (typeof tool?.name !== "string" || tool.name.trim() === "") {
+      continue;
+    }
+    const hit = toolNameSegments(tool.name).find((s) => ROW_DATA_TOOL_SEGMENTS.has(s));
+    if (hit !== undefined) {
+      offenders.push(`${tool.name} (row-data segment "${hit}")`);
+    }
+  }
+  if (offenders.length > 0) {
+    throw new ExtensionContractError(
+      `no-row-data contract violated: ${context} must expose only schema/metadata tools, ` +
+        `but these look like row/cell/result fetchers: ${offenders.join(", ")}. Remove the ` +
+        `tool, or — if a live-gated row tool is genuinely required — raise it as a discrete ` +
+        `I17 design discussion (out of scope for the no-row-data tier).`,
+    );
+  }
+}
+
+/**
+ * Validates a {@link ExtensionManifest} for CI / `nimbus test` (no network, no Gateway).
+ */
+export async function runContractTests(manifest: ExtensionManifest): Promise<void> {
+  const errors: string[] = [
+    ...validateRequiredStrings(manifest),
+    ...validateRuntime(manifest),
+    ...validatePermissions(manifest),
+    ...validateHitlRequired(manifest),
+    ...validateMinNimbusVersion(manifest),
+  ];
+  if (errors.length > 0) {
+    throw new ExtensionContractError(errors.join("; "));
+  }
+  assertV1HitlRequestGuard();
+  assertV1AuditLoggerShape(
+    createScopedAuditLogger(manifest.id, async () => {}),
+    manifest.id,
+  );
+}

package/src/crypto/app-store-connect-jwt.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import crypto from "node:crypto";
+
+import { signAppStoreConnectJwt } from "./app-store-connect-jwt";
+
+function generateP8Pem(): string {
+  const { privateKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+  return privateKey.export({ type: "pkcs8", 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("signAppStoreConnectJwt", () => {
+  const privateKeyPem = generateP8Pem();
+  const params = { issuerId: "issuer-123", keyId: "KEY456", privateKeyPem };
+
+  test("produces a 3-part token with the documented ES256 header", () => {
+    const parts = signAppStoreConnectJwt(params, NOW_MS).split(".");
+    expect(parts).toHaveLength(3);
+    expect(decode(parts[0] as string)).toEqual({ alg: "ES256", kid: "KEY456", typ: "JWT" });
+  });
+
+  test("payload carries iss/aud and an exp within Apple's 20-min cap", () => {
+    const payload = decode(signAppStoreConnectJwt(params, NOW_MS).split(".")[1] as string);
+    const nowSec = Math.floor(NOW_MS / 1000);
+    expect(payload["iss"]).toBe("issuer-123");
+    expect(payload["aud"]).toBe("appstoreconnect-v1");
+    expect(payload["iat"]).toBe(nowSec);
+    expect(payload["exp"]).toBe(nowSec + 600);
+    expect((payload["exp"] as number) - (payload["iat"] as number)).toBeLessThanOrEqual(20 * 60);
+  });
+
+  test("signature verifies under ES256 / ieee-p1363", () => {
+    const [h, p, sig] = signAppStoreConnectJwt(params, NOW_MS).split(".");
+    const ok = crypto.verify(
+      "sha256",
+      Buffer.from(`${h}.${p}`, "utf8"),
+      { key: crypto.createPublicKey(privateKeyPem), 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);
+  });
+
+  test("default nowMs branch — omitting nowMs uses Date.now() and produces a valid iat/exp", () => {
+    const before = Math.floor(Date.now() / 1000);
+    const token = signAppStoreConnectJwt(params); // no explicit nowMs → hits the default-param branch
+    const after = Math.floor(Date.now() / 1000);
+
+    const parts = token.split(".");
+    expect(parts).toHaveLength(3);
+
+    const payload = JSON.parse(
+      Buffer.from(parts[1] as string, "base64url").toString("utf8"),
+    ) as Record<string, unknown>;
+
+    const iat = payload["iat"] as number;
+    const exp = payload["exp"] as number;
+
+    // iat must fall within the wall-clock window bracketing the call
+    expect(iat).toBeGreaterThanOrEqual(before);
+    expect(iat).toBeLessThanOrEqual(after);
+
+    // exp must be exactly iat + 600 (TOKEN_TTL_SECONDS)
+    expect(exp).toBe(iat + 600);
+
+    // The JWT is structurally and cryptographically valid
+    const [h, p, sig] = parts;
+    const ok = crypto.verify(
+      "sha256",
+      Buffer.from(`${h}.${p}`, "utf8"),
+      { key: crypto.createPublicKey(privateKeyPem), 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/app-store-connect-jwt.ts

@@ -0,0 +1,42 @@
+/**
+ * Apple App Store Connect API authentication — a short-lived ES256 JWT.
+ *
+ * The App Store Connect API authenticates with a JWT bearer token minted from
+ * the developer's EC P-256 `.p8` private key (Apple caps the lifetime at 20
+ * min). Shared so the gateway sync and a connector's MCP server sign
+ * identically without duplicating the flow.
+ *
+ * See: https://developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests
+ */
+
+import { signJwt } from "./jwt";
+
+export interface AppStoreConnectJwtParams {
+  readonly issuerId: string;
+  readonly keyId: string;
+  /** Full `.p8` PEM text (`-----BEGIN PRIVATE KEY----- …`). */
+  readonly privateKeyPem: string;
+}
+
+const AUDIENCE = "appstoreconnect-v1";
+const TOKEN_TTL_SECONDS = 600;
+
+/** Mint an ES256 JWT bearer token for the App Store Connect API. */
+export function signAppStoreConnectJwt(
+  params: AppStoreConnectJwtParams,
+  nowMs: number = Date.now(),
+): string {
+  const nowSec = Math.floor(nowMs / 1000);
+  return signJwt({
+    header: { alg: "ES256", kid: params.keyId, typ: "JWT" },
+    payload: {
+      iss: params.issuerId,
+      iat: nowSec,
+      exp: nowSec + TOKEN_TTL_SECONDS,
+      aud: AUDIENCE,
+    },
+    privateKeyPem: params.privateKeyPem,
+    // ES256 = ECDSA over P-256; `ieee-p1363` gives the raw r||s JWS needs.
+    dsaEncoding: "ieee-p1363",
+  });
+}

package/src/crypto/canonical-json.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Unit tests for `canonical-json.ts`.
+ *
+ * The existing SDK test suite imports `canonicalize` indirectly through
+ * `signManifest` / `verifyManifestSignature`, but does not exercise the
+ * function directly. These tests target lines that are currently uncovered:
+ *
+ *  - Object key sorting (the explicit UTF-16 comparator added in the main
+ *    branch merge, and flagged by Sonar S2871).
+ *  - The `null` / boolean / array / number literal paths.
+ *  - The three error classes.
+ *  - `canonicalizeManifest` (strips `signature` then delegates).
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  canonicalize,
+  canonicalizeManifest,
+  ManifestNestedTooDeep,
+  NonIntegerNumberInManifest,
+  UnsupportedManifestValueType,
+} from "./canonical-json.ts";
+
+describe("canonicalize — primitives", () => {
+  test("null serializes to 'null'", () => {
+    expect(canonicalize(null)).toBe("null");
+  });
+
+  test("true serializes to 'true'", () => {
+    expect(canonicalize(true)).toBe("true");
+  });
+
+  test("false serializes to 'false'", () => {
+    expect(canonicalize(false)).toBe("false");
+  });
+
+  test("integer number serializes to its string representation", () => {
+    expect(canonicalize(42)).toBe("42");
+    expect(canonicalize(0)).toBe("0");
+    expect(canonicalize(-7)).toBe("-7");
+  });
+
+  test("string is JSON-encoded", () => {
+    expect(canonicalize("hello")).toBe('"hello"');
+    expect(canonicalize('say "hi"')).toBe(String.raw`"say \"hi\""`);
+  });
+
+  test("empty array serializes to '[]'", () => {
+    expect(canonicalize([])).toBe("[]");
+  });
+
+  test("array of mixed primitives", () => {
+    expect(canonicalize([1, "a", null, true])).toBe('[1,"a",null,true]');
+  });
+});
+
+describe("canonicalize — object key sorting", () => {
+  test("keys are sorted in UTF-16 code-unit order (lexicographic)", () => {
+    expect(canonicalize({ b: 1, a: 2 })).toBe('{"a":2,"b":1}');
+  });
+
+  test("numeric string keys sort before alphabetic", () => {
+    const result = canonicalize({ z: "z", "0": "zero", a: "a" });
+    expect(result).toBe('{"0":"zero","a":"a","z":"z"}');
+  });
+
+  test("nested objects have keys sorted independently", () => {
+    const result = canonicalize({ z: { b: 2, a: 1 }, a: 0 });
+    expect(result).toBe('{"a":0,"z":{"a":1,"b":2}}');
+  });
+
+  test("empty object serializes to '{}'", () => {
+    expect(canonicalize({})).toBe("{}");
+  });
+});
+
+describe("canonicalize — error paths", () => {
+  test("non-integer number throws NonIntegerNumberInManifest", () => {
+    expect(() => canonicalize(1.5)).toThrow(NonIntegerNumberInManifest);
+  });
+
+  test("unsupported value type (function) throws UnsupportedManifestValueType", () => {
+    expect(() => canonicalize(() => {})).toThrow(UnsupportedManifestValueType);
+  });
+
+  test("undefined throws UnsupportedManifestValueType", () => {
+    expect(() => canonicalize(undefined)).toThrow(UnsupportedManifestValueType);
+  });
+
+  test("exceeding MAX_DEPTH throws ManifestNestedTooDeep", () => {
+    let deep: unknown = "leaf";
+    for (let i = 0; i < 34; i++) {
+      deep = [deep];
+    }
+    expect(() => canonicalize(deep)).toThrow(ManifestNestedTooDeep);
+  });
+});
+
+describe("canonicalizeManifest", () => {
+  test("strips the signature field before canonicalizing", () => {
+    const manifest = { id: "ext.test", version: "1.0.0", signature: "abc123" };
+    const bytes = canonicalizeManifest(manifest);
+    const text = new TextDecoder().decode(bytes);
+    expect(text).not.toContain("signature");
+    expect(text).toContain("ext.test");
+    expect(text).toContain("1.0.0");
+  });
+
+  test("returns a Uint8Array of UTF-8 bytes", () => {
+    const bytes = canonicalizeManifest({ id: "x", version: "0.1.0" });
+    expect(bytes).toBeInstanceOf(Uint8Array);
+    expect(bytes.length).toBeGreaterThan(0);
+  });
+
+  test("keys are sorted in the output (id before version)", () => {
+    const bytes = canonicalizeManifest({ version: "1.0.0", id: "ext.x" });
+    const text = new TextDecoder().decode(bytes);
+    expect(text.indexOf('"id"')).toBeLessThan(text.indexOf('"version"'));
+  });
+});