@xemahq/xema 0.48.0 → 0.49.1

package/edition/third-party-bundle-registry.mjs

@@ -0,0 +1,147 @@
+// The registry side of the third-party writer (XEMA-1611 design section 3 (a)): the biome bundle, by digest, and the
+// sigstore bundle of its SLSA provenance, read as an OCI referrer. Nothing here is trusted: every byte it returns is
+// verified by cosign (`third-party-source-evidence.mjs`) before it is committed.
+
+import { execFileSync } from 'node:child_process';
+
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
+import { COSIGN_ENV, decodeExactUtf8, sha256Digest, validatePinnedTrustedRoot } from './image-evidence.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+import { SLSA_PROVENANCE_V1, decodeJsonStatement, digestOfOciRef } from './third-party-source-evidence.mjs';
+import { assertPreparedExecutable } from './trusted-executable.mjs';
+
+const BIOME_MANIFEST_FILE = 'xema-biome.json';
+const BIOME_GENERATED_INDEX_FILE = 'xema-biome.index.json';
+const OCI_TITLE_ANNOTATION = 'org.opencontainers.image.title';
+const MAX_BIOME_MANIFEST_BYTES = 4 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
+const REGISTRY_COSIGN_TIMEOUT_MS = 120_000;
+/** What `cosign verify-attestation --type` calls the SLSA v1 provenance predicate. */
+const COSIGN_SLSA_PROVENANCE_ALIAS = 'slsaprovenance1';
+
+const repositoryOf = (ociRef) => splitImageRef(ociRef.slice(0, ociRef.indexOf('@')));
+
+/**
+ * The biome bundle manifest JSON (`xema-biome.json`) of an OCI artifact, fetched by digest.
+ *
+ * @returns {Promise<{manifest: object, bytes: Buffer}>}
+ */
+export async function fetchBundleManifest({ clientFor, ociRef }) {
+  const bytes = await fetchTitledLayer({ clientFor, ociRef, title: BIOME_MANIFEST_FILE });
+  return { manifest: decodeJsonStatement(bytes, `${ociRef} ${BIOME_MANIFEST_FILE}`), bytes };
+}
+
+/**
+ * The committed generated index (`xema-biome.index.json`) of an OCI biome bundle, fetched by digest: the authority for
+ * the biomes the bundle requires, read from the same bundle bytes as its manifest, so it cannot describe another revision.
+ */
+export async function fetchBundleGeneratedIndex({ clientFor, ociRef }) {
+  const bytes = await fetchTitledLayer({ clientFor, ociRef, title: BIOME_GENERATED_INDEX_FILE });
+  return decodeJsonStatement(bytes, `${ociRef} ${BIOME_GENERATED_INDEX_FILE}`);
+}
+
+/** The one layer of the bundle manifest at `ociRef` (by digest) annotated with `title`. */
+async function fetchTitledLayer({ clientFor, ociRef, title }) {
+  const { authority, repository } = repositoryOf(ociRef);
+  const client = clientFor(authority);
+  const { document } = await client.getManifestByDigest(repository, digestOfOciRef(ociRef));
+  const layers = (document.layers ?? []).filter((layer) => layer.annotations?.[OCI_TITLE_ANNOTATION] === title);
+  if (layers.length !== 1) {
+    throw new Error(`${ociRef} has ${layers.length} layers titled ${title}; a biome bundle has exactly one`);
+  }
+  const bytes = await client.getBlob(repository, layers[0].digest, MAX_BIOME_MANIFEST_BYTES);
+  if (sha256Digest(bytes) !== layers[0].digest) {
+    throw new Error(`${ociRef} layer titled ${title} does not match its descriptor`);
+  }
+  return bytes;
+}
+
+/**
+ * The image names a biome manifest ships: its service and worker components with an `oci-image` artifact, named the way
+ * the index builder names them (a service by `protocol.serviceName`, a worker by its component `key`).
+ */
+export function bundleImageNames(manifest) {
+  const components = Array.isArray(manifest?.xema?.components) ? manifest.xema.components : [];
+  return new Set(
+    components
+      .filter((component) => (component?.kind === 'service' || component?.kind === 'worker') && component.artifact?.kind === 'oci-image')
+      .map((component) => (component.kind === 'service' ? component.protocol?.serviceName : component.key)),
+  );
+}
+
+function provenanceOf(bundleBytes, bundleDigest) {
+  const bundle = JSON.parse(decodeExactUtf8(bundleBytes, 'sigstore bundle'));
+  if (bundle?.dsseEnvelope === undefined) {
+    return null; // a message-signature bundle (the artifact signature): not an attestation
+  }
+  const payload = Buffer.from(bundle.dsseEnvelope.payload, 'base64');
+  const statement = decodeJsonStatement(payload, 'DSSE payload');
+  if (statement.predicateType !== SLSA_PROVENANCE_V1) {
+    return null;
+  }
+  if (`sha256:${statement.subject?.[0]?.digest?.sha256}` !== bundleDigest) {
+    throw new Error(`a SLSA provenance referrer attests ${statement.subject?.[0]?.digest?.sha256}, not ${bundleDigest}`);
+  }
+  return { statementBytes: payload, bundleBytes };
+}
+
+/**
+ * The SLSA provenance attestation of the bundle: the one sigstore-bundle referrer of `ociRef` whose DSSE statement is a
+ * `https://slsa.dev/provenance/v1` attestation over exactly this digest. None, or more than one, is refused.
+ *
+ * @returns {Promise<{statementBytes: Buffer, bundleBytes: Buffer}>}
+ */
+export async function fetchBundleProvenance({ clientFor, ociRef }) {
+  const { authority, repository } = repositoryOf(ociRef);
+  const client = clientFor(authority);
+  const subjectDigest = digestOfOciRef(ociRef);
+  const referrers = await client.listReferrers(repository, subjectDigest, BUNDLE_MEDIA_TYPE);
+  const found = [];
+  for (const referrer of referrers) {
+    const { document } = await client.getManifestByDigest(repository, referrer.digest);
+    for (const layer of document.layers ?? []) {
+      if (layer.mediaType !== BUNDLE_MEDIA_TYPE) {continue;}
+      const bytes = await client.getBlob(repository, layer.digest, MAX_BUNDLE_BYTES);
+      if (sha256Digest(bytes) !== layer.digest) {
+        throw new Error(`${ociRef} referrer ${referrer.digest} layer does not match its descriptor`);
+      }
+      const provenance = provenanceOf(bytes, subjectDigest);
+      if (provenance !== null) {found.push(provenance);}
+    }
+  }
+  if (found.length === 0) {
+    throw new Error(`${ociRef} has no SLSA provenance attestation (${SLSA_PROVENANCE_V1}) among its ${referrers.length} sigstore-bundle referrers; the bundle must be published with provenance`);
+  }
+  if (found.length > 1) {
+    throw new Error(`${ociRef} has ${found.length} SLSA provenance attestations; exactly one is required, so the evidence is unambiguous`);
+  }
+  return found[0];
+}
+
+const tail = (error) => String(error?.stderr ?? error?.message ?? error).trim().split('\n').slice(-4).join(' | ').slice(0, 1024);
+
+/**
+ * (a) against the registry: keyless `cosign verify` and `cosign verify-attestation --type slsaprovenance1` of the bundle
+ * artifact under EXACTLY the signer row's identity and issuer, the row's workflow repository, ref and the stated
+ * commit, the pinned trusted root and the trusted cosign binary. `--offline` verifies the tlog inclusion proof carried
+ * with the signature; the tlog is never ignored. The registry credential is the operator's (HOME / DOCKER_CONFIG).
+ */
+export function verifyBundleOnRegistry({ trustedCosign, policy, policyRoot, row, workflowSha, ociRef, env = process.env }) {
+  const root = validatePinnedTrustedRoot(policyRoot, policy);
+  const common = ['--offline', '--trusted-root', root.path, ...certificateConstraintArgs(row, workflowSha)];
+  const environment = {
+    ...COSIGN_ENV,
+    ...(env.HOME === undefined ? {} : { HOME: env.HOME }),
+    ...(env.DOCKER_CONFIG === undefined ? {} : { DOCKER_CONFIG: env.DOCKER_CONFIG }),
+  };
+  const run = (command, args) => {
+    try {
+      execFileSync(assertPreparedExecutable(trustedCosign, 'cosign'), [command, ...args], { env: environment, stdio: ['ignore', 'ignore', 'pipe'], timeout: REGISTRY_COSIGN_TIMEOUT_MS });
+    } catch (error) {
+      throw new Error(`cosign ${command} refused ${ociRef} under row "${row.policyId}": ${tail(error)}`);
+    }
+  };
+  run('verify', [...common, ociRef]);
+  run('verify-attestation', ['--type', COSIGN_SLSA_PROVENANCE_ALIAS, ...common, ociRef]);
+}

