@xemahq/xema 0.26.0 → 0.28.0

package/edition/evidence-trust-pin.mjs

@@ -0,0 +1,304 @@
+// The data root's declared evidence trust policy and the PIN that binds it.
+//
+// `edition-workspace.json` may declare `evidenceTrustPolicy: {policy, pin}`. The
+// policy is the offline Sigstore trust policy (who may sign, which binaries may
+// verify); the pin is a reviewed data-root file that fixes the digest of that
+// policy, the digests of the one verifier bundle and its provenance, the
+// kernel contract authority every evidence statement is held to, and the oras
+// binaries that may read a registry. So the policy cannot change, the verifier
+// that enforces it cannot change, the kernel contract the evidence binds cannot
+// change and the registry reader cannot change without a reviewed data-root
+// commit.
+//
+// The kernel contract authority is pinned HERE because nothing else can hold
+// it: `runtime-image-source-index.json` states the authority, and the image
+// locks and statements are compared with what that file states. Comparing the
+// file with itself decides nothing, so its authority is first held to this
+// pin, and only the pinned authority is what evidence is compared with.
+
+import { closeSync, constants as fsConstants, openSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { COMMIT_PATTERN } from './evidence-grammars.mjs';
+import {
+  canonicalJsonBytes,
+  readCanonicalJsonFromRoot,
+  sha256Digest,
+  validatePinnedTrustedRoot,
+} from './image-evidence.mjs';
+import { readBoundedNoFollowFile } from './no-follow-file.mjs';
+import { parseStrictJson } from './strict-json.mjs';
+
+export const EVIDENCE_TRUST_PIN_SCHEMA_VERSION = 2;
+export const RUNTIME_IMAGE_SOURCE_INDEX_FILE = 'runtime-image-source-index.json';
+
+/** A data root that declares no evidence trust has no pin to hold the kernel contract authority to. */
+export const KERNEL_CONTRACT_AUTHORITY_UNPINNED = 'KERNEL_CONTRACT_AUTHORITY_UNPINNED';
+/** The data root's runtime image source index states another authority than the pin records. */
+export const KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE = 'KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE';
+
+export class KernelContractAuthorityPinError extends Error {
+  /** @param {string} code @param {string} message */
+  constructor(code, message) {
+    super(message);
+    this.name = 'KernelContractAuthorityPinError';
+    this.code = code;
+  }
+}
+export const REPIN_COMMAND = 'xema edition repin-evidence-trust';
+
+const MAX_PIN_BYTES = 64 * 1024;
+const MAX_INDEX_BYTES = 16 * 1024 * 1024;
+const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+const PIN_KEYS = Object.freeze([
+  'kernelContractAuthority',
+  'policyDigest',
+  'schemaVersion',
+  'trustedOrasBinaryDigests',
+  'verifier',
+]);
+const VERIFIER_KEYS = Object.freeze(['bundleDigest', 'provenanceDigest']);
+const AUTHORITY_PIN_KEYS = Object.freeze(['digest', 'sourceCommit']);
+const PIN_SHAPE =
+  '{schemaVersion, policyDigest, verifier: {bundleDigest, provenanceDigest}, ' +
+  'kernelContractAuthority: {sourceCommit, digest}, trustedOrasBinaryDigests: [sha256:…, …]}';
+
+const exactKeys = (value, keys) =>
+  value !== null &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  Object.keys(value).sort().join() === keys.join();
+
+function requireDigest(value, what) {
+  if (typeof value !== 'string' || !SHA256_DIGEST.test(value)) {
+    throw new Error(`evidence trust pin: ${what} must be sha256:<64 hex>`);
+  }
+  return value;
+}
+
+/** Digest of the parsed policy in its canonical JSON form. */
+export const trustPolicyDigest = (policy) =>
+  sha256Digest(canonicalJsonBytes(policy));
+
+/** The verifier digests a pin records: the bundle's bytes and its provenance's bytes. */
+export function verifierDigests({ bundleBytes, provenanceBytes }) {
+  return Object.freeze({
+    bundleDigest: sha256Digest(bundleBytes),
+    provenanceDigest: sha256Digest(provenanceBytes),
+  });
+}
+
+/**
+ * Read, parse and validate the declared policy: kernel schema, then the pinned
+ * Sigstore trusted root it names (resolved against the data root).
+ */
+export function loadDeclaredTrustPolicy({ dataRoot, declaration, schemas }) {
+  const policy = schemas.parseSigstoreOfflineTrustPolicy(
+    readCanonicalJsonFromRoot(
+      dataRoot,
+      declaration.policy,
+      'declared image evidence trust policy',
+    ),
+  );
+  validatePinnedTrustedRoot(dataRoot, policy);
+  return Object.freeze({ policy, policyDigest: trustPolicyDigest(policy) });
+}
+
+/** Read the declared pin file: strict JSON, exact keys. */
+export function readEvidenceTrustPin({ dataRoot, declaration }) {
+  const label = 'declared image evidence trust pin';
+  const { bytes } = readBoundedNoFollowFile(
+    dataRoot,
+    declaration.pin,
+    label,
+    MAX_PIN_BYTES,
+  );
+  const pin = parseStrictJson(bytes.toString('utf8'), declaration.pin);
+  if (
+    !exactKeys(pin, PIN_KEYS) ||
+    !exactKeys(pin.verifier, VERIFIER_KEYS) ||
+    !exactKeys(pin.kernelContractAuthority, AUTHORITY_PIN_KEYS) ||
+    !Array.isArray(pin.trustedOrasBinaryDigests)
+  ) {
+    throw new Error(`${declaration.pin}: the pin is exactly ${PIN_SHAPE}`);
+  }
+  if (pin.schemaVersion !== EVIDENCE_TRUST_PIN_SCHEMA_VERSION) {
+    throw new Error(
+      `${declaration.pin}: schemaVersion must be ${EVIDENCE_TRUST_PIN_SCHEMA_VERSION}`,
+    );
+  }
+  return Object.freeze({
+    schemaVersion: pin.schemaVersion,
+    policyDigest: requireDigest(pin.policyDigest, 'policyDigest'),
+    verifier: Object.freeze({
+      bundleDigest: requireDigest(pin.verifier.bundleDigest, 'verifier.bundleDigest'),
+      provenanceDigest: requireDigest(
+        pin.verifier.provenanceDigest,
+        'verifier.provenanceDigest',
+      ),
+    }),
+    kernelContractAuthority: Object.freeze({
+      sourceCommit: requireCommit(pin.kernelContractAuthority.sourceCommit),
+      digest: requireDigest(pin.kernelContractAuthority.digest, 'kernelContractAuthority.digest'),
+    }),
+    trustedOrasBinaryDigests: requireOrasDigests(pin.trustedOrasBinaryDigests),
+  });
+}
+
+function requireCommit(value) {
+  if (typeof value !== 'string' || !COMMIT_PATTERN.test(value)) {
+    throw new Error('evidence trust pin: kernelContractAuthority.sourceCommit must be an exact 40-hex commit');
+  }
+  return value;
+}
+
+/** At least one digest, each canonical, none repeated: a pin that trusts no oras cannot read a registry. */
+export function requireOrasDigests(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(
+      'evidence trust pin: trustedOrasBinaryDigests must list at least one sha256 digest of an oras binary ' +
+        '(`shasum -a 256` of the real file); state it with --trusted-oras-digest when re-pinning',
+    );
+  }
+  const digests = value.map((digest, index) => requireDigest(digest, `trustedOrasBinaryDigests[${index}]`));
+  if (new Set(digests).size !== digests.length) {
+    throw new Error('evidence trust pin: trustedOrasBinaryDigests repeats a digest');
+  }
+  return Object.freeze([...digests]);
+}
+
+/** What a pin records of a kernel contract authority: its commit, and the digest of the whole authority. */
+export function kernelContractAuthorityPin(authority) {
+  return Object.freeze({
+    sourceCommit: requireCommit(authority?.sourceCommit),
+    digest: sha256Digest(canonicalJsonBytes(authority)),
+  });
+}
+
+/** The kernel contract authority the data root's runtime image source index STATES; nothing is trusted yet. */
+export function readStatedKernelContractAuthority({ dataRoot, schemas }) {
+  if (!schemas?.parseRuntimeImageSourceIndex) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  const { bytes } = readBoundedNoFollowFile(
+    dataRoot,
+    RUNTIME_IMAGE_SOURCE_INDEX_FILE,
+    'runtime image source index',
+    MAX_INDEX_BYTES,
+  );
+  return schemas.parseRuntimeImageSourceIndex(JSON.parse(bytes.toString('utf8'))).contractAuthority;
+}
+
+/** Refuse an authority that is not the one the pin records. */
+export function assertPinnedKernelContractAuthority({ pin, authority, label }) {
+  const actual = kernelContractAuthorityPin(authority);
+  if (
+    actual.sourceCommit !== pin.kernelContractAuthority.sourceCommit ||
+    actual.digest !== pin.kernelContractAuthority.digest
+  ) {
+    throw new KernelContractAuthorityPinError(
+      KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE,
+      `${label} states kernel contract authority ${actual.sourceCommit} (${actual.digest}) but the pin records ` +
+        `${pin.kernelContractAuthority.sourceCommit} (${pin.kernelContractAuthority.digest}); ` +
+        `review the kernel contract change, then re-pin with \`${REPIN_COMMAND}\``,
+    );
+  }
+  return authority;
+}
+
+/**
+ * The kernel contract authority evidence is held to: the one the data root's
+ * runtime image source index states, ONLY once it is the one the data root's
+ * evidence-trust pin records. A data root that declares no evidence trust has
+ * no pin, so it has no authority to hold evidence to and this refuses.
+ *
+ * @param {{dataRoot: string, declaration: {policy: string|null, pin: string|null}, schemas: object}} options
+ */
+export function readPinnedKernelContractAuthority({ dataRoot, declaration, schemas }) {
+  if (declaration.policy === null) {
+    throw new KernelContractAuthorityPinError(
+      KERNEL_CONTRACT_AUTHORITY_UNPINNED,
+      `${dataRoot} declares no evidenceTrustPolicy in edition-workspace.json, so no pin records the kernel contract ` +
+        'authority and no image evidence can be produced, planned or checked against it',
+    );
+  }
+  return assertPinnedKernelContractAuthority({
+    pin: readEvidenceTrustPin({ dataRoot, declaration }),
+    authority: readStatedKernelContractAuthority({ dataRoot, schemas }),
+    label: `${dataRoot}/${RUNTIME_IMAGE_SOURCE_INDEX_FILE}`,
+  });
+}
+
+/** Refuse a pin whose policy digest is not the declared policy's. */
+export function assertPinnedPolicy({ pin, policyDigest }) {
+  if (pin.policyDigest !== policyDigest) {
+    throw new Error(
+      `the trust policy hashes to ${policyDigest} but the pin records ${pin.policyDigest}; ` +
+        `review the policy change, then re-pin it with \`${REPIN_COMMAND}\``,
+    );
+  }
+}
+
+/**
+ * The declared policy, held to the pin's record of it. Refuses a data root that
+ * declares none: there is no policy to produce or accept evidence under.
+ */
+export function loadPinnedDeclaredTrustPolicy({ dataRoot, declaration, schemas }) {
+  if (declaration.policy === null) {
+    throw new Error(
+      `${dataRoot} declares no evidenceTrustPolicy in edition-workspace.json; there is no policy to produce evidence under`,
+    );
+  }
+  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot, declaration, schemas });
+  assertPinnedPolicy({ pin: readEvidenceTrustPin({ dataRoot, declaration }), policyDigest });
+  return policy;
+}
+
+/** Refuse a pin whose verifier digests are not the verifier's actual ones. */
+export function assertPinnedVerifier({ pin, actual }) {
+  for (const key of VERIFIER_KEYS) {
+    if (pin.verifier[key] !== actual[key]) {
+      throw new Error(
+        `the verifier's ${key} is ${actual[key]} but the pin records ${pin.verifier[key]}; ` +
+          `this CLI's verifier is not the one the data root pinned. Install the pinned ` +
+          `CLI version, or review the verifier change and re-pin with \`${REPIN_COMMAND}\``,
+      );
+    }
+  }
+}
+
+/** Write the pin for the declared policy, the verifier digests, the kernel contract authority and the oras digests. */
+export function writeEvidenceTrustPin({
+  dataRoot,
+  declaration,
+  policyDigest,
+  verifier,
+  kernelContractAuthority,
+  trustedOrasBinaryDigests,
+}) {
+  const pin = {
+    schemaVersion: EVIDENCE_TRUST_PIN_SCHEMA_VERSION,
+    policyDigest,
+    verifier: {
+      bundleDigest: verifier.bundleDigest,
+      provenanceDigest: verifier.provenanceDigest,
+    },
+    kernelContractAuthority: { ...kernelContractAuthorityPin(kernelContractAuthority) },
+    trustedOrasBinaryDigests: [...requireOrasDigests(trustedOrasBinaryDigests)].sort(),
+  };
+  const text = `${JSON.stringify(pin, null, 2)}\n`;
+  const descriptor = openSync(
+    join(dataRoot, declaration.pin),
+    fsConstants.O_WRONLY |
+      fsConstants.O_CREAT |
+      fsConstants.O_TRUNC |
+      fsConstants.O_NOFOLLOW,
+    0o644,
+  );
+  try {
+    writeFileSync(descriptor, text);
+  } finally {
+    closeSync(descriptor);
+  }
+  return pin;
+}

