@intentius/chant 0.13.0 → 0.15.0

package/src/components/verbs/lockfile-sbom-generator.ts

@@ -0,0 +1,236 @@
+/**
+ * Hermetic lockfile/manifest-derived `SbomGenerator` (#613, epic #551 closes
+ * the "HERMETIC-generator half of #610" per #613's scope note). Pure
+ * TypeScript: reads a declared-dependency manifest already on disk (Node
+ * `package-lock.json`, JVM `pom.xml`) and emits a real SPDX/CycloneDX
+ * document via ./bom-writer.ts. No `syft`, no `docker buildx`, no
+ * `cyclonedx-maven`, no network — every package in the resulting BOM comes
+ * from parsing bytes chant already has locally.
+ *
+ * **What this backend is, and isn't.** A lockfile enumerates every declared
+ * (transitive-resolved) dependency at the versions actually installed, so
+ * the resulting SBOM is complete for **declared** dependencies — accurate
+ * package identity and version for everything npm/Maven resolved. It is
+ * **not** a container-layer scan: it cannot see OS packages baked into a base
+ * image, binaries copied in by a Dockerfile `COPY`/`RUN`, or anything not
+ * expressed as a lockfile entry. That deeper, image-layer-aware scan is
+ * `syft`'s job (or BuildKit's native `--sbom` attestation) and stays exactly
+ * where #610 already scoped it: the optional *deep* path, layered on top of
+ * (never replacing) this hermetic baseline. See
+ * docs/components/build-archive.mdx's SBOM section, updated alongside this
+ * change, for the customer-facing version of this distinction.
+ *
+ * Registered as `forDir`/`forZip`/`forJar` implementations (the artifact
+ * shapes a source-tree or packaged-but-uninspected artifact naturally maps
+ * to); `forImage` still throws `SbomGeneratorNotImplementedError` — an image
+ * SBOM needs either BuildKit's attestation or a container-layer scan, neither
+ * of which a lockfile read can substitute for, so this backend deliberately
+ * does not claim to cover it (mirrors how ./sbom-generator.ts's own
+ * `notImplementedSbomGenerator` prefers a loud, specific failure over a
+ * silently wrong answer).
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { writeBom, type BomPackage } from "./bom-writer";
+import { DEFAULT_SBOM_FORMAT } from "./sbom-generator";
+import type {
+  GenerateDirSbomInput,
+  GenerateImageSbomInput,
+  GenerateJarSbomInput,
+  GenerateZipSbomInput,
+  SbomDocument,
+  SbomGenerator,
+} from "./sbom-generator";
+import { SbomGeneratorNotImplementedError } from "./sbom-generator";
+
+// ── package-lock.json (npm, lockfile v2/v3) ─────────────────────────────────
+
+/** Shape of the subset of `package-lock.json` this parser reads (lockfile v2/v3 — npm >= 7). */
+interface NpmPackageLock {
+  name?: string;
+  version?: string;
+  /** Lockfile v2/v3: every resolved package, keyed by its node_modules path (""=root). */
+  packages?: Record<string, { name?: string; version?: string; resolved?: string; dev?: boolean; dependencies?: Record<string, string> }>;
+  /** Lockfile v1 fallback: nested `dependencies` tree keyed by package name. */
+  dependencies?: Record<string, { version?: string; resolved?: string; dev?: boolean; requires?: Record<string, string> }>;
+}
+
+/**
+ * Parse a `package-lock.json` (v1, v2, or v3) into a flat `BomPackage[]`.
+ * Prefers the v2/v3 `packages` map (flat, one entry per resolved install
+ * location) since that's what `npm` >= 7 writes; falls back to the v1
+ * `dependencies` tree for older lockfiles. De-duplicates by `name@version`
+ * so a package appearing at multiple install paths (npm's dedup/hoisting)
+ * contributes one BOM entry, matching how a real scanner reports installed
+ * packages rather than filesystem paths.
+ */
+export function parseNpmPackageLock(content: string): BomPackage[] {
+  const lock: NpmPackageLock = JSON.parse(content);
+  const seen = new Map<string, BomPackage>();
+
+  const add = (name: string, version: string | undefined, deps?: string[]) => {
+    if (!name) return;
+    const key = `${name}@${version ?? ""}`;
+    const existing = seen.get(key);
+    if (existing) {
+      if (deps?.length) existing.dependsOn = [...new Set([...(existing.dependsOn ?? []), ...deps])];
+      return;
+    }
+    seen.set(key, {
+      name,
+      version,
+      type: "npm",
+      purl: version ? `pkg:npm/${encodeURIComponent(name)}@${version}` : undefined,
+      dependsOn: deps?.length ? deps : undefined,
+    });
+  };
+
+  if (lock.packages) {
+    for (const [path, pkg] of Object.entries(lock.packages)) {
+      if (path === "") continue; // the root project itself, not a dependency
+      const name = pkg.name ?? path.replace(/^.*node_modules\//, "");
+      add(name, pkg.version, pkg.dependencies ? Object.keys(pkg.dependencies) : undefined);
+    }
+  } else if (lock.dependencies) {
+    for (const [name, pkg] of Object.entries(lock.dependencies)) {
+      add(name, pkg.version, pkg.requires ? Object.keys(pkg.requires) : undefined);
+    }
+  }
+
+  return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ── pom.xml (Maven — cheap, declared <dependencies> only) ───────────────────
+
+/**
+ * Parse the `<dependencies>` block of a `pom.xml` into a flat `BomPackage[]`.
+ * Deliberately minimal (#613 calls this out as "add JVM pom.xml if cheap"):
+ * a small tag-scoped regex walk over `<dependency>...</dependency>` blocks
+ * extracting `groupId`/`artifactId`/`version`, no XML DOM dependency, no
+ * property (`${...}`) resolution, no transitive resolution (Maven's own
+ * dependency-mediation graph isn't reproducible without invoking `mvn`,
+ * which would break the hermetic requirement). This is deliberately narrower
+ * than the npm parser above: it covers the common case (a flat, literal
+ * `<dependencies>` list) and documents its own limits rather than silently
+ * mis-resolving a `${property}` version or a `<dependencyManagement>`
+ * inheritance chain.
+ */
+export function parsePomXml(content: string): BomPackage[] {
+  const packages: BomPackage[] = [];
+  // Strip <dependencyManagement>...</dependencyManagement> first — it
+  // declares version *policy*, not necessarily artifacts actually used, and
+  // (like the real <dependencies> block) can itself contain a nested
+  // <dependencies> block, which a naive non-nesting-aware regex would match
+  // in its place. Removing it up front guarantees the subsequent
+  // <dependencies> match is the real, top-level one.
+  const withoutManagement = content.replace(/<dependencyManagement>[\s\S]*?<\/dependencyManagement>/, "");
+  const depsBlockMatch = withoutManagement.match(/<dependencies>([\s\S]*?)<\/dependencies>/);
+  if (!depsBlockMatch) return packages;
+
+  const depBlock = depsBlockMatch[1]!;
+  const depRegex = /<dependency>([\s\S]*?)<\/dependency>/g;
+  let match: RegExpExecArray | null;
+  while ((match = depRegex.exec(depBlock)) !== null) {
+    const entry = match[1]!;
+    const groupId = entry.match(/<groupId>([^<]+)<\/groupId>/)?.[1]?.trim();
+    const artifactId = entry.match(/<artifactId>([^<]+)<\/artifactId>/)?.[1]?.trim();
+    const version = entry.match(/<version>([^<]+)<\/version>/)?.[1]?.trim();
+    if (!groupId || !artifactId) continue;
+    const name = `${groupId}:${artifactId}`;
+    packages.push({
+      name,
+      version,
+      type: "maven",
+      purl: version ? `pkg:maven/${encodeURIComponent(groupId)}/${encodeURIComponent(artifactId)}@${version}` : undefined,
+    });
+  }
+  return packages.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ── hermetic SbomGenerator backend ───────────────────────────────────────────
+
+export interface LockfileSbomGeneratorOptions {
+  /** Where generated SBOM documents are written on disk, as a sibling of the scanned path (see `sbomOutputPath`). Default: alongside the scanned manifest, named `sbom.<format>.json`. */
+  outDir?: string;
+  /** Clock override for deterministic tests. */
+  now?: () => Date;
+}
+
+/** Locate the first readable lockfile/manifest under `dir` this generator knows how to parse, in preference order (npm before Maven — most chant components are Node-first). Returns `undefined` if none is found. */
+function findManifest(dir: string): { kind: "npm" | "maven"; path: string } | undefined {
+  for (const [kind, filename] of [["npm", "package-lock.json"], ["maven", "pom.xml"]] as const) {
+    const candidate = join(dir, filename);
+    try {
+      readFileSync(candidate, "utf-8");
+      return { kind, path: candidate };
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+
+/** Default on-disk path for a generated SBOM: `<dir>/sbom.<format>.json`, matching #613's `sbom.<format>.json` naming convention. */
+export function sbomOutputPath(dir: string, format: string): string {
+  return join(dir, `sbom.${format}.json`);
+}
+
+/**
+ * Build a hermetic `SbomGenerator` backed by lockfile parsing. `forDir` scans
+ * `input.path` for a known manifest (`package-lock.json`, then `pom.xml`),
+ * parses it into a `BomPackage[]`, and writes both the SBOM document (via
+ * ./bom-writer.ts) to disk and returns it as an `SbomDocument`. `forZip`/
+ * `forJar` reuse the same scan against the artifact's source directory
+ * (the directory the archive was built from is the natural place a lockfile
+ * lives — the packaged bytes themselves are not re-inspected, matching this
+ * backend's "declared deps, not a binary scan" scope). `forImage` is not
+ * implemented here: an image's dependency surface includes its base layers,
+ * which no lockfile enumerates — see this module's doc comment.
+ */
+export function createLockfileSbomGenerator(options: LockfileSbomGeneratorOptions = {}): SbomGenerator {
+  const now = options.now ?? (() => new Date());
+
+  function generateFromDir(dir: string, subjectName: string, digest?: string, format = DEFAULT_SBOM_FORMAT): SbomDocument {
+    const manifest = findManifest(dir);
+    if (!manifest) {
+      throw new Error(
+        `no supported lockfile/manifest found under "${dir}" (looked for package-lock.json, pom.xml) — ` +
+          `the hermetic lockfile SBOM backend requires a lockfile on disk; use the deep-scan path (#610) for images with no lockfile`,
+      );
+    }
+    const content = readFileSync(manifest.path, "utf-8");
+    const packages = manifest.kind === "npm" ? parseNpmPackageLock(content) : parsePomXml(content);
+    const generatorName = manifest.kind === "npm" ? "chant-lockfile-sbom/package-lock.json" : "chant-lockfile-sbom/pom.xml";
+
+    const doc = writeBom(
+      format,
+      { subjectName, subjectId: digest ?? manifest.path, packages, generator: generatorName },
+      now,
+    );
+
+    const outDir = options.outDir ?? dir;
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(sbomOutputPath(outDir, format), doc.bytes);
+
+    return { ...doc, packageCount: packages.length, generator: generatorName };
+  }
+
+  return {
+    async forImage(_input: GenerateImageSbomInput): Promise<SbomDocument> {
+      throw new SbomGeneratorNotImplementedError("forImage");
+    },
+    async forJar(input: GenerateJarSbomInput): Promise<SbomDocument> {
+      return generateFromDir(dirname(input.jarPath), input.jarPath, input.digest, input.format);
+    },
+    async forZip(input: GenerateZipSbomInput): Promise<SbomDocument> {
+      return generateFromDir(dirname(input.zipPath), input.zipPath, input.digest, input.format);
+    },
+    async forDir(input: GenerateDirSbomInput): Promise<SbomDocument> {
+      return generateFromDir(input.path, input.path, undefined, input.format);
+    },
+  };
+}
+
+/** Process-wide hermetic lockfile-backed `SbomGenerator`, ready to inject wherever ./sbom-generator.ts's `notImplementedSbomGenerator` default previously required an explicit real backend. */
+export const lockfileSbomGenerator: SbomGenerator = createLockfileSbomGenerator();

package/src/components/verbs/process-runner.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Tests `q`/`requireTool` (../process-runner.ts) plus `MockProcessRunner`
+ * itself (./__tests__/mock-process-runner.ts) — no real process spawned. The
+ * real `ProcessRunner`'s `child_process`-backed methods are exercised
+ * indirectly by every #610 backend's own tests via the mock; this file
+ * covers the shared helpers every one of those backends depends on.
+ */
+
+import { describe, expect, it } from "vitest";
+import { q, requireTool, ToolNotAvailableError } from "./process-runner";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+describe("q (shell quoting)", () => {
+  it("wraps a plain argument in single quotes", () => {
+    expect(q("hello")).toBe("'hello'");
+  });
+
+  it("escapes an embedded single quote", () => {
+    expect(q("it's")).toBe("'it'\\''s'");
+  });
+});
+
+describe("requireTool", () => {
+  it("resolves silently when the tool is available", async () => {
+    const mock = createMockProcessRunner({ tools: { syft: true } });
+    await expect(requireTool(mock.runner, "syft", "scan an artifact")).resolves.toBeUndefined();
+  });
+
+  it("throws ToolNotAvailableError with an actionable message when the tool is absent", async () => {
+    const mock = createMockProcessRunner({ tools: { syft: false } });
+    await expect(requireTool(mock.runner, "syft", "scan an artifact")).rejects.toThrow(ToolNotAvailableError);
+    await expect(requireTool(mock.runner, "syft", "scan an artifact")).rejects.toThrow(
+      /syft.*not installed.*scan an artifact/,
+    );
+  });
+});
+
+describe("MockProcessRunner", () => {
+  it("records every run() and available() call", async () => {
+    const mock = createMockProcessRunner();
+    await mock.runner.available("syft");
+    await mock.runner.run("syft dir:. -o spdx-json");
+    expect(mock.calls.map((c) => c.command)).toEqual([
+      "command -v syft",
+      "syft dir:. -o spdx-json",
+    ]);
+  });
+
+  it("defaults every tool to available unless scripted otherwise", async () => {
+    const mock = createMockProcessRunner();
+    expect(await mock.runner.available("anything")).toBe(true);
+  });
+
+  it("respects defaultAvailable: false", async () => {
+    const mock = createMockProcessRunner({ defaultAvailable: false, tools: { syft: true } });
+    expect(await mock.runner.available("syft")).toBe(true);
+    expect(await mock.runner.available("oras")).toBe(false);
+  });
+
+  it("matches a scripted response by command substring", async () => {
+    const mock = createMockProcessRunner({ responses: { "cat ": "canned-output" } });
+    const { stdout } = await mock.runner.run("cat /tmp/whatever.json");
+    expect(stdout).toBe("canned-output");
+  });
+
+  it("rejects when the command matches a scripted failure substring", async () => {
+    const mock = createMockProcessRunner({ failures: { syft: "syft: command failed" } });
+    await expect(mock.runner.run("syft dir:.")).rejects.toThrow("syft: command failed");
+  });
+
+  it("setAvailable/setResponse update behavior after construction", async () => {
+    const mock = createMockProcessRunner();
+    mock.setAvailable("oras", false);
+    expect(await mock.runner.available("oras")).toBe(false);
+    mock.setResponse("oras discover", '{"manifests":[]}');
+    const { stdout } = await mock.runner.run("oras discover --format json foo@sha256:abc");
+    expect(stdout).toBe('{"manifests":[]}');
+  });
+});

package/src/components/verbs/process-runner.ts

@@ -0,0 +1,113 @@
+/**
+ * Injectable external-process boundary for the #610 deep-scan/attach
+ * backends (`ToolSbomGenerator` in ./tool-sbom-generator.ts,
+ * `OrasReferrerLookup` in ../../lifecycle/oras-referrer-lookup.ts, and
+ * `publish-image`'s referrer-attach step in ./publish.ts). Mirrors
+ * ./cloud-executor.ts's `CloudExecutor` pattern exactly: production code gets
+ * a `RealProcessRunner` that shells out via `node:child_process`, tests get a
+ * `MockProcessRunner` (./__tests__/mock-process-runner.ts) that records calls
+ * and returns canned output — no live `syft`/`buildx`/`cyclonedx-maven`/
+ * `cdxgen`/`oras`, ever, in a test run.
+ *
+ * Kept deliberately narrower than `CloudExecutor`: every one of #610's real
+ * backends reduces to "run this external CLI, capture stdout, tell me if the
+ * tool exists" — a single `ProcessRunner` interface (`run` + `available`)
+ * covers `syft`, `docker buildx`, `cyclonedx-maven`, `cdxgen`, and `oras`
+ * alike, rather than one bespoke client per tool the way `CloudExecutor`
+ * models AWS's genuinely distinct service APIs (CloudFormation, ECS,
+ * CodeDeploy, ...).
+ */
+
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+/** One external command invocation's result. */
+export interface ProcessResult {
+  stdout: string;
+  stderr: string;
+}
+
+export interface RunOptions {
+  /** Working directory the command runs in. Defaults to the current process cwd. */
+  cwd?: string;
+  /** Max buffer size for stdout/stderr, matching ./cloud-executor.ts's `run`'s 64MB allowance (SBOM/BOM documents can be large). */
+  maxBuffer?: number;
+}
+
+/**
+ * Injectable boundary for shelling out to a deep-scan/attach CLI tool and for
+ * checking whether one is installed. A real implementation runs the command
+ * via `node:child_process`; every method here is injected so tests substitute
+ * `MockProcessRunner` (./__tests__/mock-process-runner.ts) and never invoke a
+ * real tool.
+ */
+export interface ProcessRunner {
+  /** Run a shell command, returning its stdout/stderr. Rejects (with the tool's own stderr in the error) on a non-zero exit. */
+  run(command: string, options?: RunOptions): Promise<ProcessResult>;
+  /** True if `tool` (a CLI binary name, e.g. "syft", "oras") resolves on `PATH`. Never throws — a missing tool is a normal, expected outcome the caller checks before attempting to `run` it. */
+  available(tool: string): Promise<boolean>;
+}
+
+/** Shell-quote a single argument for POSIX shells (wrap in single quotes, escaping embedded ones) — same convention as ./cloud-executor.ts's `q`. */
+export function q(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+const realProcessRunner: ProcessRunner = {
+  async run(command, options) {
+    return execAsync(command, {
+      cwd: options?.cwd,
+      maxBuffer: options?.maxBuffer ?? 64 * 1024 * 1024,
+    });
+  },
+  async available(tool) {
+    try {
+      // `command -v` is POSIX-portable (works in sh/bash/zsh) and prints
+      // nothing to stderr for a normal miss, unlike `which` on some systems.
+      await execAsync(`command -v ${q(tool)}`);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+
+/** Build a `ProcessRunner` that shells out for real via `node:child_process`. Never used in tests. */
+export function realProcessExecutor(): ProcessRunner {
+  return realProcessRunner;
+}
+
+/** Lazily-constructed process-wide default, mirroring ./cloud-executor.ts's `defaultCloudExecutor`. */
+let defaultRunner: ProcessRunner | undefined;
+
+/** The default `ProcessRunner` each real #610 backend falls back to when none is supplied. */
+export function defaultProcessRunner(): ProcessRunner {
+  if (!defaultRunner) defaultRunner = realProcessExecutor();
+  return defaultRunner;
+}
+
+/**
+ * Thrown when a #610 real backend needs a CLI tool that `ProcessRunner.available`
+ * reports as absent — the "graceful, actionable error if the tool is absent"
+ * #610 asks for, distinct from a generic `Error` so callers (and tests) can
+ * assert on it specifically, mirroring `SbomGeneratorNotImplementedError`'s
+ * role in ./sbom-generator.ts.
+ */
+export class ToolNotAvailableError extends Error {
+  constructor(
+    public readonly tool: string,
+    public readonly purpose: string,
+  ) {
+    super(`"${tool}" is not installed or not on PATH — required to ${purpose}. Install it and retry.`);
+    this.name = "ToolNotAvailableError";
+  }
+}
+
+/** Throw `ToolNotAvailableError` unless `tool` is available, per `runner.available`. Shared guard every #610 real backend calls before shelling out. */
+export async function requireTool(runner: ProcessRunner, tool: string, purpose: string): Promise<void> {
+  if (!(await runner.available(tool))) {
+    throw new ToolNotAvailableError(tool, purpose);
+  }
+}

package/src/components/verbs/reproducibility.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { defaultReproducibility } from "./reproducibility";
+
+describe("defaultReproducibility (#614)", () => {
+  it("a template (synthesized IaC) entry defaults to deterministic-synthesis, verifiable by re-synth", () => {
+    expect(defaultReproducibility("template")).toEqual({ basis: "deterministic-synthesis", verifyBy: "re-synth" });
+  });
+
+  it("an image entry defaults to best-effort, with no verification method claimed", () => {
+    expect(defaultReproducibility("image")).toEqual({ basis: "best-effort" });
+  });
+
+  it("an asset entry (jar/zip) defaults to best-effort, same as image — an externally-built artifact either way", () => {
+    expect(defaultReproducibility("asset")).toEqual({ basis: "best-effort" });
+  });
+
+  it("an sbom entry gets no reproducibility claim of its own — it describes another artifact, it isn't one", () => {
+    expect(defaultReproducibility("sbom")).toBeUndefined();
+  });
+
+  it("never gives an image the same basis claim as a template — the honest-per-artifact-type distinction #614 requires", () => {
+    expect(defaultReproducibility("image")!.basis).not.toBe(defaultReproducibility("template")!.basis);
+  });
+});

package/src/components/verbs/reproducibility.ts

@@ -0,0 +1,100 @@
+/**
+ * Per-artifact reproducibility + provenance record (#614, epic #551 follow-up
+ * to #613's BOM-doc model). Attaches to a `BuildArchiveEntry`
+ * (./build-archive.ts) alongside the BOM entries #613 already added, so every
+ * artifact in a build archive carries not just "what's in it" (the BOM) but
+ * also "can this be reproduced, and from what source."
+ *
+ * **Honesty over convenience.** A single blanket "reproducible: true/false"
+ * bit on a *component* would misrepresent a component that builds more than
+ * one artifact type — a synthesized IaC template and a container image are
+ * not equally reproducible, and collapsing them into one flag would either
+ * overstate the image's reproducibility or understate the template's. This
+ * module therefore records `basis` **per artifact entry**, never per
+ * component:
+ *
+ *  - `"deterministic-synthesis"` — chant's own synthesis produced this
+ *    artifact from declarative input (a `template`-kind entry, see
+ *    ../../build.ts). Re-running `chant build` against the same source
+ *    reproduces byte-identical output — the same content-addressing property
+ *    ./build-archive.ts's `contentDigest`/`manifestDigest` already rely on.
+ *    Verification is exactly "re-synth and compare digests," expressed here
+ *    as `verifyBy: "re-synth"`.
+ *  - `"best-effort"` — an `image`/`asset` entry built by an external tool
+ *    (`docker build`, a JVM/zip packager). Nothing here observes whether the
+ *    underlying build was actually bit-for-bit reproducible (timestamps,
+ *    build-arg ordering, and base-image drift are common, unglamorous causes
+ *    of non-determinism that chant does not control) — `"best-effort"` is
+ *    the honest default absent a real reproducible-build attestation. A
+ *    future SLSA/reproducible-build-flagged backend can upgrade this to a
+ *    stronger basis; nothing here forecloses that, it just refuses to claim
+ *    it today.
+ *
+ * **Provenance** is the companion source -> output link: which source
+ * ref/commit produced this artifact's digest. Recorded per artifact for the
+ * same reason `basis` is — two artifacts from one component build may trace
+ * to different source trees (e.g. an image built from `services/search/` vs
+ * a template synthesized from `infra/search.component.ts`), so the link
+ * belongs on the entry, not hoisted to the component.
+ */
+
+// ── reproducibility ─────────────────────────────────────────────────────────
+
+/**
+ * How an artifact's reproducibility is established. Deliberately two values,
+ * not a spectrum: chant either produced the artifact itself via deterministic
+ * synthesis (verifiable by re-running `chant build`), or it didn't (an
+ * external build tool produced it, and no attestation proves determinism).
+ * Adding a third value (e.g. a real SLSA-attested "reproducible-build") is a
+ * later, additive change — widening `basis` never requires touching every
+ * existing artifact's recorded value, since `"best-effort"` remains true of
+ * anything not upgraded.
+ */
+export type ReproducibilityBasis = "deterministic-synthesis" | "best-effort";
+
+/** How a claimed `basis` can actually be checked. Optional — a `"best-effort"` entry commonly has no verification path at all. */
+export type VerificationMethod = "re-synth";
+
+/** The reproducibility record for one build-archive entry (#614). */
+export interface ArtifactReproducibility {
+  /** Honest, per-artifact basis for the claim — never inferred from a sibling artifact's basis. */
+  basis: ReproducibilityBasis;
+  /** How to verify the claim, when there is one. `"re-synth"` applies only to `"deterministic-synthesis"` entries — re-run `chant build` and compare the resulting digest. */
+  verifyBy?: VerificationMethod;
+}
+
+/**
+ * Default reproducibility basis for a given `BuildArchiveEntryKind`, absent
+ * an explicit override. A `template` entry is chant's own synthesized IaC
+ * output — deterministic by construction (the same synthesis run over the
+ * same source produces the same bytes, per ./build-archive.ts's module doc).
+ * `image`/`asset` entries are produced by an external build tool chant only
+ * orchestrates (`docker build`, a JVM/zip packager) — best-effort absent a
+ * real reproducible-build attestation. `sbom` entries describe another
+ * artifact rather than being one themselves, so they carry no
+ * reproducibility claim of their own (`undefined`) — see
+ * `../build-archive.ts`'s `BuildArchiveEntry.reproducibility` doc.
+ */
+export function defaultReproducibility(
+  kind: "image" | "template" | "asset" | "sbom",
+): ArtifactReproducibility | undefined {
+  switch (kind) {
+    case "template":
+      return { basis: "deterministic-synthesis", verifyBy: "re-synth" };
+    case "image":
+    case "asset":
+      return { basis: "best-effort" };
+    case "sbom":
+      return undefined;
+  }
+}
+
+// ── provenance ───────────────────────────────────────────────────────────────
+
+/** One source -> output link: the source ref/commit that produced a given artifact digest. */
+export interface ProvenanceLink {
+  /** Source ref/commit the artifact was built or synthesized from (e.g. a git sha, or `"<sha>:<path>"` when a monorepo subpath matters). */
+  sourceRef: string;
+  /** The artifact digest this provenance describes — the same `BuildArchiveEntry.digest` it is attached to, repeated here so a `ProvenanceLink` remains meaningful if ever extracted/serialized apart from its entry. */
+  artifactDigest: string;
+}

package/src/components/verbs/sbom-generator.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_SBOM_FORMAT,
+  SBOM_MEDIA_TYPES,
+  SbomGeneratorNotImplementedError,
+  defaultSbomGenerator,
+  notImplementedSbomGenerator,
+} from "./sbom-generator";
+import { lockfileSbomGenerator } from "./lockfile-sbom-generator";
+import { createMockSbomGenerator } from "./__tests__/mock-sbom-generator";
+
+describe("SBOM document media types (#606 — format-agnostic storage)", () => {
+  it("declares both SPDX and CycloneDX media types — no format is hardcoded as the only one", () => {
+    expect(SBOM_MEDIA_TYPES.spdx).toBe("application/spdx+json");
+    expect(SBOM_MEDIA_TYPES.cyclonedx).toBe("application/vnd.cyclonedx+json");
+  });
+
+  it("defaults to SPDX (BuildKit's native attestation format) per the epic's article-validated refinement", () => {
+    expect(DEFAULT_SBOM_FORMAT).toBe("spdx");
+  });
+});
+
+describe("notImplementedSbomGenerator (#606) — still exported, no longer the default", () => {
+  it("every method throws SbomGeneratorNotImplementedError, naming the method", async () => {
+    await expect(notImplementedSbomGenerator.forImage({ imagePath: "x", digest: "sha256:1" })).rejects.toBeInstanceOf(
+      SbomGeneratorNotImplementedError,
+    );
+    await expect(notImplementedSbomGenerator.forJar({ jarPath: "x", digest: "sha256:1" })).rejects.toThrow(
+      /forJar/,
+    );
+    await expect(notImplementedSbomGenerator.forZip({ zipPath: "x", digest: "sha256:1" })).rejects.toThrow(
+      /forZip/,
+    );
+    await expect(notImplementedSbomGenerator.forDir({ path: "x" })).rejects.toThrow(/forDir/);
+  });
+});
+
+describe("defaultSbomGenerator (#630 — hermetic by default)", () => {
+  it("returns the same lockfileSbomGenerator instance every call, never shelling out at import/call time", () => {
+    expect(defaultSbomGenerator()).toBe(lockfileSbomGenerator);
+    expect(defaultSbomGenerator()).toBe(defaultSbomGenerator());
+  });
+
+  it("forImage still throws SbomGeneratorNotImplementedError — no hermetic backend can see an image's base layers", async () => {
+    await expect(defaultSbomGenerator().forImage({ imagePath: "x", digest: "sha256:1" })).rejects.toBeInstanceOf(
+      SbomGeneratorNotImplementedError,
+    );
+  });
+
+  it("forDir generates a real SBOM tool-free from a package-lock.json on disk", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-sbom-default-"));
+    writeFileSync(
+      join(dir, "package-lock.json"),
+      JSON.stringify({
+        name: "fixture",
+        version: "1.0.0",
+        packages: { "": { name: "fixture" }, "node_modules/left-pad": { version: "1.3.0" } },
+      }),
+    );
+
+    const doc = await defaultSbomGenerator().forDir({ path: dir });
+    expect(doc.packageCount).toBe(1);
+    expect(doc.generator).toBe("chant-lockfile-sbom/package-lock.json");
+    expect(JSON.parse(doc.bytes)).toBeTruthy();
+  });
+});
+
+describe("MockSbomGenerator (test double)", () => {
+  it("produces a format-agnostic document whose mediaType always matches the requested/default format", async () => {
+    const mock = createMockSbomGenerator();
+    const spdxDoc = await mock.generator.forImage({ imagePath: "a.tar", digest: "sha256:1" });
+    expect(spdxDoc.format).toBe("spdx");
+    expect(spdxDoc.mediaType).toBe(SBOM_MEDIA_TYPES.spdx);
+
+    const cyclonedxDoc = await mock.generator.forJar({ jarPath: "a.jar", digest: "sha256:2", format: "cyclonedx" });
+    expect(cyclonedxDoc.format).toBe("cyclonedx");
+    expect(cyclonedxDoc.mediaType).toBe(SBOM_MEDIA_TYPES.cyclonedx);
+  });
+
+  it("records every call for assertion, keyed by artifact-type method", async () => {
+    const mock = createMockSbomGenerator();
+    await mock.generator.forImage({ imagePath: "a.tar", digest: "sha256:1" });
+    await mock.generator.forZip({ zipPath: "b.zip", digest: "sha256:2" });
+    expect(mock.calls.map((c) => c.method)).toEqual(["forImage", "forZip"]);
+  });
+
+  it("fail option surfaces a rejected promise from every method", async () => {
+    const mock = createMockSbomGenerator({ fail: true });
+    await expect(mock.generator.forImage({ imagePath: "a.tar", digest: "sha256:1" })).rejects.toThrow(
+      /sbom generation failed/,
+    );
+  });
+});