package/edition/third-party-certificate-extensions.mjs

@@ -0,0 +1,21 @@
+// (d) of the third-party checks: the Fulcio extensions of a bundle's leaf certificate, held to a source pin. Its own module
+// (it imports no evidence module) because admission in `image-evidence.mjs` and the pin verifier both use it.
+
+import { FulcioExtensionOid, GITHUB_HOSTED_RUNNER_ENVIRONMENT, readFulcioExtensionsFromBundle } from './fulcio-certificate-extensions.mjs';
+
+/** The leaf certificate of a parsed Sigstore `bundle` states the pinned repository id, owner id and a GitHub-hosted runner. */
+export function assertCertificateExtensions({ bundle, source, label }) {
+  const read = readFulcioExtensionsFromBundle(bundle);
+  const expectations = [
+    [FulcioExtensionOid.SourceRepositoryIdentifier, 'Source Repository Identifier', read.sourceRepositoryIdentifier, source.repositoryId, 'repositoryId'],
+    [FulcioExtensionOid.SourceRepositoryOwnerIdentifier, 'Source Repository Owner Identifier', read.sourceRepositoryOwnerIdentifier, source.repositoryOwnerId, 'repositoryOwnerId'],
+    [FulcioExtensionOid.RunnerEnvironment, 'Runner Environment', read.runnerEnvironment, GITHUB_HOSTED_RUNNER_ENVIRONMENT, GITHUB_HOSTED_RUNNER_ENVIRONMENT],
+  ];
+  for (const [oid, name, actual, expected, pinned] of expectations) {
+    if (actual !== expected) {
+      throw new Error(
+        `${label} certificate ${name} (${oid}) is ${JSON.stringify(actual)}, but the pin requires ${JSON.stringify(expected)} (${pinned})`,
+      );
+    }
+  }
+}