package/edition/evidence-trust-policy.mjs

@@ -0,0 +1,294 @@
+// The evidence-trust part of `xema edition check`, and the state an edition
+// records in its descriptor.
+//
+// A data root DECLARES an evidence trust policy (`evidenceTrustPolicy: {policy,
+// pin}` in `edition-workspace.json`) or states that it declares none (`null`).
+// No switch admits an ungated release:
+//
+//   * a RELEASE edition is written only against a policy ARMED on the release
+//     channel. No policy, UNARMED or PARTIALLY ARMED there -> refused
+//     (EvidenceTrustRequiredError, code EVIDENCE_TRUST_REQUIRED_UNARMED);
+//   * a DEVELOP edition admits not-armed and says so in one line; a policy
+//     PARTIALLY ARMED on the develop channel is refused;
+//   * `xema edition check` FAILS when the editions tree holds a release
+//     edition (an edition directory holding a release lock) and the policy is
+//     not ARMED on the release channel (none declared, UNARMED or PARTIAL):
+//     that edition cannot be published as an artifact. A tree holding no
+//     release edition passes for develop-only use, with a notice saying so;
+//   * no policy declared but a policy file is present at the top level or under
+//     `trust/` -> refused: a policy nothing reads is a policy someone believes
+//     is enforced;
+//   * declared -> the policy parses with the kernel schema, its pinned Sigstore
+//     root matches, the data-root pin records the policy's digest AND this
+//     CLI's built verifier (a missing bundle is refused, never skipped), and
+//     the authority configuration is judged PER CHANNEL
+//     (trust-policy-arming.mjs); a channel that is partially armed is refused.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { locateBuiltVerifier, readBuiltVerifierDigests } from './built-verifier.mjs';
+import { EDITION_WORKSPACE_CONFIG_FILE, editionWorkspaceConfig } from './edition-config.mjs';
+import { EDITION_CONTRACT, EditionChannel, EvidenceTrustState } from './edition-constants.mjs';
+import { dataRoot as configuredDataRoot, editionsRoot as configuredEditionsRoot } from './edition-workspace.mjs';
+import {
+  assertPinnedPolicy,
+  assertPinnedVerifier,
+  loadDeclaredTrustPolicy,
+  readEvidenceTrustPin,
+} from './evidence-trust-pin.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import { heldReleaseLocks } from './release-channel-guard.mjs';
+import {
+  TrustPolicyArmingState,
+  assertArmingChannel,
+  assessTrustPolicyArming,
+} from './trust-policy-arming.mjs';
+
+const TAG = '[dist:check]';
+
+/**
+ * The stable code of the refusal to write a RELEASE edition without an armed
+ * evidence trust policy. Consumers (xema-deploy, workflows) match on the code,
+ * never on the message; it is also listed in edition-contract.json.
+ */
+export const EVIDENCE_TRUST_REQUIRED_UNARMED = EDITION_CONTRACT.evidenceTrust.refusal.code;
+
+/**
+ * What `xema edition check` says of a data root whose policy is not armed on
+ * the release channel. Sealing is not gated (nothing sealed leaves without
+ * `xema edition artifact`); publishing is.
+ */
+export const NO_RELEASE_ARTIFACT_NOTICE =
+  'no release edition of this data root can be published as an artifact (written by `xema edition artifact`) until the policy is armed on the release channel';
+
+/**
+ * The release editions of the configured editions tree: the edition directories
+ * (those holding `xema-distribution.json`) that hold a release lock. An edition
+ * that is only defined, with no lock resolved yet, is not one.
+ */
+export function releaseEditionIds() {
+  const root = configuredEditionsRoot();
+  if (!existsSync(root)) {return [];}
+  return readdirSync(root, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        existsSync(join(root, entry.name, 'xema-distribution.json')) &&
+        heldReleaseLocks(join(root, entry.name)).length > 0,
+    )
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/**
+ * The verdict of the check for a policy that is not armed on the release
+ * channel: red when the tree holds a release edition (it names them and the
+ * repair), green with the notice when it holds none.
+ */
+function notArmedOnReleaseVerdict(what, repair) {
+  const releaseEditions = releaseEditionIds();
+  if (releaseEditions.length === 0) {
+    console.warn(
+      `${TAG} image-evidence trust policy: NOT ARMED on the release channel — ${what}. ${configuredEditionsRoot()} holds no release edition, ` +
+        `so this passes for develop-only use: ${NO_RELEASE_ARTIFACT_NOTICE}.`,
+    );
+    return true;
+  }
+  console.error(
+    `${TAG} image-evidence trust policy FAILED: ${what}, and ${configuredEditionsRoot()} holds ${String(releaseEditions.length)} release edition(s) ` +
+      `(${releaseEditions.join(', ')}): ${NO_RELEASE_ARTIFACT_NOTICE}. ${repair}`,
+  );
+  return false;
+}
+
+/**
+ * A release edition requires an armed evidence trust policy and this data root
+ * has none: it declares no policy, or declares one that is UNARMED or PARTIALLY
+ * ARMED on the release channel. Writing the release descriptor or artifact is
+ * refused with this error; a release edition never records `not-armed`.
+ */
+export class EvidenceTrustRequiredError extends Error {
+  /** @param {string} dataRoot @param {string} reason what is not armed, in words */
+  constructor(dataRoot, reason) {
+    super(
+      `a release edition requires an armed evidence trust policy, but ${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} ${reason}: ` +
+        'declare a policy ({"policy": ..., "pin": ...}) and arm it on the release channel (`xema edition check` says what is unmet).',
+    );
+    this.name = 'EvidenceTrustRequiredError';
+    this.code = EVIDENCE_TRUST_REQUIRED_UNARMED;
+  }
+}
+
+/**
+ * Load the declared policy and hold it to its data-root pin: the policy must
+ * hash to what the pin records, and this CLI's built verifier must be the one
+ * the pin records (a missing bundle is refused, never skipped).
+ */
+function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
+  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot, declaration, schemas });
+  const pin = readEvidenceTrustPin({ dataRoot, declaration });
+  assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedVerifier({ pin, actual: readBuiltVerifierDigests(locateVerifier) });
+  return { policy, policyDigest };
+}
+
+/** What a develop edition says, once, when it is written or checked without an armed develop channel. */
+export const DEVELOP_NOT_ARMED_NOTICE = 'develop channel: trust policy not armed, evidence is not signature-verified';
+
+/**
+ * The evidence state an edition of `channel` records in its descriptor. Arming
+ * is judged for that ONE channel (`assessTrustPolicyArming`): the signers of
+ * the other channel count for nothing.
+ *
+ *   * `armed`      - the data root declares a policy, the policy is pinned (the
+ *                    policy and this CLI's verifier match the data-root pin) and
+ *                    ARMED on `channel`;
+ *   * `not-armed`  - a DEVELOP edition only: its channel is not armed (no
+ *                    policy, or UNARMED there), and it says so in one stderr line.
+ *
+ * Every other state is refused. A RELEASE edition that is not ARMED on the
+ * release channel (no policy, UNARMED or PARTIAL there) throws
+ * EvidenceTrustRequiredError: this function never returns `not-armed` for it.
+ * A policy edited after pinning, a drifted verifier, and a policy PARTIALLY
+ * ARMED on `channel` are refused on either channel.
+ *
+ * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
+ */
+export async function descriptorEvidenceTrust({ channel, locateVerifier = locateBuiltVerifier }) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  const schemas = await loadKernelDistributionSchemas();
+  assertArmingChannel(schemas, channel);
+  const release = channel === EditionChannel.Release;
+  const developNotArmed = () => {
+    console.error(DEVELOP_NOT_ARMED_NOTICE);
+    return EvidenceTrustState.NotArmed;
+  };
+  if (declaration.policy === null) {
+    if (release) {throw new EvidenceTrustRequiredError(root, 'declares no policy');}
+    return developNotArmed();
+  }
+  const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
+  if (state === TrustPolicyArmingState.ARMED) {return EvidenceTrustState.Armed;}
+  if (state === TrustPolicyArmingState.PARTIAL) {
+    if (release) {throw new EvidenceTrustRequiredError(root, `declares a policy that is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')})`);}
+    throw new Error(`the declared evidence trust policy is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')}); an edition cannot be written against it`);
+  }
+  if (release) {throw new EvidenceTrustRequiredError(root, `declares a policy that is UNARMED on the ${channel} channel`);}
+  return developNotArmed();
+}
+
+export const UNDECLARED_TRUST_DIRECTORY = 'trust';
+
+/**
+ * Policy files the data root holds without declaring them: a top-level `*.json`
+ * the kernel parses as an offline trust policy, or a `trust/` directory. A file
+ * the kernel schema does not accept is not a policy, which is the whole test.
+ */
+function undeclaredPolicyArtifacts(dataRoot, schemas) {
+  const found = [];
+  for (const entry of readdirSync(dataRoot, { withFileTypes: true })) {
+    if (entry.isDirectory() && entry.name === UNDECLARED_TRUST_DIRECTORY) {
+      found.push(`${UNDECLARED_TRUST_DIRECTORY}/`);
+    } else if (entry.isFile() && entry.name.endsWith('.json')) {
+      if (isTrustPolicy(join(dataRoot, entry.name), schemas)) {
+        found.push(entry.name);
+      }
+    }
+  }
+  return found.sort();
+}
+
+function isTrustPolicy(path, schemas) {
+  try {
+    schemas.parseSigstoreOfflineTrustPolicy(JSON.parse(readFileSync(path, 'utf8')));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run the gate against the configured data root. Returns true when green; every
+ * refusal is printed, naming the repair.
+ *
+ * @param {{ locateVerifier?: () => {bundlePath: string, provenancePath: string} }} [options]
+ *   `locateVerifier` is a parameter so a test can supply a fixture bundle.
+ */
+export async function checkEvidenceTrustPolicy({
+  locateVerifier = locateBuiltVerifier,
+} = {}) {
+  try {
+    const dataRoot = configuredDataRoot();
+    const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+    const schemas = await loadKernelDistributionSchemas();
+    if (declaration.policy === null) {
+      const undeclared = undeclaredPolicyArtifacts(dataRoot, schemas);
+      if (undeclared.length > 0) {
+        console.error(
+          `${TAG} image-evidence trust policy FAILED: ${dataRoot} holds ${undeclared.join(', ')} ` +
+            `but ${EDITION_WORKSPACE_CONFIG_FILE} declares no evidenceTrustPolicy, so nothing reads it. ` +
+            'Declare it ({"policy": ..., "pin": ...}) or remove it.',
+        );
+        return false;
+      }
+      return notArmedOnReleaseVerdict(
+        `${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} declares no evidenceTrustPolicy (its develop editions are not evidence-gated)`,
+        'Declare a policy ({"policy": ..., "pin": ...}), authorize the release signers in it, pin it with `xema edition repin-evidence-trust`, and re-run `xema edition check` until it reports ARMED on the release channel.',
+      );
+    }
+
+    const { policy, policyDigest } = loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier });
+    console.log(
+      `${TAG} image-evidence trust policy pin: green — ${declaration.pin} pins ${declaration.policy} ` +
+        `at ${policyDigest} and this CLI's verifier.`,
+    );
+
+    console.log(
+      `${TAG} image-evidence trust policy: schema green — pinned ${policy.cosignVersion}, ` +
+        `${policy.policies.length} authorized signer identities, ` +
+        `${policy.trustedCosignBinaryDigests.length} cosign / ` +
+        `${policy.trustedGitBinaryDigests.length} git binary pins.`,
+    );
+    // Each channel is judged on its own signers. The develop channel admits
+    // not-armed and says so; a release channel that is not armed fails the
+    // check as soon as the tree holds a release edition.
+    const partial = (channel, unmet) => {
+      console.error(
+        `${TAG} image-evidence trust policy is PARTIALLY ARMED on the ${channel} channel — this mixed state is invalid ` +
+          `and no ${channel} image evidence can verify against it:`,
+      );
+      for (const reason of unmet) {
+        console.error(`${TAG}   - ${reason}`);
+      }
+    };
+    const develop = assessTrustPolicyArming(policy, schemas, EditionChannel.Develop);
+    if (develop.state === TrustPolicyArmingState.PARTIAL) {
+      partial(EditionChannel.Develop, develop.unmet);
+      return false;
+    }
+    const release = assessTrustPolicyArming(policy, schemas, EditionChannel.Release);
+    if (release.state === TrustPolicyArmingState.PARTIAL) {
+      partial(EditionChannel.Release, release.unmet);
+      console.error(
+        `${TAG} ${NO_RELEASE_ARTIFACT_NOTICE}. Complete the release channel in ${declaration.policy} (every line above), ` +
+          're-pin with `xema edition repin-evidence-trust`, and re-run `xema edition check`.',
+      );
+      return false;
+    }
+    if (develop.state === TrustPolicyArmingState.UNARMED) {console.error(`${TAG} ${DEVELOP_NOT_ARMED_NOTICE}`);}
+    if (release.state === TrustPolicyArmingState.UNARMED) {
+      return notArmedOnReleaseVerdict(
+        `${declaration.policy} is declared but UNARMED on the release channel (it authorizes no release signer)`,
+        `Authorize the release signers and pin the cosign and git binaries in ${declaration.policy}, re-pin with \`xema edition repin-evidence-trust\`, and re-run \`xema edition check\` until it reports ARMED on the release channel.`,
+      );
+    }
+    console.log(`${TAG} image-evidence trust policy: ARMED on the release channel${develop.armed ? ' and on the develop channel' : ''}.`);
+    return true;
+  } catch (error) {
+    console.error(`${TAG} image-evidence trust policy FAILED: ${error.message}`);
+    return false;
+  }
+}