@xemahq/xema 0.59.1 → 0.60.1

package/edition/evidence-trust-pin.mjs

@@ -1,380 +0,0 @@
-// 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.
-//
-// A customer data root has no such index; its pin records `kernelContractAuthority: null` and pins only what exists.
-//
-// 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, existsSync, 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';
-import { THIRD_PARTY_SOURCE_PINS_FILE, thirdPartySourcePinsDigest } from './third-party-source-pins.mjs';
-import { assertTrustPolicyImageOwnership, firstPartyOwnersFromIndex } from './trust-policy-image-ownership.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',
-]);
-/**
- * Present iff the data root holds `third-party-source-pins.json`. Optional so a pin written before third-party
- * sources existed, for a data root without that file, keeps loading unchanged (the schemaVersion stays 2).
- */
-const THIRD_PARTY_SOURCE_PINS_DIGEST_KEY = 'thirdPartySourcePinsDigest';
-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} | null, trustedOrasBinaryDigests: [sha256:…, …], ' +
-  `[${THIRD_PARTY_SOURCE_PINS_DIGEST_KEY}: sha256:… (only when the data root holds ${THIRD_PARTY_SOURCE_PINS_FILE})]}`;
-
-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);
-  assertTrustPolicyImageOwnership({
-    policy,
-    firstPartyOwners: hasRuntimeImageSourceIndex(dataRoot) ? firstPartyOwnersFromIndex(readRuntimeImageSourceIndexDocument(dataRoot)) : null,
-  });
-  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);
-  const hasSourcePinsDigest = pin !== null && typeof pin === 'object' && THIRD_PARTY_SOURCE_PINS_DIGEST_KEY in pin;
-  if (
-    !exactKeys(pin, hasSourcePinsDigest ? [...PIN_KEYS, THIRD_PARTY_SOURCE_PINS_DIGEST_KEY].sort() : PIN_KEYS) ||
-    !exactKeys(pin.verifier, VERIFIER_KEYS) ||
-    !(pin.kernelContractAuthority === null || 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:
-      pin.kernelContractAuthority === null
-        ? null
-        : Object.freeze({
-            sourceCommit: requireCommit(pin.kernelContractAuthority.sourceCommit),
-            digest: requireDigest(pin.kernelContractAuthority.digest, 'kernelContractAuthority.digest'),
-          }),
-    trustedOrasBinaryDigests: requireOrasDigests(pin.trustedOrasBinaryDigests),
-    thirdPartySourcePinsDigest: hasSourcePinsDigest
-      ? requireDigest(pin[THIRD_PARTY_SOURCE_PINS_DIGEST_KEY], THIRD_PARTY_SOURCE_PINS_DIGEST_KEY)
-      : null,
-  });
-}
-
-/**
- * Hold the data root's `third-party-source-pins.json` to the pin: when the file exists the pin must record its sha256
- * (and it must be the file's); when the file does not exist the pin must record none.
- */
-export function assertPinnedThirdPartySourcePins({ pin, dataRoot }) {
-  const actual = thirdPartySourcePinsDigest(dataRoot);
-  if (actual === null) {
-    if (pin.thirdPartySourcePinsDigest !== null) {
-      throw new Error(
-        `the pin records ${THIRD_PARTY_SOURCE_PINS_FILE} at ${pin.thirdPartySourcePinsDigest} but the data root holds no such file; ` +
-          `review the removal, then re-pin with \`${REPIN_COMMAND}\``,
-      );
-    }
-    return;
-  }
-  if (pin.thirdPartySourcePinsDigest === null) {
-    throw new Error(
-      `the data root holds ${THIRD_PARTY_SOURCE_PINS_FILE} (${actual}) but the pin records none; ` +
-        `review the third-party source pins, then re-pin with \`${REPIN_COMMAND}\``,
-    );
-  }
-  if (pin.thirdPartySourcePinsDigest !== actual) {
-    throw new Error(
-      `${THIRD_PARTY_SOURCE_PINS_FILE} hashes to ${actual} but the pin records ${pin.thirdPartySourcePinsDigest}; ` +
-        `review the third-party source pin change, then re-pin with \`${REPIN_COMMAND}\``,
-    );
-  }
-}
-
-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)),
-  });
-}
-
-/**
- * Whether the data root holds a runtime image source index. A vendor data root does; a customer data root has none
- * (it consumes a catalogue and states no kernel contract authority of its own), and its pin records `null`.
- */
-export function hasRuntimeImageSourceIndex(dataRoot) {
-  return existsSync(join(dataRoot, RUNTIME_IMAGE_SOURCE_INDEX_FILE));
-}
-
-/** The data root's runtime image source index as parsed JSON (not schema-validated here). */
-function readRuntimeImageSourceIndexDocument(dataRoot) {
-  const { bytes } = readBoundedNoFollowFile(
-    dataRoot,
-    RUNTIME_IMAGE_SOURCE_INDEX_FILE,
-    'runtime image source index',
-    MAX_INDEX_BYTES,
-  );
-  return JSON.parse(bytes.toString('utf8'));
-}
-
-/** 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');
-  }
-  return schemas.parseRuntimeImageSourceIndex(readRuntimeImageSourceIndexDocument(dataRoot)).contractAuthority;
-}
-
-/** Refuse an authority that is not the one the pin records. */
-export function assertPinnedKernelContractAuthority({ pin, authority, label }) {
-  const actual = kernelContractAuthorityPin(authority);
-  if (pin.kernelContractAuthority === null) {
-    throw new KernelContractAuthorityPinError(
-      KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE,
-      `${label} states kernel contract authority ${actual.sourceCommit} (${actual.digest}) but the pin records none ` +
-        `(it was written for a data root without a runtime image source index); review the index, then re-pin with \`${REPIN_COMMAND}\``,
-    );
-  }
-  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 });
-  const pin = readEvidenceTrustPin({ dataRoot, declaration });
-  assertPinnedPolicy({ pin, policyDigest });
-  assertPinnedThirdPartySourcePins({ pin, dataRoot });
-  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, the oras digests and (when the data root holds the file) the third-party source pins' digest. */
-export function writeEvidenceTrustPin({
-  dataRoot,
-  declaration,
-  policyDigest,
-  verifier,
-  kernelContractAuthority,
-  trustedOrasBinaryDigests,
-  thirdPartySourcePinsDigest: sourcePinsDigest = null,
-}) {
-  const pin = {
-    schemaVersion: EVIDENCE_TRUST_PIN_SCHEMA_VERSION,
-    policyDigest,
-    verifier: {
-      bundleDigest: verifier.bundleDigest,
-      provenanceDigest: verifier.provenanceDigest,
-    },
-    kernelContractAuthority: kernelContractAuthority === null ? null : { ...kernelContractAuthorityPin(kernelContractAuthority) },
-    trustedOrasBinaryDigests: [...requireOrasDigests(trustedOrasBinaryDigests)].sort(),
-    ...(sourcePinsDigest === null
-      ? {}
-      : { [THIRD_PARTY_SOURCE_PINS_DIGEST_KEY]: requireDigest(sourcePinsDigest, THIRD_PARTY_SOURCE_PINS_DIGEST_KEY) }),
-  };
-  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;
-}