@xemahq/xema 0.40.2 → 0.41.0

package/edition/build-runtime-image-source-index.mjs

@@ -4,9 +4,10 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 
+import { buildValidatedPlatformServiceIndex } from './build-platform-service-index.mjs';
 import { connectorCrossRepoBuildInputs } from './connector-source-authority.mjs';
 import { editionWorkspaceConfig, workspaceSection } from './edition-config.mjs';
-import { biomeIndexPath, dataRoot, runtimeImageSourceIndexPath, WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath } from './edition-workspace.mjs';
+import { biomeIndexPath, dataRoot, platformServiceIndexPath, runtimeImageSourceIndexPath, WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, sourcePath } from './edition-workspace.mjs';
 import { COMMIT_PATTERN } from './evidence-grammars.mjs';
 import {
   buildTrustedKernelContractAuthority,
@@ -15,8 +16,10 @@ import {
   validateKernelContractAuthorityFromGit,
 } from './kernel-contract-authority.mjs';
 import {
+  buildBiomeIndex,
   canonicalPublicHttpsRepositoryUrl,
   compareStrings,
+  distributionBiomeSourceRepositories,
   loadKernelDistributionSchemas,
   readGitJsonAtCommit,
   serializeJson,
@@ -27,6 +30,7 @@ import {
 } from './platform-service-source-authority.mjs';
 import {
   createExactCommitSourceAuthority,
+  createPinnedSourceAuthority,
   createSourceAuthority,
   parseSourceModeArgs,
 } from './source-authority.mjs';
@@ -140,7 +144,7 @@ function declaredSourceRepositories() {
  * ONE authority that answers both questions about a component, never two
  * competing ones that can disagree about which commit a component is at.
  */
-function repositoryIdentity(repo, sourceAuthority) {
+export function repositoryIdentity(repo, sourceAuthority) {
   const repoDirectory = sourcePath(repo);
   const sourceCommit = sourceAuthority.commitForRepository(repo);
   const vendoredSourceCommit =
@@ -834,6 +838,107 @@ function parseKernelCommit(argv) {
   };
 }
 
+/**
+ * @param {{ schemas: object, repositoryPins: object[], kernelRoot?: string, producerWorkflowPins?: object[] }} request
+ * `kernelRoot` is the kernel checkout the committed contract authority is re-verified against
+ * (the default checkout when omitted); `producerWorkflowPins` are the operator-stated ones a
+ * trusted write merges over the committed ones.
+ * @returns {{ platformServiceIndex, biomeIndex, runtimeImageSourceIndex }}
+ */
+export async function buildIndexesAtPins({ schemas, repositoryPins, kernelRoot, producerWorkflowPins = [] }) {
+  const sourceAuthority = createPinnedSourceAuthority({ pins: repositoryPins });
+  const platformServiceIndex = buildValidatedPlatformServiceIndex(schemas, sourceAuthority);
+  const biomeIndex = await buildBiomeIndex(platformServiceIndex, distributionBiomeSourceRepositories(), sourceAuthority);
+  const runtimeImageSourceIndex = schemas.parseRuntimeImageSourceIndex(
+    await buildTrustedIndex(schemas, sourceAuthority, kernelRoot, undefined, {
+      biomeIndex,
+      platformServiceIndex,
+      producerWorkflowPins,
+    }),
+  );
+  await validateRuntimeImageSourceIndex(runtimeImageSourceIndex, schemas, { biomeIndex, platformServiceIndex, kernelRoot });
+  return { platformServiceIndex, biomeIndex, runtimeImageSourceIndex };
+}
+
+/**
+ * A repository JOINING the index (`--repo <repository>` with no committed pin): all three indexes,
+ * from ONE resolution of the joining repository, with every committed pin kept.
+ *
+ * WHY HERE AND NOT A `--repo` ON THE BIOME BUILDER. The biome builder's `--repo` was removed
+ * because it resolved the scoped repository LIVE a second time, so a build landing between the two
+ * commands split the two artifacts on exactly that repository (see `build-biome-index.mjs`). A
+ * joining repository has the same shape: the runtime index cannot take it until the biome index
+ * names its biomes, and the biome index cannot take it until a pin exists. So the joining
+ * repository is resolved ONCE here (`sourceAuthority`, live or `--at`), appended to the committed
+ * pins, and every index is derived from that one pin set by the same builders a develop snapshot
+ * uses; nothing else is resolved live.
+ *
+ * Every committed pin that survives must come back field for field; one that differs is refused by
+ * name. A committed pin whose repository is no longer a source repository is DROPPED, and the caller
+ * names it (`describeRepositoryPinChanges`). A second declared repository with no pin is refused by
+ * the pinned authority: one joining repository per write.
+ */
+export async function buildIndexesWithJoiningRepository({
+  schemas,
+  sourceAuthority,
+  repoScope,
+  committedPins,
+  kernelRoot,
+  producerWorkflowPins = [],
+}) {
+  if (committedPins.some((pin) => pin.repo === repoScope)) {
+    throw new Error(`--repo "${repoScope}" already has a committed pin: it is a refresh, not a join`);
+  }
+  const kept = committedPins.map(({ repo, repositoryUrl, sourceCommit, vendoredSourceCommit }) => ({
+    repo,
+    repositoryUrl,
+    sourceCommit,
+    vendoredSourceCommit,
+  }));
+  const repositoryPins = [...kept, repositoryIdentity(repoScope, sourceAuthority)];
+  const built = await buildIndexesAtPins({ schemas, repositoryPins, kernelRoot, producerWorkflowPins });
+  const written = new Map(built.runtimeImageSourceIndex.repositoryPins.map((pin) => [pin.repo, pin]));
+  const moved = kept.filter((pin) => written.has(pin.repo) && serializeJson(written.get(pin.repo)) !== serializeJson(pin));
+  if (moved.length > 0) {
+    throw new Error(
+      `a join must keep every committed pin, and ${moved.map((pin) => pin.repo).join(', ')} came back different ` +
+        '(its repositoryUrl no longer matches its origin remote?)',
+    );
+  }
+  if (!written.has(repoScope)) {
+    throw new Error(
+      `--repo "${repoScope}" contributes no biome, platform service or supplemental subject at ` +
+        `${repositoryPins.at(-1).sourceCommit}: there is nothing for it to join`,
+    );
+  }
+  return built;
+}
+
+/**
+ * What a write did to the committed `repositoryPins`, by NAME: the repositories added, the ones
+ * dropped (a committed pin whose repository no longer sources any subject), the ones moved, and
+ * how many were kept unchanged. A count alone hid a dropped pin inside "N other pin(s)
+ * preserved", which is the one change a reviewer must see.
+ */
+export function describeRepositoryPinChanges(committedPins, writtenPins) {
+  const committed = new Map((committedPins ?? []).map((pin) => [pin.repo, pin]));
+  const written = new Map(writtenPins.map((pin) => [pin.repo, pin]));
+  const added = [...written.keys()].filter((repo) => !committed.has(repo)).sort(compareStrings);
+  const dropped = [...committed.keys()].filter((repo) => !written.has(repo)).sort(compareStrings);
+  const moved = [...written.keys()]
+    .filter((repo) => committed.has(repo) && serializeJson(committed.get(repo)) !== serializeJson(written.get(repo)))
+    .sort(compareStrings);
+  const kept = written.size - added.length - moved.length;
+  const named = (label, repos) => `${label} ${repos.length}${repos.length > 0 ? ` (${repos.join(', ')})` : ''}`;
+  return {
+    added,
+    dropped,
+    moved,
+    kept,
+    summary: `${named('added', added)}; ${named('moved', moved)}; ${named('dropped', dropped)}; kept ${kept} unchanged`,
+  };
+}
+
 const REPIN_FLAG = '--repin-contract-authority';
 const USAGE =
   'usage: build-runtime-image-source-index.mjs (--check | --check-sources | --trusted-write | ' +
@@ -898,55 +1003,78 @@ async function main() {
     );
     return;
   }
-  const candidate = schemas.parseRuntimeImageSourceIndex(
-    await buildTrustedIndex(
+  const committedPins = existsSync(runtimeImageSourceIndexPath())
+    ? readJson(runtimeImageSourceIndexPath()).repositoryPins ?? []
+    : [];
+  const liveAuthority = () => createSourceAuthority({ mode, knownRepositories: declaredSourceRepositories() });
+  const sourceAuthority =
+    exactCommit === undefined
+      ? liveAuthority()
+      : createExactCommitSourceAuthority({ delegate: liveAuthority(), repo: repoScope, commit: exactCommit });
+  // A `--repo` with no committed pin JOINS the index, and the biome and platform-service indexes
+  // must take it in the same write: see `buildIndexesWithJoiningRepository`.
+  const joining = repoScope !== undefined && !committedPins.some((pin) => pin.repo === repoScope);
+  let candidate;
+  let joined;
+  if (joining) {
+    if (committedPins.length === 0) {
+      throw new Error(
+        `--repo requires ${runtimeImageSourceIndexPath()} with committed repositoryPins: there are none to keep. ` +
+          'Bootstrap with --trusted-write and no --repo.',
+      );
+    }
+    if (kernelCommit !== undefined) {
+      throw new Error(`${KERNEL_COMMIT_FLAG} chooses a new contract authority; a join keeps the committed one`);
+    }
+    joined = await buildIndexesWithJoiningRepository({
       schemas,
-      exactCommit === undefined
-        ? createSourceAuthority({
-            mode,
-            knownRepositories: declaredSourceRepositories(),
-          })
-        : createExactCommitSourceAuthority({
-            delegate: createSourceAuthority({
-              mode,
-              knownRepositories: declaredSourceRepositories(),
-            }),
-            repo: repoScope,
-            commit: exactCommit,
-          }),
-      kernelRoot,
+      sourceAuthority,
       repoScope,
-      {
+      committedPins,
+      kernelRoot,
+      producerWorkflowPins,
+    });
+    candidate = joined.runtimeImageSourceIndex;
+  } else {
+    candidate = schemas.parseRuntimeImageSourceIndex(
+      await buildTrustedIndex(schemas, sourceAuthority, kernelRoot, repoScope, {
         biomeIndex: readJson(biomeIndexPath()),
         platformServiceIndex: readJson(join(dataRoot(), 'platform-service-index.json')),
         kernelCommit,
         producerWorkflowPins,
-      },
-    ),
-  );
-  await validateRuntimeImageSourceIndex(candidate, schemas, { kernelRoot });
+      }),
+    );
+    await validateRuntimeImageSourceIndex(candidate, schemas, { kernelRoot });
+  }
+  const outputs = [
+    [runtimeImageSourceIndexPath(), serializeJson(candidate)],
+    ...(joined === undefined
+      ? []
+      : [
+          [biomeIndexPath(), serializeJson(joined.biomeIndex)],
+          [platformServiceIndexPath(), serializeJson(joined.platformServiceIndex)],
+        ]),
+  ];
   if (flag === '--check-sources') {
-    if (
-      readFileSync(runtimeImageSourceIndexPath(), 'utf8') !==
-      serializeJson(candidate)
-    ) {
+    const stale = outputs.filter(([path, text]) => !existsSync(path) || readFileSync(path, 'utf8') !== text);
+    if (stale.length > 0) {
       throw new Error(
-        'runtime-image-source-index.json does not match exact trusted sources',
+        `${stale.map(([path]) => path).join(', ')} does not match exact trusted sources`,
       );
     }
     console.log('[runtime-image-source-index] trusted source check passed');
     return;
   }
-  writeFileSync(runtimeImageSourceIndexPath(), serializeJson(candidate));
+  for (const [path, text] of outputs) {writeFileSync(path, text);}
+  const changes = describeRepositoryPinChanges(committedPins, candidate.repositoryPins);
   console.log(
-    `[runtime-image-source-index] wrote ${runtimeImageSourceIndexPath()}` +
-      (repoScope === undefined
-        ? ' (all repository pins re-resolved)'
-        : ` (${
-            exactCommit === undefined
-              ? `re-resolved ${repoScope}`
-              : `pinned ${repoScope} at the exact commit ${exactCommit}`
-          }; ${candidate.repositoryPins.length - 1} other pin(s) preserved)`),
+    `[runtime-image-source-index] wrote ${outputs.map(([path]) => path).join(', ')} (${
+      repoScope === undefined
+        ? 'all repository pins re-resolved'
+        : `${joining ? 'joined' : 're-resolved'} ${repoScope}${
+            exactCommit === undefined ? '' : ` at the exact commit ${exactCommit}`
+          }`
+    }; ${changes.summary})`,
   );
 }
 

package/edition/catalogue-evidence.mjs

@@ -0,0 +1,225 @@
+// catalogue-evidence — the catalogue's signed E4 evidence, verified BEFORE the catalogue is read.
+//
+// A release catalogue is the ceiling of everything resolved against it, so its bytes are not parsed, and not even
+// fetched, until the E4 statement over its digest, catalogue layer and lock layer has been verified against the evidence
+// trust policy of the CALLER'S OWN data root (never the vendor's). The statement is an `oras attach` referrer of the
+// edition artifact digest (`EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE`): two layers, `statement.json` (in-toto) and
+// `bundle.sigstore.json` (the Sigstore bundle), and the exact commit of the signing workflow as an annotation.
+//
+// The verification is ONE seam, `verifyCatalogueEvidenceReferrer`, and it is done by the data root's PINNED built
+// verifier (`catalogue-evidence verify`, verify-catalogue-evidence.mjs): there is no second verifier. The only
+// kernel-dependent parts of the judgement are the policy schema (parseSigstoreOfflineTrustPolicy) and the
+// predicate-type/channel constants; before the catalogue's kernel is adopted (kernel-package.mjs) there is no kernel
+// package to load them from, so they come from the pinned bundle's own embedded kernel. The library never judges the
+// statement itself: it checks the referrer's layout, hands the two blobs to the bundle (only after the bundle's digests
+// equal the data-root pin; otherwise CatalogueVerifierNotPinnedError, before anything is spawned) and reads its verdict.
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { locateBuiltVerifier, readBuiltVerifierDigests } from './built-verifier.mjs';
+import { editionWorkspaceConfig } from './edition-config.mjs';
+import { dataRoot as configuredDataRoot } from './edition-workspace.mjs';
+import { assertPinnedVerifier, readEvidenceTrustPin } from './evidence-trust-pin.mjs';
+import { EvidenceTrustRequiredError } from './evidence-trust-policy.mjs';
+import { EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE } from './oci-image-source-evidence.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+
+const TITLE = 'org.opencontainers.image.title';
+/** The titles of the two layers of an E4 referrer, the in-toto statement's media type and the annotation naming the signing workflow commit. */
+export const CATALOGUE_EVIDENCE_STATEMENT_TITLE = 'statement.json';
+export const CATALOGUE_EVIDENCE_BUNDLE_TITLE = 'bundle.sigstore.json';
+export const CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE = 'application/vnd.in-toto+json';
+export const CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION = 'dev.xema.evidence.signer-workflow-sha';
+/** The variables the pinned verifier bundle is launched with (it refuses NODE_OPTIONS, NODE_PATH, DYLD_*, LD_*, GIT_*). */
+export const VERIFIER_LAUNCH_ENV_KEYS = Object.freeze(['PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_ALL', 'TZ']);
+const STATEMENT_MAX_BYTES = 2 * 1024 * 1024;
+const BUNDLE_MAX_BYTES = 16 * 1024 * 1024;
+const SPAWN_TIMEOUT_MS = 120_000;
+const COMMIT = /^[a-f0-9]{40}$/;
+const sha256Of = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+
+/** No E4 referrer is attached to the artifact: the catalogue has no signed evidence at all. */
+export class CatalogueEvidenceMissingError extends Error {
+  constructor(ref) {
+    super(
+      `${ref} carries no ${EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE} referrer: its catalogue has no signed edition evidence (E4), ` +
+        'so it is refused before it is read',
+    );
+    this.name = 'CatalogueEvidenceMissingError';
+  }
+}
+
+/** An E4 referrer exists but does not verify against the caller's evidence trust policy. */
+export class CatalogueEvidenceNotVerifiedError extends Error {
+  constructor(ref, reason) {
+    super(`${ref}: the catalogue's edition evidence (E4) is not verified: ${reason}; the catalogue is refused before it is read`);
+    this.name = 'CatalogueEvidenceNotVerifiedError';
+  }
+}
+
+/** The built verifier is not the one the data root pins (or is missing): nothing is spawned. */
+export class CatalogueVerifierNotPinnedError extends Error {
+  constructor(reason) {
+    super(`the catalogue's edition evidence (E4) cannot be verified: this CLI's built evidence verifier is not the one the data root pins: ${reason}`);
+    this.name = 'CatalogueVerifierNotPinnedError';
+  }
+}
+
+/** The pinned built verifier's bundle path, after the data root's pin of it held; refuses before anything is spawned. */
+function pinnedVerifierBundle(locateVerifier) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  if (declaration.policy === null) {throw new EvidenceTrustRequiredError(root, 'declares no policy');}
+  try {
+    const pin = readEvidenceTrustPin({ dataRoot: root, declaration });
+    assertPinnedVerifier({ pin, actual: readBuiltVerifierDigests(locateVerifier) });
+    return { bundlePath: locateVerifier().bundlePath, root };
+  } catch (error) {
+    throw new CatalogueVerifierNotPinnedError(error.message);
+  }
+}
+
+function launchEnvironment(source = process.env) {
+  const reduced = {};
+  for (const key of VERIFIER_LAUNCH_ENV_KEYS) {
+    if (source[key] !== undefined) {reduced[key] = source[key];}
+  }
+  return reduced;
+}
+
+function runVerifier({ spawn, bundlePath, args }) {
+  return spawn(process.execPath, [bundlePath, 'catalogue-evidence', ...args], {
+    encoding: 'utf8',
+    env: launchEnvironment(),
+    timeout: SPAWN_TIMEOUT_MS,
+    maxBuffer: 1024 * 1024,
+  });
+}
+
+const stderrOf = (result) => String(result.stderr ?? '').trim() || (result.error ? result.error.message : `exit ${String(result.status)}`);
+
+/**
+ * Before any registry call: the caller's data root declares a policy, the built verifier is the one the pin records, and
+ * the policy is ARMED on `channel` with the E4 row required (the one arming rule, judged by the pinned bundle with its own
+ * kernel). Throws EvidenceTrustRequiredError for no policy / not armed, CatalogueVerifierNotPinnedError for a verifier the
+ * pin does not record.
+ *
+ * @param {{ channel: string, locateVerifier?: Function, spawn?: Function }} options
+ */
+export function assertCatalogueConsumerArmed({ channel, locateVerifier = locateBuiltVerifier, spawn = spawnSync }) {
+  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier);
+  const result = runVerifier({ spawn, bundlePath, args: ['arming', '--channel', channel, '--data-root', root] });
+  if (result.status === 0) {return;}
+  const stderr = stderrOf(result);
+  if (stderr.includes('EVIDENCE_TRUST_REQUIRED_UNARMED')) {
+    throw new EvidenceTrustRequiredError(root, `declares a policy that is not armed on the ${channel} channel for a catalogue consumer (${stderr})`);
+  }
+  throw new CatalogueEvidenceNotVerifiedError(`the ${channel} catalogue`, `the arming check failed: ${stderr}`);
+}
+
+function layerOf(layers, title, mediaType, ref) {
+  const found = layers.filter((layer) => layer?.annotations?.[TITLE] === title);
+  if (found.length !== 1 || found[0].mediaType !== mediaType || typeof found[0].digest !== 'string') {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `the referrer must carry exactly one ${title} layer of media type ${mediaType}`);
+  }
+  return found[0];
+}
+
+async function readReferrerLayers({ client, repository, referrer, manifestDigest, ref }) {
+  const manifest = await client.getManifestByDigest(repository, referrer.digest);
+  const document = manifest.document ?? {};
+  if (document.artifactType !== EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} is not a ${EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE} artifact`);
+  }
+  if (document.subject?.digest !== manifestDigest) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} is a referrer of ${String(document.subject?.digest)}, not of ${manifestDigest}`);
+  }
+  const layers = Array.isArray(document.layers) ? document.layers : [];
+  if (layers.length !== 2) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} must carry exactly two layers (${CATALOGUE_EVIDENCE_STATEMENT_TITLE}, ${CATALOGUE_EVIDENCE_BUNDLE_TITLE}), it carries ${layers.length}`);
+  }
+  const statement = layerOf(layers, CATALOGUE_EVIDENCE_STATEMENT_TITLE, CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE, ref);
+  const bundle = layerOf(layers, CATALOGUE_EVIDENCE_BUNDLE_TITLE, BUNDLE_MEDIA_TYPE, ref);
+  const workflowSha = document.annotations?.[CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION];
+  if (typeof workflowSha !== 'string' || !COMMIT.test(workflowSha)) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, `referrer ${referrer.digest} states no 40-hex ${CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION} annotation`);
+  }
+  return { statement, bundle, workflowSha };
+}
+
+/**
+ * The seam. Hold one E4 referrer to the caller's policy and to the exact catalogue and lock layers: read its two layers
+ * (bounded) into a private temporary directory and have the PINNED built verifier judge them. Throws when it does not
+ * verify, returns when it does. The verifier's pin is re-checked here, before anything is spawned.
+ *
+ * @param {{ ref: string, client: object, repository: string, referrer: object, channel: string, offeringId: string, manifestDigest: string, catalogueLayerDigest: string, lockLayerDigest: string, cosign: string, locateVerifier?: Function, spawn?: Function }} subject
+ */
+export async function verifyCatalogueEvidenceReferrer({
+  ref,
+  client,
+  repository,
+  referrer,
+  channel,
+  offeringId,
+  manifestDigest,
+  catalogueLayerDigest,
+  lockLayerDigest,
+  cosign,
+  locateVerifier = locateBuiltVerifier,
+  spawn = spawnSync,
+}) {
+  if (typeof cosign !== 'string' || !cosign.startsWith('/')) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, 'a release catalogue is verified with a cosign binary: pass --cosign <absolute path>');
+  }
+  const layers = await readReferrerLayers({ client, repository, referrer, manifestDigest, ref });
+  const statementBytes = await client.getBlob(repository, layers.statement.digest, STATEMENT_MAX_BYTES);
+  const bundleBytes = await client.getBlob(repository, layers.bundle.digest, BUNDLE_MAX_BYTES);
+  if (sha256Of(statementBytes) !== layers.statement.digest || sha256Of(bundleBytes) !== layers.bundle.digest) {
+    throw new CatalogueEvidenceNotVerifiedError(ref, 'a referrer layer does not hash to its digest');
+  }
+  const { bundlePath, root } = pinnedVerifierBundle(locateVerifier);
+  const evidenceRoot = mkdtempSync(join(tmpdir(), 'xema-catalogue-evidence-'));
+  try {
+    writeFileSync(join(evidenceRoot, CATALOGUE_EVIDENCE_STATEMENT_TITLE), statementBytes, { flag: 'wx', mode: 0o600 });
+    writeFileSync(join(evidenceRoot, CATALOGUE_EVIDENCE_BUNDLE_TITLE), bundleBytes, { flag: 'wx', mode: 0o600 });
+    const result = runVerifier({
+      spawn,
+      bundlePath,
+      args: [
+        'verify',
+        '--channel', channel,
+        '--data-root', root,
+        '--evidence-root', evidenceRoot,
+        '--statement-digest', layers.statement.digest,
+        '--bundle-digest', layers.bundle.digest,
+        '--workflow-sha', layers.workflowSha,
+        '--offering-id', offeringId,
+        '--subject-digest', manifestDigest,
+        '--catalogue-layer-digest', catalogueLayerDigest,
+        '--lock-layer-digest', lockLayerDigest,
+        '--cosign', cosign,
+      ],
+    });
+    if (result.status !== 0) {throw new CatalogueEvidenceNotVerifiedError(ref, stderrOf(result));}
+  } finally {
+    rmSync(evidenceRoot, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Verify the catalogue's E4 evidence from the registry, before any catalogue byte is fetched or parsed.
+ *
+ * @param {{ client: object, ref: string, repository: string, manifestDigest: string, channel: string, offeringId: string, catalogueLayerDigest: string, lockLayerDigest: string, cosign?: string, locateVerifier?: Function, verifyReferrer?: Function }} options
+ */
+export async function verifyCatalogueEvidence({ client, ref, repository, manifestDigest, channel, offeringId, catalogueLayerDigest, lockLayerDigest, cosign, locateVerifier, verifyReferrer = verifyCatalogueEvidenceReferrer }) {
+  const listed = await client.listReferrers(repository, manifestDigest, EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE);
+  const referrers = listed.filter((descriptor) => descriptor?.artifactType === EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE);
+  if (referrers.length === 0) {throw new CatalogueEvidenceMissingError(ref);}
+  for (const referrer of referrers) {
+    await verifyReferrer({ ref, client, repository, referrer, channel, offeringId, manifestDigest, catalogueLayerDigest, lockLayerDigest, cosign, ...(locateVerifier === undefined ? {} : { locateVerifier }) });
+  }
+}

package/edition/catalogue-fetch.mjs

@@ -13,9 +13,10 @@
 
 import { Buffer } from 'node:buffer';
 
+import { verifyCatalogueEvidence } from './catalogue-evidence.mjs';
 import { CATALOGUE_FILE, CatalogueError, parseCatalogue } from './catalogue.mjs';
 import { parseEditionRepository } from './edition-artifact.mjs';
-import { EDITION_ARTIFACT_TYPE } from './edition-constants.mjs';
+import { EDITION_ARTIFACT_TYPE, EditionChannel, EditionLockFile } from './edition-constants.mjs';
 import { OrasRegistry } from './oras.mjs';
 import { splitImageRef } from './registry-credentials.mjs';
 
@@ -55,8 +56,23 @@ export function catalogueCredential({ authority, username, tokenEnv, env = proce
   return { authority, access: 'authenticated', basicAuth: Buffer.from(`${username}:${token}`, 'utf8').toString('base64') };
 }
 
-/** Fetch and strictly parse the catalogue of the artifact at `ref`, resolving for `channel`. `client` is injectable for tests. */
-export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = process.env, client }) {
+/** The one layer of `manifest` titled `title`; an offering artifact carries exactly one of each. */
+export function layerTitled(manifest, title, ref) {
+  const layers = (manifest.document.layers ?? []).filter((layer) => layer.annotations?.[TITLE] === title);
+  if (layers.length !== 1) {
+    throw new CatalogueError(`${ref} carries ${layers.length} layers titled ${title}; an offering artifact carries exactly one`);
+  }
+  return layers[0];
+}
+
+/**
+ * Fetch and strictly parse the catalogue of the artifact at `ref`, resolving for `channel`. A RELEASE catalogue is read
+ * only after its E4 evidence verified against the caller's own evidence trust policy (catalogue-evidence.mjs): the
+ * verification precedes the blob fetch and the parse, so an unverified catalogue is never read. It is done by the data
+ * root's pinned built verifier, with the absolute `cosign` the caller names. `client` and `verifyEvidence` are injectable
+ * for tests.
+ */
+export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = process.env, client, cosign, locateVerifier, verifyEvidence = verifyCatalogueEvidence }) {
   const { authority, repository, digest, edition } = parseCatalogueRef(ref);
   if (edition.channel !== channel) {
     throw new CatalogueError(
@@ -69,11 +85,22 @@ export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = p
   if (manifest.isIndex || manifest.document.artifactType !== EDITION_ARTIFACT_TYPE) {
     throw new CatalogueError(`${ref} is not an edition artifact (artifactType ${JSON.stringify(manifest.document.artifactType)}, expected ${EDITION_ARTIFACT_TYPE})`);
   }
-  const layers = (manifest.document.layers ?? []).filter((layer) => layer.annotations?.[TITLE] === CATALOGUE_FILE);
-  if (layers.length !== 1) {
-    throw new CatalogueError(`${ref} carries ${layers.length} layers titled ${CATALOGUE_FILE}; an offering artifact carries exactly one`);
+  const catalogueLayer = layerTitled(manifest, CATALOGUE_FILE, ref);
+  if (channel === EditionChannel.Release) {
+    await verifyEvidence({
+      client: registry,
+      ref,
+      repository,
+      manifestDigest: digest,
+      channel,
+      offeringId: edition.distributionId,
+      cosign,
+      locateVerifier,
+      catalogueLayerDigest: catalogueLayer.digest,
+      lockLayerDigest: layerTitled(manifest, EditionLockFile.Distribution, ref).digest,
+    });
   }
-  const bytes = await registry.getBlob(repository, layers[0].digest, CATALOGUE_MAX_BYTES);
+  const bytes = await registry.getBlob(repository, catalogueLayer.digest, CATALOGUE_MAX_BYTES);
   let document;
   try {
     document = JSON.parse(bytes.toString('utf8'));
@@ -81,6 +108,12 @@ export async function fetchCatalogue({ ref, channel, username, tokenEnv, env = p
     throw new CatalogueError(`${ref}: ${CATALOGUE_FILE} is not JSON: ${error.message}`);
   }
   const catalogue = parseCatalogue(document);
+  if (catalogue.offeringId !== edition.distributionId) {
+    throw new CatalogueError(
+      `${ref}: ${CATALOGUE_FILE} is the catalogue of offering ${catalogue.offeringId}, but it was fetched from the repository of offering ${edition.distributionId}; ` +
+        'an artifact whose stated offering differs from its repository is refused',
+    );
+  }
   if (catalogue.channel !== edition.channel) {
     throw new CatalogueError(
       `${ref}: ${CATALOGUE_FILE} states channel ${catalogue.channel}, but it was fetched from the ${edition.channel} repository ${authority}/${repository}; ` +