@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/trusted-executable.mjs

@@ -0,0 +1,166 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  closeSync,
+  constants as fsConstants,
+  fsyncSync,
+  lstatSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+
+const PREPARED_EXECUTABLES = new WeakMap();
+
+function sha256Digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function validatePreparedExecutable(record, label) {
+  const stats = lstatSync(record.path);
+  if (!stats.isFile() || stats.isSymbolicLink()) {
+    throw new Error(
+      `prepared trusted ${label} must be a no-follow regular file`,
+    );
+  }
+  if (record.kind === 'root-owned') {
+    for (const field of ['dev', 'ino', 'uid', 'mode', 'size']) {
+      if (stats[field] !== record.snapshot[field]) {
+        throw new Error(`prepared trusted ${label} file identity changed`);
+      }
+    }
+    let current = record.path;
+    while (true) {
+      const currentStats = lstatSync(current);
+      if (currentStats.uid !== 0 || (currentStats.mode & 0o022) !== 0) {
+        throw new Error(
+          `${label} and every ancestor must be root-owned and not group/world writable`,
+        );
+      }
+      if (current === '/') {break;}
+      current = dirname(current);
+    }
+    if ((stats.mode & 0o777) !== 0o755) {
+      throw new Error(`prepared trusted ${label} must have exact mode 0755`);
+    }
+  }
+  if (sha256Digest(readFileSync(record.path)) !== record.digest) {
+    throw new Error(`prepared trusted ${label} bytes changed`);
+  }
+}
+
+export function prepareDigestPinnedExecutable({
+  executablePath,
+  trustedDigests,
+  label,
+  verifyVersion,
+}) {
+  if (!isAbsolute(executablePath)) {
+    throw new Error(`${label} executable path must be absolute`);
+  }
+  const sourceStats = lstatSync(executablePath);
+  if (!sourceStats.isFile() || sourceStats.isSymbolicLink()) {
+    throw new Error(`${label} executable must be a no-follow regular file`);
+  }
+  const bytes = readFileSync(executablePath);
+  const digest = sha256Digest(bytes);
+  if (!trustedDigests.includes(digest)) {
+    throw new Error(
+      `${label} executable digest ${digest} is not trusted by policy`,
+    );
+  }
+  const directory = mkdtempSync(join(tmpdir(), `xema-trusted-${label}-`));
+  const privatePath = join(directory, basename(executablePath));
+  try {
+    let descriptor;
+    try {
+      descriptor = openSync(
+        privatePath,
+        fsConstants.O_CREAT |
+          fsConstants.O_EXCL |
+          fsConstants.O_WRONLY |
+          fsConstants.O_NOFOLLOW,
+        0o500,
+      );
+      writeFileSync(descriptor, bytes);
+      fsyncSync(descriptor);
+    } finally {
+      if (descriptor !== undefined) {closeSync(descriptor);}
+    }
+    verifyVersion(privatePath);
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true });
+    throw error;
+  }
+  const handle = {
+    path: privatePath,
+    dispose() {
+      rmSync(directory, { recursive: true, force: true });
+    },
+  };
+  PREPARED_EXECUTABLES.set(handle, {
+    kind: 'private-copy',
+    path: privatePath,
+    digest,
+  });
+  return handle;
+}
+
+export function prepareRootOwnedPinnedExecutable({
+  executablePath,
+  trustedDigests,
+  label,
+  verifyVersion,
+}) {
+  if (!isAbsolute(executablePath)) {
+    throw new Error(`${label} executable path must be absolute`);
+  }
+  const initialStats = lstatSync(executablePath);
+  if (!initialStats.isFile() || initialStats.isSymbolicLink()) {
+    throw new Error(`${label} executable must be a no-follow regular file`);
+  }
+  const handle = { path: executablePath, dispose() {} };
+  const record = {
+    kind: 'root-owned',
+    path: executablePath,
+    digest: sha256Digest(readFileSync(executablePath)),
+    snapshot: {
+      dev: initialStats.dev,
+      ino: initialStats.ino,
+      uid: initialStats.uid,
+      mode: initialStats.mode,
+      size: initialStats.size,
+    },
+  };
+  PREPARED_EXECUTABLES.set(handle, record);
+  validatePreparedExecutable(record, label);
+  if (!trustedDigests.includes(record.digest)) {
+    throw new Error(
+      `${label} executable digest ${record.digest} is not trusted by policy`,
+    );
+  }
+  verifyVersion(executablePath);
+  validatePreparedExecutable(record, label);
+  return handle;
+}
+
+export function assertPreparedExecutable(handle, label) {
+  const record = PREPARED_EXECUTABLES.get(handle);
+  if (!record) {
+    throw new Error(`a prepared trusted ${label} executable is required`);
+  }
+  validatePreparedExecutable(record, label);
+  return record.path;
+}
+
+export function exactExecutableOutput(path, args, options = {}) {
+  return execFileSync(path, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...options,
+  });
+}

