@xemahq/xema 0.59.0 → 0.60.1

package/edition/verifier-provenance.mjs

@@ -1,64 +0,0 @@
-// The provenance record written beside the evidence verifier bundle, and the
-// one reader of it. The build writes it (`scripts/build-evidence-verifier.mjs`);
-// the data root pins its digest beside the bundle's.
-//
-// Deterministic by construction: no timestamps, no host paths. Every bundled
-// input is {package, version, path relative to ITS package root, sha256}, so the
-// record does not depend on how the dependencies were installed.
-
-import { sha256Digest } from './image-evidence.mjs';
-import { compareStrings } from './string-order.mjs';
-
-export const VERIFIER_PROVENANCE_SCHEMA_VERSION = 1;
-
-const PROVENANCE_KEYS = Object.freeze([
-  'artifactSha256',
-  'esbuild',
-  'inputs',
-  'schemaVersion',
-]);
-const INPUT_KEYS = Object.freeze(['package', 'path', 'sha256', 'version']);
-const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
-
-const exactKeys = (value, keys) =>
-  value !== null &&
-  typeof value === 'object' &&
-  !Array.isArray(value) &&
-  Object.keys(value).sort().join() === keys.join();
-
-/** Total order of inputs: package, then path. */
-export const compareProvenanceInputs = (a, b) =>
-  compareStrings(a.package, b.package) || compareStrings(a.path, b.path);
-
-/** Parse provenance bytes strictly, binding them to the bundle they describe. */
-export function parseVerifierProvenance({ provenanceBytes, bundleBytes }) {
-  const provenance = JSON.parse(provenanceBytes.toString('utf8'));
-  if (
-    !exactKeys(provenance, PROVENANCE_KEYS) ||
-    provenance.schemaVersion !== VERIFIER_PROVENANCE_SCHEMA_VERSION ||
-    !exactKeys(provenance.esbuild, ['version']) ||
-    typeof provenance.esbuild.version !== 'string' ||
-    !Array.isArray(provenance.inputs) ||
-    provenance.inputs.length === 0
-  ) {
-    throw new Error('verifier provenance has an invalid structure');
-  }
-  provenance.inputs.forEach((input, index) => {
-    if (
-      !exactKeys(input, INPUT_KEYS) ||
-      INPUT_KEYS.some((key) => typeof input[key] !== 'string' || input[key] === '') ||
-      !SHA256_DIGEST.test(input.sha256) ||
-      input.path.startsWith('/') ||
-      input.path.split('/').includes('..') ||
-      (index > 0 && compareProvenanceInputs(provenance.inputs[index - 1], input) >= 0)
-    ) {
-      throw new Error(
-        `verifier provenance input ${index} is malformed or out of order`,
-      );
-    }
-  });
-  if (provenance.artifactSha256 !== sha256Digest(bundleBytes)) {
-    throw new Error('verifier provenance does not describe this bundle');
-  }
-  return provenance;
-}

package/edition/verify-catalogue-evidence.mjs

