@intentius/chant 0.124.12 → 0.124.14

package/dist/components/verbs/sbom-generator.js

@@ -0,0 +1,119 @@
+/**
+ * SBOM document type + the injectable, artifact-type-keyed `SbomGenerator`
+ * boundary (#606, epic #551 "Build & deploy observability" follow-up to
+ * #564/#568). Mirrors ./cloud-executor.ts's `CloudExecutor` pattern: a real
+ * backend may shell out to `syft`/`docker buildx --sbom`/`cyclonedx-maven`,
+ * but no test and no default import ever does — every backend here is
+ * injected, and tests construct a `MockSbomGenerator`
+ * (./__tests__/mock-sbom-generator.ts) instead.
+ *
+ * **Format-agnostic by construction.** An SBOM is stored as an opaque typed
+ * doc: `{ format, mediaType, bytes }`. Nothing downstream (the build-archive
+ * manifest, the build ledger, `chant components status`) branches on
+ * `format` — every consumer keys off `mediaType`, the same convention
+ * `BuildArchiveEntry.mediaType` already uses for image/template/asset
+ * entries (./build-archive.ts). SPDX (`application/spdx+json`) and
+ * CycloneDX (`application/vnd.cyclonedx+json`) are both first-class; neither
+ * is hardcoded as *the* format anywhere in this module or its consumers.
+ *
+ * **Default format:** SPDX, matching the epic's refinement from the
+ * devops-cloud.news SBOM article — BuildKit natively emits SPDX attestations
+ * for images, so the image/BuildKit backend defaults to SPDX; the `syft`
+ * backend can emit either and defaults to SPDX here too, for one predictable
+ * default across artifact types. Override via `chant.config.ts`'s
+ * `sbom.format` (see ../../config.ts) and/or a component's own `build.sbom`
+ * (see ../component.ts's `BuildSpec`). Documented in
+ * docs/components/build-archive.mdx.
+ *
+ * **Artifact-type-keyed generation.** "Generate an SBOM" has a different
+ * real implementation per artifact type — an image asks BuildKit or scans
+ * the built image with `syft`; a JAR is scanned with `syft` or
+ * `cyclonedx-maven`; a zip/Lambda package is scanned with `syft`; a bare
+ * source directory is scanned with `syft`/`cdxgen`. `SbomGenerator` is one
+ * interface with one method per artifact type — analogous to
+ * `PublishImageBackend` being one interface satisfied by two backends
+ * (./publish.ts) — so the *capability* (./sbom.ts) stays artifact-type
+ * agnostic and simply calls the method matching the archive entry it was
+ * handed.
+ */
+// `lockfileSbomGenerator` (#630's hermetic default, below) lives in
+// ./lockfile-sbom-generator.ts, which itself imports `DEFAULT_SBOM_FORMAT`/
+// `SbomGeneratorNotImplementedError` from *this* module — a deliberate
+// circular import. Safe here because the only use of `lockfileSbomGenerator`
+// in this file is inside `defaultSbomGenerator()`'s function body (evaluated
+// lazily, on first call), never at this module's own top-level/import time,
+// so it doesn't matter which module's evaluation finishes first.
+import { lockfileSbomGenerator } from "./lockfile-sbom-generator.js";
+/** Canonical media type per format, mirroring `BuildArchiveEntry.mediaType`'s convention (./build-archive.ts). */
+export const SBOM_MEDIA_TYPES = {
+    spdx: "application/spdx+json",
+    cyclonedx: "application/vnd.cyclonedx+json",
+};
+/** Project-wide default SBOM format when neither `chant.config.ts`'s `sbom.format` nor a component's `build.sbom.format` says otherwise. Documented in docs/components/build-archive.mdx. */
+export const DEFAULT_SBOM_FORMAT = "spdx";
+/**
+ * Thrown by `NotImplementedSbomGenerator` — the "no real backend wired yet"
+ * signal, matching `CapabilityNotImplementedError`'s role for verb stubs
+ * (../capability.ts). Kept distinct from a generic `Error` so callers (and
+ * tests) can assert on it specifically.
+ */
+export class SbomGeneratorNotImplementedError extends Error {
+    constructor(method) {
+        super(`SbomGenerator.${method} has no real implementation configured — inject a real generator ` +
+            `(shelling out to syft/buildx/cyclonedx-maven/cdxgen) or use a mock in tests`);
+        this.method = method;
+        this.name = "SbomGeneratorNotImplementedError";
+    }
+}
+/**
+ * All-throwing `SbomGenerator`: every method throws
+ * `SbomGeneratorNotImplementedError`. No longer the process-wide default (see
+ * `defaultSbomGenerator` below, #630) — kept exported for callers that
+ * deliberately want the loud, no-backend-at-all behavior (e.g. a test
+ * asserting on the thrown error itself, or a caller that wants to force
+ * "nothing is wired" rather than silently getting the hermetic backend).
+ */
+export const notImplementedSbomGenerator = {
+    async forImage() {
+        throw new SbomGeneratorNotImplementedError("forImage");
+    },
+    async forJar() {
+        throw new SbomGeneratorNotImplementedError("forJar");
+    },
+    async forZip() {
+        throw new SbomGeneratorNotImplementedError("forZip");
+    },
+    async forDir() {
+        throw new SbomGeneratorNotImplementedError("forDir");
+    },
+};
+/** Lazily-constructed process-wide default, mirroring ./cloud-executor.ts's `defaultCloudExecutor`. */
+let defaultGenerator;
+/**
+ * The default `SbomGenerator` the `generate-sbom` capability falls back to
+ * when none is supplied.
+ *
+ * **Hermetic by default (#630).** This is `./lockfile-sbom-generator.ts`'s
+ * `lockfileSbomGenerator` — `forDir`/`forZip`/`forJar` parse a
+ * `package-lock.json`/`pom.xml` already on disk (no `syft`, no network, no
+ * external tool) and emit a real SPDX/CycloneDX document. That means a
+ * newcomer composing `generate-sbom` over a source directory, a zip/Lambda
+ * package, or a JAR gets a working SBOM the moment they `chant run
+ * --components`, with nothing to install first — the whole point of #630's
+ * "runnable proof" bar. `forImage` still throws
+ * `SbomGeneratorNotImplementedError`: no hermetic backend can see an image's
+ * base layers, so an image SBOM still needs the real deep-scan tool backend
+ * (`syft`/`docker buildx --sbom`/`cyclonedx-maven`/`cdxgen`, #610) — a
+ * documented, deliberate gap, not an oversight. This was previously
+ * `notImplementedSbomGenerator` (every method throwing); switching the
+ * default is intentional per #630 — the prior "loud failure by default"
+ * traded newcomer runnability for a default nobody exercised without opting
+ * in, which #613 already built a hermetic backend to fix but never wired up.
+ * A project that truly wants the old all-throwing behavior can construct
+ * `createGenerateSbomCapability(notImplementedSbomGenerator)` explicitly.
+ */
+export function defaultSbomGenerator() {
+    if (!defaultGenerator)
+        defaultGenerator = lockfileSbomGenerator;
+    return defaultGenerator;
+}

