@xemahq/xema 0.40.3 → 0.41.0

package/edition/produce-edition-catalogue-evidence.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// The edition catalogue statement (E4): "this offering artifact's catalogue layer and lock layer are these digests, on this
+// channel", signed by the vendor's release workflow and attached to the artifact as an `oras attach` referrer.
+//
+//   xema edition evidence statement catalogue stage|accept …
+//
+// `stage` reads the artifact manifest by digest, derives the statement from its catalogue layer and lock layer and writes
+// the canonical statement into a NEW staging directory, printing the signing plan; the caller signs it (`cosign
+// attest-blob`); `accept` re-derives the statement from the same flags, refuses staged bytes that differ, verifies the
+// signed bundle with cosign against the declared signer, seals the output (built from the re-derived files, never renamed
+// from the staging) and ATTACHES statement.json and bundle.sigstore.json to the artifact digest as a referrer carrying the
+// signing workflow's commit. A customer's pinned verifier reads exactly that referrer (catalogue-evidence.mjs).
+// This module never signs and never requests an OIDC token.
+
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+
+import {
+  CATALOGUE_EVIDENCE_BUNDLE_TITLE,
+  CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE,
+  CATALOGUE_EVIDENCE_STATEMENT_TITLE,
+  CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION,
+} from './catalogue-evidence.mjs';
+import { layerTitled, parseCatalogueRef } from './catalogue-fetch.mjs';
+import { CATALOGUE_FILE } from './catalogue.mjs';
+import {
+  acceptSignedEvidenceStatement,
+  assertPinnedCosignVersion,
+  evidenceChannelOfSigner,
+  loadPinnedTrustPolicy,
+  parseEvidenceCliFlags,
+  stageEvidenceStatement,
+} from './distribution-evidence-set.mjs';
+import { EDITION_ARTIFACT_TYPE, EditionLockFile } from './edition-constants.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromArgv, dataRoot, isEntryModule } from './edition-workspace.mjs';
+import { serializeJson } from './lib.mjs';
+import { EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE, createRegistryClientResolver } from './oci-image-source-evidence.mjs';
+import { githubWorkflowSigner } from './produce-distribution-completeness-evidence.mjs';
+import {
+  BUNDLE_MEDIA_TYPE,
+  assertGitHubProducerContext,
+  createCosignVerifier,
+  loadProducerKernelSchemas,
+} from './produce-image-source-evidence.mjs';
+import { assertStagedExactly, discardStaging, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
+
+const STATEMENT_TYPE = 'https://in-toto.io/Statement/v1';
+const hexOf = (digest) => digest.slice('sha256:'.length);
+
+const SHARED_FLAGS = Object.freeze([
+  'artifact',
+  'offering',
+  'staging',
+  'signer-repository',
+  'signer-ref',
+  'signer-workflow-path',
+  'github-repository',
+  'github-ref',
+  'github-sha',
+  'github-workflow-ref',
+]);
+
+/**
+ * The E4 statement of the offering artifact `artifact` (`oci://<repository>@sha256:<d>`), derived from the manifest the
+ * registry serves for that digest: its catalogue layer and lock layer, exactly as a customer's `fetchCatalogue` reads them.
+ * The channel is the signer's, and must be the repository's.
+ */
+export async function deriveEditionCatalogueStatement({ artifact, offeringId, signer, schemas, client }) {
+  const { repository, digest, edition } = parseCatalogueRef(artifact);
+  const channel = evidenceChannelOfSigner(signer, schemas);
+  if (edition.distributionId !== offeringId) {
+    throw new Error(`--offering ${offeringId} is not the offering of ${artifact} (its repository is the offering ${edition.distributionId})`);
+  }
+  if (edition.channel !== channel) {
+    throw new Error(`${artifact} is in a ${edition.channel} repository, but the signer signs for the ${channel} channel`);
+  }
+  const manifest = await client.getManifestByDigest(repository, digest);
+  if (manifest.isIndex || manifest.document.artifactType !== EDITION_ARTIFACT_TYPE) {
+    throw new Error(`${artifact} is not an edition artifact (artifactType ${JSON.stringify(manifest.document.artifactType)}, expected ${EDITION_ARTIFACT_TYPE})`);
+  }
+  const catalogueLayer = layerTitled(manifest, CATALOGUE_FILE, artifact);
+  const lockLayer = layerTitled(manifest, EditionLockFile.Distribution, artifact);
+  const statement = {
+    _type: STATEMENT_TYPE,
+    subject: [{ name: `xema-edition-${offeringId}`, digest: { sha256: hexOf(digest) } }],
+    predicateType: schemas.EDITION_CATALOGUE_PREDICATE_TYPE,
+    predicate: {
+      schemaVersion: 1,
+      offeringId,
+      channel,
+      catalogueDigest: catalogueLayer.digest,
+      lockDigest: hexOf(lockLayer.digest),
+    },
+  };
+  schemas.parseEditionCatalogueStatement(statement);
+  return { statement, channel, repository, subjectDigest: digest };
+}
+
+function signingOf({ derived, options }) {
+  return {
+    statement: derived.statement,
+    root: options.stagingDirectory,
+    statementPath: CATALOGUE_EVIDENCE_STATEMENT_TITLE,
+    bundlePath: CATALOGUE_EVIDENCE_BUNDLE_TITLE,
+    signer: options.signer,
+    certificateWorkflowSha: options.signingWorkflowSha,
+    predicateType: options.schemas.EDITION_CATALOGUE_PREDICATE_TYPE,
+  };
+}
+
+/** Stage the catalogue statement of an artifact for signing. Returns the signing plan and the statement. */
+export async function stageEditionCatalogueEvidence(options) {
+  const { stagingDirectory } = options;
+  if (typeof stagingDirectory !== 'string' || !isAbsolute(stagingDirectory)) {
+    throw new Error('the catalogue staging directory must be absolute');
+  }
+  if (existsSync(stagingDirectory)) {
+    throw new Error(`catalogue staging directory already exists: ${stagingDirectory}`);
+  }
+  assertGitHubProducerContext({ signer: options.signer, producerWorkflowSha: options.signingWorkflowSha }, options.githubContext);
+  const derived = await deriveEditionCatalogueStatement(options);
+  mkdirSync(stagingDirectory, { recursive: true, mode: 0o700 });
+  try {
+    const plan = stageEvidenceStatement(signingOf({ derived, options }));
+    return {
+      plan: { ...plan, kind: 'edition-catalogue', offeringId: options.offeringId, channel: derived.channel, subjectDigest: derived.subjectDigest },
+      statement: derived.statement,
+    };
+  } catch (error) {
+    rmSync(stagingDirectory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/**
+ * Accept the signed catalogue bundle, seal `outputDirectory` and attach its two files to the artifact digest as an
+ * `EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE` referrer. The output is BUILT from the re-derived statement and the
+ * canonicalized bundle, never renamed from the staging, which must hold exactly what stage recorded and does not outlive
+ * the accept.
+ */
+export async function acceptEditionCatalogueEvidence(options) {
+  const { outputDirectory, stagingDirectory, readCosignVersion, runCosign, client } = options;
+  if (
+    typeof outputDirectory !== 'string' ||
+    !isAbsolute(outputDirectory) ||
+    typeof stagingDirectory !== 'string' ||
+    !isAbsolute(stagingDirectory)
+  ) {
+    throw new Error('the catalogue output and staging directories must be absolute');
+  }
+  if (typeof readCosignVersion !== 'function' || typeof runCosign !== 'function') {
+    throw new Error('cosign seams are required');
+  }
+  const sealing = reserveSealing(outputDirectory, 'catalogue');
+  let derived;
+  try {
+    assertGitHubProducerContext({ signer: options.signer, producerWorkflowSha: options.signingWorkflowSha }, options.githubContext);
+    assertPinnedCosignVersion(readCosignVersion(), options.policy?.cosignVersion);
+    derived = await deriveEditionCatalogueStatement(options);
+  } catch (error) {
+    discardStaging(stagingDirectory);
+    throw error;
+  }
+  const descriptor = sealAccepted({
+    stagingDirectory,
+    sealing,
+    outputDirectory,
+    build: () => {
+      assertStagedExactly(stagingDirectory, [CATALOGUE_EVIDENCE_STATEMENT_TITLE, CATALOGUE_EVIDENCE_BUNDLE_TITLE]);
+      return acceptSignedEvidenceStatement({ ...signingOf({ derived, options }), sealingRoot: sealing, runCosign });
+    },
+  });
+  const referrerDigest = await client.attach(derived.repository, derived.subjectDigest, {
+    artifactType: EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE,
+    files: [
+      { path: descriptor.statementPath, mediaType: CATALOGUE_EVIDENCE_STATEMENT_MEDIA_TYPE },
+      { path: descriptor.bundlePath, mediaType: BUNDLE_MEDIA_TYPE },
+    ],
+    annotations: { [CATALOGUE_EVIDENCE_WORKFLOW_SHA_ANNOTATION]: options.signingWorkflowSha },
+    cwd: outputDirectory,
+  });
+  return {
+    outputDirectory,
+    statement: derived.statement,
+    channel: derived.channel,
+    subjectDigest: derived.subjectDigest,
+    referrerDigest,
+    descriptor,
+  };
+}
+
+async function main() {
+  const [phase, ...args] = configureEditionWorkspaceFromArgv(process.argv.slice(2), [WorkspaceRoot.Data, WorkspaceRoot.Kernel]);
+  if (phase !== 'stage' && phase !== 'accept') {
+    throw new Error('usage: xema edition evidence statement catalogue <stage|accept> …');
+  }
+  const flags = parseEvidenceCliFlags(args, {
+    single: phase === 'stage' ? SHARED_FLAGS : [...SHARED_FLAGS, 'output', 'cosign'],
+    repeated: [],
+  });
+  const { schemas } = await loadProducerKernelSchemas({ dataRoot: dataRoot() });
+  const artifact = flags.require('artifact');
+  const githubSha = flags.require('github-sha');
+  const { authority } = parseCatalogueRef(artifact);
+  const options = {
+    artifact,
+    offeringId: flags.require('offering'),
+    stagingDirectory: resolve(flags.require('staging')),
+    schemas,
+    policy: loadPinnedTrustPolicy({ dataRoot: dataRoot(), schemas }),
+    client: createRegistryClientResolver({ dataRoot: dataRoot() })(authority),
+    signer: githubWorkflowSigner({
+      repository: flags.require('signer-repository'),
+      ref: flags.require('signer-ref'),
+      path: flags.require('signer-workflow-path'),
+    }),
+    githubContext: {
+      repository: flags.require('github-repository'),
+      ref: flags.require('github-ref'),
+      sha: githubSha,
+      workflowRef: flags.require('github-workflow-ref'),
+    },
+    signingWorkflowSha: githubSha,
+  };
+  if (phase === 'stage') {
+    process.stdout.write(serializeJson((await stageEditionCatalogueEvidence(options)).plan));
+    return;
+  }
+  const result = await acceptEditionCatalogueEvidence({
+    ...options,
+    outputDirectory: resolve(flags.require('output')),
+    ...createCosignVerifier(resolve(flags.require('cosign'))),
+  });
+  process.stdout.write(
+    serializeJson({
+      schemaVersion: 1,
+      kind: 'edition-catalogue',
+      offeringId: options.offeringId,
+      channel: result.channel,
+      subjectDigest: result.subjectDigest,
+      referrerDigest: result.referrerDigest,
+      evidence: result.descriptor,
+    }),
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[edition-catalogue] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/edition/produce-image-source-evidence.mjs

@@ -36,6 +36,8 @@ import {
 } from './edition-workspace.mjs';
 import { COMMIT_PATTERN, GITHUB_REF_PATTERN, GITHUB_REPOSITORY_PATTERN, SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
 import {
+  KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE,
+  KernelContractAuthorityPinError,
   RUNTIME_IMAGE_SOURCE_INDEX_FILE,
   loadPinnedDeclaredTrustPolicy,
   readEvidenceTrustPin,
@@ -50,9 +52,9 @@ import {
 import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
 import { serializeJson } from './lib.mjs';
 import { assertStagedExactly, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
 
-export const BUNDLE_MEDIA_TYPE =
-  'application/vnd.dev.sigstore.bundle.v0.3+json';
+export { BUNDLE_MEDIA_TYPE };
 const STAGED_STATEMENTS_DIRECTORY = 'statements';
 const STAGED_BUNDLES_DIRECTORY = 'bundles';
 
@@ -135,6 +137,13 @@ export async function loadProducerKernelSchemas({
   }
   const expected = readRawContractAuthority(root);
   const pinned = readEvidenceTrustPin({ dataRoot: root, declaration }).kernelContractAuthority;
+  if (pinned === null) {
+    throw new KernelContractAuthorityPinError(
+      KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE,
+      `${RUNTIME_IMAGE_SOURCE_INDEX_FILE} at ${root} states kernel contract authority commit ${expected.sourceCommit} ` +
+        'but the evidence-trust pin records none; re-pin with `xema edition repin-evidence-trust`',
+    );
+  }
   if (expected.sourceCommit !== pinned.sourceCommit) {
     throw new Error(
       `${RUNTIME_IMAGE_SOURCE_INDEX_FILE} at ${root} states kernel contract authority commit ` +

package/edition/release-edition.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// release-edition — the customer RELEASE edition's command line: `xema edition release <verb> --definition <file>`.
+//
+// It is `xema edition develop <verb> --definition <file>` on the release channel: the same parser, the same frame
+// and the same verbs (customer-edition-verbs.mjs); only the inputs differ. The id is the definition's, and the
+// catalogue is the one pinned for `release` in catalogue.pin.json beside the definition.
+//
+//   freeze-sources --definition <file> --out <file>
+//       one `sources/<name>` pin per source the definition declares, each at the source's DECLARED ref (a branch,
+//       or a tag taken at its peeled commit); a ref that is both a branch and a tag, or missing, is refused.
+//       Written exclusively (wx).
+//   target --definition <file> --pins <file> --registry <root> --engine-image <repository>@sha256:<digest>
+//          [--source-image <source>=<registry>/<prefix>]...
+//       print <root>/<release segment>/xema-edition-<id>:<tag>, the tag being snapshotEditionTag of the CLI
+//       version, the engine image, the pins and the source-image map (as on develop).
+//   check-existing --definition <file> --pins <file> --artifact <dir> --engine-image <repository>@sha256:<digest>
+//                  [--catalogue-username <name> --catalogue-token-env <VAR>] [--source-image <source>=<registry>/<prefix>]...
+//       refuse to reuse a pulled artifact whose descriptor disagrees with this snapshot.
+//   resolve --definition <file> --pins <file> --out <dir> --registry <root> --engine-image <repository>@sha256:<digest>
+//           [--source-image <source>=<registry>/<prefix>]... [--catalogue-username <name> --catalogue-token-env <VAR>] [--local]
+//       resolve the edition against the pinned release catalogue, seal the customer's own image rows at the digests
+//       the registry serves for `<repository>:<contentHash>` (it never builds an image), and write the descriptor and
+//       the four locks to <dir>.
+//
+// `resolve` and `check-existing` read the release catalogue only after its signed E4 evidence verified against the
+// CUSTOMER's own evidence trust policy (catalogue-evidence.mjs), and require that policy armed on the release channel.
+// Until the E4 referrer layout lands, no catalogue verifies and both refuse. Takes the roots of the
+// develop customer form (--data-root, --editions-root, --sources-root, --cache-dir per verb), never the kernel.
+
+import { customerRootsOf, parseEditionVerbArgs, runCustomerVerb } from './customer-edition-verbs.mjs';
+import { EditionChannel } from './edition-constants.mjs';
+import { configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  const [command] = process.argv.slice(2);
+  try {
+    configureEditionWorkspaceFromProcess(customerRootsOf(command), { refuseOthers: true });
+  } catch (error) {
+    console.error(`[release-edition] ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function run(argv, env) {
+  const { command, options } = parseEditionVerbArgs(EditionChannel.Release, argv);
+  await runCustomerVerb({ channel: EditionChannel.Release, command, options, env });
+}
+
+if (isEntryModule(import.meta.url)) {
+  run(process.argv.slice(2), process.env).catch((error) => {
+    console.error(`[release-edition] ${error.message}`);
+    process.exit(1);
+  });
+}

package/edition/repin-evidence-trust.mjs

@@ -2,8 +2,9 @@
 // `xema edition repin-evidence-trust` - write the data root's evidence trust
 // pin: the digest of the declared policy, the digests of THIS CLI's built
 // verifier bundle and provenance, the kernel contract authority the data
-// root's runtime image source index states, and the oras binaries that may
-// read a registry. The result is a data-root change to review; nothing here is
+// root's runtime image source index states (a customer data root has no such
+// index: the pin then records none and pins only what exists), and the oras
+// binaries that may read a registry. The result is a data-root change to review; nothing here is
 // generated into the library.
 //
 //   [--trusted-oras-digest sha256:<64 hex>]…   the oras binaries to trust. Without
@@ -24,6 +25,7 @@ import {
 } from './edition-workspace.mjs';
 import {
   loadDeclaredTrustPolicy,
+  hasRuntimeImageSourceIndex,
   readEvidenceTrustPin,
   readStatedKernelContractAuthority,
   requireOrasDigests,
@@ -62,7 +64,7 @@ export async function repinEvidenceTrust({
     declaration,
     policyDigest,
     verifier,
-    kernelContractAuthority: readStatedKernelContractAuthority({ dataRoot: root, schemas }),
+    kernelContractAuthority: hasRuntimeImageSourceIndex(root) ? readStatedKernelContractAuthority({ dataRoot: root, schemas }) : null,
     trustedOrasBinaryDigests: orasDigests,
   });
 }

package/edition/sigstore-bundle-media-type.mjs

@@ -0,0 +1,4 @@
+// The one Sigstore bundle media type this plane stores. Its own module because the evidence verifier bundle needs it and
+// must not import a producer entry (every module of a bundle shares one `import.meta.url`, so a producer's entry guard
+// would run inside the verifier).
+export const BUNDLE_MEDIA_TYPE = 'application/vnd.dev.sigstore.bundle.v0.3+json';

package/edition/trust-policy-arming.mjs

@@ -21,6 +21,11 @@
 //   trustedGitBinaryDigests     -> same, for the git binary that pins the
 //                                 graded checkouts.
 //
+// THE REQUIRED RELEASE ROWS ARE ONE RULE: the edition-catalogue (E4) predicate iff the edition consumes a catalogue
+// (`consumesCatalogue`: a customer edition does, a vendor edition does not), plus the image producer, distribution
+// completeness and delivery entitlement predicates. The same function judges the data root before the catalogue's
+// kernel is adopted (inside the pinned verifier bundle, with its own embedded kernel) and after it (descriptorEvidenceTrust).
+//
 // The three predicate types are checked separately because a policy can be
 // non-empty and still be unarmed for a stage: the verifier resolves candidates
 // per predicate type, so authorizing only the producer identity leaves the
@@ -60,7 +65,7 @@ export function assertArmingChannel(schemas, channel) {
  * field and what makes verification impossible, so the failure is actionable
  * without reading the verifier.
  */
-export function assessTrustPolicyArming(policy, schemas, channel) {
+export function assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue = false } = {}) {
   assertArmingChannel(schemas, channel);
   const unmet = [];
   const stages = [
@@ -68,6 +73,14 @@ export function assessTrustPolicyArming(policy, schemas, channel) {
     ['distribution-completeness', schemas.DISTRIBUTION_IMAGES_PREDICATE_TYPE],
     ['delivery-entitlement', schemas.IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE],
   ];
+  if (consumesCatalogue) {
+    // A kernel that states no E4 predicate cannot arm a catalogue consumer: an unmet entry, never a skip.
+    if (typeof schemas.EDITION_CATALOGUE_PREDICATE_TYPE !== 'string') {
+      unmet.push('this kernel states no edition-catalogue predicate (EDITION_CATALOGUE_PREDICATE_TYPE), so a catalogue consumer cannot be armed against it.');
+    } else {
+      stages.push(['edition-catalogue', schemas.EDITION_CATALOGUE_PREDICATE_TYPE]);
+    }
+  }
   const onChannel = policy.policies.filter((candidate) => candidate.channel === channel);
   const authorized = stages.filter(([, predicateType]) => onChannel.some((candidate) => candidate.predicateTypes.includes(predicateType)));
 

package/edition/verify-catalogue-evidence.mjs

@@ -0,0 +1,245 @@
+// verify-catalogue-evidence — the `catalogue-evidence` mode of the evidence verifier bundle.
+//
+//   <bundle> catalogue-evidence arming --channel <release|develop> --data-root <dir>
+//   <bundle> catalogue-evidence verify --channel <c> --data-root <dir> --evidence-root <abs dir>
+//     --statement-digest <sha256:..> --bundle-digest <sha256:..> --workflow-sha <40hex> --offering-id <id>
+//     --subject-digest <sha256:..> --catalogue-layer-digest <sha256:..> --lock-layer-digest <sha256:..>
+//     --cosign <abs path>
+//
+// A customer verifies the E4 statement of a release catalogue BEFORE the catalogue's kernel is adopted, so there is no
+// kernel package to load schemas from yet. The only kernel-dependent parts of the judgement are the policy schema
+// (parseSigstoreOfflineTrustPolicy) and the predicate-type/channel constants; before adoption they come from the pinned
+// bundle's own embedded kernel, through `loadVerifierKernelSchemas` and nowhere else. This mode never takes `--kernel`.
+//
+// The anchors are the customer's pinned policy and the pinned verifier itself (the bundle refuses to run unless its own
+// bytes are the ones the data-root pin records). There is NO git grading in this mode: it reads no checkout of an editions
+// root, only the declared policy and pin of the data root, both of which the pin binds by digest.
+//
+// ONE arming rule (trust-policy-arming.mjs): the policy must be ARMED on the channel with the E4 row required
+// (`consumesCatalogue: true`); `arming` stops there. `verify` then holds the statement to that policy and to the exact
+// manifest, catalogue layer and lock layer the caller read, with the kernel's own `editionCatalogueRefusal`.
+
+import { editionWorkspaceConfig, resetEditionWorkspaceConfig } from './edition-config.mjs';
+import { EDITION_CONTRACT } from './edition-constants.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromArgv, dataRoot } from './edition-workspace.mjs';
+import {
+  assertPinnedPolicy,
+  assertPinnedVerifier,
+  loadDeclaredTrustPolicy,
+  readEvidenceTrustPin,
+  verifierDigests,
+} from './evidence-trust-pin.mjs';
+import { prepareTrustedCosignBinary, verifySigstoreEvidenceDescriptor } from './image-evidence.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+import { TrustPolicyArmingState, assessTrustPolicyArming } from './trust-policy-arming.mjs';
+import { assertSanitizedOperatorEnvironment, readRunningVerifier } from './verifier-binding.mjs';
+import { loadVerifierKernelSchemas } from './verifier-kernel-schemas.mjs';
+
+/** The first argument that selects this mode of the bundle. */
+export const CATALOGUE_EVIDENCE_MODE = 'catalogue-evidence';
+export const CATALOGUE_EVIDENCE_USAGE =
+  'usage: catalogue-evidence arming --channel <release|develop> --data-root <dir> | ' +
+  'catalogue-evidence verify --channel <c> --data-root <dir> --evidence-root <abs dir> --statement-digest <sha256:..> ' +
+  '--bundle-digest <sha256:..> --workflow-sha <40-hex> --offering-id <id> --subject-digest <sha256:..> ' +
+  '--catalogue-layer-digest <sha256:..> --lock-layer-digest <sha256:..> --cosign <abs path>';
+
+export const CATALOGUE_EVIDENCE_STATEMENT_FILE = 'statement.json';
+export const CATALOGUE_EVIDENCE_BUNDLE_FILE = 'bundle.sigstore.json';
+/** The code of the refusal that the data root's policy is not armed (also the code of the library's error). */
+export const CATALOGUE_EVIDENCE_UNARMED_CODE = EDITION_CONTRACT.evidenceTrust.refusal.code;
+
+export const CatalogueEvidenceRefusalCode = Object.freeze({
+  SubjectMismatch: 'catalogue_evidence_subject_mismatch',
+  OfferingMismatch: 'catalogue_evidence_offering_mismatch',
+  LockDigestMismatch: 'catalogue_evidence_lock_digest_mismatch',
+});
+
+const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+const COMMIT = /^[a-f0-9]{40}$/;
+const ARMING_FLAGS = Object.freeze(['--channel']);
+const VERIFY_FLAGS = Object.freeze([
+  '--channel',
+  '--evidence-root',
+  '--statement-digest',
+  '--bundle-digest',
+  '--workflow-sha',
+  '--offering-id',
+  '--subject-digest',
+  '--catalogue-layer-digest',
+  '--lock-layer-digest',
+  '--cosign',
+]);
+const ABSOLUTE_FLAGS = Object.freeze(['--evidence-root', '--cosign']);
+const DIGEST_FLAGS = Object.freeze(['--statement-digest', '--bundle-digest', '--subject-digest', '--catalogue-layer-digest', '--lock-layer-digest']);
+
+/** A bad command line: exit 2. */
+export class CatalogueEvidenceUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CatalogueEvidenceUsageError';
+  }
+}
+
+/** The data root's policy is not armed (or declared) for a catalogue consumer on the channel. Carries the stable code. */
+export class CatalogueEvidenceUnarmedError extends Error {
+  constructor(message) {
+    super(`${CATALOGUE_EVIDENCE_UNARMED_CODE}: ${message}`);
+    this.name = 'EvidenceTrustRequiredError';
+    this.code = CATALOGUE_EVIDENCE_UNARMED_CODE;
+  }
+}
+
+/** The statement does not bind what the caller read; `code` is the refusal's stable name. */
+export class CatalogueEvidenceRefusal extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.name = 'CatalogueEvidenceRefusal';
+    this.code = code;
+  }
+}
+
+const hexOf = (digest) => digest.slice('sha256:'.length);
+
+function parseFlags(args, allowed) {
+  const flags = new Map();
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1];
+    if (typeof flag !== 'string' || !allowed.includes(flag)) {
+      throw new CatalogueEvidenceUsageError(`unknown or unexpected argument ${JSON.stringify(flag)}`);
+    }
+    if (value === undefined || value.startsWith('--')) {throw new CatalogueEvidenceUsageError(`${flag} requires a value`);}
+    if (flags.has(flag)) {throw new CatalogueEvidenceUsageError(`${flag} was given twice`);}
+    flags.set(flag, value);
+  }
+  for (const flag of allowed) {
+    if (!flags.has(flag)) {throw new CatalogueEvidenceUsageError(`${flag} is required`);}
+  }
+  for (const flag of ABSOLUTE_FLAGS.filter((candidate) => flags.has(candidate))) {
+    if (!flags.get(flag).startsWith('/')) {throw new CatalogueEvidenceUsageError(`${flag} must be an absolute path`);}
+  }
+  for (const flag of DIGEST_FLAGS.filter((candidate) => flags.has(candidate))) {
+    if (!SHA256_DIGEST.test(flags.get(flag))) {throw new CatalogueEvidenceUsageError(`${flag} must be sha256:<64 lowercase hex>`);}
+  }
+  if (flags.has('--workflow-sha') && !COMMIT.test(flags.get('--workflow-sha'))) {
+    throw new CatalogueEvidenceUsageError('--workflow-sha must be a 40-character lowercase hexadecimal git commit SHA');
+  }
+  return flags;
+}
+
+/**
+ * The anchors, then the ONE arming rule: the sanitized launch, the running verifier, the declared policy held to the
+ * data-root pin of both the policy and THIS verifier, and the policy ARMED on `channel` with the E4 row required.
+ */
+async function armedAnchors({ channel, env, bundlePath }) {
+  assertSanitizedOperatorEnvironment(env);
+  const running = readRunningVerifier(bundlePath);
+  const { schemas } = await loadVerifierKernelSchemas();
+  resetEditionWorkspaceConfig();
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  if (declaration.policy === null) {
+    throw new CatalogueEvidenceUnarmedError(`${dataRoot()} declares no evidenceTrustPolicy in edition-workspace.json`);
+  }
+  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot: dataRoot(), declaration, schemas });
+  const pin = readEvidenceTrustPin({ dataRoot: dataRoot(), declaration });
+  assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedVerifier({ pin, actual: verifierDigests(running) });
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue: true });
+  if (state !== TrustPolicyArmingState.ARMED) {
+    throw new CatalogueEvidenceUnarmedError(
+      `the declared policy is ${state.toUpperCase()} on the ${channel} channel for a catalogue consumer: ${unmet.join('; ')}`,
+    );
+  }
+  return { schemas, policy };
+}
+
+/**
+ * Run the mode. `argv` is the bundle's arguments (`['catalogue-evidence', '<phase>', ...]`). Resolves to the JSON line to
+ * print on success; rejects with a named error otherwise.
+ */
+export async function runCatalogueEvidence({ argv, env, bundlePath }) {
+  const [mode, phase, ...tail] = argv;
+  if (mode !== CATALOGUE_EVIDENCE_MODE || (phase !== 'arming' && phase !== 'verify')) {
+    throw new CatalogueEvidenceUsageError(CATALOGUE_EVIDENCE_USAGE);
+  }
+  // `--kernel` is no root of this mode: the schemas are the bundle's own.
+  let rest;
+  try {
+    rest = configureEditionWorkspaceFromArgv(tail, [WorkspaceRoot.Data], { refuseOthers: true });
+  } catch (error) {
+    throw new CatalogueEvidenceUsageError(error.message);
+  }
+  const flags = parseFlags(rest, phase === 'arming' ? ARMING_FLAGS : VERIFY_FLAGS);
+  const channel = flags.get('--channel');
+  const { schemas, policy } = await armedAnchors({ channel, env, bundlePath });
+  if (phase === 'arming') {
+    return `${JSON.stringify({ channel, state: TrustPolicyArmingState.ARMED })}\n`;
+  }
+  const offeringId = flags.get('--offering-id');
+  const descriptor = {
+    statementPath: CATALOGUE_EVIDENCE_STATEMENT_FILE,
+    statementDigest: flags.get('--statement-digest'),
+    bundlePath: CATALOGUE_EVIDENCE_BUNDLE_FILE,
+    bundleDigest: flags.get('--bundle-digest'),
+    bundleMediaType: BUNDLE_MEDIA_TYPE,
+  };
+  const trustedCosign = prepareTrustedCosignBinary({ cosignBinary: flags.get('--cosign'), policy });
+  let statement;
+  try {
+    ({ statement } = verifySigstoreEvidenceDescriptor({
+      evidenceRoot: flags.get('--evidence-root'),
+      descriptor,
+      policy,
+      predicateType: schemas.EDITION_CATALOGUE_PREDICATE_TYPE,
+      channel,
+      expectedWorkflowSha: flags.get('--workflow-sha'),
+      parseStatement: schemas.parseEditionCatalogueStatement,
+      policyRoot: dataRoot(),
+      trustedCosign,
+    }));
+  } finally {
+    trustedCosign.dispose();
+  }
+  const [subject] = statement.subject;
+  const expectedSubject = `xema-edition-${offeringId}`;
+  if (subject.digest.sha256 !== hexOf(flags.get('--subject-digest')) || subject.name !== expectedSubject) {
+    throw new CatalogueEvidenceRefusal(
+      CatalogueEvidenceRefusalCode.SubjectMismatch,
+      `the statement is over ${subject.name}@sha256:${subject.digest.sha256}, not ${expectedSubject}@${flags.get('--subject-digest')}`,
+    );
+  }
+  const refusal = schemas.editionCatalogueRefusal(statement.predicate, {
+    channel,
+    catalogueLayerDigest: flags.get('--catalogue-layer-digest'),
+  });
+  if (refusal !== undefined) {
+    throw new CatalogueEvidenceRefusal(
+      refusal,
+      `the statement states channel ${statement.predicate.channel} and catalogue ${statement.predicate.catalogueDigest}; ` +
+        `this catalogue is on ${channel} with layer ${flags.get('--catalogue-layer-digest')}`,
+    );
+  }
+  if (statement.predicate.offeringId !== offeringId) {
+    throw new CatalogueEvidenceRefusal(
+      CatalogueEvidenceRefusalCode.OfferingMismatch,
+      `the statement is for offering ${statement.predicate.offeringId}, not ${offeringId}`,
+    );
+  }
+  if (statement.predicate.lockDigest !== hexOf(flags.get('--lock-layer-digest'))) {
+    throw new CatalogueEvidenceRefusal(
+      CatalogueEvidenceRefusalCode.LockDigestMismatch,
+      `the statement states lock digest ${statement.predicate.lockDigest}, not that of the lock layer ${flags.get('--lock-layer-digest')}`,
+    );
+  }
+  return `${JSON.stringify({ verified: true, offeringId, channel, statementDigest: descriptor.statementDigest })}\n`;
+}
+
+/** Run the mode as the bundle's entry: print its line, or the named refusal on stderr with exit 1 (usage: 2). */
+export async function runCatalogueEvidenceEntry({ argv, env, bundlePath }) {
+  try {
+    process.stdout.write(await runCatalogueEvidence({ argv, env, bundlePath }));
+  } catch (error) {
+    process.stderr.write(`catalogue-evidence: ${error.name}: ${error.message}\n`);
+    process.exitCode = error instanceof CatalogueEvidenceUsageError ? 2 : 1;
+  }
+}