@intentius/chant 0.13.1 → 0.15.1

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

@@ -0,0 +1,194 @@
+/**
+ * Tests the real, deep-scan `SbomGenerator` backend (#610,
+ * ./tool-sbom-generator.ts) against a `MockProcessRunner`
+ * (./__tests__/mock-process-runner.ts) — no live `syft`/`docker buildx`/
+ * `cyclonedx-maven`/`cdxgen` invoked. Asserts the command each artifact type
+ * dispatches to, that output is parsed (package count), and that a missing
+ * tool surfaces `ToolNotAvailableError` rather than a silent/empty SBOM.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createToolSbomGenerator } from "./tool-sbom-generator";
+import { ToolNotAvailableError } from "./process-runner";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+const dirs: string[] = [];
+function tempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-tool-sbom-"));
+  dirs.push(dir);
+  return dir;
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true });
+});
+
+const CYCLONEDX_DOC = JSON.stringify({ bomFormat: "CycloneDX", components: [{ name: "left-pad" }, { name: "express" }] });
+const SPDX_DOC = JSON.stringify({ spdxVersion: "SPDX-2.3", packages: [{ name: "left-pad" }] });
+
+describe("createToolSbomGenerator — forDir (#610)", () => {
+  it("scans with syft when available, requesting the SPDX format by default", async () => {
+    const dir = tempDir();
+    const mock = createMockProcessRunner({ responses: { "cat ": SPDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forDir({ path: dir });
+
+    expect(doc.format).toBe("spdx");
+    expect(doc.mediaType).toBe("application/spdx+json");
+    expect(doc.generator).toBe("syft");
+    expect(doc.packageCount).toBe(1);
+    const syftCall = mock.calls.find((c) => c.command.startsWith("syft "))!;
+    expect(syftCall.command).toContain(`syft '${dir}' -o spdx-json=`);
+  });
+
+  it("requests CycloneDX output when format is cyclonedx", async () => {
+    const dir = tempDir();
+    const mock = createMockProcessRunner({ responses: { "cat ": CYCLONEDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forDir({ path: dir, format: "cyclonedx" });
+
+    expect(doc.mediaType).toBe("application/vnd.cyclonedx+json");
+    expect(doc.packageCount).toBe(2);
+    const syftCall = mock.calls.find((c) => c.command.startsWith("syft "))!;
+    expect(syftCall.command).toContain("-o cyclonedx-json=");
+  });
+
+  it("falls back to cdxgen when syft is unavailable", async () => {
+    const dir = tempDir();
+    const mock = createMockProcessRunner({
+      tools: { syft: false, cdxgen: true },
+      responses: { "cat ": CYCLONEDX_DOC },
+    });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forDir({ path: dir });
+
+    expect(doc.generator).toBe("cdxgen");
+    expect(doc.format).toBe("cyclonedx"); // cdxgen is CycloneDX-only, even though SPDX is the project default.
+    expect(mock.calls.some((c) => c.command.startsWith("cdxgen "))).toBe(true);
+    expect(mock.calls.some((c) => c.command.startsWith("syft "))).toBe(false);
+  });
+
+  it("throws ToolNotAvailableError when neither syft nor cdxgen is installed", async () => {
+    const dir = tempDir();
+    const mock = createMockProcessRunner({ tools: { syft: false, cdxgen: false } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    await expect(generator.forDir({ path: dir })).rejects.toThrow(ToolNotAvailableError);
+  });
+});
+
+describe("createToolSbomGenerator — forZip (#610)", () => {
+  it("always scans with syft", async () => {
+    const mock = createMockProcessRunner({ responses: { "cat ": CYCLONEDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forZip({ zipPath: "archive/lambda.zip", digest: "sha256:aaa", format: "cyclonedx" });
+
+    expect(doc.generator).toBe("syft");
+    expect(doc.packageCount).toBe(2);
+    expect(mock.calls.some((c) => c.command.includes("archive/lambda.zip"))).toBe(true);
+  });
+
+  it("throws ToolNotAvailableError when syft is unavailable (no fallback for zip)", async () => {
+    const mock = createMockProcessRunner({ tools: { syft: false } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+    await expect(generator.forZip({ zipPath: "archive/lambda.zip", digest: "sha256:aaa" })).rejects.toThrow(
+      ToolNotAvailableError,
+    );
+  });
+});
+
+describe("createToolSbomGenerator — forJar (#610)", () => {
+  it("scans with syft when no pom.xml sits alongside the jar", async () => {
+    const dir = tempDir();
+    const jarPath = join(dir, "app.jar");
+    const mock = createMockProcessRunner({ responses: { "cat ": CYCLONEDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forJar({ jarPath, digest: "sha256:bbb", format: "cyclonedx" });
+
+    expect(doc.generator).toBe("syft");
+    expect(mock.calls.some((c) => c.command.startsWith("mvn "))).toBe(false);
+  });
+
+  it("prefers cyclonedx-maven when a pom.xml sits alongside the jar and mvn is available", async () => {
+    const dir = tempDir();
+    writeFileSync(join(dir, "pom.xml"), "<project></project>");
+    const jarPath = join(dir, "app.jar");
+    const mock = createMockProcessRunner({ tools: { mvn: true }, responses: { "cat ": CYCLONEDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forJar({ jarPath, digest: "sha256:bbb" });
+
+    expect(doc.generator).toBe("cyclonedx-maven");
+    expect(doc.format).toBe("cyclonedx"); // cyclonedx-maven always produces CycloneDX regardless of the requested default.
+    const mvnCall = mock.calls.find((c) => c.command.startsWith("mvn "))!;
+    expect(mvnCall.command).toContain("cyclonedx-maven-plugin");
+  });
+
+  it("falls back to syft when a pom.xml is present but mvn is not installed", async () => {
+    const dir = tempDir();
+    writeFileSync(join(dir, "pom.xml"), "<project></project>");
+    const jarPath = join(dir, "app.jar");
+    const mock = createMockProcessRunner({ tools: { mvn: false, syft: true }, responses: { "cat ": CYCLONEDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forJar({ jarPath, digest: "sha256:bbb" });
+    expect(doc.generator).toBe("syft");
+  });
+});
+
+describe("createToolSbomGenerator — forImage (#610)", () => {
+  it("scans the saved tarball with syft when no Dockerfile sits next to it", async () => {
+    const dir = tempDir();
+    const imagePath = join(dir, "search.tar");
+    const mock = createMockProcessRunner({ responses: { "cat ": SPDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forImage({ imagePath, digest: "sha256:ccc" });
+
+    expect(doc.generator).toBe("syft");
+    expect(mock.calls.some((c) => c.command.startsWith("docker buildx"))).toBe(false);
+  });
+
+  it("prefers BuildKit's --sbom attestation when a Dockerfile sits next to the tarball and docker is available", async () => {
+    const dir = tempDir();
+    writeFileSync(join(dir, "Dockerfile"), "FROM scratch");
+    const imagePath = join(dir, "search.tar");
+    const mock = createMockProcessRunner({ tools: { docker: true }, responses: { "cat ": SPDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forImage({ imagePath, digest: "sha256:ccc" });
+
+    expect(doc.generator).toBe("buildkit");
+    expect(doc.format).toBe("spdx");
+    const buildxCall = mock.calls.find((c) => c.command.startsWith("docker buildx"))!;
+    expect(buildxCall.command).toContain("--sbom=true");
+    expect(buildxCall.command).toContain(dir);
+  });
+
+  it("falls back to syft when a Dockerfile is present but docker is unavailable", async () => {
+    const dir = tempDir();
+    writeFileSync(join(dir, "Dockerfile"), "FROM scratch");
+    const imagePath = join(dir, "search.tar");
+    const mock = createMockProcessRunner({ tools: { docker: false, syft: true }, responses: { "cat ": SPDX_DOC } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    const doc = await generator.forImage({ imagePath, digest: "sha256:ccc" });
+    expect(doc.generator).toBe("syft");
+  });
+
+  it("throws ToolNotAvailableError when falling back to syft and syft is also unavailable", async () => {
+    const dir = tempDir();
+    const imagePath = join(dir, "search.tar");
+    const mock = createMockProcessRunner({ tools: { syft: false } });
+    const generator = createToolSbomGenerator({ runner: mock.runner });
+
+    await expect(generator.forImage({ imagePath, digest: "sha256:ccc" })).rejects.toThrow(ToolNotAvailableError);
+  });
+});

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

@@ -0,0 +1,192 @@
+/**
+ * Real, deep-scan `SbomGenerator` backend (#610, epic #551's "deep external
+ * tool" half of the SBOM story — the counterpart to ./lockfile-sbom-generator.ts's
+ * hermetic, zero-dependency default from #613). Shells out to whichever
+ * external scanner fits the artifact type, through the injectable
+ * `ProcessRunner` (./process-runner.ts, itself mirroring
+ * ./cloud-executor.ts's `CloudExecutor` pattern):
+ *
+ *  - `image` -> `docker buildx build --sbom=true` (BuildKit's native SPDX
+ *    attestation) when a Dockerfile build context is available, otherwise a
+ *    `syft <tarball>` scan of the already-built OCI-layout tarball;
+ *  - `jar`   -> `syft`, or `cyclonedx-maven` when the jar's project directory
+ *    carries a `pom.xml` (a more Maven-native scan than a bytecode-level jar
+ *    scan);
+ *  - `zip`   -> `syft <zip>`;
+ *  - `dir`   -> `syft <dir>`, falling back to `cdxgen <dir>` when `syft` is
+ *    unavailable (`cdxgen`'s "wnat's on disk" mode covers ecosystems syft
+ *    might not have detected).
+ *
+ * Every method resolves the specific tool it needs, checks availability via
+ * `ProcessRunner.available` first, and throws `ToolNotAvailableError`
+ * (./process-runner.ts) with an actionable install hint if the tool is
+ * missing — never a silent empty SBOM. Tests inject `MockProcessRunner`
+ * (./__tests__/mock-process-runner.ts) and assert on the constructed command
+ * line + parsed output; nothing here ever spawns a real process.
+ *
+ * This backend is **not** the process-wide default (see
+ * ./sbom-generator.ts's `notImplementedSbomGenerator` and
+ * ./lockfile-sbom-generator.ts's `lockfileSbomGenerator` module docs for why):
+ * a project opts in explicitly by constructing
+ * `createGenerateSbomCapability(createToolSbomGenerator())` when it wants the
+ * deeper, external-tool-backed scan (e.g. to see an image's base-layer OS
+ * packages, which no lockfile read can see).
+ */
+
+import { basename, dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import {
+  DEFAULT_SBOM_FORMAT,
+  SBOM_MEDIA_TYPES,
+  type GenerateDirSbomInput,
+  type GenerateImageSbomInput,
+  type GenerateJarSbomInput,
+  type GenerateZipSbomInput,
+  type SbomDocument,
+  type SbomFormat,
+  type SbomGenerator,
+} from "./sbom-generator";
+import { defaultProcessRunner, q, requireTool, type ProcessRunner } from "./process-runner";
+
+/** `syft`'s CycloneDX/SPDX JSON output format flags, keyed by `SbomFormat`. */
+const SYFT_FORMAT: Record<SbomFormat, string> = {
+  spdx: "spdx-json",
+  cyclonedx: "cyclonedx-json",
+};
+
+/** `cdxgen` only emits CycloneDX; SPDX is not one of its output formats. */
+const CDXGEN_FORMAT: SbomFormat = "cyclonedx";
+
+export interface ToolSbomGeneratorOptions {
+  /** Injected process boundary. Defaults to the real, `child_process`-backed runner. */
+  runner?: ProcessRunner;
+  /** Directory `syft`/`cdxgen`/`cyclonedx-maven` write their output file into before this backend reads it back. Defaults to `node:os`'s tmpdir via each call's own scratch path — see `scratchPath`. */
+  workDir?: string;
+}
+
+/** Parse a package count out of a CycloneDX or SPDX JSON document, without requiring a full schema-aware parse — mirrors how ./lockfile-sbom-generator.ts's callers only need a count, not full re-validation. */
+function countPackages(format: SbomFormat, bytes: string): number | undefined {
+  try {
+    const doc = JSON.parse(bytes) as Record<string, unknown>;
+    if (format === "cyclonedx" && Array.isArray(doc.components)) return doc.components.length;
+    if (format === "spdx" && Array.isArray(doc.packages)) return doc.packages.length;
+  } catch {
+    // Malformed/unexpected output — report no count rather than throwing;
+    // the SBOM bytes themselves are still returned to the caller as-is.
+  }
+  return undefined;
+}
+
+/** Build a per-call scratch output path so concurrent scans never collide. */
+function scratchPath(workDir: string | undefined, subject: string, format: SbomFormat): string {
+  const dir = workDir ?? "/tmp/chant-sbom";
+  const safeName = basename(subject).replace(/[^a-zA-Z0-9_.-]/g, "_");
+  return join(dir, `${safeName}.${Date.now()}.${format}.json`);
+}
+
+/**
+ * Build a real, deep-scan `SbomGenerator` backend. Every method shells out
+ * through `options.runner` (default: the real `ProcessRunner`); tests should
+ * always pass a `MockProcessRunner` instead.
+ */
+export function createToolSbomGenerator(options: ToolSbomGeneratorOptions = {}): SbomGenerator {
+  const runner = options.runner ?? defaultProcessRunner();
+
+  async function runSyft(target: string, format: SbomFormat): Promise<{ bytes: string; generator: string }> {
+    await requireTool(runner, "syft", `scan ${target} for a software bill of materials`);
+    const out = scratchPath(options.workDir, target, format);
+    await runner.run(`syft ${q(target)} -o ${SYFT_FORMAT[format]}=${q(out)}`);
+    const { stdout } = await runner.run(`cat ${q(out)}`);
+    return { bytes: stdout, generator: "syft" };
+  }
+
+  return {
+    async forImage(input: GenerateImageSbomInput): Promise<SbomDocument> {
+      const format = input.format ?? DEFAULT_SBOM_FORMAT;
+
+      // Prefer BuildKit's own attestation when the image was built from a
+      // context on disk right next to the tarball (the common docker-build ->
+      // generate-sbom composition); otherwise fall back to scanning the
+      // already-saved tarball with syft, which needs no rebuild.
+      const buildContext = dirname(input.imagePath);
+      const hasDockerfile = existsSync(join(buildContext, "Dockerfile"));
+
+      if (hasDockerfile && (await runner.available("docker"))) {
+        const out = scratchPath(options.workDir, input.imagePath, format);
+        await runner.run(
+          `docker buildx build --sbom=true --output type=local,dest=${q(out)} ${q(buildContext)}`,
+        );
+        const { stdout } = await runner.run(`cat ${q(join(out, "sbom.spdx.json"))}`);
+        return {
+          format,
+          mediaType: SBOM_MEDIA_TYPES[format],
+          bytes: stdout,
+          packageCount: countPackages(format, stdout),
+          generator: "buildkit",
+        };
+      }
+
+      const { bytes, generator } = await runSyft(input.imagePath, format);
+      return { format, mediaType: SBOM_MEDIA_TYPES[format], bytes, packageCount: countPackages(format, bytes), generator };
+    },
+
+    async forJar(input: GenerateJarSbomInput): Promise<SbomDocument> {
+      const format = input.format ?? DEFAULT_SBOM_FORMAT;
+      const projectDir = dirname(input.jarPath);
+      const hasPom = existsSync(join(projectDir, "pom.xml"));
+
+      if (hasPom && (await runner.available("mvn"))) {
+        await requireTool(runner, "mvn", `run cyclonedx-maven against ${projectDir}`);
+        const out = scratchPath(options.workDir, input.jarPath, "cyclonedx");
+        await runner.run(
+          `mvn -f ${q(join(projectDir, "pom.xml"))} org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom -DoutputFormat=json -DoutputName=${q(basename(out, ".json"))}`,
+          { cwd: projectDir },
+        );
+        const { stdout } = await runner.run(`cat ${q(out)}`);
+        return {
+          format: "cyclonedx",
+          mediaType: SBOM_MEDIA_TYPES.cyclonedx,
+          bytes: stdout,
+          packageCount: countPackages("cyclonedx", stdout),
+          generator: "cyclonedx-maven",
+        };
+      }
+
+      const { bytes, generator } = await runSyft(input.jarPath, format);
+      return { format, mediaType: SBOM_MEDIA_TYPES[format], bytes, packageCount: countPackages(format, bytes), generator };
+    },
+
+    async forZip(input: GenerateZipSbomInput): Promise<SbomDocument> {
+      const format = input.format ?? DEFAULT_SBOM_FORMAT;
+      const { bytes, generator } = await runSyft(input.zipPath, format);
+      return { format, mediaType: SBOM_MEDIA_TYPES[format], bytes, packageCount: countPackages(format, bytes), generator };
+    },
+
+    async forDir(input: GenerateDirSbomInput): Promise<SbomDocument> {
+      const format = input.format ?? DEFAULT_SBOM_FORMAT;
+
+      if (await runner.available("syft")) {
+        const { bytes, generator } = await runSyft(input.path, format);
+        return { format, mediaType: SBOM_MEDIA_TYPES[format], bytes, packageCount: countPackages(format, bytes), generator };
+      }
+
+      // syft absent — fall back to cdxgen (CycloneDX-only; requested SPDX is
+      // reported back as the CycloneDX doc's own format, never silently
+      // mislabeled as SPDX).
+      await requireTool(runner, "cdxgen", `scan ${input.path} for a software bill of materials (syft is also unavailable)`);
+      const out = scratchPath(options.workDir, input.path, CDXGEN_FORMAT);
+      await runner.run(`cdxgen -o ${q(out)} ${q(input.path)}`);
+      const { stdout } = await runner.run(`cat ${q(out)}`);
+      return {
+        format: CDXGEN_FORMAT,
+        mediaType: SBOM_MEDIA_TYPES[CDXGEN_FORMAT],
+        bytes: stdout,
+        packageCount: countPackages(CDXGEN_FORMAT, stdout),
+        generator: "cdxgen",
+      };
+    },
+  };
+}
+
+/** Process-wide, real-tool-backed `SbomGenerator`, ready to inject wherever a project opts into the deep-scan path over ./lockfile-sbom-generator.ts's hermetic default. Never constructed by a test. */
+export const toolSbomGenerator: SbomGenerator = createToolSbomGenerator();

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

@@ -0,0 +1,159 @@
+/**
+ * Tests the `verify` gate (#622, ./verify.ts) against a `MockProcessRunner`
+ * (./__tests__/mock-process-runner.ts) — no live `cosign`, no real
+ * Rekor/Fulcio network call. Asserts: passes on a valid mock (signature +
+ * provenance both verify), fails on missing/invalid signature, fails on
+ * wrong identity, and handles a missing `cosign` binary gracefully (throws
+ * rather than silently passing the gate).
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  buildVerifyAttestationArgs,
+  buildVerifySignatureArgs,
+  createVerifyCapability,
+  VerificationFailedError,
+} from "./verify";
+import { ToolNotAvailableError } from "./process-runner";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+const ctx = { env: "prod", component: "search-service" };
+const DIGEST_REF = "123.dkr.ecr.us-east-1.amazonaws.com/search@sha256:" + "a".repeat(64);
+
+const POLICY = {
+  expectedIssuer: "https://token.actions.githubusercontent.com",
+  expectedIdentity: "https://github.com/my-org/my-repo/.github/workflows/release.yml@refs/heads/main",
+};
+
+describe("verify — command construction", () => {
+  it("builds cosign verify with the expected issuer/identity flags", () => {
+    const cmd = buildVerifySignatureArgs({ imageRef: DIGEST_REF, policy: POLICY });
+    expect(cmd).toBe(
+      `cosign verify --certificate-oidc-issuer '${POLICY.expectedIssuer}' --certificate-identity '${POLICY.expectedIdentity}' '${DIGEST_REF}'`,
+    );
+  });
+
+  it("builds cosign verify-attestation with the slsaprovenance1 type", () => {
+    const cmd = buildVerifyAttestationArgs({ imageRef: DIGEST_REF, policy: POLICY });
+    expect(cmd).toBe(
+      `cosign verify-attestation --type slsaprovenance1 --certificate-oidc-issuer '${POLICY.expectedIssuer}' --certificate-identity '${POLICY.expectedIdentity}' '${DIGEST_REF}'`,
+    );
+  });
+
+  it("uses --certificate-identity-regexp when identityIsRegexp is set", () => {
+    const cmd = buildVerifySignatureArgs({
+      imageRef: DIGEST_REF,
+      policy: { ...POLICY, expectedIdentity: ".*release.yml@refs/heads/.*", identityIsRegexp: true },
+    });
+    expect(cmd).toContain("--certificate-identity-regexp");
+    expect(cmd).not.toContain("--certificate-identity '");
+  });
+
+  it("uses --key instead of the identity policy flags when policy.key is set", () => {
+    const cmd = buildVerifySignatureArgs({ imageRef: DIGEST_REF, policy: { ...POLICY, key: "cosign.pub" } });
+    expect(cmd).toBe(`cosign verify --key 'cosign.pub' '${DIGEST_REF}'`);
+  });
+});
+
+describe("verify — passes on a valid mock", () => {
+  it("verifies both signature and provenance by default", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createVerifyCapability(mock.runner);
+
+    const output = await capability.run(ctx, { imageRef: DIGEST_REF, policy: POLICY });
+
+    expect(output).toEqual({ verified: true, checked: ["signature", "provenance"] });
+    expect(mock.calls.some((c) => c.command.startsWith("cosign verify --certificate"))).toBe(true);
+    expect(mock.calls.some((c) => c.command.startsWith("cosign verify-attestation"))).toBe(true);
+  });
+
+  it("skips the provenance check when requireProvenance is false", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createVerifyCapability(mock.runner);
+
+    const output = await capability.run(ctx, { imageRef: DIGEST_REF, policy: POLICY, requireProvenance: false });
+
+    expect(output).toEqual({ verified: true, checked: ["signature"] });
+    expect(mock.calls.some((c) => c.command.startsWith("cosign verify-attestation"))).toBe(false);
+  });
+});
+
+describe("verify — FAILS the deploy on a missing/invalid signature", () => {
+  it("throws VerificationFailedError when cosign verify rejects (e.g. no signature found)", async () => {
+    const mock = createMockProcessRunner({
+      failures: { "cosign verify --certificate": "Error: no matching signatures" },
+    });
+    const capability = createVerifyCapability(mock.runner);
+
+    await expect(capability.run(ctx, { imageRef: DIGEST_REF, policy: POLICY })).rejects.toThrow(
+      VerificationFailedError,
+    );
+    await expect(capability.run(ctx, { imageRef: DIGEST_REF, policy: POLICY })).rejects.toThrow(
+      /signature verification failed/,
+    );
+  });
+
+  it("never runs the provenance check once the signature check has already failed", async () => {
+    const mock = createMockProcessRunner({
+      failures: { "cosign verify --certificate": "Error: no matching signatures" },
+    });
+    const capability = createVerifyCapability(mock.runner);
+
+    await expect(capability.run(ctx, { imageRef: DIGEST_REF, policy: POLICY })).rejects.toThrow();
+    expect(mock.calls.some((c) => c.command.startsWith("cosign verify-attestation"))).toBe(false);
+  });
+});
+
+describe("verify — FAILS the deploy on missing/invalid provenance", () => {
+  it("throws VerificationFailedError when cosign verify-attestation rejects", async () => {
+    const mock = createMockProcessRunner({
+      failures: { "cosign verify-attestation": "Error: no matching attestations" },
+    });
+    const capability = createVerifyCapability(mock.runner);
+
+    await expect(capability.run(ctx, { imageRef: DIGEST_REF, policy: POLICY })).rejects.toThrow(
+      VerificationFailedError,
+    );
+    await expect(capability.run(ctx, { imageRef: DIGEST_REF, policy: POLICY })).rejects.toThrow(
+      /provenance verification failed/,
+    );
+  });
+});
+
+describe("verify — FAILS the deploy on wrong identity", () => {
+  it("surfaces cosign's own identity-mismatch failure as VerificationFailedError", async () => {
+    const mock = createMockProcessRunner({
+      failures: {
+        "cosign verify --certificate": "Error: none of the expected identities matched what was in the certificate",
+      },
+    });
+    const capability = createVerifyCapability(mock.runner);
+
+    await expect(
+      capability.run(ctx, {
+        imageRef: DIGEST_REF,
+        policy: { ...POLICY, expectedIdentity: "https://github.com/someone-else/other-repo/.github/workflows/x.yml@refs/heads/main" },
+      }),
+    ).rejects.toThrow(/none of the expected identities matched/);
+  });
+});
+
+describe("verify — cosign absence handled gracefully", () => {
+  it("throws ToolNotAvailableError rather than silently passing the gate when cosign is not installed", async () => {
+    const mock = createMockProcessRunner({ tools: { cosign: false } });
+    const capability = createVerifyCapability(mock.runner);
+
+    await expect(capability.run(ctx, { imageRef: DIGEST_REF, policy: POLICY })).rejects.toThrow(
+      ToolNotAvailableError,
+    );
+    // No verify/verify-attestation call was even attempted.
+    expect(mock.calls.some((c) => c.command.startsWith("cosign verify"))).toBe(false);
+  });
+});
+
+describe("verify — no rollback (read-only observation)", () => {
+  it("declares no rollback", () => {
+    const capability = createVerifyCapability(createMockProcessRunner().runner);
+    expect(capability.rollback).toBeUndefined();
+  });
+});