@wenathlan/devthink 2.0.12 → 2.0.14

package/tests/runtimeadapters.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "vitest";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  adapterdeclarationsof,
+  capabilityprobeof,
+  chromestorageadapter,
+  denokvadapter,
+  dommapof,
+  downgradesof,
+  fetchshellof,
+  filesystemstorageadapter,
+  memorystorageadapter,
+  portablecapabilityset,
+  runtimeadapterdeclarationof,
+  runtimeadapterof,
+  runtimecapabilitiestable,
+  timershellof,
+  workermapof,
+} from "../runtime.js";
+import { actionkindcatalog, actionrisk, adaptermappinggate, capabilitydowngradegate } from "../policy.js";
+import { sessionmemory } from "../memory.js";
+import type { capabilityprobe } from "../types.js";
+
+const now = 1_800_000_000_000;
+
+describe("capability probes", () => {
+  it("probes the dom, storage, network and worker capabilities of one runtime without failing anything", () => {
+    expect(capabilityprobeof({ dom: true, storage: true, network: true, worker: true })).toEqual({
+      dom: true,
+      storage: true,
+      network: true,
+      worker: true,
+    });
+    const table = runtimecapabilitiestable();
+    expect(table.browser).toEqual({ dom: true, storage: true, network: true, worker: true });
+    expect(table.node.dom).toBe(false);
+    expect(table.bun.storage).toBe(true);
+    expect(table.deno.worker).toBe(true);
+  });
+
+  it("declares the adapter mapping of every platform target", () => {
+    expect(runtimeadapterdeclarationof("browser")).toMatchObject({
+      runtime: "browser",
+      storage: "chrome",
+      worker: "webworker",
+      dom: "livepage",
+    });
+    expect(runtimeadapterdeclarationof("browser", true).dom).toBe("remote");
+    expect(runtimeadapterdeclarationof("node")).toMatchObject({
+      storage: "filesystem",
+      worker: "workerthreads",
+      dom: "remote",
+    });
+    expect(runtimeadapterdeclarationof("bun").storage).toBe("filesystem");
+    expect(runtimeadapterdeclarationof("deno")).toMatchObject({
+      storage: "denokv",
+      worker: "webworker",
+      dom: "remote",
+    });
+    expect(adapterdeclarationsof()).toHaveLength(4);
+    expect(workermapof("node")).toBe("workerthreads");
+    expect(workermapof("deno")).toBe("webworker");
+    expect(dommapof("browser")).toBe("livepage");
+    expect(dommapof("headless")).toBe("remote");
+  });
+
+  it("gates the adapter mapping against its platform target", () => {
+    for (const runtime of ["browser", "node", "bun", "deno"] as const) {
+      expect(adaptermappinggate({ adapter: runtimeadapterdeclarationof(runtime) }).allowed).toBe(true);
+      expect(
+        adaptermappinggate({
+          adapter: runtimeadapterdeclarationof(runtime, runtime === "browser"),
+          headless: runtime === "browser",
+        }).allowed,
+      ).toBe(true);
+    }
+    expect(adaptermappinggate({ adapter: { ...runtimeadapterdeclarationof("node"), storage: "chrome" } }).allowed).toBe(
+      false,
+    );
+    expect(
+      adaptermappinggate({ adapter: { ...runtimeadapterdeclarationof("deno"), storage: "filesystem" } }).allowed,
+    ).toBe(false);
+    expect(
+      adaptermappinggate({ adapter: { ...runtimeadapterdeclarationof("bun"), worker: "webworker" } }).allowed,
+    ).toBe(false);
+    expect(
+      adaptermappinggate({ adapter: { ...runtimeadapterdeclarationof("browser"), dom: "remote" }, headless: false })
+        .allowed,
+    ).toBe(false);
+    expect(
+      adaptermappinggate({ adapter: { ...runtimeadapterdeclarationof("node"), fetch: "shim" as never } }).allowed,
+    ).toBe(false);
+  });
+
+  it("downgrades features instead of failing the runtime", () => {
+    const probes = capabilityprobeof({ dom: false, storage: true, network: true, worker: true });
+    const downgrades = downgradesof({
+      features: [
+        { feature: "page capture", capability: "dom" },
+        { feature: "profile store", capability: "storage" },
+      ],
+      probes,
+    });
+    expect(downgrades).toHaveLength(1);
+    expect(downgrades[0]).toMatchObject({ feature: "page capture", capability: "dom" });
+    expect(downgrades[0]?.reason).toMatch(/downgrades instead of failing the runtime/);
+    expect(capabilitydowngradegate({ downgraded: downgrades, failed: [] }).allowed).toBe(true);
+    expect(capabilitydowngradegate({ downgraded: [], failed: ["dom"] }).allowed).toBe(false);
+    expect(capabilitydowngradegate({ downgraded: [], failed: [] }).reason).toMatch(/no feature downgrades/);
+  });
+
+  it("derives the portable capability set from the probes and the reviewed vocabulary", () => {
+    const vocabulary = actionkindcatalog();
+    expect(vocabulary).toContain("observe");
+    expect(vocabulary).toContain("click");
+    const domprobes = capabilityprobeof({ dom: true, storage: true, network: true, worker: true });
+    expect(portablecapabilityset({ vocabulary, probes: domprobes })).toEqual(vocabulary);
+    const domless = portablecapabilityset({
+      vocabulary,
+      probes: capabilityprobeof({ dom: false, storage: true, network: true, worker: true }),
+      domlesskinds: vocabulary.filter((kind) => {
+        try {
+          return actionrisk(kind as never) === "read";
+        } catch {
+          return false;
+        }
+      }),
+    });
+    expect(domless).not.toContain("click");
+    expect(domless).toContain("readtext");
+    expect(
+      portablecapabilityset({
+        vocabulary,
+        probes: { dom: false, storage: true, network: true, worker: true } as capabilityprobe,
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("runtime shells", () => {
+  it("maps the filesystem onto the storage seam for node and bun runtimes", async () => {
+    const base = join("tests", "artifacts", "librarymodes", "storage");
+    await rm(base, { recursive: true, force: true });
+    const adapter = filesystemstorageadapter(
+      {
+        readfile: (path) => readFile(path, "utf8"),
+        writefile: (path, data) => writeFile(path, data, "utf8"),
+        mkdir: async (path) => {
+          await mkdir(path, { recursive: true });
+        },
+        join: (...parts) => join(...parts),
+      },
+      base,
+    );
+    expect(await adapter.get("config")).toBeUndefined();
+    await adapter.set("config", { provider: "local" });
+    expect(await adapter.get("config")).toMatchObject({ provider: "local" });
+    await adapter.set("audit", [{ id: "a1" }]);
+    expect(await adapter.get<Array<{ id: string }>>("audit")).toEqual([{ id: "a1" }]);
+    await rm(base, { recursive: true, force: true });
+  });
+
+  it("maps chrome storage and deno kv onto the same seam", async () => {
+    const area = new Map<string, unknown>();
+    const chrome = chromestorageadapter({
+      get: async (key) => area.get(key),
+      set: async (key, value) => {
+        area.set(key, value);
+      },
+    });
+    await chrome.set("session", { id: "s1" });
+    expect(await chrome.get("session")).toMatchObject({ id: "s1" });
+    const kv = new Map<string, unknown>();
+    const deno = denokvadapter({
+      get: async <T>(key: string) => kv.get(key) as T | undefined,
+      set: async <T>(key: string, value: T) => {
+        kv.set(key, value);
+      },
+    });
+    await deno.set("profile", { name: "work" });
+    expect(await deno.get("profile")).toMatchObject({ name: "work" });
+    const memory = memorystorageadapter();
+    await memory.set("plan", { id: "p1" });
+    expect(await memory.get("plan")).toMatchObject({ id: "p1" });
+    const seeded = memorystorageadapter(new Map([["seeded", 7]]));
+    expect(await seeded.get("seeded")).toBe(7);
+  });
+
+  it("drives the same session memory through every adapter so the profile store format stays one", async () => {
+    const store = new Map<string, unknown>();
+    const memory = new sessionmemory(
+      chromestorageadapter({
+        get: async (key) => store.get(key),
+        set: async (key, value) => {
+          store.set(key, value);
+        },
+      }),
+    );
+    await memory.setconfig({ provider: "local" } as never);
+    const filesystem = new sessionmemory(memorystorageadapter(store));
+    expect(await filesystem.getconfig()).toMatchObject({ provider: "local" });
+  });
+
+  it("provides the timer and fetch shells from the injected platform primitives", async () => {
+    const scheduled: Array<() => void> = [];
+    const timer = timershellof({
+      settimeout: (callback) => {
+        scheduled.push(callback);
+        return scheduled.length;
+      },
+      now: () => now,
+    });
+    const handle = timer.schedule(() => "ran", 50);
+    expect(handle).toBe(1);
+    expect(timer.now()).toBe(now);
+    (scheduled[0] as () => void)();
+    const fetches: string[] = [];
+    const fetchshell = fetchshellof({
+      fetch: async (input) => {
+        fetches.push(input);
+        return { ok: true };
+      },
+    });
+    await fetchshell.fetch("https://example.org");
+    expect(fetches).toEqual(["https://example.org"]);
+  });
+
+  it("composes one runtime adapter from its declaration, probes and injected primitives", () => {
+    const store = new Map<string, unknown>();
+    const adapter = runtimeadapterof({
+      runtime: "node",
+      storage: memorystorageadapter(store),
+      timer: {
+        settimeout: (callback) => {
+          callback();
+          return 0;
+        },
+        now: () => now,
+      },
+      fetch: { fetch: async (input) => input },
+    });
+    expect(adapter.declaration).toMatchObject({ runtime: "node", storage: "filesystem" });
+    expect(adapter.probes.dom).toBe(false);
+    expect(adapter.storage).toBeDefined();
+    expect(adapter.timer?.now()).toBe(now);
+    expect(adapter.fetch).toBeDefined();
+    expect(runtimeadapterof({ runtime: "browser" }).storage).toBeUndefined();
+    expect(runtimeadapterof({ runtime: "deno" }).declaration.storage).toBe("denokv");
+  });
+});

package/tests/safariskeleton.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import {
+  safariskeletonbuild,
+  safariskeletonprojectfiles,
+  safariskeletonpopoverof,
+  safarizipfile,
+  safaricentraldirectory,
+  safariendrecord,
+} from "../crossbrowser.js";
+import type { safariskeletoninput } from "../types.js";
+
+const input: safariskeletoninput = {
+  version: "1.1.86",
+  bundleid: "com.wenathlan.devthink",
+  extensionpayload: [
+    { name: "manifest.json", bytes: new Uint8Array([0, 1, 2]) },
+    { name: "background.js", bytes: new Uint8Array([3, 4, 5]) },
+  ],
+  entitlements: ["com.apple.security.app-sandbox", "com.apple.security.network.client"],
+};
+
+describe("safariskeleton", () => {
+  it("generates the xcode project wrapper for the extension", () => {
+    const files = safariskeletonprojectfiles();
+    expect(files.length).toBeGreaterThan(0);
+    expect(files.some((file) => file.path.endsWith("project.pbxproj"))).toBe(true);
+    expect(files.some((file) => file.path.endsWith("Info.plist"))).toBe(true);
+    expect(files.some((file) => file.path.endsWith("AppDelegate.swift"))).toBe(true);
+  });
+
+  it("embeds the chromium build as the safari web extension payload", () => {
+    const output = safariskeletonbuild(input);
+    expect(output.archive.name).toBe("devthink-safari-1.1.86.zip");
+    expect(output.archive.bytes.length).toBeGreaterThan(100);
+    expect(output.projectfiles.length).toBeGreaterThan(0);
+  });
+
+  it("declares the app entitlements for extension distribution", () => {
+    const output = safariskeletonbuild(input);
+    expect(output.entitlements).toContain("com.apple.security.app-sandbox");
+    expect(output.entitlements).toContain("com.apple.security.network.client");
+    const entitlementsfile = safariskeletonprojectfiles().find((file) => file.path.endsWith(".entitlements"));
+    expect(entitlementsfile).toBeDefined();
+    expect(entitlementsfile?.text).toContain("com.apple.security.app-sandbox");
+  });
+
+  it("includes a minimal app shell that opens the extension", () => {
+    const output = safariskeletonbuild(input);
+    expect(output.appshell).toBe("Devthink/AppDelegate.swift");
+    const shell = safariskeletonprojectfiles().find((file) => file.path.endsWith("AppDelegate.swift"));
+    expect(shell?.text).toContain("SFSafariApplication");
+  });
+
+  it("renders the sidepanel surface as a popover equivalent", () => {
+    const popover = safariskeletonpopoverof();
+    expect(popover.path).toBe("sidepanel.html");
+    expect(popover.bounds.width).toBe(480);
+    expect(popover.bounds.height).toBe(720);
+  });
+
+  it("stamps the release version into the project files", () => {
+    const output = safariskeletonbuild(input);
+    const plist = output.projectfiles.find((file) => file.path.endsWith("Info.plist"));
+    expect(plist?.text).toContain("1.1.86");
+  });
+
+  it("stamps the bundle id into the project files", () => {
+    const output = safariskeletonbuild(input);
+    const plist = output.projectfiles.find((file) => file.path.endsWith("Info.plist"));
+    expect(plist?.text).toContain("com.wenathlan.devthink");
+  });
+
+  it("refuses an empty payload or an empty entitlements list", () => {
+    expect(() => safariskeletonbuild({ ...input, extensionpayload: [] })).toThrow();
+    expect(() => safariskeletonbuild({ ...input, entitlements: [] })).toThrow();
+  });
+
+  it("refuses a non semver version or an invalid bundle id", () => {
+    expect(() => safariskeletonbuild({ ...input, version: "not-a-version" })).toThrow();
+    expect(() => safariskeletonbuild({ ...input, bundleid: "" })).toThrow();
+    expect(() => safariskeletonbuild({ ...input, bundleid: "Invalid Bundle Id" })).toThrow();
+  });
+
+  it("writes the wrapper files and the payload entries as stored zip entries with readable offsets", () => {
+    const header = safarizipfile("Resources/manifest.json", Buffer.from("{}", "utf8"));
+    expect(header.readUInt32LE(0)).toBe(0x04034b50);
+    expect(header.readUInt16LE(8)).toBe(0);
+    const central = safaricentraldirectory([{ name: "Resources/manifest.json", size: 2, offset: 0 }]);
+    expect(central.bytes.readUInt32LE(0)).toBe(0x02014b50);
+    expect(central.bytes.readUInt32LE(20)).toBe(2);
+    expect(central.bytes.readUInt32LE(42)).toBe(0);
+    const end = safariendrecord(1, central.bytes.length, header.length);
+    expect(end.readUInt32LE(0)).toBe(0x06054b50);
+    expect(end.readUInt32LE(16)).toBe(header.length);
+    /* the assembled archive reads back through the standard structure: the end record points at the central directory and every central offset lands on a local file header signature */
+    const built = safariskeletonbuild({
+      version: "1.1.87",
+      bundleid: "devthink.wenathlan.safari",
+      extensionpayload: [{ name: "manifest.json", bytes: new Uint8Array([123, 125]) }],
+      entitlements: ["com.apple.security.app-sandbox"],
+    });
+    const archive = Buffer.from(built.archive.bytes);
+    const endoffset = archive.length - 22;
+    expect(archive.readUInt32LE(endoffset)).toBe(0x06054b50);
+    const centralstart = archive.readUInt32LE(endoffset + 16);
+    const entrycount = archive.readUInt16LE(endoffset + 10);
+    expect(archive.readUInt32LE(centralstart)).toBe(0x02014b50);
+    let cursor = centralstart;
+    for (let index = 0; index < entrycount; index += 1) {
+      const localoffset = archive.readUInt32LE(cursor + 42);
+      expect(archive.readUInt32LE(localoffset)).toBe(0x04034b50);
+      cursor += 46 + archive.readUInt16LE(cursor + 28);
+    }
+  });
+});

package/tests/sandboxframe.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import {
+  acceptrenderresult,
+  nonceof,
+  rendermessage,
+  renderprovenance,
+  sandboxrenderof,
+  stripscripts,
+} from "../environments.js";
+
+const now = 1_000;
+
+describe("sandbox frame", () => {
+  it("strips scripts and event handlers from untrusted markup before render", () => {
+    expect(stripscripts("<p>ok</p><script>alert(1)</script>")).toBe("<p>ok</p>");
+    expect(stripscripts('<p onclick="alert(1)">ok</p>')).toBe("<p>ok</p>");
+    expect(stripscripts("<p onclick='alert(1)'>ok</p>")).toBe("<p>ok</p>");
+    expect(stripscripts('<div ONMOUSEOVER="x()">ok</div>')).toBe("<div>ok</div>");
+    expect(stripscripts('<a href="javascript:alert(1)">link</a>')).toBe('<a href="alert(1)">link</a>');
+    expect(stripscripts('<img src="x" onerror="alert(1)" alt="a">')).toBe('<img src="x" alt="a">');
+    expect(stripscripts("<script src='https://evil.example/x.js'></script><b>bold</b>")).toBe("<b>bold</b>");
+    expect(stripscripts("<script/>")).toBe("");
+  });
+
+  it("issues a per render nonce for every sandbox render message", () => {
+    const one = nonceof("render:1:1000");
+    const two = nonceof("render:2:1000");
+    expect(one).toMatch(/^[a-z0-9]{16}$/);
+    expect(two).toMatch(/^[a-z0-9]{16}$/);
+    expect(one).not.toBe(two);
+    expect(nonceof("render:1:1000")).toBe(one);
+  });
+
+  it("builds the sandbox render descriptor with its nonce, source origin and sanitized markup", () => {
+    const render = sandboxrenderof({
+      id: "r1",
+      markup: "<p>hello</p><script>alert(1)</script>",
+      sourceorigin: "https://example.com",
+      stepid: "s1",
+      now,
+    });
+    expect(render.nonce).toMatch(/^[a-z0-9]{16}$/);
+    expect(render.markup).toBe("<p>hello</p>");
+    expect(render.sourceorigin).toBe("https://example.com");
+    expect(render.stepid).toBe("s1");
+    expect(() =>
+      sandboxrenderof({ id: "r2", markup: " ", sourceorigin: "https://example.com", stepid: "s1", now }),
+    ).toThrow(/markup/i);
+    expect(() => sandboxrenderof({ id: "r3", markup: "<p/>", sourceorigin: " ", stepid: "s1", now })).toThrow(
+      /source origin/i,
+    );
+    expect(() =>
+      sandboxrenderof({ id: "r4", markup: "<p/>", sourceorigin: "https://example.com", stepid: " ", now }),
+    ).toThrow(/step/i);
+  });
+
+  it("posts the render through the devthinksandbox channel and accepts the nonce checked answer", () => {
+    const render = sandboxrenderof({
+      id: "r1",
+      markup: "<p>hello</p>",
+      sourceorigin: "https://example.com",
+      stepid: "s1",
+      now,
+    });
+    const message = rendermessage(render);
+    expect(message).toMatchObject({
+      channel: "devthinksandbox",
+      type: "render",
+      nonce: render.nonce,
+      markup: "<p>hello</p>",
+    });
+    const accepted = acceptrenderresult({
+      renders: [render],
+      message: {
+        channel: "devthinksandbox",
+        type: "renderresult",
+        nonce: render.nonce,
+        ok: true,
+        text: "<p>hello</p> inert text",
+        summary: "The frame answered.",
+      },
+      now: now + 10,
+    });
+    expect(accepted.accepted).toBe(true);
+    expect(accepted.result?.text).toBe("hello inert text");
+    expect(accepted.result?.nonce).toBe(render.nonce);
+    expect(accepted.result?.summary).toBe("The frame answered.");
+  });
+
+  it("refuses stale, off channel, unknown nonce and replayed sandbox messages so a render result never reenters the dom outside the frame", () => {
+    const render = sandboxrenderof({
+      id: "r1",
+      markup: "<p>hello</p>",
+      sourceorigin: "https://example.com",
+      stepid: "s1",
+      now,
+    });
+    expect(
+      acceptrenderresult({
+        renders: [render],
+        message: { channel: "other", type: "renderresult", nonce: render.nonce },
+        now: now + 10,
+      }).accepted,
+    ).toBe(false);
+    expect(
+      acceptrenderresult({
+        renders: [render],
+        message: { channel: "devthinksandbox", type: "other", nonce: render.nonce },
+        now: now + 10,
+      }).accepted,
+    ).toBe(false);
+    expect(
+      acceptrenderresult({
+        renders: [render],
+        message: { channel: "devthinksandbox", type: "renderresult", nonce: "unknown000000000" },
+        now: now + 10,
+      }).reason,
+    ).toMatch(/no nonce of a known unanswered render/i);
+    const early = acceptrenderresult({
+      renders: [render],
+      message: {
+        channel: "devthinksandbox",
+        type: "renderresult",
+        nonce: render.nonce,
+        ok: true,
+        text: "early",
+        summary: "early",
+      },
+      now: now - 10,
+    });
+    expect(early.accepted).toBe(false);
+    const plain = acceptrenderresult({
+      renders: [render],
+      message: {
+        channel: "devthinksandbox",
+        type: "renderresult",
+        nonce: render.nonce,
+        ok: true,
+        text: "<b>bold</b>",
+        summary: " ",
+      },
+      now: now + 10,
+    });
+    expect(plain.result?.text).toBe("bold");
+    expect(plain.result?.summary).toMatch(/sandbox frame rendered/i);
+    const replayed = acceptrenderresult({
+      renders: plain.renders,
+      message: {
+        channel: "devthinksandbox",
+        type: "renderresult",
+        nonce: render.nonce,
+        ok: false,
+        text: "",
+        summary: "The render failed.",
+      },
+      now: now + 10,
+    });
+    expect(replayed.accepted).toBe(false);
+    expect(replayed.reason).toMatch(/replayed or already answered/i);
+    const second = sandboxrenderof({
+      id: "r2",
+      markup: "<p>hello</p>",
+      sourceorigin: "https://example.com",
+      stepid: "s2",
+      now: now + 1,
+    });
+    const failed = acceptrenderresult({
+      renders: [second],
+      message: {
+        channel: "devthinksandbox",
+        type: "renderresult",
+        nonce: second.nonce,
+        ok: false,
+        text: "",
+        summary: "The render failed.",
+      },
+      now: now + 10,
+    });
+    expect(failed.result?.ok).toBe(false);
+  });
+
+  it("records the provenance of every sandbox render with its source origin and nonce", () => {
+    const render = sandboxrenderof({
+      id: "r1",
+      markup: "<p>hello</p>",
+      sourceorigin: "https://example.com",
+      stepid: "s1",
+      now,
+    });
+    expect(renderprovenance(render)).toEqual({
+      origin: "https://example.com",
+      stepid: "s1",
+      environment: "sandboxframe",
+    });
+  });
+});

package/tests/sbom.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import {
+  sbomcomponentof,
+  sbomcoveragecheck,
+  sbominventory,
+  sbominventorytext,
+  sbomlicense,
+  sbomnameof,
+  sbomspecversion,
+} from "../pack.js";
+
+const valid = "a".repeat(64);
+
+describe("sbom", () => {
+  it("builds the cyclonedx component record of one artifact with its hash and channels", () => {
+    const component = sbomcomponentof({
+      name: "devthink1.1.87.zip",
+      size: 2048,
+      checksum: valid,
+      channels: ["github", "chromium"],
+    });
+    expect(component.type).toBe("file");
+    expect(component.name).toBe("devthink1.1.87.zip");
+    expect(component.hashes).toEqual([{ alg: "SHA-256", content: valid }]);
+    expect(component.properties).toContainEqual({ name: "devthink:channel", value: "github,chromium" });
+    expect(component.properties).toContainEqual({ name: "devthink:size", value: "2048" });
+    expect(component.size).toBe(2048);
+    expect(() => sbomcomponentof({ name: "", size: 1, checksum: valid })).toThrow();
+    expect(() => sbomcomponentof({ name: "a.zip", size: 1, checksum: "short" })).toThrow();
+  });
+
+  it("covers every artifact of the release in one cyclonedx inventory", () => {
+    const artifacts = [
+      { name: "devthink1.1.87.zip", size: 10, checksum: "a".repeat(64) },
+      { name: "devthink-vscode-1.1.87.vsix", size: 20, checksum: "b".repeat(64) },
+      { name: "devthink-firefox-1.1.87.xpi", size: 30, checksum: "c".repeat(64) },
+    ];
+    const inventory = JSON.parse(sbominventorytext({ version: "1.1.87", artifacts })) as {
+      bomformat: string;
+      specversion: string;
+      components: Array<{ name?: string; hashes?: Array<{ alg?: string; content?: string }> }>;
+      metadata: { component: { name: string; version: string; licenses: Array<{ license: { id: string } }> } };
+    };
+    const document = sbominventory({ version: "1.1.87", artifacts });
+    expect(document.bomformat).toBe("CycloneDX");
+    expect(document.specversion).toBe(sbomspecversion);
+    expect(document.specversion).toBe("1.5");
+    expect(inventory.components).toHaveLength(3);
+    const metadata = inventory.metadata;
+    expect(metadata.component?.name ?? "").toBe("devthink");
+    expect(metadata.component?.version ?? "").toBe("1.1.87");
+    expect(metadata.component.licenses[0]?.license.id ?? "").toBe(sbomlicense);
+    /* every artifact appears once with its checksum */
+    const coverage = sbomcoveragecheck({ inventory, artifacts });
+    expect(coverage.ok).toBe(true);
+    expect(coverage.missing).toEqual([]);
+  });
+
+  it("renders byte identical output for the same artifact set because no timestamp enters the document", () => {
+    const artifacts = [{ name: "devthink-site-1.1.87.zip", size: 5, checksum: "d".repeat(64) }];
+    expect(sbominventorytext({ version: "1.1.87", artifacts })).toBe(
+      sbominventorytext({ version: "1.1.87", artifacts }),
+    );
+    expect(sbominventorytext({ version: "1.1.87", artifacts })).not.toContain("timestamp");
+  });
+
+  it("refuses an empty artifact set and a duplicate artifact name", () => {
+    expect(() => sbominventory({ version: "1.1.87", artifacts: [] })).toThrow();
+    expect(() =>
+      sbominventory({
+        version: "1.1.87",
+        artifacts: [
+          { name: "a.zip", size: 1, checksum: valid },
+          { name: "a.zip", size: 1, checksum: valid },
+        ],
+      }),
+    ).toThrow();
+    expect(() =>
+      sbominventory({ version: "not-a-version", artifacts: [{ name: "a.zip", size: 1, checksum: valid }] }),
+    ).toThrow();
+  });
+
+  it("reports the artifacts the inventory misses or records with another hash", () => {
+    const inventory = JSON.parse(
+      sbominventorytext({ version: "1.1.87", artifacts: [{ name: "a.zip", size: 1, checksum: "a".repeat(64) }] }),
+    );
+    const missing = sbomcoveragecheck({
+      inventory,
+      artifacts: [
+        { name: "a.zip", checksum: "a".repeat(64) },
+        { name: "b.zip", checksum: "b".repeat(64) },
+      ],
+    });
+    expect(missing.ok).toBe(false);
+    expect(missing.missing).toEqual(["b.zip"]);
+    const mismatched = sbomcoveragecheck({ inventory, artifacts: [{ name: "a.zip", checksum: "c".repeat(64) }] });
+    expect(mismatched.ok).toBe(false);
+    expect(mismatched.missing).toEqual(["a.zip"]);
+  });
+
+  it("names the sbom asset with the release version", () => {
+    expect(sbomnameof("1.1.87")).toBe("devthink-sbom-1.1.87.json");
+    expect(() => sbomnameof("not-a-version")).toThrow();
+  });
+});