@xemahq/xema 0.25.1 → 0.27.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,256 @@
+// The evidence-trust part of `xema edition check`.
+//
+// A data root states whether its editions MUST be evidence-gated
+// (`evidenceTrustPolicy.required` in `edition-workspace.json`, no default) and
+// may DECLARE a policy (`policy` + `pin`). This gate says which, in words, and
+// refuses every state in which the answer would be a silent one:
+//
+//   * required but no policy  -> refused (EvidenceTrustRequiredError, code
+//                               EVIDENCE_TRUST_REQUIRED_UNARMED): a data root that
+//                               insists on gating cannot run ungated. Sealing an
+//                               edition (descriptorEvidenceTrust) refuses the same
+//                               way for a RELEASE edition of a required data
+//                               root whose declared policy is UNARMED or PARTIAL
+//                               on the release channel;
+//   * not required, no policy and clean -> passes, printing that the editions are NOT
+//                               evidence-gated (an explicit absence, not a skip);
+//   * 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): on
+//                               the release channel it is unarmed (passes,
+//                               delivery fail-closed) or armed; the develop
+//                               channel admits not-armed and says so in one
+//                               line; a channel that is partially armed is refused.
+
+import { 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 } from './edition-workspace.mjs';
+import {
+  assertPinnedPolicy,
+  assertPinnedVerifier,
+  loadDeclaredTrustPolicy,
+  readEvidenceTrustPin,
+} from './evidence-trust-pin.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+import {
+  TrustPolicyArmingState,
+  assertArmingChannel,
+  assessTrustPolicyArming,
+} from './trust-policy-arming.mjs';
+
+const TAG = '[dist:check]';
+
+/**
+ * The stable code of the refusal to write a `not-armed` edition for a data root
+ * that requires evidence gating. 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;
+
+/**
+ * The data root requires evidence gating (`required: true`) but its evidence
+ * trust is not armed: it declares no policy, or declares one that is UNARMED or
+ * PARTIALLY ARMED. Sealing an edition or writing an artifact is refused with this
+ * error; `not-armed` is never recorded for `required: true`.
+ */
+export class EvidenceTrustRequiredError extends Error {
+  /** @param {string} dataRoot @param {string} reason what is not armed, in words */
+  constructor(dataRoot, reason) {
+    super(
+      `${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} sets evidenceTrustPolicy.required to true but ${reason}: ` +
+        'arm the declared policy (`xema edition check` says what is unmet), declare {"required": true, "policy": ..., "pin": ...}, ' +
+        'or set required to false to run this data root NOT ARMED.',
+    );
+    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, two
+ * states and fail closed. 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 release edition: exactly `required: false` and no armed
+ *                    policy. A develop edition: its channel is not armed, whatever
+ *                    `required` says, and it says so in one stderr line.
+ *
+ * Every other state is refused: a release edition of a `required: true` data
+ * root that is not ARMED on the release channel (no policy, or UNARMED or
+ * PARTIAL there) throws EvidenceTrustRequiredError; a data root that requires
+ * gating and declares no policy at all, 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 notArmed = () => {
+    if (channel === EditionChannel.Develop) {console.error(DEVELOP_NOT_ARMED_NOTICE);}
+    return EvidenceTrustState.NotArmed;
+  };
+  if (declaration.policy === null) {
+    if (declaration.required) {throw new EvidenceTrustRequiredError(root, 'declares no policy');}
+    return notArmed();
+  }
+  const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
+  if (state === TrustPolicyArmingState.PARTIAL) {
+    if (declaration.required) {throw new EvidenceTrustRequiredError(root, `its declared policy 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 (state === TrustPolicyArmingState.ARMED) {return EvidenceTrustState.Armed;}
+  if (declaration.required && channel !== EditionChannel.Develop) {
+    throw new EvidenceTrustRequiredError(root, `its declared policy is UNARMED on the ${channel} channel`);
+  }
+  return notArmed();
+}
+
+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) {
+      if (declaration.required) {throw new EvidenceTrustRequiredError(dataRoot, 'declares no policy');}
+      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 evidenceTrustPolicy {"required": false} with no policy, so nothing reads it. ` +
+            'Declare it ({"required": ..., "policy": ..., "pin": ...}) or remove it.',
+        );
+        return false;
+      }
+      console.log(
+        `${TAG} image-evidence trust policy: NOT ARMED — ${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} ` +
+          'declares evidenceTrustPolicy {"required": false} with no policy, so this data root\'s editions are not evidence-gated.',
+      );
+      return true;
+    }
+
+    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 release channel is the one
+    // `required` speaks for; the develop channel admits not-armed and says so.
+    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);
+      return false;
+    }
+    if (release.state === TrustPolicyArmingState.UNARMED && declaration.required) {
+      const refusal = new EvidenceTrustRequiredError(dataRoot, 'its declared policy is UNARMED on the release channel');
+      console.error(`${TAG} ${refusal.code}: ${refusal.message}`);
+      return false;
+    }
+    if (develop.state === TrustPolicyArmingState.UNARMED) {console.error(`${TAG} ${DEVELOP_NOT_ARMED_NOTICE}`);}
+    if (release.state === TrustPolicyArmingState.UNARMED) {
+      console.warn(
+        `${TAG} image-evidence trust policy: declared but UNARMED on the release channel — delivery stays fail-closed ` +
+          'until `xema edition check` reports it armed.',
+      );
+      return true;
+    }
+    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;
+  }
+}