@xemahq/xema 0.59.0 → 0.60.1

package/edition/verify-image-evidence.mjs

@@ -1,475 +0,0 @@
-// The evidence verifier. This module is the ENTRY of the verifier bundle
-// (`scripts/build-evidence-verifier.mjs` -> dist/edition/verify-image-evidence
-// .bundle.mjs); `xema edition verify-evidence` runs that built file, never this
-// source. Run as the bundle it refuses, before it trusts anything, unless:
-//
-//   * its launch environment carries no NODE_OPTIONS/NODE_PATH/DYLD_*/LD_*/GIT_*;
-//   * its own file and provenance hash to the digests the data root PINS, and
-//     its install path and every ancestor are not group/world writable or
-//     foreign-owned;
-//   * the kernel `--kernel` states declares, as data, exactly the edition
-//     protocol compiled into the bundle, and this CLI supports it;
-//   * the data root and the editions root are clean git checkouts at an exact
-//     HEAD with every file read from them bound to its HEAD blob.
-//
-// A second mode, `catalogue-evidence arming|verify` (verify-catalogue-evidence.mjs), judges a release catalogue's E4
-// statement for a customer before the catalogue's kernel is adopted; it is selected by the first argument.
-//
-// usage: verify-image-evidence <distributionId> --evidence-root <dir>
-//   --descriptor <absolute-path> --state <absolute-path> --cosign <absolute-path> --git <absolute-path>
-//   [--evidence-set <relative-path>] --data-root <dir> --editions-root <dir>
-//   --kernel <dir>
-
-import { readFileSync, realpathSync } from 'node:fs';
-import { isAbsolute } from 'node:path';
-
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import { parseEditionDescriptor } from './edition-artifact.mjs';
-import { EditionChannel } from './edition-channel.mjs';
-import { editionWorkspaceConfig, resetEditionWorkspaceConfig } from './edition-config.mjs';
-import { assertKernelSpeaksBundledProtocol } from './edition-protocol.mjs';
-import {
-  WorkspaceRoot,
-  configureEditionWorkspaceFromArgv,
-  dataRoot,
-  editionsRoot,
-  isEntryModule,
-  kernelPackageDir,
-} from './edition-workspace.mjs';
-import {
-  assertExternalInput,
-  gradeTrustedCheckouts,
-  prepareTrustedGitBinary,
-} from './evidence-checkout.mjs';
-import {
-  RUNTIME_IMAGE_SOURCE_INDEX_FILE,
-  assertPinnedKernelContractAuthority,
-  assertPinnedPolicy,
-  assertPinnedThirdPartySourcePins,
-  assertPinnedVerifier,
-  readStatedKernelContractAuthority,
-  loadDeclaredTrustPolicy,
-  readEvidenceTrustPin,
-  trustPolicyDigest,
-  verifierDigests,
-} from './evidence-trust-pin.mjs';
-import {
-  assertEntitlementDescriptorStates,
-  entitlementEvidenceRoot,
-  parseEntitlementDescriptorDocument,
-} from './image-delivery-entitlement-descriptor.mjs';
-import { verifyAndAdvanceReplayState } from './image-evidence-replay-state.mjs';
-import {
-  readCanonicalJsonFromRoot,
-  verifyDistributionImageEvidenceSet,
-  verifyImageDeliveryEntitlement,
-} from './image-evidence.mjs';
-import {
-  assertSanitizedOperatorEnvironment,
-  readRunningVerifier,
-} from './verifier-binding.mjs';
-import { loadVerifierKernelSchemas } from './verifier-kernel-schemas.mjs';
-import {
-  CATALOGUE_EVIDENCE_MODE,
-  runCatalogueEvidenceEntry,
-} from './verify-catalogue-evidence.mjs';
-
-const USAGE =
-  'usage: verify-image-evidence <distributionId> --evidence-root <dir> --descriptor <absolute-path> --state <absolute-path> ' +
-  '--cosign <absolute-path> --git <absolute-path> [--evidence-set <relative-path>] [--json] ' +
-  '[--entitlement <relative-path> --entitlement-workflow-sha <40-hex git sha> --customer <id> --mode <mode> [--target-registry <registry>]] ' +
-  '--data-root <dir> --editions-root <dir> --kernel <dir>';
-// The edition channel -> the kernel's evidence channel, stated once and explicitly.
-const EVIDENCE_CHANNEL_OF_EDITION_CHANNEL = Object.freeze({
-  [EditionChannel.Release]: 'release',
-  [EditionChannel.Develop]: 'develop',
-});
-const GIT_COMMIT_SHA = /^[a-f0-9]{40}$/;
-const DATA_ROOT_FILES = Object.freeze(['edition-workspace.json', 'runtime-image-source-index.json']);
-
-function requireOptionValue(args, index, flag) {
-  const value = args[index + 1];
-  if (value === undefined || value.startsWith('--')) {
-    throw new Error(`${flag} requires a value`);
-  }
-  return value;
-}
-
-function parseArgs(args) {
-  const [distributionId, ...withJson] = args;
-  const jsonFlags = withJson.filter((arg) => arg === '--json').length;
-  if (jsonFlags > 1) {throw new Error('--json was given twice');}
-  const rest = withJson.filter((arg) => arg !== '--json');
-  try {
-    assertCanonicalDistributionId(distributionId);
-  } catch {
-    throw new Error(USAGE);
-  }
-  const options = {
-    distributionId,
-    evidenceRoot: null,
-    evidenceSetPath: 'evidence-set.json',
-    json: jsonFlags === 1,
-    descriptorPath: null,
-    statePath: null,
-    cosignBinary: null,
-    gitBinary: null,
-    entitlementDescriptorPath: null,
-    entitlementWorkflowSha: null,
-    customerId: null,
-    mode: null,
-    targetRegistry: null,
-  };
-  const seen = new Set();
-  for (let index = 0; index < rest.length; index += 2) {
-    const flag = rest[index];
-    const value = requireOptionValue(rest, index, flag);
-    if (seen.has(flag)) {throw new Error(`${flag} was given twice`);}
-    seen.add(flag);
-    if (flag === '--evidence-root') {options.evidenceRoot = value;}
-    else if (flag === '--evidence-set') {options.evidenceSetPath = value;}
-    else if (flag === '--descriptor') {options.descriptorPath = value;}
-    else if (flag === '--state') {options.statePath = value;}
-    else if (flag === '--cosign') {options.cosignBinary = value;}
-    else if (flag === '--git') {options.gitBinary = value;}
-    else if (flag === '--entitlement') {options.entitlementDescriptorPath = value;}
-    else if (flag === '--entitlement-workflow-sha') {options.entitlementWorkflowSha = value;}
-    else if (flag === '--customer') {options.customerId = value;}
-    else if (flag === '--mode') {options.mode = value;}
-    else if (flag === '--target-registry') {options.targetRegistry = value;}
-    else {throw new Error(`unknown option "${flag}"`);}
-  }
-  if (!options.evidenceRoot) {
-    throw new Error('--evidence-root is required');
-  }
-  for (const [flag, value] of [
-    ['--descriptor', options.descriptorPath],
-    ['--state', options.statePath],
-    ['--cosign', options.cosignBinary],
-    ['--git', options.gitBinary],
-  ]) {
-    if (!value || !isAbsolute(value)) {
-      throw new Error(`${flag} is required and must be an absolute path`);
-    }
-  }
-  // An entitlement is verified whole or not at all: the descriptor names the
-  // signed statement, the workflow SHA is the exact commit its certificate is
-  // held to (stated by the caller, never read from the evidence), and the
-  // customer and mode are what it must be bound to.
-  const entitlementFlags = [
-    ['--entitlement', options.entitlementDescriptorPath],
-    ['--entitlement-workflow-sha', options.entitlementWorkflowSha],
-    ['--customer', options.customerId],
-    ['--mode', options.mode],
-  ];
-  const stated = entitlementFlags.filter(([, value]) => value !== null);
-  if (stated.length !== 0 && stated.length !== entitlementFlags.length) {
-    throw new Error(
-      `${entitlementFlags.map(([flag]) => flag).join(', ')} are given together or not at all`,
-    );
-  }
-  if (stated.length === 0 && options.targetRegistry !== null) {
-    throw new Error('--target-registry needs --entitlement, --entitlement-workflow-sha, --customer and --mode');
-  }
-  if (options.entitlementWorkflowSha !== null && !GIT_COMMIT_SHA.test(options.entitlementWorkflowSha)) {
-    throw new Error('--entitlement-workflow-sha must be a 40-character lowercase hexadecimal git commit SHA');
-  }
-  if (options.entitlementDescriptorPath !== null && isAbsolute(options.entitlementDescriptorPath)) {
-    throw new Error('--entitlement must be an evidence-root-relative path');
-  }
-  return options;
-}
-
-/**
- * The channel the edition being verified was produced on: the descriptor's
- * `provenance.channel`, mapped to the kernel's evidence channel. The descriptor
- * must be the one of the requested distribution; an unmapped channel is refused.
- */
-function readEvidenceChannel({ descriptorPath, distributionId, schemas }) {
-  const descriptor = parseEditionDescriptor(JSON.parse(readFileSync(descriptorPath, 'utf8')));
-  if (descriptor.distributionId !== distributionId) {
-    throw new Error(
-      `--descriptor is the descriptor of "${descriptor.distributionId}", not of the requested distribution "${distributionId}"`,
-    );
-  }
-  const channel = EVIDENCE_CHANNEL_OF_EDITION_CHANNEL[descriptor.provenance.channel];
-  if (channel === undefined || !schemas.EVIDENCE_CHANNELS.includes(channel)) {
-    throw new Error(
-      `the descriptor channel "${descriptor.provenance.channel}" maps to no kernel evidence channel`,
-    );
-  }
-  return channel;
-}
-
-export const EDITION_EVIDENCE_VERIFICATION_SCHEMA = 'xema.edition-evidence-verification/v1';
-
-/**
- * What `--json` prints once the evidence is verified: the channel it was verified
- * on, the release sequence it proved, and the statementDigest (the digest of the verified in-toto statement, not of the image) of every statement verified
- * (producers by subject, then completeness, then the entitlement if one was asked for).
- * `entitlementDescriptor` is the Sigstore evidence descriptor `entitlement.json` holds.
- */
-export function evidenceVerificationDocument({ distributionId, channel, evidenceSet, verified, entitlementDescriptor }) {
-  const producers = evidenceSet.producerEvidence
-    .map((producer) => {
-      const statement = verified.producerStatements.get(`${producer.subjectKind}\0${producer.subjectId}`);
-      return {
-        predicateType: statement.predicateType,
-        subject: statement.subject[0].name,
-        statementDigest: producer.evidence.statementDigest,
-      };
-    })
-    .sort((left, right) => (left.subject < right.subject ? -1 : left.subject > right.subject ? 1 : 0));
-  const statements = [
-    ...producers,
-    {
-      predicateType: verified.completenessStatement.predicateType,
-      subject: verified.completenessStatement.subject[0].name,
-      statementDigest: evidenceSet.completeness.statementDigest,
-    },
-  ];
-  if (verified.entitlementStatement !== null) {
-    statements.push({
-      predicateType: verified.entitlementStatement.predicateType,
-      subject: verified.entitlementStatement.subject[0].name,
-      statementDigest: entitlementDescriptor.statementDigest,
-    });
-  }
-  return {
-    schema: EDITION_EVIDENCE_VERIFICATION_SCHEMA,
-    distributionId,
-    channel,
-    releaseSequence: verified.completenessStatement.predicate.releaseSequence,
-    statements,
-  };
-}
-
-/**
- * The declared policy, held to the data-root pin of both the policy and THIS
- * running verifier. Read from the working tree: it is read twice, before the
- * checkouts are graded (the policy names the git binary that grades them) and
- * after, and the two readings must be the same policy.
- */
-function readTrustAnchors({ schemas, running }) {
-  resetEditionWorkspaceConfig();
-  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
-  if (declaration.policy === null) {
-    throw new Error(
-      `${dataRoot()} declares no evidenceTrustPolicy in edition-workspace.json; there is no policy to verify against`,
-    );
-  }
-  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) });
-  // The authority the producer statements are held to is read from the data
-  // root's index downstream; it is the pinned one, or nothing is verified.
-  assertPinnedKernelContractAuthority({
-    pin,
-    authority: readStatedKernelContractAuthority({ dataRoot: dataRoot(), schemas }),
-    label: RUNTIME_IMAGE_SOURCE_INDEX_FILE,
-  });
-  return { declaration, policy, policyDigest };
-}
-
-/**
- * Verify the evidence for one edition. `bundlePath` is the running bundle
- * (`process.argv[1]` when run as one).
- */
-export async function verifyEvidence({ argv, env, bundlePath }) {
-  assertSanitizedOperatorEnvironment(env);
-  const options = parseArgs(
-    configureEditionWorkspaceFromArgv(argv, [
-      WorkspaceRoot.Data,
-      WorkspaceRoot.Editions,
-      WorkspaceRoot.Kernel,
-    ]),
-  );
-  const evidenceRoot = realpathSync(options.evidenceRoot);
-  const running = readRunningVerifier(bundlePath);
-  const { schemas, editionProtocol } = await loadVerifierKernelSchemas();
-  assertKernelSpeaksBundledProtocol({
-    kernelPackageDir: kernelPackageDir(),
-    bundled: editionProtocol,
-  });
-  const first = readTrustAnchors({ schemas, running });
-  const trustedGit = prepareTrustedGitBinary({
-    gitBinary: options.gitBinary,
-    policy: first.policy,
-  });
-  try {
-    const grades = [
-      {
-        root: dataRoot(),
-        label: 'data root',
-        requiredPaths: [
-          ...DATA_ROOT_FILES,
-          first.declaration.policy,
-          first.declaration.pin,
-          first.policy.trustedRootPath,
-        ],
-      },
-      {
-        root: editionsRoot(),
-        label: 'editions root',
-        requiredPaths: [
-          'distribution.lock.json',
-          'images.lock.json',
-          'xema-distribution.json',
-        ].map((file) => `${options.distributionId}/${file}`),
-      },
-    ];
-    const graded = gradeTrustedCheckouts({ grades, trustedGit });
-    const repositoryRoots = new Set(
-      [...graded.values()].map((checkout) => checkout.repositoryRoot),
-    );
-    // Now that the files are bound to HEAD, the policy and pin read above must
-    // be the ones that were graded.
-    const anchors = readTrustAnchors({ schemas, running });
-    if (anchors.policyDigest !== first.policyDigest) {
-      throw new Error('the trust policy changed while the checkouts were graded');
-    }
-    assertExternalInput(repositoryRoots, evidenceRoot, 'evidence root');
-    assertExternalInput(repositoryRoots, options.statePath, 'replay state');
-    assertExternalInput(repositoryRoots, options.descriptorPath, 'edition descriptor');
-    const channel = readEvidenceChannel({
-      descriptorPath: options.descriptorPath,
-      distributionId: options.distributionId,
-      schemas,
-    });
-    const releaseSourceCommit = graded.get(realpathSync(editionsRoot())).commit;
-    const assertCheckoutsUnchanged = () =>
-      gradeTrustedCheckouts({ grades, trustedGit, expected: graded });
-    const evidenceSet = schemas.parseDistributionImageEvidenceSet(
-      readCanonicalJsonFromRoot(
-        evidenceRoot,
-        options.evidenceSetPath,
-        'distribution image evidence set',
-      ),
-    );
-    const policyDigest = trustPolicyDigest(anchors.policy);
-    const { verified } = await verifyAndAdvanceReplayState({
-      statePath: options.statePath,
-      distributionId: options.distributionId,
-      trustPolicyDigest: policyDigest,
-      parseReplayState: schemas.parseDistributionImageReplayState,
-      verify: async () => {
-        assertCheckoutsUnchanged();
-        const result = await verifyDistributionImageEvidenceSet({
-          distributionId: options.distributionId,
-          channel,
-          dataRoot: dataRoot(),
-          editionsRoot: editionsRoot(),
-          evidenceRoot,
-          evidenceSet,
-          policy: anchors.policy,
-          policyRoot: dataRoot(),
-          now: new Date(),
-          expectedReleaseSourceCommit: releaseSourceCommit,
-          cosignBinary: options.cosignBinary,
-          schemas,
-        });
-        const entitlement =
-          options.entitlementDescriptorPath === null
-            ? null
-            : parseEntitlementDescriptorDocument(
-                readCanonicalJsonFromRoot(
-                  evidenceRoot,
-                  options.entitlementDescriptorPath,
-                  'delivery entitlement descriptor',
-                ),
-                schemas,
-              );
-        if (entitlement !== null) {
-          assertEntitlementDescriptorStates(entitlement, {
-            distributionId: options.distributionId,
-            customerId: options.customerId,
-            mode: options.mode,
-            targetRegistry: options.targetRegistry,
-            distributionStatementDigest: result.completenessStatementDigest,
-          });
-        }
-        const entitlementDescriptor = entitlement === null ? null : entitlement.evidence;
-        const entitlementStatement =
-          entitlementDescriptor === null
-            ? null
-            : await verifyImageDeliveryEntitlement({
-                evidenceRoot: entitlementEvidenceRoot(evidenceRoot, options.entitlementDescriptorPath),
-                descriptor: entitlementDescriptor,
-                policy: anchors.policy,
-                policyRoot: dataRoot(),
-                completenessStatementDigest: result.completenessStatementDigest,
-                customerId: options.customerId,
-                distributionId: options.distributionId,
-                distributionLock: result.distributionLock,
-                channel,
-                mode: options.mode,
-                targetRegistry: options.targetRegistry,
-                now: new Date(),
-                // The entitlement predicate carries no producer run: the commit
-                // its certificate is held to is the caller's statement.
-                expectedWorkflowSha: options.entitlementWorkflowSha,
-                // A nonce spent by a producer or completeness statement of
-                // this release cannot be reused by its entitlement.
-                consumedNonces: result.verifiedNonces,
-                cosignBinary: options.cosignBinary,
-                schemas,
-              });
-        assertCheckoutsUnchanged();
-        return { ...result, entitlementStatement, entitlementDescriptor };
-      },
-    });
-    // With --json the human text goes to stderr and stdout carries the one document.
-    (options.json ? process.stderr : process.stdout).write(
-      `verified ${verified.producerStatements.size} image producers and distribution completeness for ` +
-        `"${options.distributionId}" at release sequence ` +
-        `${verified.completenessStatement.predicate.releaseSequence}\n` +
-        `edition read from ${editionsRoot()} at editions checkout commit ${releaseSourceCommit}\n` +
-        (verified.entitlementStatement === null
-          ? ''
-          : `verified the delivery entitlement of "${options.customerId}" (${options.mode})\n`),
-    );
-    if (options.json) {
-      process.stdout.write(
-        `${JSON.stringify(
-          evidenceVerificationDocument({
-            distributionId: options.distributionId,
-            channel,
-            evidenceSet,
-            verified,
-            entitlementDescriptor: verified.entitlementDescriptor,
-          }),
-          null,
-          2,
-        )}\n`,
-      );
-    }
-  } finally {
-    trustedGit.dispose();
-  }
-}
-
-if (isEntryModule(import.meta.url) && process.argv[2] === CATALOGUE_EVIDENCE_MODE) {
-  // The customer's pre-adoption mode: the E4 statement of a catalogue, judged with this bundle's own embedded kernel.
-  await runCatalogueEvidenceEntry({
-    argv: process.argv.slice(2),
-    env: process.env,
-    bundlePath: process.argv[1],
-  });
-} else if (isEntryModule(import.meta.url)) {
-  await verifyEvidence({
-    argv: process.argv.slice(2),
-    env: process.env,
-    bundlePath: process.argv[1],
-  }).catch((error) => {
-    // A named refusal (e.g. EditionProtocolMismatchError) is printed with its name.
-    const named = error.name && error.name !== 'Error' ? `${error.name}: ` : '';
-    console.error(`verify-image-evidence: ${named}${error.message}`);
-    process.exitCode = 1;
-  });
-}