@greensecurity/javascript-sdk 0.46.0-beta.1 → 0.46.0-beta.10

package/src/__tests__/apps/contract.test.ts

@@ -0,0 +1,893 @@
+/*
+ * Hand-written. Tests for the third-party app platform contract in src/apps.
+ *
+ * The JSON files in shared/app-platform are what the server validates against. They are checked
+ * against the TypeScript sources here; regenerate them with
+ *   UPDATE_APP_PLATFORM_JSON=1 npx vitest run src/__tests__/apps
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  canonicalBuildPayload,
+  APP_WEBHOOK_EVENTS,
+  COMPONENTS,
+  componentsCatalogJson,
+  CSP_DENYLIST,
+  cspDenylistEntry,
+  DATA_IMAGE_MAX_CHARS,
+  DEV_SIGNATURE_ALGORITHM,
+  DevManifestError,
+  effectivePostInstallAction,
+  devManifestSchema,
+  getComponentByTag,
+  getSurface,
+  isBootstrapToHost,
+  isCalendarDate,
+  isPlatformPermission,
+  isRouteDescriptor,
+  isSensitivePermission,
+  isSurfaceId,
+  manifestJsonSchema,
+  mergeDevManifest,
+  permissionReviewIssues,
+  PLATFORM_PERMISSIONS,
+  REVIEW_RULES,
+  SAFE_INTEGER_STRING_PATTERN,
+  sanitizeProps,
+  SURFACES,
+  surfacesForPortal,
+  tokenNeedsRefresh,
+  validateManifest,
+  type AppManifestV2,
+  type ComponentProps,
+  type HostToBootstrap,
+} from "../../apps/index.js";
+
+// Resolved from the package root (vitest's cwd) rather than `import.meta.url`: Speakeasy also
+// compiles this file to CommonJS, where `import.meta` is a type error (TS1470).
+const SHARED_DIR = resolve(process.cwd(), "..", "shared", "app-platform");
+
+function baseManifest(): Record<string, unknown> {
+  return {
+    id: 42,
+    name: "Acme Credentials",
+    icon: "https://cdn.acme.com/icon.png",
+    short_description: "Shows Acme status for a vendor.",
+    version: "1.3.0",
+    permissions: [{ permission: "vendors.view", purpose: "Read the vendor you are looking at." }],
+    configuration_instructions: "Install and sign in.",
+    support_instructions: "support@acme.com",
+    constants: { API_BASE: "https://api.acme.com/gs/" },
+    ui_extensions: {
+      bundle: { url: "https://cdn.acme.com/gs-app/1.3.0/app.js", integrity: "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC" },
+      views: [
+        { viewport: "gs.company.vendor.detail", component: "VendorPanel" },
+        { viewport: "gs.company.drawer.default", component: "Home" },
+        { viewport: "settings", component: "AppSettings" },
+      ],
+      csp: { connect_src: ["https://api.acme.com/gs/"], image_src: ["https://cdn.acme.com/img/"], purpose: "Talk to Acme." },
+    },
+    post_install_action: { type: "app_settings_view" },
+  };
+}
+
+function withCsp(connectSrc: string[]): Record<string, unknown> {
+  const m = baseManifest();
+  const ui = m["ui_extensions"] as Record<string, unknown>;
+  ui["csp"] = { connect_src: connectSrc, purpose: "x" };
+  return m;
+}
+
+describe("surfaces", () => {
+  test("ids are unique and follow gs.<portal>.<entity>.<kind>", () => {
+    const ids = SURFACES.map((s) => s.id);
+    expect(new Set(ids).size).toBe(ids.length);
+
+    for (const s of SURFACES) {
+      if (s.id === "settings") continue;
+      expect(s.id).toMatch(/^gs\.(vendor|company|facility|system)\.[a-z_]+(\.[a-z_]+)*$/);
+      expect(s.id.startsWith(`gs.${s.portal}.`)).toBe(true);
+      expect(s.id.endsWith(s.kind)).toBe(true);
+    }
+  });
+
+  test("every route names its portal: a literal portal segment, or [portal] for portal-less surfaces", () => {
+    for (const s of SURFACES) {
+      expect(s.route.startsWith(s.portal === null ? "/[portal]/" : `/${s.portal}`)).toBe(true);
+    }
+    expect(getSurface("settings")?.route).toBe("/[portal]/apps/[appId]/settings");
+  });
+
+  test("wave 1 is the vendor and company portals only", () => {
+    const wave1Portals = new Set(SURFACES.filter((s) => s.wave === 1).map((s) => s.portal));
+    expect([...wave1Portals].sort()).toEqual(["company", "vendor", null].sort());
+    expect(surfacesForPortal("facility")).toEqual([]);
+    expect(surfacesForPortal("facility", 2).length).toBeGreaterThan(0);
+  });
+
+  test("record surfaces name an object type, and every list has a row-action surface", () => {
+    for (const s of SURFACES) {
+      if (s.kind === "detail" || s.kind === "list.row_action") expect(s.objectType).not.toBeNull();
+      if (s.kind === "list") expect(getSurface(`${s.id}.row_action`)).toBeDefined();
+    }
+  });
+
+  test("isSurfaceId narrows only catalog ids", () => {
+    expect(isSurfaceId("gs.company.vendor.detail")).toBe(true);
+    expect(isSurfaceId("gs.company.nope")).toBe(false);
+    expect(isSurfaceId(7)).toBe(false);
+  });
+});
+
+describe("manifest", () => {
+  test("accepts a complete v2 manifest", () => {
+    const result = validateManifest(baseManifest());
+    expect(result.ok).toBe(true);
+  });
+
+  test("accepts a back-end-only app: a versioned manifest with no ui_extensions", () => {
+    const m = baseManifest();
+    delete m["ui_extensions"];
+    m["permissions"] = [{ permission: "app_secrets.write", purpose: "Store the customer's API key." }];
+    m["post_install_action"] = { type: "url", url: "https://acme.com/gs/connect" };
+    expect(validateManifest(m).ok).toBe(true);
+    delete m["post_install_action"];
+    expect(validateManifest(m).ok).toBe(true);
+  });
+
+  test("a versioned manifest's post-install view needs a view to land on (v1 is exempt)", () => {
+    const noViews = baseManifest();
+    delete noViews["ui_extensions"];
+    expect(validateManifest({ ...noViews, post_install_action: { type: "app_settings_view" } }).ok).toBe(false);
+    expect(validateManifest({ ...noViews, post_install_action: { type: "app_main_view" } }).ok).toBe(false);
+
+    const noSettings = baseManifest();
+    const ui = noSettings["ui_extensions"] as { views: Array<{ viewport: string }> };
+    ui.views = ui.views.filter((v) => v.viewport !== "settings");
+    expect(validateManifest({ ...noSettings, post_install_action: { type: "app_settings_view" } }).ok).toBe(false);
+    expect(validateManifest({ ...noSettings, post_install_action: { type: "app_main_view" } }).ok).toBe(true);
+    expect(validateManifest(baseManifest()).ok).toBe(true);
+
+    const settingsOnly = baseManifest();
+    const only = settingsOnly["ui_extensions"] as { views: Array<{ viewport: string }> };
+    only.views = only.views.filter((v) => v.viewport === "settings");
+    expect(validateManifest({ ...settingsOnly, post_install_action: { type: "app_main_view" } }).ok).toBe(false);
+    expect(validateManifest({ ...settingsOnly, post_install_action: { type: "app_settings_view" } }).ok).toBe(true);
+  });
+
+  test("an omitted post_install_action defaults to what the app can actually show", () => {
+    const backend = baseManifest();
+    delete backend["ui_extensions"];
+    delete backend["post_install_action"];
+    expect(effectivePostInstallAction(backend as AppManifestV2)).toBeNull();
+
+    const settingsOnly = baseManifest();
+    delete settingsOnly["post_install_action"];
+    const ui = settingsOnly["ui_extensions"] as { views: Array<{ viewport: string }> };
+    ui.views = ui.views.filter((v) => v.viewport === "settings");
+    expect(effectivePostInstallAction(settingsOnly as AppManifestV2)).toEqual({ type: "app_settings_view" });
+
+    const withMain = baseManifest();
+    delete withMain["post_install_action"];
+    expect(effectivePostInstallAction(withMain as AppManifestV2)).toEqual({ type: "app_main_view" });
+
+    const explicit = { ...baseManifest(), post_install_action: { type: "url", url: "https://acme.com/gs/connect" } };
+    expect(effectivePostInstallAction(explicit as AppManifestV2)).toEqual({ type: "url", url: "https://acme.com/gs/connect" });
+
+    // Every default is itself valid for its manifest, so a versioned manifest never installs into a
+    // post-install action the schema would reject if it were written out.
+    for (const m of [backend, settingsOnly, withMain]) {
+      const effective = effectivePostInstallAction(m as AppManifestV2);
+      const written = effective === null ? m : { ...m, post_install_action: effective };
+      expect(validateManifest(written).ok).toBe(true);
+    }
+  });
+
+  test("an app-level webhook endpoint takes a named https host and known events", () => {
+    const ok = (webhooks: unknown) => validateManifest({ ...baseManifest(), webhooks }).ok;
+    expect(ok({ url: "https://api.acme.com/gs/webhooks" })).toBe(true);
+    expect(ok({ url: "https://api.acme.com/gs/webhooks", events: ["MarketplaceAppActivation.created"] })).toBe(true);
+    expect(ok({ url: "http://api.acme.com/gs/webhooks" })).toBe(false);
+    expect(ok({ url: "https://10.0.0.1/hooks" })).toBe(false);
+    expect(ok({ url: "https://api.acme.com/hooks", events: [] })).toBe(false);
+    expect(ok({ url: "https://api.acme.com/hooks", events: ["Vendor.created"] })).toBe(false);
+    expect(ok({ url: "https://api.acme.com/hooks", events: ["MarketplaceAppActivation.created", "MarketplaceAppActivation.created"] })).toBe(false);
+    expect(ok({ url: "https://api.acme.com/hooks", secret: "x" })).toBe(false);
+    expect(APP_WEBHOOK_EVENTS).toHaveLength(3);
+  });
+
+  test("accepts a v1-style manifest without a bundle or views", () => {
+    const m = baseManifest();
+    delete m["ui_extensions"];
+    delete m["version"];
+    m["id"] = "42";
+    expect(validateManifest(m).ok).toBe(true);
+  });
+
+  test.each([
+    ["1", true],
+    ["999999999999999", true],
+    ["1000000000000000", true],
+    ["9007199254740990", true],
+    ["9007199254740991", true],
+    ["9007199254740992", false],
+    ["9007199254740999", false],
+    ["9008000000000000", false],
+    ["10000000000000000", false],
+    ["0", false],
+    ["042", false],
+  ])("a string id %s is accepted only as a safe integer: %s", (id, ok) => {
+    expect(validateManifest({ ...baseManifest(), id }).ok).toBe(ok);
+    expect(new RegExp(SAFE_INTEGER_STRING_PATTERN).test(id)).toBe(ok);
+    if (/^[1-9][0-9]*$/.test(id)) expect(Number.isSafeInteger(Number(id)) && BigInt(id) <= BigInt(Number.MAX_SAFE_INTEGER)).toBe(ok);
+  });
+
+  test.each([
+    ["http scheme", "http://api.acme.com/gs/"],
+    ["bare origin", "https://api.acme.com/"],
+    ["no path", "https://api.acme.com"],
+    ["wildcard spanning a registrable domain", "https://*.com/x/"],
+    ["wildcard under a registrable domain", "https://*.acme.com/api/"],
+    ["wildcard under a public suffix", "https://*.co.uk/x/"],
+    ["wildcard under a private public suffix", "https://*.github.io/x/"],
+    ["an IPv4 loopback literal", "https://127.0.0.1/private/"],
+    ["a private IPv4 literal", "https://10.0.0.1/api/"],
+    ["a numeric last label", "https://0x7f.1/x/"],
+    ["wildcard outside the left-most label", "https://api.*.acme.com/x/"],
+    ["partial-label wildcard", "https://*evil.com/x/"],
+    ["single-label host", "https://localhost/x/"],
+    ["a directive separator", "https://api.acme.com/x;frame-ancestors *"],
+    ["a policy separator", "https://api.acme.com/x,script-src"],
+    ["a quote", "https://api.acme.com/x'unsafe-inline'"],
+    ["non-ASCII", "https://api.acme.com/größe/"],
+    ["credentials", "https://user@api.acme.com/x/"],
+    ["an out-of-range port", "https://api.acme.com:70000/x/"],
+    ["a zero-padded port", "https://api.acme.com:0443/x/"],
+  ])("rejects a CSP source with %s", (_label, source) => {
+    expect(validateManifest(withCsp([source])).ok).toBe(false);
+  });
+
+  test.each([
+    "https://api.acme.com/gs/",
+    "https://api.acme.com:8443/v1/users",
+  ])("accepts CSP source %s", (source) => {
+    expect(validateManifest(withCsp([source])).ok).toBe(true);
+  });
+
+  test("rejects an unknown viewport, a duplicate viewport, and views without a bundle", () => {
+    const unknown = baseManifest();
+    (unknown["ui_extensions"] as { views: unknown[] }).views = [{ viewport: "gs.company.nope", component: "X" }];
+    expect(validateManifest(unknown).ok).toBe(false);
+
+    const dup = baseManifest();
+    (dup["ui_extensions"] as { views: unknown[] }).views = [
+      { viewport: "settings", component: "A" },
+      { viewport: "settings", component: "B" },
+    ];
+    const dupResult = validateManifest(dup);
+    expect(dupResult.ok).toBe(false);
+    if (!dupResult.ok) expect(dupResult.issues[0]?.path).toBe("ui_extensions.views.1.viewport");
+
+    const noBundle = baseManifest();
+    delete (noBundle["ui_extensions"] as Record<string, unknown>)["bundle"];
+    expect(validateManifest(noBundle).ok).toBe(false);
+  });
+
+  test("rejects a bad integrity value, unknown keys, and url post-install actions without a url", () => {
+    const badSri = baseManifest();
+    (badSri["ui_extensions"] as { bundle: { integrity: string } }).bundle.integrity = "md5-abc";
+    expect(validateManifest(badSri).ok).toBe(false);
+
+    expect(validateManifest({ ...baseManifest(), surprise: true }).ok).toBe(false);
+    expect(validateManifest({ ...baseManifest(), post_install_action: { type: "url" } }).ok).toBe(false);
+  });
+});
+
+describe("manifest review fixes", () => {
+  test.each([
+    "https:///", "https://?x", "https://", "https:// acme.com/x", "http://acme.com/icon.png",
+    "https://user:pw@cdn.acme.com/app.js", "https://cdn.acme.com/app.js;x", "https://cdn.acme.com/a'b.js",
+  ])(
+    "rejects malformed https URL %s for icon, bundle and post-install url",
+    (url) => {
+      expect(validateManifest({ ...baseManifest(), icon: url }).ok).toBe(false);
+
+      const bundle = baseManifest();
+      (bundle["ui_extensions"] as { bundle: { url: string } }).bundle.url = url;
+      expect(validateManifest(bundle).ok).toBe(false);
+
+      expect(validateManifest({ ...baseManifest(), post_install_action: { type: "url", url } }).ok).toBe(false);
+    },
+  );
+
+  test.each([
+    ["sha384 digest of the wrong length", { integrity: "sha384-x" }],
+    ["sha256 without padding", { integrity: "sha256-" + "A".repeat(43) }],
+    ["two hashes", { integrity: "sha384-" + "A".repeat(64) + " sha512-" + "A".repeat(86) + "==" }],
+  ])("rejects an integrity value with %s", (_label, bundle) => {
+    const m = baseManifest();
+    Object.assign((m["ui_extensions"] as { bundle: object }).bundle, bundle);
+    expect(validateManifest(m).ok).toBe(false);
+  });
+
+  test.each(["sha256-" + "A".repeat(43) + "=", "sha512-" + "A".repeat(86) + "=="])("accepts integrity %s", (integrity) => {
+    const m = baseManifest();
+    (m["ui_extensions"] as { bundle: { integrity: string } }).bundle.integrity = integrity;
+    expect(validateManifest(m).ok).toBe(true);
+  });
+
+  test.each(["1.0.0-.", "1.0.0-", "01.0.0", "1.0.0-01", "1.0", "1.0.0+"])("rejects version %s", (version) => {
+    expect(validateManifest({ ...baseManifest(), version }).ok).toBe(false);
+  });
+
+  test.each(["1.0.0", "1.0.0-rc.1", "1.0.0-alpha-2.x", "1.0.0+build.7", "10.20.30-0.1+sha.abc"])("accepts version %s", (version) => {
+    expect(validateManifest({ ...baseManifest(), version }).ok).toBe(true);
+  });
+
+  test("caps CSP sources per item, per directive and in total so the CSP header stays small", () => {
+    const long = "https://api.acme.com/" + "a".repeat(512);
+    expect(validateManifest(withCsp([long])).ok).toBe(false);
+
+    const many = Array.from({ length: 21 }, (_, i) => `https://api${i}.acme.com/x/`);
+    expect(validateManifest(withCsp(many)).ok).toBe(false);
+
+    // 20 connect + 20 image sources of ~120 chars each is under the per-item and per-directive
+    // limits but over the 4096-char total budget.
+    const source = (i: number, kind: string) => `https://${kind}${i}.acme.com/` + "p".repeat(100) + "/";
+    const m = baseManifest();
+    (m["ui_extensions"] as Record<string, unknown>)["csp"] = {
+      connect_src: Array.from({ length: 20 }, (_, i) => source(i, "c")),
+      image_src: Array.from({ length: 20 }, (_, i) => source(i, "i")),
+      purpose: "x",
+    };
+    const result = validateManifest(m);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.issues.map((i) => i.path)).toContain("ui_extensions.csp");
+  });
+
+  test("accepts https URLs with a port, path and query", () => {
+    expect(validateManifest({ ...baseManifest(), icon: "https://cdn.acme.com:8443/i/icon.png?v=2" }).ok).toBe(true);
+  });
+
+  test("requires version once a bundle or views are declared, not for legacy manifests", () => {
+    const m = baseManifest();
+    delete m["version"];
+    const result = validateManifest(m);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.issues.map((i) => i.path)).toContain("version");
+  });
+});
+
+describe("dev preview", () => {
+  test("canonical payload has a fixed key order and no whitespace", () => {
+    expect(canonicalBuildPayload({ ts: 2, seq: 1, integrity: "sha384-x", sessionId: "s1" }))
+      .toBe('{"session_id":"s1","integrity":"sha384-x","seq":1,"ts":2}');
+  });
+
+  test("a Node crypto P1363 signature, base64url-encoded, verifies with WebCrypto", async () => {
+    const { generateKeyPairSync, sign } = await import("node:crypto");
+    const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+    const payload = canonicalBuildPayload({ sessionId: "s1", integrity: "sha384-abc", seq: 1, ts: 5 });
+    const sig = sign("sha256", Buffer.from(payload), { key: privateKey, dsaEncoding: "ieee-p1363" }).toString("base64url");
+
+    const jwk = publicKey.export({ format: "jwk" });
+    const key = await globalThis.crypto.subtle.importKey("jwk", jwk, DEV_SIGNATURE_ALGORITHM, false, ["verify"]);
+    const raw = Buffer.from(sig, "base64url");
+    expect(raw.length).toBe(64);
+    expect(await globalThis.crypto.subtle.verify(DEV_SIGNATURE_ALGORITHM, key, raw, new TextEncoder().encode(payload))).toBe(true);
+  });
+
+  test("a signature made by the CLI verifies in the bootstrap, and fails for a changed payload", async () => {
+    const { subtle } = globalThis.crypto;
+    const keys = await subtle.generateKey(DEV_SIGNATURE_ALGORITHM, true, ["sign", "verify"]);
+    const jwk = await subtle.exportKey("jwk", keys.publicKey);
+    const publicKey = await subtle.importKey("jwk", jwk, DEV_SIGNATURE_ALGORITHM, false, ["verify"]);
+
+    const payload = canonicalBuildPayload({ sessionId: "s1", integrity: "sha384-abc", seq: 3, ts: 1000 });
+    const sig = await subtle.sign(DEV_SIGNATURE_ALGORITHM, keys.privateKey, new TextEncoder().encode(payload));
+
+    expect(await subtle.verify(DEV_SIGNATURE_ALGORITHM, publicKey, sig, new TextEncoder().encode(payload))).toBe(true);
+
+    const tampered = canonicalBuildPayload({ sessionId: "s1", integrity: "sha384-evil", seq: 3, ts: 1000 });
+    expect(await subtle.verify(DEV_SIGNATURE_ALGORITHM, publicKey, sig, new TextEncoder().encode(tampered))).toBe(false);
+  });
+
+  test("dev manifests allow local http sources but not public http, and never permissions or a bundle", () => {
+    const ok = devManifestSchema.safeParse({
+      extends: "green-app.json",
+      constants: { API_BASE: "http://localhost:8888/v1" },
+      ui_extensions: { csp: { connect_src: ["http://localhost:8888/v1", "http://10.0.2.2:8888/", "http://192.168.1.20:8888/"] } },
+    });
+    expect(ok.success).toBe(true);
+
+    expect(devManifestSchema.safeParse({ extends: "x", ui_extensions: { csp: { connect_src: ["http://api.acme.com/"] } } }).success).toBe(false);
+    expect(devManifestSchema.safeParse({ extends: "x", ui_extensions: { csp: { connect_src: ["http://localhost:8888/x;script-src *"] } } }).success).toBe(false);
+    for (const bad of ["http://10.999.999.999:8888/", "http://localhost:00000/", "http://localhost:65536/", "http://192.168.1.300/", "http://localhost:0/"]) {
+      expect(devManifestSchema.safeParse({ extends: "x", ui_extensions: { csp: { connect_src: [bad] } } }).success).toBe(false);
+    }
+    for (const good of ["http://10.1.2.3:8888/", "http://localhost:65535/", "http://192.168.0.1/", "http://172.31.255.255:1/"]) {
+      expect(devManifestSchema.safeParse({ extends: "x", ui_extensions: { csp: { connect_src: [good] } } }).success).toBe(true);
+    }
+    expect(devManifestSchema.safeParse({ extends: "x", permissions: [] }).success).toBe(false);
+    expect(devManifestSchema.safeParse({ extends: "x", ui_extensions: { bundle: {} } }).success).toBe(false);
+  });
+
+  test("dev manifests reject duplicate viewports like published ones", () => {
+    const dup = devManifestSchema.safeParse({
+      extends: "green-app.json",
+      ui_extensions: { views: [{ viewport: "settings", component: "A" }, { viewport: "settings", component: "B" }] },
+    });
+    expect(dup.success).toBe(false);
+  });
+
+  test("mergeDevManifest rejects a merged CSP over the budget from a partial override", () => {
+    const base = validateManifest({
+      ...baseManifest(),
+      ui_extensions: {
+        ...(baseManifest()["ui_extensions"] as object),
+        csp: { image_src: Array.from({ length: 20 }, (_, i) => `https://i${i}.acme.com/` + "p".repeat(100) + "/"), purpose: "x" },
+      },
+    });
+    if (!base.ok) throw new Error("fixture invalid");
+
+    const dev = devManifestSchema.parse({
+      extends: "green-app.json",
+      ui_extensions: { csp: { connect_src: Array.from({ length: 20 }, (_, i) => `http://localhost:${4000 + i}/` + "p".repeat(90) + "/") } },
+    });
+
+    expect(() => mergeDevManifest(base.manifest, dev)).toThrow(DevManifestError);
+  });
+
+  test("mergeDevManifest merges constants and replaces views and CSP sources", () => {
+    const base = validateManifest(baseManifest());
+    if (!base.ok) throw new Error("fixture invalid");
+
+    const merged: AppManifestV2 = mergeDevManifest(base.manifest, {
+      extends: "green-app.json",
+      constants: { DEBUG: true },
+      ui_extensions: {
+        views: [{ viewport: "gs.company.vendor.list", component: "VendorList" }],
+        csp: { connect_src: ["http://localhost:8888/v1"] },
+      },
+    });
+
+    expect(merged.constants).toEqual({ API_BASE: "https://api.acme.com/gs/", DEBUG: true });
+    expect(merged.ui_extensions?.views).toEqual([{ viewport: "gs.company.vendor.list", component: "VendorList" }]);
+    expect(merged.ui_extensions?.csp).toEqual({
+      connect_src: ["http://localhost:8888/v1"],
+      image_src: ["https://cdn.acme.com/img/"],
+      purpose: "Talk to Acme.",
+    });
+    expect(merged.ui_extensions?.bundle).toEqual(base.manifest.ui_extensions?.bundle);
+    expect(merged.permissions).toEqual(base.manifest.permissions);
+  });
+});
+
+describe("components", () => {
+  test("tag names are unique ui-* names and every allowed child exists", () => {
+    const specs = Object.values(COMPONENTS);
+    const tags = specs.map((c) => c.tagName);
+    expect(new Set(tags).size).toBe(tags.length);
+
+    for (const c of specs) {
+      expect(c.tagName).toMatch(/^ui-[a-z]+(-[a-z]+)*$/);
+      for (const child of c.children ?? []) expect(getComponentByTag(child)).toBeDefined();
+    }
+  });
+
+  test("text-level containers only allow text-level children", () => {
+    expect(COMPONENTS.Inline.children).toEqual(["ui-inline", "ui-link"]);
+    expect(COMPONENTS.Text.children).toEqual(["ui-inline", "ui-link"]);
+  });
+
+  test("only ContextView and SettingsView are roots", () => {
+    const roots = Object.entries(COMPONENTS).filter(([, c]) => "root" in c).map(([name]) => name);
+    expect(roots.sort()).toEqual(["ContextView", "SettingsView"]);
+  });
+
+  test("sanitizeProps keeps declared props of the right type and drops everything else", () => {
+    const result = sanitizeProps("ui-button", {
+      type: "primary",
+      size: "huge",
+      style: { color: "red" },
+      className: "bg-red-500",
+      href: "javascript:alert(1)",
+      disabled: true,
+    });
+    expect(result.props).toEqual({ type: "primary", disabled: true });
+    expect(result.dropped.sort()).toEqual(["className", "href", "size", "style"]);
+    expect(result.missing).toEqual([]);
+  });
+
+  test("sanitizeProps accepts route descriptors and https hrefs, and reports missing required props", () => {
+    expect(sanitizeProps("ui-link", { href: { type: "surface", surfaceId: "gs.company.vendor.detail", objectId: 5 } }).props["href"])
+      .toBeDefined();
+    expect(sanitizeProps("ui-link", { href: "https://acme.com/help" }).props["href"]).toBe("https://acme.com/help");
+
+    const img = sanitizeProps("ui-img", { src: "http://tracker.example/pixel.gif" });
+    expect(img.props).toEqual({});
+    expect(img.missing.sort()).toEqual(["alt", "src"]);
+
+    expect(sanitizeProps("ui-script", { src: "x" })).toEqual({ props: {}, dropped: ["src"], missing: [] });
+  });
+
+  test.each(["https:///", "https://?x", "https://user@acme.com/x", "https://acme.com/a;b"])(
+    "sanitizeProps drops malformed https destination %s from href, img src and externalLink",
+    (url) => {
+      expect(sanitizeProps("ui-link", { href: url }).dropped).toEqual(["href"]);
+      expect(sanitizeProps("ui-img", { src: url, alt: "x" }).dropped).toEqual(["src"]);
+      expect(sanitizeProps("ui-context-view", { title: "T", externalLink: { href: url, label: "x" } }).dropped).toEqual(["externalLink"]);
+    },
+  );
+
+  test("required strings must be non-blank", () => {
+    expect(sanitizeProps("ui-text-field", { label: "" }).missing).toEqual(["label"]);
+    expect(sanitizeProps("ui-text-field", { label: "   " }).missing).toEqual(["label"]);
+    expect(sanitizeProps("ui-context-view", { title: "" }).missing).toEqual(["title"]);
+    expect(componentsCatalogJson().find((c) => c.name === "TextField")?.props["label"]?.minLength).toBe(1);
+  });
+
+  test("form controls require an accessible label and accept hideLabel", () => {
+    for (const tag of ["ui-text-field", "ui-text-area", "ui-select", "ui-checkbox", "ui-switch", "ui-radio-group", "ui-date-field"]) {
+      expect(sanitizeProps(tag, {}).missing).toContain("label");
+      const labelled = sanitizeProps(tag, { label: "Email", hideLabel: true });
+      expect(labelled.missing).toEqual([]);
+      expect(labelled.props).toEqual({ label: "Email", hideLabel: true });
+    }
+  });
+
+  describe("data: image sources", () => {
+    const dataUrl = (type: string, bytes: number[]): string =>
+      `data:image/${type};base64,${Buffer.from(bytes).toString("base64")}`;
+    const be32 = (n: number): number[] => [(n >>> 24) & 255, (n >>> 16) & 255, (n >>> 8) & 255, n & 255];
+    const le16 = (n: number): number[] => [n & 255, (n >>> 8) & 255];
+    const le24 = (n: number): number[] => [n & 255, (n >>> 8) & 255, (n >>> 16) & 255];
+    const ascii = (s: string): number[] => [...s].map((c) => c.charCodeAt(0));
+    const png = (w: number, h: number): string =>
+      dataUrl("png", [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13, ...ascii("IHDR"), ...be32(w), ...be32(h), 8, 6, 0, 0, 0]);
+    const gif = (w: number, h: number): string => dataUrl("gif", [...ascii("GIF89a"), ...le16(w), ...le16(h), 0, 0, 0]);
+    const jpeg = (w: number, h: number): string =>
+      dataUrl("jpeg", [0xff, 0xd8, 0xff, 0xe0, 0, 4, 0, 0, 0xff, 0xc0, 0, 11, 8, h >> 8, h & 255, w >> 8, w & 255, 3, 0, 0, 0]);
+    const webpX = (w: number, h: number): string =>
+      dataUrl("webp", [...ascii("RIFF"), 0, 0, 0, 0, ...ascii("WEBP"), ...ascii("VP8X"), 10, 0, 0, 0, 0, 0, 0, 0, ...le24(w - 1), ...le24(h - 1), 0, 0]);
+    const webpL = (w: number, h: number): string => {
+      const bits = ((w - 1) & 0x3fff) | (((h - 1) & 0x3fff) << 14);
+      return dataUrl("webp", [...ascii("RIFF"), 0, 0, 0, 0, ...ascii("WEBP"), ...ascii("VP8L"), 5, 0, 0, 0, 0x2f,
+        bits & 255, (bits >>> 8) & 255, (bits >>> 16) & 255, (bits >>> 24) & 255, 0, 0, 0, 0, 0]);
+    };
+    const img = (src: string): string[] => sanitizeProps("ui-img", { src, alt: "x" }).dropped;
+
+    test.each([["png", png], ["jpeg", jpeg], ["webp VP8X", webpX], ["webp VP8L", webpL]])(
+      "%s: accepts a small image and rejects one whose header declares too many pixels",
+      (_type, make) => {
+        expect(img(make(64, 64))).toEqual([]);
+        expect(img(make(1024, 1024))).toEqual([]);
+        expect(img(make(1025, 1024))).toEqual(["src"]);
+        expect(img(make(2049, 16))).toEqual(["src"]);
+        expect(img(make(3000, 3000))).toEqual(["src"]);
+      },
+    );
+
+    test("rejects an empty size, a header that does not match its type, and oversized or malformed data", () => {
+      expect(img(png(0, 10))).toEqual(["src"]);
+      expect(img(png(64, 64).replace("image/png", "image/gif"))).toEqual(["src"]);
+      expect(img("data:image/png;base64," + "A".repeat(100))).toEqual(["src"]);
+      expect(img("data:image/png;base64," + "A".repeat(DATA_IMAGE_MAX_CHARS))).toEqual(["src"]);
+      expect(img("data:image/png;base64,iVBORw0KGgo")).toEqual(["src"]);
+      expect(img("data:image/svg+xml;base64,PHN2Zz4=")).toEqual(["src"]);
+      // GIF frames carry their own sizes, so a GIF is never accepted as a data: URL.
+      expect(img(gif(1, 1))).toEqual(["src"]);
+    });
+  });
+
+  test.each([
+    ["ui-progress", { label: "Upload" }, "value", [0, 42.5, 100], [-1, 100.5, Number.NaN, Number.POSITIVE_INFINITY]],
+    ["ui-img", { src: "https://cdn.acme.com/a.png", alt: "A" }, "width", [1, 640, 4096], [0, -5, 12.5, 4097]],
+    ["ui-img", { src: "https://cdn.acme.com/a.png", alt: "A" }, "height", [1, 480, 4096], [0, -5, 0.5, 4097]],
+    ["ui-text-field", { label: "Name" }, "maxLength", [1, 10000], [0, -1, 2.5, 10001]],
+    ["ui-text-area", { label: "Notes" }, "rows", [1, 50], [0, -3, 1.5, 51]],
+    ["ui-text-area", { label: "Notes" }, "maxLength", [1, 50000], [0, 3.5, 50001]],
+  ] as const)("%s %s: bounded numeric prop %s", (tag, base, prop, good, bad) => {
+    for (const v of good) expect(sanitizeProps(tag, { ...base, [prop]: v }).dropped).toEqual([]);
+    for (const v of bad) {
+      const result = sanitizeProps(tag, { ...base, [prop]: v });
+      expect(result.props[prop]).toBeUndefined();
+    }
+  });
+
+  test("the catalog JSON carries numeric bounds", () => {
+    const img = componentsCatalogJson().find((c) => c.tagName === "ui-img");
+    expect(img?.props["width"]).toEqual({ type: "number", required: false, integer: true, minimum: 1, maximum: 4096 });
+    const progress = componentsCatalogJson().find((c) => c.tagName === "ui-progress");
+    expect(progress?.props["value"]).toEqual({ type: "number", required: true, minimum: 0, maximum: 100 });
+  });
+
+  test("bootstrap init carries the protocol version the context declares (compile-time)", () => {
+    const bundle = { url: "https://cdn.acme.com/app.js", integrity: "sha384-" + "A".repeat(64) };
+    const ok: HostToBootstrap = { kind: "init", protocolVersion: 1, appId: 1, bundle };
+    // @ts-expect-error: only the current PROTOCOL_VERSION is a valid init version.
+    const unsupported: HostToBootstrap = { kind: "init", protocolVersion: 2, appId: 1, bundle };
+    expect([ok, unsupported]).toHaveLength(2);
+  });
+
+  test.each([
+    ["2026-09-23", true],
+    ["2024-02-29", true],
+    ["0001-01-01", true],
+    ["2026-02-29", false],
+    ["2026-02-31", false],
+    ["2026-13-01", false],
+    ["2026-00-10", false],
+    ["2026-9-23", false],
+    ["not-a-date", false],
+    ["2026-09-23T00:00:00Z", false],
+  ])("DateField dates must exist: %s -> %s", (date, ok) => {
+    expect(isCalendarDate(date)).toBe(ok);
+    for (const prop of ["value", "defaultValue", "min", "max"]) {
+      const dropped = sanitizeProps("ui-date-field", { label: "Due", [prop]: date }).dropped;
+      expect(dropped).toEqual(ok ? [] : [prop]);
+    }
+  });
+
+  test("the catalog JSON marks DateField props as dates", () => {
+    const field = componentsCatalogJson().find((c) => c.tagName === "ui-date-field");
+    expect(field?.props["value"]).toEqual({ type: "string", required: false, maxLength: 10, format: "date" });
+  });
+
+  test("Button and Link accept an accessibilityLabel for icon-only content", () => {
+    for (const tag of ["ui-button", "ui-link"]) {
+      expect(sanitizeProps(tag, { accessibilityLabel: "Refresh" }).props).toEqual({ accessibilityLabel: "Refresh" });
+      expect(sanitizeProps(tag, { accessibilityLabel: "x".repeat(201) }).dropped).toEqual(["accessibilityLabel"]);
+    }
+  });
+
+  test("external links and close-confirmation text must be visible", () => {
+    const link = (label: string) => sanitizeProps("ui-context-view", { title: "T", externalLink: { href: "https://acme.com/", label } }).dropped;
+    expect(link("Acme")).toEqual([]);
+    expect(link("")).toEqual(["externalLink"]);
+    expect(link("   ")).toEqual(["externalLink"]);
+    expect(link("x".repeat(101))).toEqual(["externalLink"]);
+
+    const messages = { title: "Discard?", description: "Unsaved changes will be lost.", cancelAction: "Keep editing", exitAction: "Discard" };
+    const confirm = (m: Record<string, string>) => sanitizeProps("ui-focus-view", { title: "T", confirmCloseMessages: m }).dropped;
+    expect(confirm(messages)).toEqual([]);
+    for (const key of Object.keys(messages)) {
+      expect(confirm({ ...messages, [key]: " " })).toEqual(["confirmCloseMessages"]);
+    }
+  });
+
+  test("json props are shape-checked", () => {
+    expect(sanitizeProps("ui-context-view", { title: "T", externalLink: { href: "http://x", label: "x" } }).dropped).toEqual(["externalLink"]);
+    expect(sanitizeProps("ui-context-view", { title: "T", externalLink: { href: "https://acme.com/", label: "Acme" } }).dropped).toEqual([]);
+  });
+
+  test("ComponentProps types real props and handler details (compile-time)", () => {
+    const view: ComponentProps<"ContextView", string> = { title: "x", actions: "a", children: "c" };
+    const box: ComponentProps<"Box"> = { stack: "y", gap: "small" };
+    const field: ComponentProps<"TextField"> = { label: "Email", hideLabel: true, onChange: (v: string) => v.length };
+    const check: ComponentProps<"Checkbox"> = { label: "OK", onChange: (checked: boolean) => !checked };
+    const button: ComponentProps<"Button"> = { type: "primary", onPress: () => undefined };
+    // A name that is both a data prop and a slot takes either a string or slotted content.
+    const asText: ComponentProps<"PropertyListItem", { el: true }> = { label: "Status", value: "Active" };
+    const asSlot: ComponentProps<"PropertyListItem", { el: true }> = { label: "Status", value: { el: true } };
+
+    // @ts-expect-error unknown prop on a component with no events or slots
+    const bad: ComponentProps<"Divider"> = { style: {} };
+    // @ts-expect-error label is required on form controls
+    const unlabelled: ComponentProps<"Switch"> = {};
+
+    expect([view, box, field, check, button, asText, asSlot, bad, unlabelled]).toHaveLength(9);
+  });
+
+  test("the catalog serializes to JSON", () => {
+    const json = componentsCatalogJson();
+    expect(json.find((c) => c.name === "Button")?.events).toEqual({ onPress: "press" });
+    expect(() => JSON.stringify(json)).not.toThrow();
+  });
+});
+
+describe("protocol and helpers", () => {
+  test("isBootstrapToHost accepts known envelopes only", () => {
+    expect(isBootstrapToHost({ kind: "ready" })).toBe(true);
+    expect(isBootstrapToHost({ kind: "reloaded", seq: 2 })).toBe(true);
+    expect(isBootstrapToHost({ kind: "exec", code: "x" })).toBe(false);
+    expect(isBootstrapToHost("ready")).toBe(false);
+  });
+
+  test.each([
+    { kind: "reloaded" },
+    { kind: "reloaded", seq: "2" },
+    { kind: "log" },
+    { kind: "log", level: "shout", message: "x" },
+    { kind: "build_error", diagnostics: null },
+    { kind: "build_error", diagnostics: [{ line: 3 }] },
+    { kind: "crashed" },
+    { kind: "integrity_failed", reason: 1 },
+    { kind: "thread" },
+  ])("isBootstrapToHost rejects malformed payload %j", (envelope) => {
+    expect(isBootstrapToHost(envelope)).toBe(false);
+  });
+
+  test("isBootstrapToHost accepts well-formed payloads of every kind", () => {
+    expect(isBootstrapToHost({ kind: "thread", data: null })).toBe(true);
+    expect(isBootstrapToHost({ kind: "crashed", reason: "oom" })).toBe(true);
+    expect(isBootstrapToHost({ kind: "log", level: "warn", message: "x" })).toBe(true);
+    expect(isBootstrapToHost({ kind: "build_error", diagnostics: [{ file: "a.tsx", line: 3, message: "x" }] })).toBe(true);
+  });
+
+  test("an init names exactly one code source", () => {
+    const published: HostToBootstrap = { kind: "init", protocolVersion: 1, appId: 1, bundle: { url: "https://a.b/c.js", integrity: "sha384-x" } };
+    expect(published.kind).toBe("init");
+
+    // @ts-expect-error neither bundle nor devSession
+    const neither: HostToBootstrap = { kind: "init", protocolVersion: 1, appId: 1 };
+    expect(neither).toBeDefined();
+  });
+
+  test("isRouteDescriptor rejects paths and malformed ids", () => {
+    expect(isRouteDescriptor({ type: "appSettings" })).toBe(true);
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "gs.vendor.facility.detail", objectId: 3 })).toBe(true);
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "gs.vendor.facility.detail", objectId: -1 })).toBe(false);
+    expect(isRouteDescriptor({ type: "path", path: "/admin" })).toBe(false);
+    expect(isRouteDescriptor({ type: "appSettings", envParams: { a: 1 } })).toBe(false);
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "gs.company.nope" })).toBe(false);
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "gs.company.vendor.detail", objectId: 2 ** 53 })).toBe(false);
+    // `settings` is reachable only as `appSettings`: as a surface its objectId would name another app.
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "settings", objectId: 7 })).toBe(false);
+    expect(isRouteDescriptor({ type: "surface", surfaceId: "settings" })).toBe(false);
+    expect(sanitizeProps("ui-link", { href: { type: "surface", surfaceId: "gs.company.nope" } }).dropped).toEqual(["href"]);
+  });
+
+  test("tokenNeedsRefresh fires a minute before expiry", () => {
+    expect(tokenNeedsRefresh({ expiresAt: 1_000_000 }, 1_000_000 - 61_000)).toBe(false);
+    expect(tokenNeedsRefresh({ expiresAt: 1_000_000 }, 1_000_000 - 60_000)).toBe(true);
+  });
+});
+
+describe("bundle hygiene", () => {
+  // The host renderer imports these; a value import of zod (directly or via manifest.ts or
+  // devpreview.ts) would pull zod into the host app bundle. Type-only imports are erased.
+  test.each(["surfaces.ts", "route.ts", "context.ts", "protocol.ts", "components.ts", "url.ts", "devsession.ts", "review.ts"])(
+    "%s has no value import of zod, manifest.ts or devpreview.ts",
+    (file) => {
+      const source = readFileSync(resolve(process.cwd(), "src", "apps", file), "utf8");
+      const valueImports = source.match(/^import (?!type )[^;]*from "[^"]+";/gm) ?? [];
+      for (const line of valueImports) expect(line).not.toMatch(/"(zod[^"]*|\.\/manifest\.js|\.\/devpreview\.js)"/);
+    },
+  );
+});
+
+describe("platform permissions", () => {
+  test("app_secrets.write is a platform permission a manifest can list", () => {
+    expect(isPlatformPermission("app_secrets.write")).toBe(true);
+    expect(isPlatformPermission("vendors.view")).toBe(false);
+    expect(isPlatformPermission(undefined)).toBe(false);
+    for (const { permission } of PLATFORM_PERMISSIONS) {
+      const result = validateManifest({ ...baseManifest(), permissions: [{ permission, purpose: "Store API keys." }] });
+      expect(result.ok).toBe(true);
+    }
+  });
+});
+
+describe("catalog review rules", () => {
+  test("a permission that writes, or that reads records about people, is sensitive", () => {
+    expect(isSensitivePermission("facilities.view")).toBe(false);
+    expect(isSensitivePermission("zones.search")).toBe(false);
+    expect(isSensitivePermission("facilities.edit")).toBe(true);
+    expect(isSensitivePermission("zones.add")).toBe(true);
+    expect(isSensitivePermission("zones.delete")).toBe(true);
+    expect(isSensitivePermission("app_secrets.write")).toBe(true);
+    expect(isSensitivePermission("vendors.view")).toBe(true);
+    expect(isSensitivePermission("users.view")).toBe(true);
+    // A name the rule cannot read is treated as the stricter case.
+    expect(isSensitivePermission("vendors")).toBe(true);
+    expect(isSensitivePermission(".view")).toBe(true);
+  });
+
+  test("a manifest permission may carry a justification", () => {
+    const permissions = [{ permission: "vendors.view", purpose: "Show each rep's status next to their record.", justification: "The panel is about the vendor on screen." }];
+    expect(validateManifest({ ...baseManifest(), permissions }).ok).toBe(true);
+    expect(validateManifest({ ...baseManifest(), permissions: [{ ...permissions[0], justification: "" }] }).ok).toBe(false);
+    expect(validateManifest({ ...baseManifest(), permissions: [{ ...permissions[0], justification: "x".repeat(1001) }] }).ok).toBe(false);
+    const schema = JSON.stringify(manifestJsonSchema());
+    expect(schema).toContain('"justification"');
+  });
+
+  test("a denylisted domain matches itself and names under it, and nothing else", () => {
+    expect(cspDenylistEntry("abc-def.trycloudflare.com")).toEqual({ domain: "trycloudflare.com", category: "tunnel" });
+    expect(cspDenylistEntry("TRYCLOUDFLARE.COM.")?.category).toBe("tunnel");
+    expect(cspDenylistEntry("raw.githubusercontent.com")?.category).toBe("raw_code_host");
+    expect(cspDenylistEntry("10.0.0.1.nip.io")?.category).toBe("dynamic_dns");
+    expect(cspDenylistEntry("bit.ly")?.category).toBe("url_shortener");
+    expect(cspDenylistEntry("pastebin.com")?.category).toBe("pastebin");
+    expect(cspDenylistEntry("api.acme.com")).toBeUndefined();
+    // A suffix match needs a label boundary: this is somebody else's domain.
+    expect(cspDenylistEntry("notngrok.io")).toBeUndefined();
+    expect(cspDenylistEntry("githubusercontent.com")).toBeUndefined();
+  });
+
+  test("every denylist domain is a lower-case DNS name, listed once", () => {
+    const domains = CSP_DENYLIST.map((entry) => entry.domain);
+    expect(new Set(domains).size).toBe(domains.length);
+    for (const domain of domains) expect(domain).toMatch(/^[a-z0-9-]+(\.[a-z0-9-]+)+$/);
+  });
+
+  describe("permissionReviewIssues", () => {
+    const good = "Show each rep's credential status next to their vendor record.";
+    const why = "The vendor panel is the whole app: without this it has nothing to show.";
+
+    test("checks only the permissions a submission adds", () => {
+      const permissions = [{ permission: "vendors.view", purpose: "short" }];
+      expect(permissionReviewIssues(permissions, new Set())).toEqual([]);
+      expect(permissionReviewIssues(permissions, new Set(["vendors.view"])).map((i) => i.code)).toEqual(["purpose_too_short", "justification_required"]);
+    });
+
+    test("a purpose at the minimum length passes; one character less does not", () => {
+      const min = REVIEW_RULES.purpose_min_chars;
+      const at = [{ permission: "facilities.view", purpose: "a".repeat(min) }];
+      const under = [{ permission: "facilities.view", purpose: ` ${"a".repeat(min - 1)} ` }];
+      expect(permissionReviewIssues(at, new Set(["facilities.view"]))).toEqual([]);
+      expect(permissionReviewIssues(under, new Set(["facilities.view"])).map((i) => i.code)).toEqual(["purpose_too_short"]);
+    });
+
+    test("a purpose that is only the permission's name is refused", () => {
+      for (const purpose of ["facilities.view", "Facilities", "view facilities", "  FACILITIES   VIEW  "]) {
+        const codes = permissionReviewIssues([{ permission: "facilities.view", purpose }], new Set(["facilities.view"])).map((i) => i.code);
+        expect(codes).toContain("purpose_is_permission_name");
+      }
+    });
+
+    test("a purpose repeated across entries is refused on the added one", () => {
+      const permissions = [
+        { permission: "facilities.view", purpose: good },
+        { permission: "zones.view", purpose: `${good.toUpperCase()}!` },
+      ];
+      const issues = permissionReviewIssues(permissions, new Set(["zones.view"]));
+      expect(issues).toEqual([expect.objectContaining({ code: "purpose_repeated", path: "permissions.1.purpose" })]);
+    });
+
+    test("a sensitive permission needs a justification of its own", () => {
+      const add = new Set(["vendors.edit"]);
+      expect(permissionReviewIssues([{ permission: "vendors.edit", purpose: good, justification: why }], add)).toEqual([]);
+      expect(permissionReviewIssues([{ permission: "vendors.edit", purpose: good }], add).map((i) => i.code)).toEqual(["justification_required"]);
+      expect(permissionReviewIssues([{ permission: "vendors.edit", purpose: good, justification: "   " }], add).map((i) => i.code)).toEqual(["justification_required"]);
+      expect(permissionReviewIssues([{ permission: "vendors.edit", purpose: good, justification: "Because." }], add).map((i) => i.code)).toEqual(["justification_too_short"]);
+      expect(permissionReviewIssues([{ permission: "vendors.edit", purpose: good, justification: good }], add).map((i) => i.code)).toEqual(["justification_repeats_purpose"]);
+    });
+  });
+});
+
+describe("shared/app-platform JSON", () => {
+  const files: Array<[string, unknown]> = [
+    ["manifest.schema.json", manifestJsonSchema()],
+    ["surfaces.json", SURFACES],
+    ["components.json", componentsCatalogJson()],
+    ["platform-permissions.json", PLATFORM_PERMISSIONS],
+    ["review-rules.json", REVIEW_RULES],
+    ["csp-denylist.json", CSP_DENYLIST],
+  ];
+
+  test.each(files)("%s matches the TypeScript source", (name, value) => {
+    const expected = `${JSON.stringify(value, null, 2)}\n`;
+    const url = resolve(SHARED_DIR, name);
+
+    if (process.env["UPDATE_APP_PLATFORM_JSON"] === "1") writeFileSync(url, expected);
+
+    expect(readFileSync(url, "utf8")).toBe(expected);
+  });
+});
+
+describe("mergeDevManifest with a versionless base", () => {
+  test("refuses to preview views on a v1 base, which has no version for the extension context", () => {
+    const base = { ...baseManifest() } as Record<string, unknown>;
+    delete base["version"];
+    delete base["ui_extensions"];
+    const dev = { extends: "green-app.json", ui_extensions: { views: [{ viewport: "gs.company.vendor.detail", component: "A" }] } };
+    expect(() => mergeDevManifest(base as AppManifestV2, dev as Parameters<typeof mergeDevManifest>[1])).toThrow(DevManifestError);
+
+    const versioned = { ...base, version: "1.0.0" };
+    expect(() => mergeDevManifest(versioned as AppManifestV2, dev as Parameters<typeof mergeDevManifest>[1])).not.toThrow();
+  });
+});