package/edition/verifier-binding.mjs

@@ -0,0 +1,45 @@
+// What the running evidence verifier is held to before it trusts anything:
+// a clean launch environment, an install nobody else can write, and the
+// data-root pin of its own bytes. (The kernel the workspace states is held to
+// the bundled edition protocol by `edition-protocol.mjs`.)
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { assertProtectedPathAncestry } from './evidence-checkout.mjs';
+import { VERIFIER_PROVENANCE_FILE } from './verifier-files.mjs';
+import { parseVerifierProvenance } from './verifier-provenance.mjs';
+
+/** The launch environment carries no variable that changes what code runs. */
+export function assertSanitizedOperatorEnvironment(env) {
+  for (const key of Object.keys(env)) {
+    if (
+      key === 'NODE_OPTIONS' ||
+      key === 'NODE_PATH' ||
+      key.startsWith('DYLD_') ||
+      key.startsWith('LD_') ||
+      key.startsWith('GIT_')
+    ) {
+      throw new Error(
+        `trusted verifier launch refuses inherited control variable ${key}`,
+      );
+    }
+  }
+}
+
+/**
+ * The verifier file that is running (the realpath of `bundlePath`) and its
+ * provenance beside it, after refusing an install anyone else can write or
+ * that a foreign user owns, and a provenance that does not describe this
+ * bundle. Returns the bytes the pin is compared with.
+ */
+export function readRunningVerifier(bundlePath) {
+  const realBundle = realpathSync(bundlePath);
+  assertProtectedPathAncestry(realBundle, 'the evidence verifier install');
+  const bundleBytes = readFileSync(realBundle);
+  const provenanceBytes = readFileSync(
+    join(dirname(realBundle), VERIFIER_PROVENANCE_FILE),
+  );
+  parseVerifierProvenance({ provenanceBytes, bundleBytes });
+  return { bundleBytes, provenanceBytes };
+}

package/edition/verifier-digest-pin.mjs

@@ -0,0 +1,17 @@
+// verifier-digest-pin — whether the running evidence verifier is held to the trust pin's recorded verifier digests. One
+// predicate, used by every site that compares the verifier's digests with the pin's.
+
+import { EditionChannel } from './edition-channel.mjs';
+
+/**
+ * Whether the verifier on `channel` must be byte-identical to the one the trust pin records. False only on the develop
+ * channel: a deployment we manage installs the moving develop CLI, and the running CLI is trusted as installed
+ * (TEAM-159), so no pin of its identity is kept. Only the pinned-digest equality is lifted; the policy digest, the
+ * kernel contract authority, the third-party source pins and the evidence signatures are checked on every channel.
+ */
+export function isVerifierDigestPinned(channel) {
+  if (!Object.values(EditionChannel).includes(channel)) {
+    throw new Error(`unknown edition channel ${JSON.stringify(channel)}`);
+  }
+  return channel !== EditionChannel.Develop;
+}

package/edition/verifier-files.mjs

@@ -0,0 +1,8 @@
+// The names and place of the built evidence verifier. Pure constants, shared by
+// the build, the gate and the verifier itself (which is bundled and so must not
+// derive anything from where it sits).
+
+export const VERIFIER_BUNDLE_FILE = 'verify-image-evidence.bundle.mjs';
+export const VERIFIER_PROVENANCE_FILE =
+  'verify-image-evidence.bundle.provenance.json';
+export const VERIFIER_DIST_SUBPATH = Object.freeze(['dist', 'edition']);

