@xemahq/xema 0.59.1 → 0.60.1

package/edition/evidence-trust-policy.mjs

@@ -1,374 +0,0 @@
-// 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';
-
-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 }) {
-  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot, declaration, schemas });
-  const pin = readEvidenceTrustPin({ dataRoot, declaration });
-  assertPinnedPolicy({ pin, policyDigest });
-  assertPinnedThirdPartySourcePins({ pin, dataRoot });
-  assertPinnedVerifier({ pin, actual: readBuiltVerifierDigests(locateVerifier) });
-  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 develop coverage verb).
- * A data root that declares no policy has nothing to report coverage against
- * and is refused, naming the declaration it lacks. The POLICY is held to its pin; this CLI's built verifier
- * is not. Coverage therefore runs this CLI's own, unpinned verifier code (case A), so a green coverage is a
- * forecast of what resolve accepts, not a guarantee: resolve can still refuse under the pinned verifier.
- *
- * @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 report coverage against`);
-  }
-  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 });
-  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 });
-  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 {{ 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;
-  }
-}