package/edition/third-party-image-pins.mjs

@@ -0,0 +1,41 @@
+// The pinned images of the third-party subjects of an images lock (XEMA-1611 design sections 3 and 4).
+//
+// A third-party subject's `contentHash` is the PUBLISHER'S `sourceTreeHash` (publisher-attested): it is never a registry
+// tag. Every seal, coverage and evidence-set path that serves such a subject goes to the pin instead: the image is read
+// BY the pin's `manifestDigest` and its evidence is the committed evidence the pin's `statementDigest` and `bundleDigest`
+// bind. This module is the one place a subject is joined to its pinned image.
+
+/** The `kind:id` key of an image subject, as the seal reports and the digest plans spell it. */
+export const imageSubjectKey = (subject) => `${subject.kind}:${subject.id}`;
+
+/**
+ * The pinned image of every third-party subject of `subjects`, by `kind:id`. A subject is third-party when its `repo` is a
+ * pinned third-party repository. Refuses a third-party subject the pin pins no image for, and one whose `imageRef` or
+ * `contentHash` is not the pin image's `imageRef` and `sourceTreeHash`.
+ *
+ * @param {{pins: {byRepository: (repository: string) => object|undefined}, subjects: readonly object[]}} request
+ * @returns {Map<string, object>}
+ */
+export function thirdPartyImagePins({ pins, subjects }) {
+  const pinned = new Map();
+  for (const subject of subjects) {
+    const pin = pins.byRepository(subject.repo);
+    if (pin === undefined) {continue;}
+    const key = imageSubjectKey(subject);
+    const image = pin.images.find((candidate) => candidate.subjectKind === subject.kind && candidate.subjectId === subject.id);
+    if (image === undefined) {
+      throw new Error(`${key} is a subject of the third-party repository "${subject.repo}" (source "${pin.name}"), but the pin pins no image for ${key}`);
+    }
+    if (subject.imageRef !== image.imageRef) {
+      throw new Error(`${key} (third-party source "${pin.name}") has imageRef ${subject.imageRef}, but the pin pins ${image.imageRef}`);
+    }
+    if (subject.contentHash !== image.sourceTreeHash) {
+      throw new Error(`${key} (third-party source "${pin.name}") has contentHash ${subject.contentHash}, but the pin's publisher-attested sourceTreeHash is ${image.sourceTreeHash}`);
+    }
+    pinned.set(key, image);
+  }
+  return pinned;
+}
+
+/** The `kind:id` -> manifestDigest map the platform verifier reads pinned subjects by. */
+export const pinnedManifestDigests = (pinnedImages) => new Map([...pinnedImages].map(([key, image]) => [key, image.manifestDigest]));

package/edition/third-party-pins-trusted.mjs

@@ -0,0 +1,24 @@
+// The data root's third-party source pins, read by a consumer that does not run the full evidence verification (the
+// develop and release seals): held to the evidence trust pin's record of the pin file's digest exactly as the verifiers
+// hold it (`assertPinnedThirdPartySourcePins`), so a pin file changed after the trust pin was last taken is refused.
+
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { assertPinnedThirdPartySourcePins, readEvidenceTrustPin } from './evidence-trust-pin.mjs';
+import { THIRD_PARTY_SOURCE_PINS_FILE, loadThirdPartySourcePins, thirdPartySourcePinsDigest } from './third-party-source-pins.mjs';
+
+/**
+ * @param {string} dataRoot
+ * @returns the loaded third-party source pins, or an empty set when the data root has none and declares no trust pin
+ */
+export function loadTrustedThirdPartySourcePins(dataRoot) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  if (declaration.policy === null) {
+    const digest = thirdPartySourcePinsDigest(dataRoot);
+    if (digest !== null) {
+      throw new Error(`the data root holds ${THIRD_PARTY_SOURCE_PINS_FILE} (${digest}) but declares no evidenceTrustPolicy, so there is no trust pin to hold it to`);
+    }
+    return loadThirdPartySourcePins(dataRoot);
+  }
+  assertPinnedThirdPartySourcePins({ pin: readEvidenceTrustPin({ dataRoot, declaration }), dataRoot });
+  return loadThirdPartySourcePins(dataRoot);
+}

package/edition/third-party-producer-evidence.mjs

