@intentius/chant 0.13.1 → 0.15.0

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

@@ -0,0 +1,210 @@
+/**
+ * Tests `sign`/`attest-provenance` (#622, ./sign.ts) against a
+ * `MockProcessRunner` (./__tests__/mock-process-runner.ts) — no live
+ * `cosign`, no real Rekor/Fulcio network call, ever. Asserts the constructed
+ * keyless `cosign sign`/`cosign attest` invocations, the digest-only guard,
+ * the opt-in key-based override, and graceful `cosign`-absent handling.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  buildAttestArgs,
+  buildProvenanceStatement,
+  buildSignArgs,
+  createAttestProvenanceCapability,
+  createSignCapability,
+  SignTargetNotDigestError,
+} from "./sign";
+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 TAG_REF = "123.dkr.ecr.us-east-1.amazonaws.com/search:latest";
+
+describe("sign — keyless by default (#622)", () => {
+  it("builds a keyless cosign sign invocation with no --key flag", () => {
+    const cmd = buildSignArgs({ imageRef: DIGEST_REF });
+    expect(cmd).toBe(`cosign sign --yes '${DIGEST_REF}'`);
+    expect(cmd).not.toContain("--key");
+  });
+
+  it("runs cosign sign against the digest and reports method: keyless", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createSignCapability(mock.runner);
+
+    const output = await capability.run(ctx, { imageRef: DIGEST_REF });
+
+    expect(output).toEqual({ imageRef: DIGEST_REF, signed: true, method: "keyless" });
+    const signCall = mock.calls.find((c) => c.command.startsWith("cosign sign"))!;
+    expect(signCall.command).toContain(DIGEST_REF);
+    expect(signCall.command).not.toContain("--key");
+  });
+
+  it("passes through explicit OIDC issuer/client-id/token overrides", () => {
+    const cmd = buildSignArgs({
+      imageRef: DIGEST_REF,
+      keyless: { identityToken: "tok", oidcIssuer: "https://issuer.example", oidcClientId: "sigstore" },
+    });
+    expect(cmd).toContain("--identity-token 'tok'");
+    expect(cmd).toContain("--oidc-issuer 'https://issuer.example'");
+    expect(cmd).toContain("--oidc-client-id 'sigstore'");
+  });
+
+  it("attaches annotations via -a k=v flags", () => {
+    const cmd = buildSignArgs({ imageRef: DIGEST_REF, annotations: { build: "123", branch: "main" } });
+    expect(cmd).toContain("-a 'build=123'");
+    expect(cmd).toContain("-a 'branch=main'");
+  });
+
+  it("refuses to sign a mutable tag reference — never a tag, only a digest", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createSignCapability(mock.runner);
+
+    await expect(capability.run(ctx, { imageRef: TAG_REF })).rejects.toThrow(SignTargetNotDigestError);
+    // Refuses before ever shelling out — no cosign call attempted at all.
+    expect(mock.calls).toHaveLength(0);
+  });
+
+  it("switches to key-based signing only when input.key is explicitly supplied (opt-in, not default)", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createSignCapability(mock.runner);
+
+    const output = await capability.run(ctx, {
+      imageRef: DIGEST_REF,
+      key: { key: "awskms://alias/my-signing-key" },
+    });
+
+    expect(output.method).toBe("key");
+    const signCall = mock.calls.find((c) => c.command.startsWith("cosign sign"))!;
+    expect(signCall.command).toContain("--key 'awskms://alias/my-signing-key'");
+    expect(signCall.command).not.toContain("--oidc-issuer");
+  });
+
+  it("throws ToolNotAvailableError when cosign is absent, rather than silently skipping the signature", async () => {
+    const mock = createMockProcessRunner({ tools: { cosign: false } });
+    const capability = createSignCapability(mock.runner);
+
+    await expect(capability.run(ctx, { imageRef: DIGEST_REF })).rejects.toThrow(ToolNotAvailableError);
+  });
+
+  it("declares no rollback — an already-signed, content-addressed image's signature is immutable evidence", () => {
+    const capability = createSignCapability(createMockProcessRunner().runner);
+    expect(capability.rollback).toBeUndefined();
+  });
+});
+
+describe("buildProvenanceStatement — SLSA in-toto statement from #614 provenance material", () => {
+  it("builds a subject/predicate from the digest ref and ProvenanceLink", () => {
+    const statement = buildProvenanceStatement({
+      imageRef: DIGEST_REF,
+      provenance: { sourceRef: "abc123def", artifactDigest: DIGEST_REF.split("@")[1]! },
+      builderId: "https://github.com/actions/runner",
+    });
+
+    expect(statement._type).toBe("https://in-toto.io/Statement/v1");
+    expect(statement.predicateType).toBe("https://slsa.dev/provenance/v1");
+    expect(statement.subject).toEqual([
+      { name: DIGEST_REF, digest: { sha256: "a".repeat(64) } },
+    ]);
+    expect(statement.predicate.buildDefinition.externalParameters).toEqual({ sourceRef: "abc123def" });
+    expect(statement.predicate.runDetails.builder.id).toBe("https://github.com/actions/runner");
+    expect(statement.predicate.runDetails.metadata?.finishedOn).toBeDefined();
+  });
+
+  it("throws when imageRef has no digest", () => {
+    expect(() =>
+      buildProvenanceStatement({
+        imageRef: TAG_REF,
+        provenance: { sourceRef: "abc", artifactDigest: "sha256:x" },
+        builderId: "builder",
+      }),
+    ).toThrow(SignTargetNotDigestError);
+  });
+});
+
+describe("attest-provenance — keyless cosign attest (#622)", () => {
+  it("builds a keyless cosign attest invocation with the slsaprovenance1 type and no --key", () => {
+    const cmd = buildAttestArgs({
+      imageRef: DIGEST_REF,
+      provenance: { sourceRef: "abc123", artifactDigest: "sha256:x" },
+      builderId: "builder",
+    }, "/tmp/scratch.json");
+
+    expect(cmd).toContain("cosign attest --yes --type slsaprovenance1 --predicate '/tmp/scratch.json'");
+    expect(cmd).toContain(DIGEST_REF);
+    expect(cmd).not.toContain("--key");
+  });
+
+  it("signs+attaches the SLSA provenance statement via cosign attest, keyless by default", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createAttestProvenanceCapability(mock.runner);
+
+    const output = await capability.run(ctx, {
+      imageRef: DIGEST_REF,
+      provenance: { sourceRef: "abc123def", artifactDigest: DIGEST_REF.split("@")[1]! },
+      builderId: "https://github.com/actions/runner",
+    });
+
+    expect(output.attested).toBe(true);
+    expect(output.method).toBe("keyless");
+    expect(output.statement.predicateType).toBe("https://slsa.dev/provenance/v1");
+
+    const attestCall = mock.calls.find((c) => c.command.startsWith("cosign attest"))!;
+    expect(attestCall.command).toContain("--type slsaprovenance1");
+    expect(attestCall.command).toContain(DIGEST_REF);
+    expect(attestCall.command).not.toContain("--key");
+
+    // The predicate file is written to a scratch path before cosign reads it.
+    expect(mock.calls.some((c) => c.command.includes("chant-provenance-attest"))).toBe(true);
+  });
+
+  it("uses key-based attestation only when explicitly configured", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createAttestProvenanceCapability(mock.runner);
+
+    const output = await capability.run(ctx, {
+      imageRef: DIGEST_REF,
+      provenance: { sourceRef: "abc123def", artifactDigest: DIGEST_REF.split("@")[1]! },
+      builderId: "builder",
+      key: { key: "cosign.key" },
+    });
+
+    expect(output.method).toBe("key");
+    const attestCall = mock.calls.find((c) => c.command.startsWith("cosign attest"))!;
+    expect(attestCall.command).toContain("--key 'cosign.key'");
+  });
+
+  it("refuses a tag-only imageRef before ever shelling out", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createAttestProvenanceCapability(mock.runner);
+
+    await expect(
+      capability.run(ctx, {
+        imageRef: TAG_REF,
+        provenance: { sourceRef: "abc", artifactDigest: "sha256:x" },
+        builderId: "builder",
+      }),
+    ).rejects.toThrow(SignTargetNotDigestError);
+    expect(mock.calls).toHaveLength(0);
+  });
+
+  it("throws ToolNotAvailableError when cosign is absent", async () => {
+    const mock = createMockProcessRunner({ tools: { cosign: false } });
+    const capability = createAttestProvenanceCapability(mock.runner);
+
+    await expect(
+      capability.run(ctx, {
+        imageRef: DIGEST_REF,
+        provenance: { sourceRef: "abc", artifactDigest: DIGEST_REF.split("@")[1]! },
+        builderId: "builder",
+      }),
+    ).rejects.toThrow(ToolNotAvailableError);
+  });
+
+  it("declares no rollback — an attached attestation is immutable evidence", () => {
+    const capability = createAttestProvenanceCapability(createMockProcessRunner().runner);
+    expect(capability.rollback).toBeUndefined();
+  });
+});

package/src/components/verbs/sign.ts

@@ -0,0 +1,350 @@
+/**
+ * `sign` capability — keyless cosign signing + SLSA provenance attestation
+ * (#622, epic #551 follow-up to #610's referrer-attach path and #614's
+ * reproducibility/provenance material). The companion gate is
+ * `./verify.ts`'s `verify` capability.
+ *
+ * **Beginner footgun #1 neutralized: sign the digest, never a tag.** `input`
+ * requires an already-resolved `sha256:` image reference (typically wired
+ * from a prior publish step, `"@Publish.uri"`, which is itself
+ * `repo@sha256:...` — see ./publish.ts) — never a bare tag. A tag is mutable;
+ * signing one says nothing about which bytes were actually signed by the
+ * time someone pulls it. `assertDigestRef` below throws before ever shelling
+ * out if a caller passes a tag-only reference.
+ *
+ * **Beginner footgun #2 neutralized: keyless by default.** Sign via cosign's
+ * keyless flow (a short-lived Fulcio cert bound to an OIDC identity, logged
+ * to the public Rekor transparency log) — `cosign sign --yes <ref>` with no
+ * `--key`. There is no private key file for a first-timer to generate, lose,
+ * leak, or forget to rotate. Key-based signing (`input.key`) is an opt-in
+ * override for teams with an existing KMS/file-based key policy, never the
+ * default — see `buildSignArgs`/`buildAttestArgs` below: `--key` is added
+ * only when `input.key` is explicitly supplied, and it is the *only* thing
+ * that changes about the invocation (still by digest, still attached the
+ * same way).
+ *
+ * **SLSA provenance.** `attestProvenance` builds an in-toto
+ * `https://slsa.dev/provenance/v1` statement from the same
+ * `ProvenanceLink`/`ArtifactReproducibility` material #614's
+ * ./reproducibility.ts already records per build-archive entry (source ref,
+ * artifact digest) plus a builder id and timestamp, then signs+attaches it
+ * via `cosign attest` (keyless by the same default). This reuses #614's
+ * provenance model rather than inventing a second one — the in-toto
+ * statement's `predicate.buildDefinition.resolvedDependencies` /
+ * `.internalParameters` are populated from the same source-ref/digest link a
+ * build archive entry already carries.
+ *
+ * Both `sign` and `attestProvenance` shell out to `cosign` through the
+ * injectable `ProcessRunner` (./process-runner.ts) — mirroring
+ * ./tool-sbom-generator.ts and ./publish.ts's referrer-attach step exactly:
+ * `requireTool` throws `ToolNotAvailableError` with an actionable message if
+ * `cosign` is absent, and no test here ever spawns a real process or talks
+ * to Rekor/Fulcio.
+ */
+
+import type { Capability } from "../capability";
+import { defaultProcessRunner, q, requireTool, type ProcessRunner } from "./process-runner";
+import type { ProvenanceLink } from "./reproducibility";
+
+// ── shared: digest-only reference guard ─────────────────────────────────────
+
+/**
+ * Thrown when a `sign`/`attest` input's image reference has no `@sha256:...`
+ * digest — refusing to sign a mutable tag (beginner footgun #1) rather than
+ * silently signing whatever the tag happens to resolve to right now.
+ */
+export class SignTargetNotDigestError extends Error {
+  constructor(
+    public readonly ref: string,
+    public readonly verb: "sign" | "attest",
+  ) {
+    super(
+      `${verb} "${ref}": expected a digest reference ("repo@sha256:...", e.g. from a prior publish step's "@Publish.uri") — ` +
+        `signing a mutable tag would not pin which bytes were signed. Pass the digest-qualified reference instead.`,
+    );
+    this.name = "SignTargetNotDigestError";
+  }
+}
+
+/** True if `ref` carries an `@sha256:<hex>` digest — the only form `sign`/`attest` accept. */
+function isDigestRef(ref: string): boolean {
+  return /@sha256:[0-9a-f]{64}$/i.test(ref);
+}
+
+/** Throw `SignTargetNotDigestError` unless `ref` is digest-qualified. */
+function assertDigestRef(ref: string, verb: "sign" | "attest"): void {
+  if (!isDigestRef(ref)) throw new SignTargetNotDigestError(ref, verb);
+}
+
+// ── keyless identity config (shared by sign + attest + verify) ─────────────
+
+/**
+ * cosign keyless signing config. Keyless is the default story this whole
+ * module encodes — every field here is optional because `cosign sign --yes`
+ * with no flags at all already does the right thing in CI (ambient OIDC from
+ * the CI provider's own token, e.g. GitHub Actions' `id-token: write`).
+ * `identityToken`/`oidcIssuer`/`oidcClientId` are the explicit overrides for
+ * environments without ambient OIDC detection.
+ */
+export interface KeylessSigningConfig {
+  /** Explicit OIDC identity token, when the environment has no ambient CI OIDC cosign can auto-detect. */
+  identityToken?: string;
+  /** OIDC issuer URL override (`cosign sign --oidc-issuer`). */
+  oidcIssuer?: string;
+  /** OIDC client id override (`cosign sign --oidc-client-id`). */
+  oidcClientId?: string;
+  /** Fulcio URL override, for a private Sigstore instance. */
+  fulcioUrl?: string;
+  /** Rekor URL override, for a private transparency log. */
+  rekorUrl?: string;
+}
+
+/**
+ * Key-based signing override config — opt-in, never the default (see this
+ * module's doc comment). Supplying `input.key` on `sign`/`attestProvenance`
+ * switches the invocation to `cosign sign --key <key>` instead of the keyless
+ * flow; every other part of the invocation (digest-only target, referrer
+ * attach) is unchanged.
+ */
+export interface KeyBasedSigningConfig {
+  /** Key reference cosign accepts: a local path, `kms://...`, `k8s://...`, `azurekms://...`, `awskms://...`, etc. An encrypted key file's password is not accepted here — `ProcessRunner.run` (./process-runner.ts) has no env-var passthrough today, and interpolating a secret into the shell command string would leak it into process listings/logs; supply an unencrypted key reference (e.g. a KMS URI) or export `COSIGN_PASSWORD` in the calling process's own environment instead. */
+  key: string;
+}
+
+/** Append the shared keyless/key-based signing flags to a cosign argv, mutating `args` in place. Shared by `buildSignArgs` and `buildAttestArgs` so both stay in lockstep. */
+function appendSigningFlags(
+  args: string[],
+  opts: { keyless?: KeylessSigningConfig; key?: KeyBasedSigningConfig },
+): void {
+  if (opts.key) {
+    args.push("--key", q(opts.key.key));
+    return;
+  }
+  // Keyless (default): no --key at all — cosign's own keyless flow (Fulcio + Rekor).
+  const k = opts.keyless;
+  if (k?.identityToken) args.push("--identity-token", q(k.identityToken));
+  if (k?.oidcIssuer) args.push("--oidc-issuer", q(k.oidcIssuer));
+  if (k?.oidcClientId) args.push("--oidc-client-id", q(k.oidcClientId));
+  if (k?.fulcioUrl) args.push("--fulcio-url", q(k.fulcioUrl));
+  if (k?.rekorUrl) args.push("--rekor-url", q(k.rekorUrl));
+}
+
+// ── sign ─────────────────────────────────────────────────────────────────────
+
+export interface SignInput {
+  /** Digest-qualified image reference to sign, e.g. `"123.dkr.ecr.us-east-1.amazonaws.com/search@sha256:abc..."` — typically wired from a prior publish step's `"@Publish.uri"`. Never a bare tag; see `SignTargetNotDigestError`. */
+  imageRef: string;
+  /** Keyless signing config (OIDC identity + Rekor/Fulcio overrides). Default: cosign's own ambient keyless detection, no explicit config needed. Ignored when `key` is supplied. */
+  keyless?: KeylessSigningConfig;
+  /** Opt-in key-based override — supply to sign with a private/KMS key instead of the keyless default. Not the default; see this module's doc comment. */
+  key?: KeyBasedSigningConfig;
+  /** Annotations to attach to the signature (`cosign sign -a k=v`), e.g. build metadata. */
+  annotations?: Record<string, string>;
+}
+
+export interface SignOutput {
+  /** The digest-qualified reference that was signed — echoed back for downstream wiring (e.g. into `attestProvenance`/`verify`). */
+  imageRef: string;
+  /** True once `cosign sign` completed without error. */
+  signed: true;
+  /** `"keyless"` or `"key"`, reflecting which flow actually ran. */
+  method: "keyless" | "key";
+}
+
+/** Build the `cosign sign` argv (as a shell command string) for `input` — factored out so tests can assert on the exact invocation without needing a full mock run. */
+export function buildSignArgs(input: SignInput): string {
+  const args = ["cosign", "sign", "--yes"];
+  appendSigningFlags(args, { keyless: input.keyless, key: input.key });
+  for (const [k, v] of Object.entries(input.annotations ?? {})) {
+    args.push("-a", q(`${k}=${v}`));
+  }
+  args.push(q(input.imageRef));
+  return args.join(" ");
+}
+
+/**
+ * Sign an artifact by digest via keyless cosign (default) or an opt-in
+ * key-based override, and attach the signature as an OCI referrer on that
+ * digest — `cosign sign` itself performs the attach (cosign's signatures are
+ * always stored as registry referrers/the legacy tag convention; no separate
+ * `oras attach` step is needed the way SBOM/BOM referrer attach in
+ * ./publish.ts requires one, since cosign natively pushes to the registry).
+ * Refuses to run at all against a non-digest reference (`SignTargetNotDigestError`)
+ * — sign is never invoked for a tag, by construction, before any process is spawned.
+ *
+ * No rollback: an already-signed, content-addressed image's signature is
+ * immutable evidence sitting in the registry — nothing to compensate, the
+ * same opt-out `publish-image`/`generate-sbom` already take for
+ * no-mutable-remote-state operations.
+ */
+export function createSignCapability(
+  processRunner: ProcessRunner = defaultProcessRunner(),
+): Capability<SignInput, SignOutput> {
+  return {
+    kind: "sign",
+    async run(_ctx, input) {
+      assertDigestRef(input.imageRef, "sign");
+      await requireTool(processRunner, "cosign", `sign ${input.imageRef}`);
+      await processRunner.run(buildSignArgs(input));
+      return { imageRef: input.imageRef, signed: true, method: input.key ? "key" : "keyless" };
+    },
+  };
+}
+
+/** Default `sign` capability, backed by the real `ProcessRunner`. */
+export const signCapability: Capability<SignInput, SignOutput> = createSignCapability();
+
+// ── SLSA provenance attestation (attest-provenance) ─────────────────────────
+
+/** Minimal in-toto `https://slsa.dev/provenance/v1` predicate — the fields this module can honestly populate from #614's `ProvenanceLink` material, not a full SLSA Level 3+ builder identity/hermeticity claim. */
+export interface SlsaProvenancePredicate {
+  buildDefinition: {
+    buildType: string;
+    externalParameters: Record<string, unknown>;
+    internalParameters?: Record<string, unknown>;
+    resolvedDependencies?: Array<{ uri: string; digest?: Record<string, string> }>;
+  };
+  runDetails: {
+    builder: { id: string };
+    metadata?: {
+      invocationId?: string;
+      startedOn?: string;
+      finishedOn?: string;
+    };
+  };
+}
+
+/** The full in-toto statement wrapping the SLSA predicate — what `cosign attest` signs+attaches. */
+export interface InTotoProvenanceStatement {
+  _type: "https://in-toto.io/Statement/v1";
+  predicateType: "https://slsa.dev/provenance/v1";
+  subject: Array<{ name: string; digest: { sha256: string } }>;
+  predicate: SlsaProvenancePredicate;
+}
+
+export interface BuildProvenanceStatementInput {
+  /** The digest-qualified artifact reference this provenance describes (subject). */
+  imageRef: string;
+  /** Source -> output link, reused from #614 (./reproducibility.ts) rather than re-deriving a second source-of-truth for "what commit produced this." */
+  provenance: ProvenanceLink;
+  /** Builder identity URI, e.g. a CI run URL or `"https://github.com/actions/runner"`. */
+  builderId: string;
+  /** Build type identifier (an arbitrary URI naming the recipe kind, e.g. `"https://chant.dev/build-archive/v1"`). Defaults to a chant-generic build type. */
+  buildType?: string;
+  /** ISO-8601 timestamp of the build's completion. Defaults to `new Date().toISOString()`. */
+  finishedOn?: string;
+  /** CI invocation/run id, when available (e.g. a GitHub Actions run id). */
+  invocationId?: string;
+}
+
+const DEFAULT_BUILD_TYPE = "https://chant.dev/build-archive/v1";
+
+/** Extract the bare `sha256:...` digest out of a digest-qualified reference (`repo@sha256:...`). */
+function digestOf(ref: string): string {
+  const match = /sha256:([0-9a-f]{64})$/i.exec(ref);
+  if (!match) throw new SignTargetNotDigestError(ref, "attest");
+  return match[1]!;
+}
+
+/**
+ * Build an in-toto SLSA provenance statement for `input.imageRef`, reusing
+ * #614's `ProvenanceLink` (source ref -> artifact digest) as the statement's
+ * `resolvedDependencies`/`internalParameters` material — the honest subset
+ * chant can actually attest to (which source commit, which builder, when),
+ * matching ./reproducibility.ts's "honesty over convenience" stance rather
+ * than fabricating a stronger provenance claim than the build system backs.
+ */
+export function buildProvenanceStatement(input: BuildProvenanceStatementInput): InTotoProvenanceStatement {
+  const digest = digestOf(input.imageRef);
+  return {
+    _type: "https://in-toto.io/Statement/v1",
+    predicateType: "https://slsa.dev/provenance/v1",
+    subject: [{ name: input.imageRef, digest: { sha256: digest } }],
+    predicate: {
+      buildDefinition: {
+        buildType: input.buildType ?? DEFAULT_BUILD_TYPE,
+        externalParameters: { sourceRef: input.provenance.sourceRef },
+        internalParameters: { artifactDigest: input.provenance.artifactDigest },
+        resolvedDependencies: [{ uri: input.provenance.sourceRef, digest: { sha256: digest } }],
+      },
+      runDetails: {
+        builder: { id: input.builderId },
+        metadata: {
+          ...(input.invocationId ? { invocationId: input.invocationId } : {}),
+          finishedOn: input.finishedOn ?? new Date().toISOString(),
+        },
+      },
+    },
+  };
+}
+
+export interface AttestProvenanceInput extends BuildProvenanceStatementInput {
+  /** Keyless signing config, same shape/default as `SignInput.keyless`. */
+  keyless?: KeylessSigningConfig;
+  /** Opt-in key-based override, same shape/default as `SignInput.key`. */
+  key?: KeyBasedSigningConfig;
+}
+
+export interface AttestProvenanceOutput {
+  /** The digest-qualified reference the provenance was attested for. */
+  imageRef: string;
+  /** The in-toto statement that was signed+attached (returned for inspection/logging/tests). */
+  statement: InTotoProvenanceStatement;
+  /** True once `cosign attest` completed without error. */
+  attested: true;
+  /** `"keyless"` or `"key"`, reflecting which flow actually ran. */
+  method: "keyless" | "key";
+}
+
+/**
+ * Build the `cosign attest` argv (as a shell command string) for a
+ * predicate-type/payload pair. Factored out (like `buildSignArgs`) so tests
+ * can assert on the exact invocation. `--predicate` reads from a scratch
+ * file path (`cosign attest` does not accept the payload on stdin any more
+ * reliably than `oras attach` does — see ./publish.ts's `attachOneReferrer`
+ * for the same scratch-file convention) — the caller passes the path already
+ * written.
+ */
+export function buildAttestArgs(
+  input: AttestProvenanceInput,
+  predicatePath: string,
+): string {
+  const args = ["cosign", "attest", "--yes", "--type", "slsaprovenance1", "--predicate", q(predicatePath)];
+  appendSigningFlags(args, { keyless: input.keyless, key: input.key });
+  args.push(q(input.imageRef));
+  return args.join(" ");
+}
+
+/**
+ * Build an in-toto SLSA provenance statement for a digest-qualified artifact
+ * (reusing #614's `ProvenanceLink` material) and sign+attach it via keyless
+ * `cosign attest` (default) or an opt-in key-based override — attached as a
+ * referrer alongside the signature (`sign`) and SBOM (`generate-sbom`) on
+ * the same digest. Refuses a non-digest `imageRef` the same way `sign` does.
+ *
+ * No rollback: same reasoning as `sign` — an attached, content-addressed
+ * attestation is immutable evidence, nothing to compensate.
+ */
+export function createAttestProvenanceCapability(
+  processRunner: ProcessRunner = defaultProcessRunner(),
+): Capability<AttestProvenanceInput, AttestProvenanceOutput> {
+  return {
+    kind: "attest-provenance",
+    async run(_ctx, input) {
+      assertDigestRef(input.imageRef, "attest");
+      await requireTool(processRunner, "cosign", `attest SLSA provenance for ${input.imageRef}`);
+
+      const statement = buildProvenanceStatement(input);
+      const scratchFile = `/tmp/chant-provenance-attest/${digestOf(input.imageRef)}-${Date.now()}.json`;
+      await processRunner.run(`mkdir -p ${q("/tmp/chant-provenance-attest")}`);
+      await processRunner.run(`printf '%s' ${q(JSON.stringify(statement))} > ${q(scratchFile)}`);
+      await processRunner.run(buildAttestArgs(input, scratchFile));
+
+      return { imageRef: input.imageRef, statement, attested: true, method: input.key ? "key" : "keyless" };
+    },
+  };
+}
+
+/** Default `attest-provenance` capability, backed by the real `ProcessRunner`. */
+export const attestProvenanceCapability: Capability<AttestProvenanceInput, AttestProvenanceOutput> =
+  createAttestProvenanceCapability();

package/src/components/verbs/stub.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared helper for building typed capability stubs.
+ *
+ * A stub is fully typed (`kind`, `In`, `Out`) so compositions can wire
+ * output -> input and lint can check the graph, but `run`/`rollback` throw
+ * `CapabilityNotImplementedError` — no cloud calls, no side effects. Cloud
+ * implementations land in a later phase (epic #551).
+ */
+
+import type { Capability } from "../capability";
+import { CapabilityNotImplementedError } from "../capability";
+
+/**
+ * Build a stub `Capability<In, Out>` for `kind`. `supportsRollback` also
+ * attaches a `rollback` that throws the same error, so compositions can
+ * already reference `rollback` in typed code ahead of the real implementation.
+ */
+export function stubCapability<In, Out>(
+  kind: string,
+  opts?: { rollback?: boolean },
+): Capability<In, Out> {
+  const capability: Capability<In, Out> = {
+    kind,
+    async run(): Promise<Out> {
+      throw new CapabilityNotImplementedError(kind);
+    },
+  };
+  if (opts?.rollback) {
+    capability.rollback = async (): Promise<void> => {
+      throw new CapabilityNotImplementedError(kind);
+    };
+  }
+  return capability;
+}