package/dist/components/verbs/sbom.js

@@ -0,0 +1,97 @@
+/**
+ * `generate-sbom` capability (#606, epic #551 follow-up to #564's build
+ * archive / #568's build ledger — closes the "produce" side #568 explicitly
+ * deferred).
+ *
+ * One capability, artifact-type-keyed via the injectable `SbomGenerator`
+ * (./sbom-generator.ts — mirrors ./cloud-executor.ts's `CloudExecutor`
+ * pattern), so a build-producing component of *any* artifact type — image,
+ * JAR, zip/Lambda package, or a bare source directory for a config-only
+ * producer — generates its SBOM through the same verb. Never docker-only:
+ * dispatch is on `input.artifactType`, not on which build capability
+ * produced the artifact.
+ *
+ * Writes the result into the build-archive manifest as an `sbom`-kind entry
+ * (../verbs/build-archive.ts), content-addressed and linked to its subject
+ * artifact's digest via `subjectDigest` — the **universal home** for the
+ * SBOM regardless of artifact type or registry availability. Registering the
+ * SBOM as an OCI referrer for image artifacts at publish time is a separate,
+ * later concern (the publish step/registry tooling's job, see
+ * ../../lifecycle/build-ledger.ts's `ReferrerLookup` for the consume side);
+ * this capability only ever writes the archive-carried copy, so it works
+ * unconditionally — including the registry-less `load-image-on-host` path.
+ *
+ * Config-only / infra components have no built artifact and simply never
+ * compose this step into their `deploy`/`build` phase — "skips cleanly" is
+ * structural (no step to run), not a special case this module needs to
+ * detect. Opt-out is the same: a component that wants no SBOM omits the
+ * `generate-sbom` step from its composition.
+ */
+import { addArchiveEntry, archiveRelativePath, contentDigest, createBuildArchiveManifest, } from "./build-archive.js";
+import { defaultSbomGenerator, DEFAULT_SBOM_FORMAT, } from "./sbom-generator.js";
+/** Default archive path for a generated SBOM when `into` is omitted: `<artifact path>.sbom.json`. */
+function defaultSbomPath(artifactPath) {
+    return `${archiveRelativePath(artifactPath)}.sbom.json`;
+}
+/**
+ * Dispatch one `SbomGenerator` call by `artifactType` — the only place this
+ * capability branches on artifact type, matching how `selectPublishBackend`
+ * (./publish.ts) is the only place the publish family branches on backend
+ * kind. Never a component/cloud name, always an artifact shape.
+ */
+async function generate(generator, input, artifactPath) {
+    switch (input.artifactType) {
+        case "image":
+            return generator.forImage({ imagePath: artifactPath, digest: input.digest ?? "", format: input.format });
+        case "jar":
+            return generator.forJar({ jarPath: artifactPath, digest: input.digest ?? "", format: input.format });
+        case "zip":
+            return generator.forZip({ zipPath: artifactPath, digest: input.digest ?? "", format: input.format });
+        case "dir":
+            return generator.forDir({ path: artifactPath, format: input.format });
+    }
+}
+/**
+ * Generate an SBOM for a build-producing component's artifact (image, JAR,
+ * zip, or source directory) via the artifact-type-keyed `SbomGenerator`, and
+ * fold the result into the build-archive manifest as an `sbom`-kind entry
+ * linked to the subject artifact's digest. Format defaults to
+ * `DEFAULT_SBOM_FORMAT` (SPDX) when neither `input.format` nor the injected
+ * generator overrides it — see ./sbom-generator.ts's module doc for the
+ * full default-resolution story. `chant.config.ts`'s `sbom.format` (see
+ * ../../config.ts's `ChantConfig.sbom` and `resolveSbomFormat`) is resolved
+ * by the caller/orchestrator into `input.format` before this capability
+ * runs, the same way env config is resolved before any other capability's
+ * `run` (this module never imports ../../config.ts directly, matching how
+ * no other verb module does either).
+ *
+ * No rollback: an already-generated SBOM sitting in the archive (or, later,
+ * projected as a registry referrer) is immutable, content-addressed
+ * evidence — nothing to compensate, the same opt-out `docker-build` and
+ * `publish-image` already take for their own no-mutable-remote-state reason.
+ */
+export function createGenerateSbomCapability(generator = defaultSbomGenerator()) {
+    return {
+        kind: "generate-sbom",
+        async run(ctx, input) {
+            const artifactPath = archiveRelativePath(input.path);
+            const format = input.format ?? DEFAULT_SBOM_FORMAT;
+            const sbom = await generate(generator, { ...input, format }, artifactPath);
+            const into = input.into ?? defaultSbomPath(input.path);
+            const digest = contentDigest(sbom.bytes);
+            const base = input.manifest ?? createBuildArchiveManifest(ctx.component);
+            const manifest = addArchiveEntry(base, {
+                kind: "sbom",
+                path: into,
+                digest,
+                mediaType: sbom.mediaType,
+                subjectDigest: input.digest,
+                packageCount: sbom.packageCount,
+                generator: sbom.generator,
+            });
+            return { sbom, archivePath: into, digest, manifest };
+        },
+    };
+}
+/** Default `generate-sbom` capability, backed by the process-wide default `SbomGenerator` — the hermetic lockfile backend (#630), so `dir`/`zip`/`jar` work with no tool installed; only `forImage` throws until `toolSbomGenerator` is injected. See ./sbom-generator.ts's `defaultSbomGenerator`. */
+export const generateSbomCapability = createGenerateSbomCapability();

