@xemahq/xema 0.59.1 → 0.60.1

package/edition/oci-evidence-verbs.mjs

@@ -1,419 +0,0 @@
-#!/usr/bin/env node
-// `xema edition evidence oci <attach-plan|validate|backfill-plan>`: the OCI
-// form of image source evidence, for a caller that runs `oras` itself.
-//
-//   attach-plan   --evidence-directory <abs dir> [--input <file>]
-//   validate      --evidence-directory <abs dir> --manifest <file> --subject-digest <digest>
-//                 [--input <file> --cosign <abs path> [--now <epoch-ms>]]
-//   backfill-plan --distribution <id>… --producer-repository-root <abs dir>…
-//
-// attach-plan and validate take --data-root <dir> --kernel <dir> (vendor mode) or --contract-authority <file>
-// (public-input mode: a publisher's run with the kernel this CLI bundles); backfill-plan is vendor mode only.
-//
-// The library reads and decides; it never writes to a registry. `attach-plan`
-// validates a produced evidence directory and prints the exact `oras attach`
-// operands; `validate` holds a pulled artifact to its manifest (and, with
-// `--input`, to the producer input, the signer and a remaining lifetime);
-// `backfill-plan` joins the committed evidence of the producing repositories
-// to the locked subjects and to what each registry already serves.
-
-import { readFileSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
-
-import { MIN_REMAINING_TTL_SECONDS } from './check-committed-image-evidence.mjs';
-import {
-  expectedProducerSource,
-  indexCommittedProducerEvidence,
-  parseEvidenceCliFlags,
-} from './distribution-evidence-set.mjs';
-import { assertCanonicalDistributionId } from './distribution-paths.mjs';
-import {
-  WorkspaceRoot,
-  configureEditionWorkspaceFromArgv,
-  dataRoot,
-  editionsRoot,
-  isEntryModule,
-} from './edition-workspace.mjs';
-import { SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
-import { EvidenceInputMode, configureEvidenceInputMode } from './evidence-input-mode.mjs';
-import { canonicalJson, loadValidatedImageLocks } from './image-evidence.mjs';
-import { compareStrings, loadKernelDistributionSchemas, serializeJson } from './lib.mjs';
-import {
-  IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE,
-  createRegistryClientResolver,
-  resolveImageSourceEvidenceReferrer,
-  validateMaterializedImageSourceEvidence,
-  writeInvalidReferrerReport,
-} from './oci-image-source-evidence.mjs';
-import { REFERRERS_DISTRIBUTION_SPEC } from './oras.mjs';
-import { assertProducerInput, buildImageSourceStatements, cosignVerifyAttestationArgs, createCosignVerifier, readPinnedContractAuthority } from './produce-image-source-evidence.mjs';
-import {
-  producerEvidenceLayerFiles,
-  producerStatementMatchesInput,
-  readProducerEvidenceDirectory,
-} from './producer-evidence-bundle.mjs';
-import { splitImageRef } from './registry-credentials.mjs';
-
-const OCI_CREATED_ANNOTATION = 'org.opencontainers.image.created';
-
-/** What `backfill-plan` reports for one locked subject. */
-export const OciBackfillStatus = Object.freeze({
-  MissingGit: 'missing-git',
-  Present: 'present',
-  Missing: 'missing',
-});
-
-const USAGE = 'usage: xema edition evidence oci <attach-plan|validate|backfill-plan> [options]';
-
-function assertAbsolute(value, label) {
-  if (typeof value !== 'string' || !isAbsolute(value)) {
-    throw new Error(`${label} must be an absolute path`);
-  }
-  return value;
-}
-
-/** One evidence artifact describes one image: one repository, one manifest digest. */
-function inputSubject(input, expectedContractAuthority) {
-  assertProducerInput(input, expectedContractAuthority);
-  const repositories = new Set(input.subjects.map((subject) => subject.imageRepository));
-  const digests = new Set(input.subjects.map((subject) => subject.manifestDigest));
-  if (repositories.size !== 1 || digests.size !== 1) {
-    throw new Error('one OCI evidence artifact requires exactly one image repository and manifest digest');
-  }
-  return { imageRepository: [...repositories][0], subjectDigest: [...digests][0] };
-}
-
-function expectedStatements(input, schemas, expectedContractAuthority) {
-  return new Map(
-    buildImageSourceStatements(input, schemas, expectedContractAuthority).map((statement) => [
-      `${statement.predicate.source.kind}:${statement.predicate.source.id}`,
-      statement,
-    ]),
-  );
-}
-
-/**
- * The `oras attach` operands of one produced evidence directory. With `input`
- * every record must be the statement that input builds; without it the image
- * is the one every record names.
- */
-export function planOciEvidenceAttach({ evidenceDirectory, input, schemas, expectedContractAuthority }) {
-  assertAbsolute(evidenceDirectory, 'the evidence directory');
-  const evidence = readProducerEvidenceDirectory({ directory: evidenceDirectory, schemas });
-  if (evidence.records.length === 0) {
-    throw new Error(`${evidenceDirectory} holds no producer evidence`);
-  }
-  let image;
-  if (input === undefined) {
-    const [{ artifact }] = evidence.records.map((record) => record.statement.predicate);
-    image = { imageRepository: artifact.imageRepository, subjectDigest: artifact.manifestDigest };
-  } else {
-    image = inputSubject(input, expectedContractAuthority);
-    const expected = expectedStatements(input, schemas, expectedContractAuthority);
-    for (const record of evidence.records) {
-      const expectedStatement = expected.get(record.key);
-      if (expectedStatement === undefined || !producerStatementMatchesInput(record.statement, expectedStatement)) {
-        throw new Error(`${record.key} produced evidence is not bound to the input`);
-      }
-    }
-  }
-  for (const record of evidence.records) {
-    const { artifact } = record.statement.predicate;
-    if (artifact.imageRepository !== image.imageRepository || artifact.manifestDigest !== image.subjectDigest) {
-      throw new Error(`${record.key} evidence is not bound to ${image.imageRepository}@${image.subjectDigest}`);
-    }
-  }
-  const created = evidence.records[0].statement.predicate.producerRun.issuedAt;
-  if (evidence.records.some((record) => record.statement.predicate.producerRun.issuedAt !== created)) {
-    throw new Error('one OCI evidence artifact cannot carry multiple issuance times');
-  }
-  return {
-    schemaVersion: 1,
-    kind: 'oci-attach-plan',
-    evidenceDirectory,
-    ...image,
-    subject: `${image.imageRepository}@${image.subjectDigest}`,
-    artifactType: IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE,
-    distributionSpec: REFERRERS_DISTRIBUTION_SPEC,
-    annotations: { [OCI_CREATED_ANNOTATION]: created },
-    files: producerEvidenceLayerFiles(evidence.records),
-  };
-}
-
-/**
- * Hold a pulled evidence artifact to its manifest. With `input` it also
- * answers whether the artifact can be reused instead of producing again: the
- * statements are the ones the input builds, every bundle verifies against the
- * declared signer, and enough lifetime remains.
- */
-export function assessMaterializedOciEvidence({
-  evidenceDirectory,
-  manifest,
-  subjectDigest,
-  schemas,
-  input,
-  expectedContractAuthority,
-  runCosign,
-  now = Date.now(),
-}) {
-  assertAbsolute(evidenceDirectory, 'the evidence directory');
-  if (!SHA256_DIGEST_PATTERN.test(subjectDigest ?? '')) {
-    throw new Error('the subject digest must be sha256:<64 hex>');
-  }
-  const evidence = validateMaterializedImageSourceEvidence({
-    directory: evidenceDirectory,
-    manifest,
-    subjectDigest,
-    schemas,
-  });
-  const base = {
-    schemaVersion: 1,
-    kind: 'oci-evidence',
-    subjectDigest,
-    created: evidence.created,
-    subjects: evidence.records.map((record) => record.key),
-  };
-  if (input === undefined) {
-    return { ...base, matchesInput: null, remainingSeconds: null, reusable: null };
-  }
-  if (typeof runCosign !== 'function') {
-    throw new Error('a cosign verifier is required to assess evidence against an input');
-  }
-  const image = inputSubject(input, expectedContractAuthority);
-  if (image.subjectDigest !== subjectDigest) {
-    throw new Error(`the input describes ${image.subjectDigest}, not ${subjectDigest}`);
-  }
-  const expected = expectedStatements(input, schemas, expectedContractAuthority);
-  let matchesInput = evidence.records.length === expected.size;
-  let oldestExpiry = Number.POSITIVE_INFINITY;
-  for (const record of evidence.records) {
-    const expectedStatement = expected.get(record.key);
-    matchesInput &&=
-      expectedStatement !== undefined && producerStatementMatchesInput(record.statement, expectedStatement);
-    oldestExpiry = Math.min(oldestExpiry, Date.parse(record.statement.predicate.producerRun.expiresAt));
-    // A bundle that does not verify is a refusal, never "not reusable".
-    runCosign(
-      cosignVerifyAttestationArgs({
-        bundlePath: join(evidenceDirectory, record.descriptor.bundlePath),
-        signer: input.signer,
-        certificateWorkflowSha: record.statement.predicate.producerRun.producerWorkflowSha,
-        predicateType: record.statement.predicateType,
-      }),
-    );
-  }
-  const remainingSeconds = Math.floor((oldestExpiry - now) / 1000);
-  return {
-    ...base,
-    matchesInput,
-    remainingSeconds,
-    reusable: matchesInput && remainingSeconds >= MIN_REMAINING_TTL_SECONDS,
-  };
-}
-
-/**
- * For every locked subject of the named editions: its committed evidence and
- * whether the registry already serves it as a referrer. A `missing` item
- * carries the attach plan the caller runs.
- */
-export async function planOciEvidenceBackfill({
-  distributionIds,
-  dataRoot: data,
-  editionsRoot: editions,
-  producerRepositoryRoots,
-  schemas,
-  expectedContractAuthority,
-  registryClientFactory,
-}) {
-  const gitIndex = indexCommittedProducerEvidence({
-    producerRepositoryRoots,
-    schemas,
-    onDefect: ({ directory, reason }) => {
-      throw new Error(`Git evidence at ${directory} is unusable: ${reason}`);
-    },
-  });
-  const clientFor = createRegistryClientResolver({ dataRoot: data, factory: registryClientFactory });
-  const work = new Map();
-  const missingGit = new Map();
-  for (const distributionId of distributionIds) {
-    assertCanonicalDistributionId(distributionId);
-    const { imageLock, repositoryPins, thirdPartySources } = await loadValidatedImageLocks(distributionId, data, schemas, {
-      editionsRoot: editions,
-    });
-    for (const subject of imageLock.subjects) {
-      if (thirdPartySources.has(subject.repo)) {
-        // Evidence is attached to the registry image of a producer this fleet owns. A third-party image belongs to its
-        // publisher (its contentHash is not a tag here): its evidence is the data root's committed evidence, bound by its pin.
-        process.stderr.write(`[oci-evidence] ${distributionId} ${subject.kind}:${subject.id} is a third-party subject (${subject.repo}): no OCI evidence is attached to a publisher's image\n`);
-        continue;
-      }
-      const source = expectedProducerSource({
-        subject,
-        repositoryPin: repositoryPins.get(subject.repo),
-        sourceHashAlgorithm: imageLock.sourceHashAlgorithm,
-      });
-      const matches = gitIndex.get(canonicalJson(source)) ?? [];
-      if (matches.length > 1) {
-        throw new Error(`current ${subject.kind}:${subject.id} requires exactly one Git bundle; found ${matches.length}`);
-      }
-      if (matches.length === 0) {
-        missingGit.set(`${subject.kind}:${subject.id}\0${subject.sourceCommit}`, {
-          status: OciBackfillStatus.MissingGit,
-          subjectKind: subject.kind,
-          subjectId: subject.id,
-          imageRepository: subject.imageRef,
-          subjectDigest: null,
-          artifactDigest: null,
-        });
-        continue;
-      }
-      const [match] = matches;
-      const subjectDigest = match.statement.predicate.artifact.manifestDigest;
-      const key = `${subject.imageRef}@${subjectDigest}`;
-      const incumbent = work.get(key);
-      if (incumbent && incumbent.directory !== match.directory) {
-        throw new Error(`${key} resolves to multiple Git evidence directories`);
-      }
-      work.set(key, { subject, directory: match.directory, imageRepository: subject.imageRef, subjectDigest });
-    }
-  }
-  const items = [...missingGit.values()];
-  for (const item of [...work.values()].sort((left, right) =>
-    compareStrings(left.imageRepository, right.imageRepository),
-  )) {
-    const { authority, repository } = splitImageRef(item.imageRepository);
-    const client = clientFor(authority);
-    const served = await client.getManifestByTag(repository, item.subject.contentHash);
-    if (served.digest !== item.subjectDigest) {
-      throw new Error(
-        `${item.imageRepository}:${item.subject.contentHash} serves ${served.digest}, not signed ${item.subjectDigest}`,
-      );
-    }
-    const existing = await resolveImageSourceEvidenceReferrer({
-      client,
-      imageRepository: item.imageRepository,
-      subjectDigest: item.subjectDigest,
-      schemas,
-      expectedContractAuthority,
-      onInvalidReferrer: writeInvalidReferrerReport,
-    });
-    const reported = {
-      subjectKind: item.subject.kind,
-      subjectId: item.subject.id,
-      imageRepository: item.imageRepository,
-      subjectDigest: item.subjectDigest,
-    };
-    items.push(
-      existing === null
-        ? {
-            status: OciBackfillStatus.Missing,
-            ...reported,
-            artifactDigest: null,
-            attach: planOciEvidenceAttach({ evidenceDirectory: item.directory, schemas }),
-          }
-        : { status: OciBackfillStatus.Present, ...reported, artifactDigest: existing.artifactDigest },
-    );
-  }
-  return { schemaVersion: 1, kind: 'oci-backfill-plan', items };
-}
-
-const readJsonFile = (path, label) => {
-  try {
-    return JSON.parse(readFileSync(resolve(path), 'utf8'));
-  } catch (error) {
-    throw new Error(`${label} ${path} is not readable JSON: ${error.message}`);
-  }
-};
-
-/**
- * `attach-plan` and `validate` in one of the two input modes: the vendor's pinned authority and kernel checkout, or
- * a publisher's `--contract-authority` file with the kernel this CLI bundles.
- */
-async function ociInputMode(argv, operation) {
-  const mode = await configureEvidenceInputMode(argv, { verb: `oci ${operation}` });
-  if (mode.mode === EvidenceInputMode.PublicInput) {
-    return { rest: mode.rest, schemas: mode.schemas, expectedContractAuthority: mode.contractAuthority };
-  }
-  const schemas = await loadKernelDistributionSchemas();
-  return { rest: mode.rest, schemas, expectedContractAuthority: readPinnedContractAuthority({ dataRoot: dataRoot(), schemas }) };
-}
-
-async function main() {
-  const [operation, ...argv] = process.argv.slice(2);
-  if (operation === 'attach-plan') {
-    const { rest, schemas, expectedContractAuthority } = await ociInputMode(argv, operation);
-    const flags = parseEvidenceCliFlags(rest, { single: ['evidence-directory', 'input'] });
-    const input = flags.optional('input');
-    process.stdout.write(
-      serializeJson(
-        planOciEvidenceAttach({
-          evidenceDirectory: flags.require('evidence-directory'),
-          input: input === undefined ? undefined : readJsonFile(input, 'producer input'),
-          schemas,
-          expectedContractAuthority,
-        }),
-      ),
-    );
-    return;
-  }
-  if (operation === 'validate') {
-    const { rest, schemas, expectedContractAuthority } = await ociInputMode(argv, operation);
-    const flags = parseEvidenceCliFlags(rest, {
-      single: ['evidence-directory', 'manifest', 'subject-digest', 'input', 'cosign', 'now'],
-    });
-    const input = flags.optional('input');
-    const cosign = flags.optional('cosign');
-    const now = flags.optional('now');
-    if ((input === undefined) !== (cosign === undefined)) {
-      throw new Error('--input and --cosign are given together or not at all');
-    }
-    if (now !== undefined && !/^\d+$/.test(now)) {
-      throw new Error('--now must be epoch milliseconds');
-    }
-    process.stdout.write(
-      serializeJson(
-        assessMaterializedOciEvidence({
-          evidenceDirectory: flags.require('evidence-directory'),
-          manifest: readJsonFile(flags.require('manifest'), 'OCI manifest'),
-          subjectDigest: flags.require('subject-digest'),
-          schemas,
-          input: input === undefined ? undefined : readJsonFile(input, 'producer input'),
-          expectedContractAuthority,
-          runCosign: cosign === undefined ? undefined : createCosignVerifier(cosign).runCosign,
-          now: now === undefined ? Date.now() : Number(now),
-        }),
-      ),
-    );
-    return;
-  }
-  if (operation === 'backfill-plan') {
-    const rest = configureEditionWorkspaceFromArgv(argv, [
-      WorkspaceRoot.Data,
-      WorkspaceRoot.Editions,
-      WorkspaceRoot.Kernel,
-    ]);
-    const flags = parseEvidenceCliFlags(rest, { repeated: ['distribution', 'producer-repository-root'] });
-    const schemas = await loadKernelDistributionSchemas();
-    const plan = await planOciEvidenceBackfill({
-      distributionIds: flags.requireMany('distribution'),
-      dataRoot: dataRoot(),
-      editionsRoot: editionsRoot(),
-      producerRepositoryRoots: flags.requireMany('producer-repository-root').map((root) => resolve(root)),
-      schemas,
-      expectedContractAuthority: readPinnedContractAuthority({ dataRoot: dataRoot(), schemas }),
-    });
-    process.stdout.write(serializeJson(plan));
-    // 2: something is still to be produced or attached.
-    if (plan.items.some((item) => item.status !== OciBackfillStatus.Present)) {
-      process.exitCode = 2;
-    }
-    return;
-  }
-  throw new Error(USAGE);
-}
-
-if (isEntryModule(import.meta.url)) {
-  main().catch((error) => {
-    console.error(`[oci-evidence] ${error.message}`);
-    process.exitCode = 1;
-  });
-}