@@ -0,0 +1,76 @@
+// The producer record of one third-party image subject in an evidence set (XEMA-1611 design section 4).
+//
+// A first-party subject's evidence is read from the registry (the OCI referrer of `<imageRef>:<contentHash>`). A
+// third-party subject has no such tag: its `contentHash` is the publisher's attested `sourceTreeHash`. Its evidence is
+// the COMMITTED evidence of the data root (`evidence/sha256-<manifest hex>/producer-evidence.json` + statements/ +
+// bundles/) that its pin binds by `statementDigest` and `bundleDigest`. This reads that evidence, holds it to the pin
+// and to the subject, and returns the SAME record shape the first-party branch of `resolveProducerEvidence` builds.
+// It makes no registry call.
+
+import { canonicalJson, decodeExactUtf8, evidenceDirectoryForDigest, sha256Digest } from './image-evidence.mjs';
+import { readBoundedNoFollowFile } from './no-follow-file.mjs';
+import { validateProducedBundle } from './produce-image-source-evidence.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+import { committedImageDescriptor } from './third-party-source-evidence.mjs';
+
+/** The bound committed evidence files are read at (the same as the first-party committed reads). */
+const MAX_EVIDENCE_FILE_BYTES = 4 * 1024 * 1024;
+
+/**
+ * @param {object} request
+ * @param {object} request.subject the third-party image subject (sealed or not)
+ * @param {object} request.pinImage its image in the third-party source pin
+ * @param {string} request.dataRoot the data root holding the committed evidence
+ * @param {object} request.schemas trusted kernel distribution schemas
+ * @param {object} request.expectedSource the canonical `predicate.source` the statement must attest
+ * @param {string} request.stem the producer's staging stem
+ */
+export function thirdPartyProducerRecord({ subject, pinImage, dataRoot, schemas, expectedSource, stem }) {
+  const key = `${subject.kind}:${subject.id}`;
+  const label = `third-party ${key} committed evidence`;
+  const descriptor = committedImageDescriptor({ image: pinImage, evidenceRoot: dataRoot, label });
+  const statementBytes = readBoundedNoFollowFile(dataRoot, descriptor.statementPath, `${label} statement`, MAX_EVIDENCE_FILE_BYTES).bytes;
+  const bundleBytes = readBoundedNoFollowFile(dataRoot, descriptor.bundlePath, `${label} bundle`, MAX_EVIDENCE_FILE_BYTES).bytes;
+  if (sha256Digest(statementBytes) !== pinImage.statementDigest) {
+    throw new Error(`${label}: the committed statement ${descriptor.statementPath} is ${sha256Digest(statementBytes)}, not the pin's statementDigest ${pinImage.statementDigest}`);
+  }
+  if (sha256Digest(bundleBytes) !== pinImage.bundleDigest) {
+    throw new Error(`${label}: the committed bundle ${descriptor.bundlePath} is ${sha256Digest(bundleBytes)}, not the pin's bundleDigest ${pinImage.bundleDigest}`);
+  }
+  validateProducedBundle(statementBytes, bundleBytes);
+  const statement = schemas.parseImageProducerStatement(JSON.parse(decodeExactUtf8(statementBytes, 'committed statement')));
+  if (canonicalJson(statement.predicate.source) !== canonicalJson(expectedSource)) {
+    throw new Error(`${label}: the committed statement attests another source than the one ${key} is locked at (${subject.repo}@${subject.sourceCommit}, publisher-attested source tree ${subject.contentHash})`);
+  }
+  const { artifact } = statement.predicate;
+  if (artifact.imageRepository !== subject.imageRef || statement.subject[0].name !== subject.imageRef) {
+    throw new Error(`${label}: it attests image "${artifact.imageRepository}" (statement subject "${statement.subject[0].name}"), not the locked "${subject.imageRef}"`);
+  }
+  if (`sha256:${statement.subject[0].digest.sha256}` !== artifact.manifestDigest) {
+    throw new Error(`${label}: its statement subject digest sha256:${statement.subject[0].digest.sha256} is not its artifact.manifestDigest ${artifact.manifestDigest}`);
+  }
+  if (artifact.manifestDigest !== pinImage.manifestDigest) {
+    throw new Error(`${label}: the committed statement attests manifest ${artifact.manifestDigest}, not the pin's manifestDigest ${pinImage.manifestDigest}`);
+  }
+  if (subject.imageDigest !== undefined && subject.imageDigest !== artifact.manifestDigest) {
+    throw new Error(`${label}: ${key} is sealed at ${subject.imageDigest}, but the committed statement attests manifest ${artifact.manifestDigest}`);
+  }
+  return {
+    stem,
+    subjectKind: subject.kind,
+    subjectId: subject.id,
+    imageRepository: subject.imageRef,
+    manifestDigest: artifact.manifestDigest,
+    statement,
+    sourceDirectory: evidenceDirectoryForDigest(pinImage.manifestDigest),
+    statementBytes,
+    bundleBytes,
+    evidence: {
+      statementPath: `producers/${stem}/statement.json`,
+      statementDigest: sha256Digest(statementBytes),
+      bundlePath: `producers/${stem}/bundle.sigstore.json`,
+      bundleDigest: sha256Digest(bundleBytes),
+      bundleMediaType: BUNDLE_MEDIA_TYPE,
+    },
+  };
+}

package/edition/third-party-source-check.mjs

