@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/evidence-trust-policy.mjs

@@ -0,0 +1,374 @@
+// 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 SEALED edition (either channel) and a RESOLVED RELEASE edition are
+//     written only against a policy ARMED on the edition's channel. No policy,
+//     UNARMED or PARTIALLY ARMED there -> refused (EvidenceTrustRequiredError,
+//     code EVIDENCE_TRUST_REQUIRED_UNARMED); edition-contract.json
+//     evidenceTrust.statesByKind is the one statement of this rule;
+//   * a RESOLVED 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, EditionKind, EvidenceTrustState, admittedEvidenceTrustStates } from './edition-constants.mjs';
+import { dataRoot as configuredDataRoot, editionsRoot as configuredEditionsRoot } from './edition-workspace.mjs';
+import {
+  assertPinnedPolicy,
+  assertPinnedThirdPartySourcePins,
+  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';
+import { isVerifierDigestPinned } from './verifier-digest-pin.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
+   * @param {{ edition: string, channel: string }} subject the edition that requires it (e.g. "release edition", "sealed release edition") and its channel
+   */
+  constructor(dataRoot, reason, { edition, channel }) {
+    super(
+      `a ${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 ${channel} 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, channel }) {
+  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot, declaration, schemas });
+  const pin = readEvidenceTrustPin({ dataRoot, declaration });
+  assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot });
+  assertPinnedVerifier({ pin, actual: readBuiltVerifierDigests(locateVerifier), channel });
+  return { policy, policyDigest };
+}
+
+/**
+ * The data root's declared policy, loaded and held to its pin exactly as the
+ * arming checks load it, for a READ-ONLY consumer (the pinned cosign of the official lane, pinned-cosign.mjs).
+ * A data root that declares no policy has no pinned cosign and is refused, naming the declaration it lacks.
+ *
+ * @returns {{ policy: object, dataRoot: string }}
+ */
+export async function loadDeclaredPinnedPolicy() {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  if (declaration.policy === null) {
+    throw new Error(`${join(root, EDITION_WORKSPACE_CONFIG_FILE)} declares no evidenceTrustPolicy; there is no pinned policy to hold cosign to`);
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot: root, declaration, schemas });
+  const pin = readEvidenceTrustPin({ dataRoot: root, declaration });
+  assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot: root });
+  return { policy, dataRoot: root };
+}
+
+/**
+ * The arming of the data root's declared policy on `channel`, loaded and pinned
+ * exactly as `descriptorEvidenceTrust` and the check load it: `{ declared, state,
+ * unmet }`. A data root that declares no policy is `unarmed` with `declared:
+ * false` and one unmet entry; a declared policy that does not hold to its pin
+ * (digest, verifier) throws. Nothing is written.
+ *
+ * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string}, consumesCatalogue?: boolean }} options
+ */
+export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier = locateBuiltVerifier, consumesCatalogue = false }) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  const schemas = await loadKernelDistributionSchemas();
+  assertArmingChannel(schemas, channel);
+  if (declaration.policy === null) {
+    return {
+      declared: false,
+      state: TrustPolicyArmingState.UNARMED,
+      unmet: [`${join(root, EDITION_WORKSPACE_CONFIG_FILE)} declares no evidenceTrustPolicy`],
+    };
+  }
+  const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier, channel });
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue });
+  return { declared: true, state, unmet };
+}
+
+/** 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';
+
+/** A customer develop edition under a policy ARMED on develop: its catalogue carries no E4 evidence to verify. */
+export class CatalogueEvidenceUnverifiableError extends Error {
+  constructor(root) {
+    super(
+      `the data root ${root} declares an evidence trust policy ARMED on the develop channel, but a develop catalogue carries no ` +
+        'signed edition-catalogue (E4) evidence, so the catalogue this customer develop edition consumes cannot be verified and ' +
+        'the edition is never recorded as armed. Resolve it under a policy that is not armed on develop (no develop signer rows), ' +
+        'or resolve a release edition, whose catalogue evidence is verified.',
+    );
+    this.name = 'CatalogueEvidenceUnverifiableError';
+  }
+}
+
+/**
+ * The evidence state an edition of `kind` on `channel` records in its descriptor. Arming
+ * is judged for that ONE channel (`assessTrustPolicyArming`): the signers of
+ * the other channel count for nothing. Which states the kind may record on the
+ * channel is the contract's (`evidenceTrust.statesByKind`, admittedEvidenceTrustStates):
+ *
+ *   * `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 RESOLVED 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 SEALED edition (either channel) and a RESOLVED
+ * RELEASE edition that is not ARMED on its channel (no policy, UNARMED or PARTIAL
+ * there) throw EvidenceTrustRequiredError: this function never returns `not-armed`
+ * for them. A policy edited after pinning, a drifted verifier, and a policy
+ * PARTIALLY ARMED on `channel` are refused for every edition.
+ *
+ * `consumesCatalogue` (a customer edition consumes a catalogue): on RELEASE it adds the edition-catalogue (E4) row to the
+ * required ones, and the catalogue's E4 evidence is verified before it is parsed. A DEVELOP catalogue carries no E4
+ * evidence (the vendor's develop-edition workflow signs the artifact but attaches no E4 statement), so on develop no E4
+ * row is required and nothing can verify the catalogue: a customer develop edition is never written `armed`. A policy
+ * ARMED on develop throws CatalogueEvidenceUnverifiableError instead of recording a claim nothing checked.
+ *
+ * @param {{ kind: string, channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string}, consumesCatalogue?: boolean }} options
+ */
+export async function descriptorEvidenceTrust({ kind, channel, locateVerifier = locateBuiltVerifier, consumesCatalogue = false }) {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  const schemas = await loadKernelDistributionSchemas();
+  assertArmingChannel(schemas, channel);
+  const release = channel === EditionChannel.Release;
+  const notArmedAdmitted = admittedEvidenceTrustStates(kind, channel).includes(EvidenceTrustState.NotArmed);
+  // A resolved edition is named by its channel ("a release edition"); a seal by its kind and channel.
+  const subject = { edition: kind === EditionKind.Sealed ? `${kind} ${channel} edition` : `${channel} edition`, channel };
+  const notArmed = (reason) => {
+    if (!notArmedAdmitted) {throw new EvidenceTrustRequiredError(root, reason, subject);}
+    console.error(DEVELOP_NOT_ARMED_NOTICE);
+    return EvidenceTrustState.NotArmed;
+  };
+  if (declaration.policy === null) {return notArmed('declares no policy');}
+  const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier, channel });
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue: consumesCatalogue && release });
+  if (state === TrustPolicyArmingState.ARMED) {
+    if (consumesCatalogue && !release) {throw new CatalogueEvidenceUnverifiableError(root);}
+    return EvidenceTrustState.Armed;
+  }
+  if (state === TrustPolicyArmingState.PARTIAL) {
+    if (!notArmedAdmitted) {throw new EvidenceTrustRequiredError(root, `declares a policy that is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')})`, subject);}
+    throw new Error(`the declared evidence trust policy is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')}); an edition cannot be written against it`);
+  }
+  return notArmed(`declares a policy that is UNARMED on the ${channel} channel`);
+}
+
+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 {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
+ *   `channel` is the lane checked: it decides whether the verifier is held to the pin's digests (`isVerifierDigestPinned`).
+ *   `locateVerifier` is a parameter so a test can supply a fixture bundle.
+ */
+export async function checkEvidenceTrustPolicy({
+  channel,
+  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, channel });
+    console.log(
+      `${TAG} image-evidence trust policy pin: green — ${declaration.pin} pins ${declaration.policy} ` +
+        `at ${policyDigest}${isVerifierDigestPinned(channel) ? " and this CLI's verifier" : ''} (channel=${channel} verifierPinned=${String(isVerifierDigestPinned(channel))}).`,
+    );
+
+    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;
+  }
+}