@@ -1,247 +0,0 @@
-// verify-catalogue-evidence — the `catalogue-evidence` mode of the evidence verifier bundle.
-//
-//   <bundle> catalogue-evidence arming --channel <release|develop> --data-root <dir>
-//   <bundle> catalogue-evidence verify --channel <c> --data-root <dir> --evidence-root <abs dir>
-//     --statement-digest <sha256:..> --bundle-digest <sha256:..> --workflow-sha <40hex> --offering-id <id>
-//     --subject-digest <sha256:..> --catalogue-layer-digest <sha256:..> --lock-layer-digest <sha256:..>
-//     --cosign <abs path>
-//
-// A customer verifies the E4 statement of a release catalogue BEFORE the catalogue's kernel is adopted, so there is no
-// kernel package to load schemas from yet. The only kernel-dependent parts of the judgement are the policy schema
-// (parseSigstoreOfflineTrustPolicy) and the predicate-type/channel constants; before adoption they come from the pinned
-// bundle's own embedded kernel, through `loadVerifierKernelSchemas` and nowhere else. This mode never takes `--kernel`.
-//
-// The anchors are the customer's pinned policy and the pinned verifier itself (the bundle refuses to run unless its own
-// bytes are the ones the data-root pin records). There is NO git grading in this mode: it reads no checkout of an editions
-// root, only the declared policy and pin of the data root, both of which the pin binds by digest.
-//
-// ONE arming rule (trust-policy-arming.mjs): the policy must be ARMED on the channel with the E4 row required
-// (`consumesCatalogue: true`); `arming` stops there. `verify` then holds the statement to that policy and to the exact
-// manifest, catalogue layer and lock layer the caller read, with the kernel's own `editionCatalogueRefusal`.
-
-import { editionWorkspaceConfig, resetEditionWorkspaceConfig } from './edition-config.mjs';
-import { EDITION_CONTRACT } from './edition-constants.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromArgv, dataRoot } from './edition-workspace.mjs';
-import {
-  assertPinnedPolicy,
-  assertPinnedThirdPartySourcePins,
-  assertPinnedVerifier,
-  loadDeclaredTrustPolicy,
-  readEvidenceTrustPin,
-  verifierDigests,
-} from './evidence-trust-pin.mjs';
-import { prepareTrustedCosignBinary, verifySigstoreEvidenceDescriptor } from './image-evidence.mjs';
-import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
-import { TrustPolicyArmingState, assessTrustPolicyArming } from './trust-policy-arming.mjs';
-import { assertSanitizedOperatorEnvironment, readRunningVerifier } from './verifier-binding.mjs';
-import { loadVerifierKernelSchemas } from './verifier-kernel-schemas.mjs';
-
-/** The first argument that selects this mode of the bundle. */
-export const CATALOGUE_EVIDENCE_MODE = 'catalogue-evidence';
-export const CATALOGUE_EVIDENCE_USAGE =
-  'usage: catalogue-evidence arming --channel <release|develop> --data-root <dir> | ' +
-  'catalogue-evidence verify --channel <c> --data-root <dir> --evidence-root <abs dir> --statement-digest <sha256:..> ' +
-  '--bundle-digest <sha256:..> --workflow-sha <40-hex> --offering-id <id> --subject-digest <sha256:..> ' +
-  '--catalogue-layer-digest <sha256:..> --lock-layer-digest <sha256:..> --cosign <abs path>';
-
-export const CATALOGUE_EVIDENCE_STATEMENT_FILE = 'statement.json';
-export const CATALOGUE_EVIDENCE_BUNDLE_FILE = 'bundle.sigstore.json';
-/** The code of the refusal that the data root's policy is not armed (also the code of the library's error). */
-export const CATALOGUE_EVIDENCE_UNARMED_CODE = EDITION_CONTRACT.evidenceTrust.refusal.code;
-
-export const CatalogueEvidenceRefusalCode = Object.freeze({
-  SubjectMismatch: 'catalogue_evidence_subject_mismatch',
-  OfferingMismatch: 'catalogue_evidence_offering_mismatch',
-  LockDigestMismatch: 'catalogue_evidence_lock_digest_mismatch',
-});
-
-const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
-const COMMIT = /^[a-f0-9]{40}$/;
-const ARMING_FLAGS = Object.freeze(['--channel']);
-const VERIFY_FLAGS = Object.freeze([
-  '--channel',
-  '--evidence-root',
-  '--statement-digest',
-  '--bundle-digest',
-  '--workflow-sha',
-  '--offering-id',
-  '--subject-digest',
-  '--catalogue-layer-digest',
-  '--lock-layer-digest',
-  '--cosign',
-]);
-const ABSOLUTE_FLAGS = Object.freeze(['--evidence-root', '--cosign']);
-const DIGEST_FLAGS = Object.freeze(['--statement-digest', '--bundle-digest', '--subject-digest', '--catalogue-layer-digest', '--lock-layer-digest']);
-
-/** A bad command line: exit 2. */
-export class CatalogueEvidenceUsageError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'CatalogueEvidenceUsageError';
-  }
-}
-
-/** The data root's policy is not armed (or declared) for a catalogue consumer on the channel. Carries the stable code. */
-export class CatalogueEvidenceUnarmedError extends Error {
-  constructor(message) {
-    super(`${CATALOGUE_EVIDENCE_UNARMED_CODE}: ${message}`);
-    this.name = 'EvidenceTrustRequiredError';
-    this.code = CATALOGUE_EVIDENCE_UNARMED_CODE;
-  }
-}
-
-/** The statement does not bind what the caller read; `code` is the refusal's stable name. */
-export class CatalogueEvidenceRefusal extends Error {
-  constructor(code, message) {
-    super(`${code}: ${message}`);
-    this.name = 'CatalogueEvidenceRefusal';
-    this.code = code;
-  }
-}
-
-const hexOf = (digest) => digest.slice('sha256:'.length);
-
-function parseFlags(args, allowed) {
-  const flags = new Map();
-  for (let index = 0; index < args.length; index += 2) {
-    const flag = args[index];
-    const value = args[index + 1];
-    if (typeof flag !== 'string' || !allowed.includes(flag)) {
-      throw new CatalogueEvidenceUsageError(`unknown or unexpected argument ${JSON.stringify(flag)}`);
-    }
-    if (value === undefined || value.startsWith('--')) {throw new CatalogueEvidenceUsageError(`${flag} requires a value`);}
-    if (flags.has(flag)) {throw new CatalogueEvidenceUsageError(`${flag} was given twice`);}
-    flags.set(flag, value);
-  }
-  for (const flag of allowed) {
-    if (!flags.has(flag)) {throw new CatalogueEvidenceUsageError(`${flag} is required`);}
-  }
-  for (const flag of ABSOLUTE_FLAGS.filter((candidate) => flags.has(candidate))) {
-    if (!flags.get(flag).startsWith('/')) {throw new CatalogueEvidenceUsageError(`${flag} must be an absolute path`);}
-  }
-  for (const flag of DIGEST_FLAGS.filter((candidate) => flags.has(candidate))) {
-    if (!SHA256_DIGEST.test(flags.get(flag))) {throw new CatalogueEvidenceUsageError(`${flag} must be sha256:<64 lowercase hex>`);}
-  }
-  if (flags.has('--workflow-sha') && !COMMIT.test(flags.get('--workflow-sha'))) {
-    throw new CatalogueEvidenceUsageError('--workflow-sha must be a 40-character lowercase hexadecimal git commit SHA');
-  }
-  return flags;
-}
-
-/**
- * The anchors, then the ONE arming rule: the sanitized launch, the running verifier, the declared policy held to the
- * data-root pin of both the policy and THIS verifier, and the policy ARMED on `channel` with the E4 row required.
- */
-async function armedAnchors({ channel, env, bundlePath }) {
-  assertSanitizedOperatorEnvironment(env);
-  const running = readRunningVerifier(bundlePath);
-  const { schemas } = await loadVerifierKernelSchemas();
-  resetEditionWorkspaceConfig();
-  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
-  if (declaration.policy === null) {
-    throw new CatalogueEvidenceUnarmedError(`${dataRoot()} declares no evidenceTrustPolicy in edition-workspace.json`);
-  }
-  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot: dataRoot(), declaration, schemas });
-  const pin = readEvidenceTrustPin({ dataRoot: dataRoot(), declaration });
-  assertPinnedPolicy({ pin, policyDigest });
-  assertPinnedThirdPartySourcePins({ pin, dataRoot: dataRoot() });
-  assertPinnedVerifier({ pin, actual: verifierDigests(running) });
-  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue: true });
-  if (state !== TrustPolicyArmingState.ARMED) {
-    throw new CatalogueEvidenceUnarmedError(
-      `the declared policy is ${state.toUpperCase()} on the ${channel} channel for a catalogue consumer: ${unmet.join('; ')}`,
-    );
-  }
-  return { schemas, policy };
-}
-
-/**
- * Run the mode. `argv` is the bundle's arguments (`['catalogue-evidence', '<phase>', ...]`). Resolves to the JSON line to
- * print on success; rejects with a named error otherwise.
- */
-export async function runCatalogueEvidence({ argv, env, bundlePath }) {
-  const [mode, phase, ...tail] = argv;
-  if (mode !== CATALOGUE_EVIDENCE_MODE || (phase !== 'arming' && phase !== 'verify')) {
-    throw new CatalogueEvidenceUsageError(CATALOGUE_EVIDENCE_USAGE);
-  }
-  // `--kernel` is no root of this mode: the schemas are the bundle's own.
-  let rest;
-  try {
-    rest = configureEditionWorkspaceFromArgv(tail, [WorkspaceRoot.Data], { refuseOthers: true });
-  } catch (error) {
-    throw new CatalogueEvidenceUsageError(error.message);
-  }
-  const flags = parseFlags(rest, phase === 'arming' ? ARMING_FLAGS : VERIFY_FLAGS);
-  const channel = flags.get('--channel');
-  const { schemas, policy } = await armedAnchors({ channel, env, bundlePath });
-  if (phase === 'arming') {
-    return `${JSON.stringify({ channel, state: TrustPolicyArmingState.ARMED })}\n`;
-  }
-  const offeringId = flags.get('--offering-id');
-  const descriptor = {
-    statementPath: CATALOGUE_EVIDENCE_STATEMENT_FILE,
-    statementDigest: flags.get('--statement-digest'),
-    bundlePath: CATALOGUE_EVIDENCE_BUNDLE_FILE,
-    bundleDigest: flags.get('--bundle-digest'),
-    bundleMediaType: BUNDLE_MEDIA_TYPE,
-  };
-  const trustedCosign = prepareTrustedCosignBinary({ cosignBinary: flags.get('--cosign'), policy });
-  let statement;
-  try {
-    ({ statement } = verifySigstoreEvidenceDescriptor({
-      evidenceRoot: flags.get('--evidence-root'),
-      descriptor,
-      policy,
-      predicateType: schemas.EDITION_CATALOGUE_PREDICATE_TYPE,
-      channel,
-      expectedWorkflowSha: flags.get('--workflow-sha'),
-      parseStatement: schemas.parseEditionCatalogueStatement,
-      policyRoot: dataRoot(),
-      trustedCosign,
-    }));
-  } finally {
-    trustedCosign.dispose();
-  }
-  const [subject] = statement.subject;
-  const expectedSubject = `xema-edition-${offeringId}`;
-  if (subject.digest.sha256 !== hexOf(flags.get('--subject-digest')) || subject.name !== expectedSubject) {
-    throw new CatalogueEvidenceRefusal(
-      CatalogueEvidenceRefusalCode.SubjectMismatch,
-      `the statement is over ${subject.name}@sha256:${subject.digest.sha256}, not ${expectedSubject}@${flags.get('--subject-digest')}`,
-    );
-  }
-  const refusal = schemas.editionCatalogueRefusal(statement.predicate, {
-    channel,
-    catalogueLayerDigest: flags.get('--catalogue-layer-digest'),
-  });
-  if (refusal !== undefined) {
-    throw new CatalogueEvidenceRefusal(
-      refusal,
-      `the statement states channel ${statement.predicate.channel} and catalogue ${statement.predicate.catalogueDigest}; ` +
-        `this catalogue is on ${channel} with layer ${flags.get('--catalogue-layer-digest')}`,
-    );
-  }
-  if (statement.predicate.offeringId !== offeringId) {
-    throw new CatalogueEvidenceRefusal(
-      CatalogueEvidenceRefusalCode.OfferingMismatch,
-      `the statement is for offering ${statement.predicate.offeringId}, not ${offeringId}`,
-    );
-  }
-  if (statement.predicate.lockDigest !== hexOf(flags.get('--lock-layer-digest'))) {
-    throw new CatalogueEvidenceRefusal(
-      CatalogueEvidenceRefusalCode.LockDigestMismatch,
-      `the statement states lock digest ${statement.predicate.lockDigest}, not that of the lock layer ${flags.get('--lock-layer-digest')}`,
-    );
-  }
-  return `${JSON.stringify({ verified: true, offeringId, channel, statementDigest: descriptor.statementDigest })}\n`;
-}
-
-/** Run the mode as the bundle's entry: print its line, or the named refusal on stderr with exit 1 (usage: 2). */
-export async function runCatalogueEvidenceEntry({ argv, env, bundlePath }) {
-  try {
-    process.stdout.write(await runCatalogueEvidence({ argv, env, bundlePath }));
-  } catch (error) {
-    process.stderr.write(`catalogue-evidence: ${error.name}: ${error.message}\n`);
-    process.exitCode = error instanceof CatalogueEvidenceUsageError ? 2 : 1;
-  }
-}