package/dist/components/verbs/shell.js

@@ -0,0 +1,32 @@
+/**
+ * escape hatch family — `shell`. Typed, but flagged: a raw shell step run by
+ * exactly one component is the "capability-per-component" smell the model
+ * exists to avoid (see docs/components/capabilities.mdx#the-discipline).
+ * `reason` is required so lint (COMP006) can flag an escape hatch used without
+ * a stated justification.
+ */
+import { defaultProcessRunner, q } from "./process-runner.js";
+import { releaseEnvironment } from "../../telemetry-attribution.js";
+/**
+ * Run an arbitrary shell command through the injectable {@link ProcessRunner}.
+ * The escape hatch — typed, lint-flagged, and requires a `reason`. A non-zero
+ * exit rejects (with the command's own stderr), failing the step like any other
+ * capability error, so `onFailure`/rollback fires.
+ */
+export function createShellCapability(processRunner = defaultProcessRunner()) {
+    return {
+        kind: "shell",
+        async run(ctx, input) {
+            // A release run exports its attributes (#3061, ws-081), so a `docker compose up` here fills the
+            // Compose file's `${CHANT_RELEASE_ATTRIBUTES:-}`. A value the step sets itself wins.
+            const env = { ...releaseEnvironment(ctx.release), ...(input.env ?? {}) };
+            const envPrefix = Object.keys(env).length > 0
+                ? `env ${Object.entries(env).map(([k, v]) => `${k}=${q(v)}`).join(" ")} `
+                : "";
+            const { stdout } = await processRunner.run(`${envPrefix}${input.cmd}`, { cwd: input.cwd });
+            return { stdout, exitCode: 0 };
+        },
+    };
+}
+/** Default `shell` capability, backed by the real process runner. */
+export const shellCapability = createShellCapability();