package/edition/verifier-kernel-schemas.mjs

@@ -0,0 +1,22 @@
+import { assertKernelEditionProtocol } from './edition-protocol.mjs';
+import { kernelPackageDir } from './edition-workspace.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+
+/**
+ * The ONE place the evidence verifier obtains the kernel distribution schemas,
+ * and the edition protocol they implement.
+ *
+ * From source it loads the built kernel the workspace states with `--kernel`,
+ * whose protocol is then trivially the stated one. The verifier build
+ * (`scripts/build-evidence-verifier.mjs`) replaces this module with the
+ * `@xemahq/contracts` distribution schemas and edition protocol identity
+ * bundled from the CLI's own dependency, so the bundle never executes a schema
+ * from outside itself; the entry then holds `--kernel`'s declared protocol
+ * equal to the bundled one.
+ */
+export async function loadVerifierKernelSchemas() {
+  return {
+    schemas: await loadKernelDistributionSchemas(),
+    editionProtocol: assertKernelEditionProtocol(kernelPackageDir()),
+  };
+}

package/edition/verifier-provenance.mjs

@@ -0,0 +1,64 @@
+// The provenance record written beside the evidence verifier bundle, and the
+// one reader of it. The build writes it (`scripts/build-evidence-verifier.mjs`);
+// the data root pins its digest beside the bundle's.
+//
+// Deterministic by construction: no timestamps, no host paths. Every bundled
+// input is {package, version, path relative to ITS package root, sha256}, so the
+// record does not depend on how the dependencies were installed.
+
+import { sha256Digest } from './image-evidence.mjs';
+import { compareStrings } from './string-order.mjs';
+
+export const VERIFIER_PROVENANCE_SCHEMA_VERSION = 1;
+
+const PROVENANCE_KEYS = Object.freeze([
+  'artifactSha256',
+  'esbuild',
+  'inputs',
+  'schemaVersion',
+]);
+const INPUT_KEYS = Object.freeze(['package', 'path', 'sha256', 'version']);
+const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+
+const exactKeys = (value, keys) =>
+  value !== null &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  Object.keys(value).sort().join() === keys.join();
+
+/** Total order of inputs: package, then path. */
+export const compareProvenanceInputs = (a, b) =>
+  compareStrings(a.package, b.package) || compareStrings(a.path, b.path);
+
+/** Parse provenance bytes strictly, binding them to the bundle they describe. */
+export function parseVerifierProvenance({ provenanceBytes, bundleBytes }) {
+  const provenance = JSON.parse(provenanceBytes.toString('utf8'));
+  if (
+    !exactKeys(provenance, PROVENANCE_KEYS) ||
+    provenance.schemaVersion !== VERIFIER_PROVENANCE_SCHEMA_VERSION ||
+    !exactKeys(provenance.esbuild, ['version']) ||
+    typeof provenance.esbuild.version !== 'string' ||
+    !Array.isArray(provenance.inputs) ||
+    provenance.inputs.length === 0
+  ) {
+    throw new Error('verifier provenance has an invalid structure');
+  }
+  provenance.inputs.forEach((input, index) => {
+    if (
+      !exactKeys(input, INPUT_KEYS) ||
+      INPUT_KEYS.some((key) => typeof input[key] !== 'string' || input[key] === '') ||
+      !SHA256_DIGEST.test(input.sha256) ||
+      input.path.startsWith('/') ||
+      input.path.split('/').includes('..') ||
+      (index > 0 && compareProvenanceInputs(provenance.inputs[index - 1], input) >= 0)
+    ) {
+      throw new Error(
+        `verifier provenance input ${index} is malformed or out of order`,
+      );
+    }
+  });
+  if (provenance.artifactSha256 !== sha256Digest(bundleBytes)) {
+    throw new Error('verifier provenance does not describe this bundle');
+  }
+  return provenance;
+}

package/edition/verify-catalogue-evidence.mjs

@@ -0,0 +1,247 @@
+// 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,
+  assertPinnedThirdPartySourcePins,
+  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 });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot: dataRoot() });
+  assertPinnedVerifier({ pin, actual: verifierDigests(running), channel });
+  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;
+  }
+}