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

package/dist/esm/__tests__/apps/contract.test.js

@@ -0,0 +1,1032 @@
+/*
+ * 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, CHART_DATA_LIMITS, CHART_THEMES, COMPONENTS, componentsCatalogJson, CSP_DENYLIST, cspDenylistEntry, DATA_IMAGE_MAX_CHARS, DEV_SIGNATURE_ALGORITHM, DevManifestError, effectivePostInstallAction, devManifestSchema, getComponentByTag, getSurface, isBootstrapToHost, isCalendarDate, isChartData, isPieChartData, CHART_OTHER_LABEL, MAX_CHART_VALUE, isComboChartData, isPlatformPermission, isRouteDescriptor, isSensitivePermission, isSeriesChartData, isSurfaceId, manifestJsonSchema, MAX_CHART_SERIES, mergeDevManifest, permissionReviewIssues, PLATFORM_PERMISSIONS, REVIEW_RULES, SAFE_INTEGER_STRING_PATTERN, sanitizeProps, SURFACES, surfacesForPortal, tokenNeedsRefresh, validateManifest, } 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() {
+    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) {
+    const m = baseManifest();
+    const ui = m["ui_extensions"];
+    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.portal === null)
+                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");
+        expect(getSurface("page")?.route).toBe("/[portal]/apps/[appId]/pages/[...path]");
+    });
+    test("the only portal-less surfaces are the app's own settings page and pages", () => {
+        expect(SURFACES.filter((s) => s.portal === null).map((s) => s.id).sort()).toEqual(["page", "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"];
+        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"];
+        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)).toBeNull();
+        const settingsOnly = baseManifest();
+        delete settingsOnly["post_install_action"];
+        const ui = settingsOnly["ui_extensions"];
+        ui.views = ui.views.filter((v) => v.viewport === "settings");
+        expect(effectivePostInstallAction(settingsOnly)).toEqual({ type: "app_settings_view" });
+        const withMain = baseManifest();
+        delete withMain["post_install_action"];
+        expect(effectivePostInstallAction(withMain)).toEqual({ type: "app_main_view" });
+        const explicit = { ...baseManifest(), post_install_action: { type: "url", url: "https://acme.com/gs/connect" } };
+        expect(effectivePostInstallAction(explicit)).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);
+            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) => 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"].views = [{ viewport: "gs.company.nope", component: "X" }];
+        expect(validateManifest(unknown).ok).toBe(false);
+        const dup = baseManifest();
+        dup["ui_extensions"].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"]["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"].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"].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"].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"].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, kind) => `https://${kind}${i}.acme.com/` + "p".repeat(100) + "/";
+        const m = baseManifest();
+        m["ui_extensions"]["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"],
+                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 = 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, SettingsView and PageView are roots", () => {
+        const roots = Object.entries(COMPONENTS).filter(([, c]) => "root" in c).map(([name]) => name);
+        expect(roots.sort()).toEqual(["ContextView", "PageView", "SettingsView"]);
+    });
+    test("PageView takes a required title, a description and the actions and banner slots", () => {
+        expect(COMPONENTS.PageView.tagName).toBe("ui-page-view");
+        expect(COMPONENTS.PageView.slots).toEqual(["actions", "banner"]);
+        expect(sanitizeProps("ui-page-view", { title: "Reports", description: "All of them" }).props).toEqual({ title: "Reports", description: "All of them" });
+        expect(sanitizeProps("ui-page-view", { title: "t".repeat(101) }).dropped).toEqual(["title"]);
+        expect(sanitizeProps("ui-page-view", { title: "Reports", description: "d".repeat(301) }).dropped).toEqual(["description"]);
+        expect(componentsCatalogJson().find((c) => c.name === "PageView")).toMatchObject({ tagName: "ui-page-view", root: true });
+    });
+    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, bytes) => `data:image/${type};base64,${Buffer.from(bytes).toString("base64")}`;
+        const be32 = (n) => [(n >>> 24) & 255, (n >>> 16) & 255, (n >>> 8) & 255, n & 255];
+        const le16 = (n) => [n & 255, (n >>> 8) & 255];
+        const le24 = (n) => [n & 255, (n >>> 8) & 255, (n >>> 16) & 255];
+        const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
+        const png = (w, h) => 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, h) => dataUrl("gif", [...ascii("GIF89a"), ...le16(w), ...le16(h), 0, 0, 0]);
+        const jpeg = (w, h) => 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, h) => 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, h) => {
+            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) => 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]],
+    ])("%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 = { kind: "init", protocolVersion: 1, appId: 1, bundle };
+        // @ts-expect-error: only the current PROTOCOL_VERSION is a valid init version.
+        const unsupported = { 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) => 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) => 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 = { title: "x", actions: "a", children: "c" };
+        const box = { stack: "y", gap: "small" };
+        const field = { label: "Email", hideLabel: true, onChange: (v) => v.length };
+        const check = { label: "OK", onChange: (checked) => !checked };
+        const 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 = { label: "Status", value: "Active" };
+        const asSlot = { label: "Status", value: { el: true } };
+        // @ts-expect-error unknown prop on a component with no events or slots
+        const bad = { style: {} };
+        // @ts-expect-error label is required on form controls
+        const unlabelled = {};
+        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("charts", () => {
+    const CHART_TAGS = {
+        BarChart: "ui-bar-chart",
+        HorizontalBarChart: "ui-horizontal-bar-chart",
+        StackedBarChart: "ui-stacked-bar-chart",
+        LineChart: "ui-line-chart",
+        AreaChart: "ui-area-chart",
+        ComboChart: "ui-combo-chart",
+        PieChart: "ui-pie-chart",
+    };
+    const labels = (n) => Array.from({ length: n }, (_, i) => `L${i}`);
+    const datums = (n) => labels(n).map((label, i) => ({ label, value: i }));
+    const seriesData = (nLabels, nSeries = 2) => ({
+        labels: labels(nLabels),
+        series: Array.from({ length: nSeries }, (_, s) => ({ name: `S${s}`, values: labels(nLabels).map((_, i) => i + s) })),
+    });
+    const combo = (n) => ({
+        labels: labels(n),
+        bars: { name: "Visits", values: labels(n).map((_, i) => i) },
+        line: { name: "Average", values: labels(n).map((_, i) => i / 2) },
+    });
+    const BAD_VALUES = [-1, Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY, "3", null];
+    const BAD_LABELS = ["", "   ", "x".repeat(61), 5, null];
+    class Datum {
+        constructor(label, value) {
+            this.label = label;
+            this.value = value;
+        }
+    }
+    class DatumArray extends Array {
+    }
+    test("seven chart entries with the same data-only props, a click event and no children", () => {
+        for (const [name, tag] of Object.entries(CHART_TAGS)) {
+            const c = COMPONENTS[name];
+            expect(c.tagName, name).toBe(tag);
+            expect(Object.keys(c.props).sort(), name).toEqual(["data", "interactive", "theme"]);
+            expect(c.events, name).toEqual({ onClick: { event: "click" } });
+            expect(c.children, name).toEqual([]);
+            expect(c.text, name).toBe(false);
+            expect(c.slots, name).toEqual([]);
+            const json = componentsCatalogJson().find((j) => j.name === name);
+            expect(json.props["data"]).toEqual({ type: "json", required: true });
+            expect(json.props["theme"]).toEqual({ type: "enum", required: false, values: ["green", "grayscale", "vibrant"] });
+            expect(json.events).toEqual({ onClick: "click" });
+        }
+        expect(CHART_THEMES).toEqual(["green", "grayscale", "vibrant"]);
+        expect(MAX_CHART_SERIES).toBe(6);
+    });
+    test("sanitizeProps requires data, checks theme and drops styling props", () => {
+        expect(sanitizeProps("ui-bar-chart", { theme: "green" }).missing).toEqual(["data"]);
+        const result = sanitizeProps("ui-bar-chart", { data: datums(3), theme: "neon", interactive: true, color: "#f00", style: {} });
+        expect(result.props).toEqual({ data: datums(3), interactive: true });
+        expect(result.dropped.sort()).toEqual(["color", "style", "theme"]);
+        expect(result.missing).toEqual([]);
+        const bad = sanitizeProps("ui-line-chart", { data: seriesData(1) });
+        expect(bad.dropped).toEqual(["data"]);
+        expect(bad.missing).toEqual(["data"]);
+    });
+    describe("chart value bounds", () => {
+        test("accepts values up to MAX_CHART_VALUE and rejects larger ones", () => {
+            const bar = CHART_DATA_LIMITS.BarChart;
+            expect(isChartData([{ label: "a", value: MAX_CHART_VALUE }], bar)).toBe(true);
+            for (const value of [MAX_CHART_VALUE + 2, 1e308, Number.MAX_VALUE]) {
+                expect(isChartData([{ label: "a", value }], bar)).toBe(false);
+            }
+        });
+        test("keeps every accepted total finite", () => {
+            const pie = Array.from({ length: 50 }, (_, i) => ({ label: `s${i}`, value: MAX_CHART_VALUE }));
+            expect(isPieChartData(pie)).toBe(true);
+            expect(Number.isFinite(pie.reduce((sum, d) => sum + d.value, 0))).toBe(true);
+            const limits = CHART_DATA_LIMITS.StackedBarChart;
+            const series = Array.from({ length: 6 }, (_, i) => ({ name: `s${i}`, values: [MAX_CHART_VALUE] }));
+            expect(isSeriesChartData({ labels: ["a"], series }, limits)).toBe(true);
+            const huge = [{ name: "x", values: [1e308] }, { name: "y", values: [1e308] }];
+            expect(isSeriesChartData({ labels: ["a"], series: huge }, limits)).toBe(false);
+        });
+    });
+    describe("isPieChartData", () => {
+        const datums = (n, first) => Array.from({ length: n }, (_, i) => ({ label: i === 0 && first !== undefined ? first : `s${i}`, value: i + 1 }));
+        test("allows an Other label when the pie will not combine slices", () => {
+            expect(isPieChartData(datums(6, CHART_OTHER_LABEL))).toBe(true);
+        });
+        test("rejects a caller Other label when extra items will be combined into Other", () => {
+            for (const label of [CHART_OTHER_LABEL, "other", " OTHER "])
+                expect(isPieChartData(datums(7, label))).toBe(false);
+            expect(isPieChartData(datums(7, "Other documents"))).toBe(true);
+        });
+        test("keeps the generic pie limits", () => {
+            expect(isPieChartData(datums(50))).toBe(true);
+            expect(isPieChartData(datums(51))).toBe(false);
+            expect(isPieChartData([])).toBe(false);
+        });
+        test("is the guard the PieChart catalog entry uses", () => {
+            expect(sanitizeProps("ui-pie-chart", { data: datums(7, "Other") }).missing).toContain("data");
+            expect(sanitizeProps("ui-pie-chart", { data: datums(7) }).missing).not.toContain("data");
+        });
+    });
+    describe("isChartData", () => {
+        const bar = CHART_DATA_LIMITS.BarChart;
+        test("accepts a valid sample, including zero values and 60-character labels", () => {
+            expect(isChartData([{ label: "Mon", value: 0 }, { label: "x".repeat(60), value: 12.5 }], bar)).toBe(true);
+        });
+        test.each(BAD_VALUES)("rejects value %s", (value) => {
+            expect(isChartData([{ label: "a", value }], bar)).toBe(false);
+        });
+        test.each(BAD_LABELS)("rejects label %j", (label) => {
+            expect(isChartData([{ label, value: 1 }], bar)).toBe(false);
+        });
+        test("rejects duplicate labels", () => {
+            expect(isChartData([{ label: "a", value: 1 }, { label: "a", value: 2 }], bar)).toBe(false);
+        });
+        test("enforces each component's item counts", () => {
+            expect(isChartData([], bar)).toBe(false);
+            expect(isChartData(datums(31), bar)).toBe(true);
+            expect(isChartData(datums(32), bar)).toBe(false);
+            expect(isChartData(datums(25), CHART_DATA_LIMITS.HorizontalBarChart)).toBe(true);
+            expect(isChartData(datums(26), CHART_DATA_LIMITS.HorizontalBarChart)).toBe(false);
+            expect(isChartData(datums(50), CHART_DATA_LIMITS.PieChart)).toBe(true);
+            expect(isChartData(datums(51), CHART_DATA_LIMITS.PieChart)).toBe(false);
+            expect(sanitizeProps("ui-bar-chart", { data: datums(32) }).dropped).toEqual(["data"]);
+            expect(sanitizeProps("ui-pie-chart", { data: datums(32) }).dropped).toEqual([]);
+        });
+        test("rejects non-arrays, class instances, sparse arrays and extra keys", () => {
+            for (const v of [undefined, null, "a", 1, { label: "a", value: 1 }, new Map()])
+                expect(isChartData(v, bar)).toBe(false);
+            expect(isChartData([new Datum("a", 1)], bar)).toBe(false);
+            expect(isChartData(DatumArray.from([{ label: "a", value: 1 }]), bar)).toBe(false);
+            // eslint-disable-next-line no-sparse-arrays
+            expect(isChartData([{ label: "a", value: 1 }, , { label: "b", value: 2 }], bar)).toBe(false);
+            expect(isChartData([{ label: "a", value: 1, color: "red" }], bar)).toBe(false);
+            expect(isChartData([Object.assign(Object.create(null), { label: "a", value: 1 })], bar)).toBe(true);
+        });
+    });
+    describe("isSeriesChartData", () => {
+        const stacked = CHART_DATA_LIMITS.StackedBarChart;
+        const line = CHART_DATA_LIMITS.LineChart;
+        test("accepts a valid sample", () => {
+            expect(isSeriesChartData(seriesData(5, 3), stacked)).toBe(true);
+            expect(isSeriesChartData(seriesData(5, MAX_CHART_SERIES), line)).toBe(true);
+        });
+        test("rejects more than six series, and no series", () => {
+            expect(isSeriesChartData(seriesData(5, MAX_CHART_SERIES + 1), stacked)).toBe(false);
+            expect(isSeriesChartData(seriesData(5, MAX_CHART_SERIES + 1), line)).toBe(false);
+            expect(isSeriesChartData(seriesData(5, 0), stacked)).toBe(false);
+        });
+        test("rejects a series whose values length differs from the labels", () => {
+            const d = seriesData(4);
+            d.series[1].values.pop();
+            expect(isSeriesChartData(d, stacked)).toBe(false);
+            d.series[1].values.push(1, 2);
+            expect(isSeriesChartData(d, stacked)).toBe(false);
+        });
+        test.each(BAD_VALUES)("rejects value %s", (value) => {
+            const d = seriesData(3);
+            d.series[0].values[1] = value;
+            expect(isSeriesChartData(d, stacked)).toBe(false);
+        });
+        test.each(BAD_LABELS)("rejects label or series name %j", (bad) => {
+            const withLabel = seriesData(3);
+            withLabel.labels[0] = bad;
+            expect(isSeriesChartData(withLabel, stacked)).toBe(false);
+            const withName = seriesData(3);
+            withName.series[0].name = bad;
+            expect(isSeriesChartData(withName, stacked)).toBe(false);
+        });
+        test("rejects duplicate labels and duplicate series names", () => {
+            const dupLabel = seriesData(3);
+            dupLabel.labels[2] = dupLabel.labels[0];
+            expect(isSeriesChartData(dupLabel, stacked)).toBe(false);
+            const dupName = seriesData(3);
+            dupName.series[1].name = dupName.series[0].name;
+            expect(isSeriesChartData(dupName, stacked)).toBe(false);
+        });
+        test("enforces each component's label counts", () => {
+            expect(isSeriesChartData(seriesData(1), stacked)).toBe(true);
+            expect(isSeriesChartData(seriesData(31), stacked)).toBe(true);
+            expect(isSeriesChartData(seriesData(32), stacked)).toBe(false);
+            expect(isSeriesChartData(seriesData(1), line)).toBe(false);
+            expect(isSeriesChartData(seriesData(60), line)).toBe(true);
+            expect(isSeriesChartData(seriesData(61), line)).toBe(false);
+            expect(isSeriesChartData(seriesData(61), CHART_DATA_LIMITS.AreaChart)).toBe(false);
+            expect(isSeriesChartData(seriesData(1), CHART_DATA_LIMITS.AreaChart)).toBe(false);
+        });
+        test("rejects non-objects, class instances and extra keys", () => {
+            for (const v of [undefined, null, [], "x", datums(3)])
+                expect(isSeriesChartData(v, stacked)).toBe(false);
+            const d = seriesData(2);
+            expect(isSeriesChartData({ labels: d.labels, series: DatumArray.from(d.series) }, stacked)).toBe(false);
+            expect(isSeriesChartData({ ...d, labels: DatumArray.from(d.labels) }, stacked)).toBe(false);
+            expect(isSeriesChartData(Object.assign(new (class Data {
+            })(), d), stacked)).toBe(false);
+            expect(isSeriesChartData({ ...d, title: "x" }, stacked)).toBe(false);
+            expect(isSeriesChartData({ ...d, series: [{ ...d.series[0], color: "red" }] }, stacked)).toBe(false);
+        });
+    });
+    describe("isComboChartData", () => {
+        const limits = CHART_DATA_LIMITS.ComboChart;
+        test("accepts a valid sample", () => {
+            expect(isComboChartData(combo(1), limits)).toBe(true);
+            expect(isComboChartData(combo(31), limits)).toBe(true);
+        });
+        test("rejects over-cap and empty labels", () => {
+            expect(isComboChartData(combo(32), limits)).toBe(false);
+            expect(isComboChartData(combo(0), limits)).toBe(false);
+        });
+        test("rejects bars or line values whose length differs from the labels", () => {
+            const bars = combo(3);
+            bars.bars.values.pop();
+            expect(isComboChartData(bars, limits)).toBe(false);
+            const line = combo(3);
+            line.line.values.push(1);
+            expect(isComboChartData(line, limits)).toBe(false);
+        });
+        test.each(BAD_VALUES)("rejects value %s", (value) => {
+            for (const key of ["bars", "line"]) {
+                const d = combo(3);
+                d[key].values[0] = value;
+                expect(isComboChartData(d, limits)).toBe(false);
+            }
+        });
+        test.each(BAD_LABELS)("rejects label or series name %j", (bad) => {
+            const withLabel = combo(3);
+            withLabel.labels[1] = bad;
+            expect(isComboChartData(withLabel, limits)).toBe(false);
+            const withName = combo(3);
+            withName.line.name = bad;
+            expect(isComboChartData(withName, limits)).toBe(false);
+        });
+        test("rejects duplicate labels and a line named like the bars", () => {
+            const dupLabel = combo(3);
+            dupLabel.labels[1] = dupLabel.labels[0];
+            expect(isComboChartData(dupLabel, limits)).toBe(false);
+            const dupName = combo(3);
+            dupName.line.name = dupName.bars.name;
+            expect(isComboChartData(dupName, limits)).toBe(false);
+        });
+        test("rejects non-objects, class instances, series arrays and extra keys", () => {
+            for (const v of [undefined, null, [], "x", seriesData(3)])
+                expect(isComboChartData(v, limits)).toBe(false);
+            const d = combo(2);
+            expect(isComboChartData({ ...d, bars: [d.bars] }, limits)).toBe(false);
+            expect(isComboChartData({ ...d, labels: DatumArray.from(d.labels) }, limits)).toBe(false);
+            expect(isComboChartData(Object.assign(new (class Data {
+            })(), d), limits)).toBe(false);
+            expect(isComboChartData({ ...d, extra: 1 }, limits)).toBe(false);
+        });
+    });
+    test("ComponentProps types chart data and the click detail (compile-time)", () => {
+        const bar = {
+            data: [{ label: "Mon", value: 3 }],
+            theme: "vibrant",
+            interactive: true,
+            onClick: (e) => e.index + e.value + e.label.length,
+        };
+        const comboProps = {
+            data: combo(2),
+            onClick: (e) => e.series ?? e.label,
+        };
+        const stacked = { data: seriesData(2) };
+        // @ts-expect-error data is required
+        const noData = { theme: "green" };
+        // @ts-expect-error a bar chart takes ChartDatum[], not series data
+        const wrongShape = { data: seriesData(2) };
+        // @ts-expect-error themes are a closed set
+        const neon = { data: datums(2), theme: "neon" };
+        // @ts-expect-error there are no colour props
+        const colored = { data: seriesData(2), colors: ["#f00"] };
+        // @ts-expect-error onClick receives a ChartClickEvent, not a string
+        const wrongDetail = { data: combo(2), onClick: (s) => s.length };
+        expect([bar, comboProps, stacked, noData, wrongShape, neon, colored, wrongDetail]).toHaveLength(8);
+    });
+});
+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 = { 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 = { 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: 1000000 }, 1000000 - 61000)).toBe(false);
+        expect(tokenNeedsRefresh({ expiresAt: 1000000 }, 1000000 - 60000)).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", "routes.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 = [
+        ["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() };
+        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, dev)).toThrow(DevManifestError);
+        const versioned = { ...base, version: "1.0.0" };
+        expect(() => mergeDevManifest(versioned, dev)).not.toThrow();
+    });
+});
+//# sourceMappingURL=contract.test.js.map