@xemahq/xema 0.26.0 → 0.27.0

package/edition/oci-image-source-evidence.mjs

@@ -0,0 +1,239 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
+import { canonicalJson, sha256Digest } from './image-evidence.mjs';
+import { compareStrings } from './lib.mjs';
+import { OrasRegistry } from './oras.mjs';
+import { BUNDLE_MEDIA_TYPE } from './produce-image-source-evidence.mjs';
+import {
+  PRODUCER_EVIDENCE_INDEX_FILE,
+  PRODUCER_EVIDENCE_INDEX_MEDIA_TYPE,
+  PRODUCER_STATEMENT_MEDIA_TYPE,
+  producerEvidenceLayerFiles,
+  readProducerEvidenceDirectory,
+} from './producer-evidence-bundle.mjs';
+import {
+  loadRegistryCredentialDeclarations,
+  resolveRegistryCredential,
+  splitImageRef,
+} from './registry-credentials.mjs';
+
+export const IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE =
+  'application/vnd.xema.image-source-evidence.v2';
+export const OCI_IMAGE_MANIFEST_MEDIA_TYPE =
+  'application/vnd.oci.image.manifest.v1+json';
+const OCI_TITLE_ANNOTATION = 'org.opencontainers.image.title';
+const OCI_CREATED_ANNOTATION = 'org.opencontainers.image.created';
+
+/** One registry reader per authority, each with the credential the data root declares for it. */
+export function createRegistryClientResolver({ dataRoot, factory }) {
+  const declarations = loadRegistryCredentialDeclarations(dataRoot);
+  const clients = new Map();
+  return (authority) => {
+    if (clients.has(authority)) {return clients.get(authority);}
+    const client = factory
+      ? factory(authority)
+      : new OrasRegistry({
+          credential: resolveRegistryCredential({ authority, declarations }),
+        });
+    clients.set(authority, client);
+    return client;
+  };
+}
+
+function exactRelativePath(value, label) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.startsWith('/') ||
+    value.split('/').some((part) => !part || part === '.' || part === '..')
+  ) {
+    throw new Error(`${label} is not a contained relative path`);
+  }
+  return value;
+}
+
+function expectedMediaType(path) {
+  if (path === PRODUCER_EVIDENCE_INDEX_FILE) {
+    return PRODUCER_EVIDENCE_INDEX_MEDIA_TYPE;
+  }
+  if (path.startsWith('statements/')) {return PRODUCER_STATEMENT_MEDIA_TYPE;}
+  if (path.startsWith('bundles/')) {return BUNDLE_MEDIA_TYPE;}
+  throw new Error(`OCI evidence layer has unsupported title "${path}"`);
+}
+
+export function validateImageSourceEvidenceManifest({
+  manifest,
+  subjectDigest,
+}) {
+  if (
+    manifest?.schemaVersion !== 2 ||
+    manifest.mediaType !== OCI_IMAGE_MANIFEST_MEDIA_TYPE ||
+    manifest.artifactType !== IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE ||
+    manifest.subject?.digest !== subjectDigest ||
+    !Array.isArray(manifest.layers) ||
+    manifest.layers.length < 3
+  ) {
+    throw new Error(
+      'image-source evidence artifact is not an OCI 1.1 manifest for the exact subject',
+    );
+  }
+  const created = manifest.annotations?.[OCI_CREATED_ANNOTATION];
+  if (typeof created !== 'string' || !Number.isFinite(Date.parse(created))) {
+    throw new Error(`image-source evidence artifact has no valid ${OCI_CREATED_ANNOTATION}`);
+  }
+  const seen = new Set();
+  let indexCount = 0;
+  for (const layer of manifest.layers) {
+    const title = exactRelativePath(
+      layer?.annotations?.[OCI_TITLE_ANNOTATION],
+      'OCI evidence layer title',
+    );
+    if (seen.has(title)) {
+      throw new Error(`OCI evidence manifest duplicates layer title "${title}"`);
+    }
+    seen.add(title);
+    if (
+      !SHA256_DIGEST_PATTERN.test(layer.digest ?? '') ||
+      !Number.isSafeInteger(layer.size) ||
+      layer.size < 0 ||
+      layer.mediaType !== expectedMediaType(title)
+    ) {
+      throw new Error(`OCI evidence layer "${title}" has an invalid descriptor`);
+    }
+    if (title === PRODUCER_EVIDENCE_INDEX_FILE) {indexCount += 1;}
+  }
+  if (indexCount !== 1) {
+    throw new Error('OCI evidence manifest requires exactly one producer evidence index');
+  }
+  return { created, layers: manifest.layers };
+}
+
+export function validateMaterializedImageSourceEvidence({
+  directory,
+  manifest,
+  subjectDigest,
+  schemas,
+}) {
+  const { created, layers } = validateImageSourceEvidenceManifest({
+    manifest,
+    subjectDigest,
+  });
+  const evidence = readProducerEvidenceDirectory({ directory, schemas });
+  const declared = producerEvidenceLayerFiles(evidence.records)
+    .map(({ path, mediaType }) => `${path}\0${mediaType}`)
+    .sort(compareStrings);
+  const materialized = layers
+    .map(
+      (layer) => `${layer.annotations[OCI_TITLE_ANNOTATION]}\0${layer.mediaType}`,
+    )
+    .sort(compareStrings);
+  if (canonicalJson(declared) !== canonicalJson(materialized)) {
+    throw new Error(
+      'OCI evidence layers are not the exact files declared by producer-evidence.json',
+    );
+  }
+  for (const record of evidence.records) {
+    const artifact = record.statement.predicate.artifact;
+    if (
+      artifact.manifestDigest !== subjectDigest ||
+      record.statement.subject[0]?.name !== artifact.imageRepository ||
+      `sha256:${record.statement.subject[0]?.digest?.sha256}` !== subjectDigest
+    ) {
+      throw new Error(`${record.key} statement is not bound to OCI subject ${subjectDigest}`);
+    }
+    if (record.statement.predicate.producerRun.issuedAt !== created) {
+      throw new Error(
+        `${record.key} issuance does not match the OCI artifact creation annotation`,
+      );
+    }
+  }
+  return { ...evidence, created };
+}
+
+/**
+ * Fetch, content-address validate and decode one OCI evidence artifact.
+ * `getBlob` verifies every digest again, independently of the manifest.
+ */
+export async function readImageSourceEvidenceArtifact({
+  client,
+  repository,
+  subjectDigest,
+  artifactDigest,
+  schemas,
+}) {
+  const fetched = await client.getManifestByDigest(repository, artifactDigest);
+  const { created, layers } = validateImageSourceEvidenceManifest({
+    manifest: fetched.document,
+    subjectDigest,
+  });
+  const directory = mkdtempSync(join(tmpdir(), 'xema-oci-evidence-'));
+  try {
+    for (const layer of layers) {
+      const title = layer.annotations[OCI_TITLE_ANNOTATION];
+      const bytes = await client.getBlob(repository, layer.digest);
+      if (bytes.length !== layer.size || sha256Digest(bytes) !== layer.digest) {
+        throw new Error(`OCI evidence layer "${title}" does not match its descriptor`);
+      }
+      const path = join(directory, title);
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, bytes, { flag: 'wx', mode: 0o600 });
+    }
+    const evidence = validateMaterializedImageSourceEvidence({
+      directory,
+      manifest: fetched.document,
+      subjectDigest,
+      schemas,
+    });
+    return { ...evidence, artifactDigest, created };
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+/** Resolve the newest valid evidence referrer deterministically. */
+export async function resolveImageSourceEvidenceReferrer({
+  client,
+  imageRepository,
+  subjectDigest,
+  schemas,
+}) {
+  const { authority, repository } = splitImageRef(imageRepository);
+  if (client.authority !== authority) {
+    throw new Error(
+      `registry client for ${client.authority} cannot read ${imageRepository}`,
+    );
+  }
+  const descriptors = await client.listReferrers(
+    repository,
+    subjectDigest,
+    IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE,
+  );
+  const matching = descriptors.filter(
+    (descriptor) =>
+      descriptor?.artifactType === IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE,
+  );
+  if (matching.length === 0) {return null;}
+  const candidates = [];
+  for (const descriptor of matching) {
+    if (!SHA256_DIGEST_PATTERN.test(descriptor.digest ?? '')) {
+      throw new Error('registry returned a non-canonical evidence referrer digest');
+    }
+    candidates.push(
+      await readImageSourceEvidenceArtifact({
+        client,
+        repository,
+        subjectDigest,
+        artifactDigest: descriptor.digest,
+        schemas,
+      }),
+    );
+  }
+  candidates.sort((left, right) => {
+    const byCreated = compareStrings(right.created, left.created);
+    return byCreated || compareStrings(left.artifactDigest, right.artifactDigest);
+  });
+  return candidates[0];
+}