@@ -0,0 +1,28 @@
+// `xema edition index runtime-image-source --check-third-party` (XEMA-1611 design section 3, `--check`): re-run checks
+// (a) to (e) for every pin of `third-party-source-pins.json` from the COMMITTED evidence, offline. A data root with no
+// pin file has no third-party source and passes trivially (zero-config); a pin file that is present but wrong throws.
+
+import { loadThirdPartySourceContext } from './third-party-source-context.mjs';
+import { verifyThirdPartySourceEvidence } from './third-party-source-evidence.mjs';
+import { loadThirdPartySourcePins } from './third-party-source-pins.mjs';
+import { assertThirdPartyUniqueness } from './third-party-source-uniqueness.mjs';
+
+/**
+ * @returns {Promise<{checked: number, absence: string|null}>}
+ */
+export async function checkThirdPartySourcePins({ dataRoot, schemas, cosignBinary }) {
+  const pins = loadThirdPartySourcePins(dataRoot);
+  if (pins.sources.length === 0) {
+    return { checked: 0, absence: pins.absence };
+  }
+  const context = loadThirdPartySourceContext({ dataRoot, schemas, cosignBinary });
+  try {
+    assertThirdPartyUniqueness({ sources: pins.sources, ...context });
+    for (const source of pins.sources) {
+      verifyThirdPartySourceEvidence({ source, evidenceRoot: dataRoot, context });
+    }
+  } finally {
+    context.dispose();
+  }
+  return { checked: pins.sources.length, absence: null };
+}

package/edition/third-party-source-context.mjs

@@ -0,0 +1,41 @@
+// What the third-party writer and `--check-third-party` verify a pin AGAINST: the data root's pinned trust policy, its
+// pinned kernel contract authority, its committed indexes and a cosign binary held to the policy's digest pins.
+// One loader, so the two cannot be given different trust.
+
+import { join } from 'node:path';
+
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { RUNTIME_IMAGE_SOURCE_INDEX_FILE, loadPinnedDeclaredTrustPolicy, readPinnedKernelContractAuthority } from './evidence-trust-pin.mjs';
+import { prepareTrustedCosignBinary } from './image-evidence.mjs';
+import { readStrictJsonFile } from './strict-json.mjs';
+
+/**
+ * Load the verification context of `dataRoot`. Throws when the data root declares no evidence trust policy, when the
+ * policy or the third-party pin file is not the one the evidence trust pin records (review, then
+ * `xema edition repin-evidence-trust`), or when the cosign binary is not one the policy pins.
+ *
+ * @returns {{policy, policyRoot, schemas, expectedContractAuthority, runtimeSourceIndex, biomeIndex, platformServiceIndex, trustedCosign, dispose: () => void}}
+ */
+export function loadThirdPartySourceContext({ dataRoot, schemas, cosignBinary }) {
+  if (cosignBinary === undefined) {
+    throw new Error('verifying a third-party source needs a cosign binary: pass --cosign <absolute path> (`dist-check` reads XEMA_COSIGN_BIN); it must be one the trust policy pins by digest');
+  }
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const policy = loadPinnedDeclaredTrustPolicy({ dataRoot, declaration, schemas });
+  const expectedContractAuthority = readPinnedKernelContractAuthority({ dataRoot, declaration, schemas });
+  const runtimeSourceIndex = schemas.parseRuntimeImageSourceIndex(readStrictJsonFile(join(dataRoot, RUNTIME_IMAGE_SOURCE_INDEX_FILE)));
+  const biomeIndex = readStrictJsonFile(join(dataRoot, 'biome-index.json'));
+  const platformServiceIndex = readStrictJsonFile(join(dataRoot, 'platform-service-index.json'));
+  const trustedCosign = prepareTrustedCosignBinary({ cosignBinary, policy });
+  return {
+    policy,
+    policyRoot: dataRoot,
+    schemas,
+    expectedContractAuthority,
+    runtimeSourceIndex,
+    biomeIndex,
+    platformServiceIndex,
+    trustedCosign,
+    dispose: () => trustedCosign.dispose(),
+  };
+}

package/edition/third-party-source-evidence.mjs