package/dist/components/verbs/sign.js

@@ -0,0 +1,221 @@
+/**
+ * `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.
+ *
+ * **#1943 extension (`run-agent` interop).** `BuildProvenanceStatementInput`
+ * gained two optional merge fields, `externalParameters`/`internalParameters`
+ * — additive only, every existing call site's statement is byte-identical
+ * without them. `run-agent` (./run-agent.ts's `buildRunAgentProvenanceStatement`)
+ * is the first caller to use them, plus `buildType` (already overridable,
+ * unchanged here) set to a `run-agent`-specific recipe URI. `predicateType`
+ * stays `"https://slsa.dev/provenance/v1"` for every caller, `run-agent`
+ * included — see ./run-agent.ts's own doc comment ("Attestation interop")
+ * for why a turn is attested as an SLSA-shaped provenance predicate rather
+ * than under a minted `run-agent`-specific `predicateType`, and why that
+ * decision means `sign`/`attestProvenance`/`../verbs/verify.ts` needed zero
+ * changes to their `cosign` invocations to attest/verify a turn.
+ */
+import { defaultProcessRunner, q, requireTool } from "./process-runner.js";
+// ── 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(ref, verb) {
+        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.ref = ref;
+        this.verb = verb;
+        this.name = "SignTargetNotDigestError";
+    }
+}
+/** True if `ref` carries an `@sha256:<hex>` digest — the only form `sign`/`attest` accept. */
+function isDigestRef(ref) {
+    return /@sha256:[0-9a-f]{64}$/i.test(ref);
+}
+/** Throw `SignTargetNotDigestError` unless `ref` is digest-qualified. */
+function assertDigestRef(ref, verb) {
+    if (!isDigestRef(ref))
+        throw new SignTargetNotDigestError(ref, verb);
+}
+/** 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, opts) {
+    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));
+}
+/** 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) {
+    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 = defaultProcessRunner()) {
+    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 = createSignCapability();
+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) {
+    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) {
+    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,
+                // Reserved keys spread LAST so a caller-supplied key can never clobber
+                // them into a signed statement that disagrees with resolvedDependencies.
+                externalParameters: { ...input.externalParameters, sourceRef: input.provenance.sourceRef },
+                internalParameters: { ...input.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(),
+                },
+            },
+        },
+    };
+}
+/**
+ * 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, predicatePath) {
+    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 = defaultProcessRunner()) {
+    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 = createAttestProvenanceCapability();

package/dist/components/verbs/stub.js

@@ -0,0 +1,28 @@
+/**
+ * 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 { CapabilityNotImplementedError } from "../capability.js";
+/**
+ * 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(kind, opts) {
+    const capability = {
+        kind,
+        async run() {
+            throw new CapabilityNotImplementedError(kind);
+        },
+    };
+    if (opts?.rollback) {
+        capability.rollback = async () => {
+            throw new CapabilityNotImplementedError(kind);
+        };
+    }
+    return capability;
+}

package/dist/components/verbs/tool-sbom-generator.js

@@ -0,0 +1,154 @@
+/**
+ * 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, } from "./sbom-generator.js";
+import { defaultProcessRunner, q, requireTool } from "./process-runner.js";
+/** `syft`'s CycloneDX/SPDX JSON output format flags, keyed by `SbomFormat`. */
+const SYFT_FORMAT = {
+    spdx: "spdx-json",
+    cyclonedx: "cyclonedx-json",
+};
+/** `cdxgen` only emits CycloneDX; SPDX is not one of its output formats. */
+const CDXGEN_FORMAT = "cyclonedx";
+/** 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, bytes) {
+    try {
+        const doc = JSON.parse(bytes);
+        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, subject, format) {
+    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 = {}) {
+    const runner = options.runner ?? defaultProcessRunner();
+    async function runSyft(target, format) {
+        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) {
+            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) {
+            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) {
+            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) {
+            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 = createToolSbomGenerator();