@@ -0,0 +1,255 @@
+// Re-verification of ONE third-party source pin from its COMMITTED evidence (XEMA-1611 design section 3, checks
+// (a) to (d)). The trusted writer runs it on the evidence it is about to commit, and `--check-third-party` runs it
+// on the committed tree, so the two cannot disagree about what a pin proves. Nothing here reads a network: the
+// signatures are verified by `verifySigstoreEvidenceDescriptor` (cosign `verify-blob-attestation --offline` against the
+// pinned trusted root, the tlog inclusion proof taken from the committed bundle, never `--insecure-ignore-tlog`).
+//
+// Where the evidence lives, relative to the data root:
+//   third-party-provenance/sha256-<bundle manifest hex>/{statement.json,bundle.sigstore.json}
+//       the SLSA provenance attestation of the biome bundle (the bytes cosign signed, which are not canonical JSON);
+//   evidence/sha256-<image manifest hex>/producer-evidence.json (+ statements/, bundles/)
+//       the image-source/v2 evidence, stored the way a first-party producer commits it.
+
+import { decodeExactUtf8, evidenceDirectoryForDigest, verifySigstoreEvidenceDescriptor } from './image-evidence.mjs';
+import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
+import { readBoundedNoFollowFile } from './no-follow-file.mjs';
+import { PRODUCER_EVIDENCE_INDEX_FILE } from './producer-evidence-index-file.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+import { assertCertificateExtensions } from './third-party-certificate-extensions.mjs';
+
+export const THIRD_PARTY_PROVENANCE_ROOT = 'third-party-provenance';
+export const PROVENANCE_STATEMENT_FILE = 'statement.json';
+export const PROVENANCE_BUNDLE_FILE = 'bundle.sigstore.json';
+/** The SLSA v1 provenance predicate a biome bundle is attested with (what the fetcher's `verify-attestation --type` matches). */
+export const SLSA_PROVENANCE_V1 = 'https://slsa.dev/provenance/v1';
+export const GITHUB_ACTIONS_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
+/** The only channel a third-party source is admitted on: signed from refs/heads/main. */
+export const THIRD_PARTY_EVIDENCE_CHANNEL = 'release';
+
+const MAX_EVIDENCE_INDEX_BYTES = 4 * 1024 * 1024;
+const IN_TOTO_STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
+
+/** `third-party-provenance/sha256-<hex>` of an OCI manifest digest. */
+export function provenanceDirectoryForDigest(manifestDigest) {
+  return `${THIRD_PARTY_PROVENANCE_ROOT}/${evidenceDirectoryForDigest(manifestDigest).split('/')[1]}`;
+}
+
+/** The digest of an `<oci repository>@sha256:<hex>` reference. */
+export const digestOfOciRef = (ociRef) => ociRef.slice(ociRef.indexOf('@') + 1);
+
+/** The statement bytes are the DSSE payload cosign signed: exact UTF-8 JSON, not this CLI's canonical form. */
+export function decodeJsonStatement(bytes, label) {
+  try {
+    return JSON.parse(decodeExactUtf8(bytes, label));
+  } catch (error) {
+    throw new Error(`${label} is not exact UTF-8 JSON: ${error.message}`);
+  }
+}
+
+/** The in-toto statement of a provenance attestation, held to the shape this plane reads (subject digest, predicate type). */
+export function parseProvenanceStatement(value) {
+  const digest = value?.subject?.[0]?.digest?.sha256;
+  if (
+    value?._type !== IN_TOTO_STATEMENT_TYPE ||
+    value.predicateType !== SLSA_PROVENANCE_V1 ||
+    !Array.isArray(value.subject) ||
+    value.subject.length !== 1 ||
+    typeof digest !== 'string'
+  ) {
+    throw new Error(
+      `the bundle provenance is not an in-toto v1 statement of ${SLSA_PROVENANCE_V1} over exactly one subject`,
+    );
+  }
+  return value;
+}
+
+const readEvidenceFile = (root, path, label, maxBytes) => readBoundedNoFollowFile(root, path, label, maxBytes);
+
+/**
+ * The trust-policy row `policyId` names, held to everything a third-party signer row must be: one row, the release
+ * channel signed from refs/heads/main, the GitHub Actions issuer, the exact identity of its own workflow, and the
+ * pinned repository and workflow. Throws naming the row and the field.
+ */
+export function thirdPartySignerRow({ policy, policyId, source, schemas, label }) {
+  const rows = policy.policies.filter((row) => row.policyId === policyId);
+  if (rows.length !== 1) {
+    throw new Error(`${label}: the trust policy has ${rows.length} rows with policyId "${policyId}"; exactly one is required`);
+  }
+  const [row] = rows;
+  const ref = schemas.EVIDENCE_CHANNEL_REFS[THIRD_PARTY_EVIDENCE_CHANNEL];
+  if (row.channel !== THIRD_PARTY_EVIDENCE_CHANNEL || row.githubWorkflow?.ref !== ref) {
+    throw new Error(
+      `${label}: row "${policyId}" is not a ${THIRD_PARTY_EVIDENCE_CHANNEL} row signed from ${ref} ` +
+        `(channel ${JSON.stringify(row.channel)}, ref ${JSON.stringify(row.githubWorkflow?.ref)})`,
+    );
+  }
+  if (row.oidcIssuer !== GITHUB_ACTIONS_OIDC_ISSUER) {
+    throw new Error(`${label}: row "${policyId}" oidcIssuer ${JSON.stringify(row.oidcIssuer)} is not ${GITHUB_ACTIONS_OIDC_ISSUER}`);
+  }
+  const { repository, path } = row.githubWorkflow;
+  const identity = `https://github.com/${repository}/${path}@${ref}`;
+  if (row.certificateIdentity !== identity) {
+    throw new Error(`${label}: row "${policyId}" certificateIdentity ${JSON.stringify(row.certificateIdentity)} is not the exact workflow identity ${identity}`);
+  }
+  if (repository !== source.repository) {
+    throw new Error(`${label}: row "${policyId}" signs for ${repository}, but the source is pinned to ${source.repository}`);
+  }
+  if (path !== source.producerWorkflow.path) {
+    throw new Error(`${label}: row "${policyId}" signs workflow ${path}, but the source pins one workflow, ${source.producerWorkflow.path}`);
+  }
+  return row;
+}
+
+/** The policy narrowed to ONE row, so cosign is run with exactly that row's identity and issuer. */
+const exactRowPolicy = (policy, row) => ({ ...policy, policies: [row] });
+
+function verifiedBundleProvenance({ source, evidenceRoot, context, hold }) {
+  const label = `third-party source "${source.name}" bundle ${source.bundle.ociRef}`;
+  const row = thirdPartySignerRow({ policy: context.policy, policyId: source.bundle.signerPolicyId, source, schemas: context.schemas, label });
+  if (!row.predicateTypes.includes(SLSA_PROVENANCE_V1)) {
+    throw new Error(`${label}: row "${row.policyId}" does not authorize ${SLSA_PROVENANCE_V1}, so it is not a bundle signer`);
+  }
+  const directory = provenanceDirectoryForDigest(digestOfOciRef(source.bundle.ociRef));
+  let verified;
+  try {
+    verified = verifySigstoreEvidenceDescriptor({
+      evidenceRoot,
+      descriptor: {
+        statementPath: `${directory}/${PROVENANCE_STATEMENT_FILE}`,
+        statementDigest: source.bundle.statementDigest,
+        bundlePath: `${directory}/${PROVENANCE_BUNDLE_FILE}`,
+        bundleDigest: source.bundle.bundleDigest,
+        bundleMediaType: BUNDLE_MEDIA_TYPE,
+      },
+      policy: exactRowPolicy(context.policy, row),
+      policyRoot: context.policyRoot,
+      predicateType: SLSA_PROVENANCE_V1,
+      channel: THIRD_PARTY_EVIDENCE_CHANNEL,
+      expectedWorkflowSha: source.sourceCommit,
+      parseStatement: parseProvenanceStatement,
+      decodeStatement: decodeJsonStatement,
+      trustedCosign: context.trustedCosign,
+      holdProducerWorkflow: hold,
+    });
+  } catch (error) {
+    throw new Error(`${label}: ${error.message}`);
+  }
+  const attested = `sha256:${verified.statement.subject[0].digest.sha256}`;
+  if (attested !== digestOfOciRef(source.bundle.ociRef)) {
+    throw new Error(`${label}: the provenance attests ${attested}, not the pinned bundle digest ${digestOfOciRef(source.bundle.ociRef)}`);
+  }
+  const bundleBytes = readEvidenceFile(evidenceRoot, `${directory}/${PROVENANCE_BUNDLE_FILE}`, `${label} bundle`, 16 * 1024 * 1024).bytes;
+  assertCertificateExtensions({ bundle: JSON.parse(decodeExactUtf8(bundleBytes, `${label} bundle`)), source, label });
+  return { row, statement: verified.statement };
+}
+
+/** The `statementPath`/`bundlePath` the committed `producer-evidence.json` of an image's evidence directory gives its subject. */
+export function committedImageDescriptor({ image, evidenceRoot, label }) {
+  const directory = evidenceDirectoryForDigest(image.manifestDigest);
+  const index = JSON.parse(
+    decodeExactUtf8(readEvidenceFile(evidenceRoot, `${directory}/${PRODUCER_EVIDENCE_INDEX_FILE}`, `${label} producer evidence index`, MAX_EVIDENCE_INDEX_BYTES).bytes, `${label} producer evidence index`),
+  );
+  const entries = Array.isArray(index?.producerEvidence) ? index.producerEvidence : [];
+  const entry = entries.find((candidate) => candidate?.subjectKind === image.subjectKind && candidate?.subjectId === image.subjectId);
+  if (entry === undefined) {
+    throw new Error(`${label}: ${directory}/${PRODUCER_EVIDENCE_INDEX_FILE} carries no evidence for ${image.subjectKind}:${image.subjectId}`);
+  }
+  const { statementPath, bundlePath } = entry.evidence;
+  return {
+    statementPath: `${directory}/${statementPath}`,
+    statementDigest: image.statementDigest,
+    bundlePath: `${directory}/${bundlePath}`,
+    bundleDigest: image.bundleDigest,
+    bundleMediaType: BUNDLE_MEDIA_TYPE,
+  };
+}
+
+const repositoryPathOf = (repositoryUrl) => new URL(repositoryUrl).pathname.replace(/^\//u, '').replace(/\.git$/u, '');
+
+/** (c) for one image statement: one repository, one commit, the pinned subject and authority. */
+export function assertImageStatementBindsPin({ statement, source, image, expectedContractAuthority, label }) {
+  const { predicate } = statement;
+  const claimed = predicate.source;
+  const mismatch = (what, actual, expected) => {
+    throw new Error(`${label}: ${what} is ${JSON.stringify(actual)}, but the pin requires ${JSON.stringify(expected)}`);
+  };
+  assertKernelContractAuthorityEqual(predicate.contractAuthority, expectedContractAuthority, label);
+  if (repositoryPathOf(claimed.repositoryUrl) !== source.repository) {
+    mismatch('predicate source.repositoryUrl repository', repositoryPathOf(claimed.repositoryUrl), source.repository);
+  }
+  if (claimed.repo !== source.repository) {mismatch('predicate source.repo', claimed.repo, source.repository);}
+  if (claimed.path !== claimed.repo && !claimed.path.startsWith(`${claimed.repo}/`)) {
+    mismatch('predicate source.path (it must be the repository or a directory of it)', claimed.path, `${source.repository}[/<directory>]`);
+  }
+  if (predicate.producerRun.producerWorkflowSha !== source.sourceCommit) {
+    mismatch('predicate producerRun.producerWorkflowSha (the certificate workflow commit)', predicate.producerRun.producerWorkflowSha, source.sourceCommit);
+  }
+  if (claimed.sourceCommit !== predicate.producerRun.producerWorkflowSha) {
+    mismatch('predicate source.sourceCommit (it must be the commit the certificate was issued for)', claimed.sourceCommit, predicate.producerRun.producerWorkflowSha);
+  }
+  if (claimed.sourceManifestHash !== source.bundle.sourceManifestHash) {
+    mismatch('predicate source.sourceManifestHash', claimed.sourceManifestHash, source.bundle.sourceManifestHash);
+  }
+  if (claimed.kind !== image.subjectKind || claimed.id !== image.subjectId) {
+    mismatch('predicate source kind/id', `${claimed.kind}:${claimed.id}`, `${image.subjectKind}:${image.subjectId}`);
+  }
+  if (claimed.sourceTreeHash !== image.sourceTreeHash) {mismatch('predicate source.sourceTreeHash', claimed.sourceTreeHash, image.sourceTreeHash);}
+  if (claimed.sourceHashAlgorithm !== image.sourceHashAlgorithm) {
+    mismatch('predicate source.sourceHashAlgorithm', claimed.sourceHashAlgorithm, image.sourceHashAlgorithm);
+  }
+  if (predicate.artifact.imageRepository !== image.imageRef || statement.subject[0].name !== image.imageRef) {
+    mismatch('predicate artifact.imageRepository', predicate.artifact.imageRepository, image.imageRef);
+  }
+  if (predicate.artifact.manifestDigest !== image.manifestDigest) {
+    mismatch('predicate artifact.manifestDigest', predicate.artifact.manifestDigest, image.manifestDigest);
+  }
+}
+
+function verifiedImageEvidence({ source, image, evidenceRoot, context, hold, bundleRow }) {
+  const label = `third-party source "${source.name}" image ${image.imageRef}@${image.manifestDigest}`;
+  const row = thirdPartySignerRow({ policy: context.policy, policyId: image.policyId, source, schemas: context.schemas, label });
+  if (!row.imageRepositories?.includes(image.imageRef)) {
+    throw new Error(`${label}: row "${row.policyId}" does not list ${image.imageRef} in its imageRepositories`);
+  }
+  if (row.githubWorkflow.repository !== bundleRow.githubWorkflow.repository || row.githubWorkflow.path !== bundleRow.githubWorkflow.path) {
+    throw new Error(`${label}: row "${row.policyId}" signs a different workflow than the bundle signer "${bundleRow.policyId}"; a source has one workflow`);
+  }
+  const descriptor = committedImageDescriptor({ image, evidenceRoot, label });
+  let verified;
+  try {
+    verified = verifySigstoreEvidenceDescriptor({
+      evidenceRoot,
+      descriptor,
+      policy: exactRowPolicy(context.policy, row),
+      policyRoot: context.policyRoot,
+      predicateType: context.schemas.IMAGE_PRODUCER_PREDICATE_TYPE,
+      channel: THIRD_PARTY_EVIDENCE_CHANNEL,
+      imageRepository: image.imageRef,
+      expectedWorkflowSha: source.sourceCommit,
+      parseStatement: context.schemas.parseImageProducerStatement,
+      trustedCosign: context.trustedCosign,
+      holdProducerWorkflow: hold,
+    });
+  } catch (error) {
+    throw new Error(`${label}: ${error.message}`);
+  }
+  assertImageStatementBindsPin({ statement: verified.statement, source, image, expectedContractAuthority: context.expectedContractAuthority, label });
+  const bundleBytes = readEvidenceFile(evidenceRoot, descriptor.bundlePath, `${label} bundle`, 16 * 1024 * 1024).bytes;
+  assertCertificateExtensions({ bundle: JSON.parse(decodeExactUtf8(bundleBytes, `${label} bundle`)), source, label });
+  return verified.statement;
+}
+
+/**
+ * Checks (a) to (d) for one pin, from the evidence under `evidenceRoot`. `context` is
+ * `{policy, policyRoot, schemas, trustedCosign, expectedContractAuthority, runtimeSourceIndex}`; the runtime
+ * image source index must already carry `{repository, workflowCommit: sourceCommit}` in its `producerWorkflowPins`
+ * (the writer passes the index it is about to write), which `holdProducerWorkflow` then enforces unchanged.
+ */
+export function verifyThirdPartySourceEvidence({ source, evidenceRoot, context }) {
+  const hold = (producer) => context.schemas.producerWorkflowPinRefusal(context.runtimeSourceIndex, producer);
+  const bundle = verifiedBundleProvenance({ source, evidenceRoot, context, hold });
+  const images = source.images.map((image) =>
+    verifiedImageEvidence({ source, image, evidenceRoot, context, hold, bundleRow: bundle.row }),
+  );
+  return { bundle, images };
+}