@xemahq/xema 0.51.0 → 0.52.0

package/edition/assemble-producer-input.mjs

@@ -132,6 +132,13 @@ const SOURCE_REPO_PATTERN = /^(?:repos|submodules)\/[a-zA-Z0-9_.-]+$/;
 // The kernel's `CanonicalIdentifierSchema` shape (runId / subject id).
 const CANONICAL_IDENTIFIER_PATTERN =
   /^[a-zA-Z0-9](?:[a-zA-Z0-9._:/@+-]{0,254}[a-zA-Z0-9])?$/;
+/** `--subject-id` has the kernel's `CanonicalIdentifierSchema` shape. */
+export function assertCanonicalSubjectId(subjectId) {
+  if (!CANONICAL_IDENTIFIER_PATTERN.test(subjectId ?? '')) {
+    throw new Error(`--subject-id ${JSON.stringify(subjectId ?? null)} is not a canonical identifier`);
+  }
+}
+
 // cosign v2 attaches every attestation of a subject as one layer of the
 // single `sha256-<subject-digest>.att` manifest; each layer is a DSSE
 // envelope whose `predicateType` annotation names the attestation.
@@ -848,6 +855,54 @@ export async function resolveImageArtifactEvidence({
   if (!SHA256_HEX_PATTERN.test(sourceTreeHash ?? '')) {
     throw new Error('sourceTreeHash must be 64 lowercase sha256 hex characters');
   }
+  assertReferenceProvenance(referenceProvenance);
+  const { authority, repository } = splitImageRef(imageRepository);
+  const declarations = loadRegistryCredentialDeclarations(distributionsRoot);
+  const credential = resolveRegistryCredential({ authority, declarations, env });
+  const client = registryFor
+    ? registryFor({ authority, credential })
+    : new OrasRegistry({ credential, fetchImpl });
+  return publishedArtifactEvidence({
+    client,
+    repository,
+    imageRepository,
+    read: { tag: sourceTreeHash },
+    expectedDigest: manifestDigest,
+    coordinate: `${imageRepository}:${sourceTreeHash}`,
+    referenceProvenance,
+  });
+}
+
+/**
+ * The artifact section of a producer subject read BY DIGEST: the manifest at
+ * `<imageRepository>@<manifestDigest>` (its bytes must hash to that digest),
+ * its hash-proven platforms and its cosign SBOM + SLSA attestation digests. A
+ * third-party publisher's image carries no `:<sourceTreeHash>` tag
+ * (`evidence assemble-third-party-input`), so nothing is read by tag.
+ */
+export async function resolveImageArtifactEvidenceByDigest({
+  client,
+  imageRepository,
+  manifestDigest,
+  referenceProvenance,
+}) {
+  if (!SHA256_DIGEST_PATTERN.test(manifestDigest ?? '')) {
+    throw new Error('the image manifest digest must be an exact sha256:<64-hex> digest');
+  }
+  assertReferenceProvenance(referenceProvenance);
+  const { repository } = splitImageRef(imageRepository);
+  return publishedArtifactEvidence({
+    client,
+    repository,
+    imageRepository,
+    read: { digest: manifestDigest },
+    expectedDigest: manifestDigest,
+    coordinate: `${imageRepository}@${manifestDigest}`,
+    referenceProvenance,
+  });
+}
+
+function assertReferenceProvenance(referenceProvenance) {
   if (
     typeof referenceProvenance !== 'object' ||
     referenceProvenance === null ||
@@ -858,19 +913,29 @@ export async function resolveImageArtifactEvidence({
         'it is what binds the selected provenance attestation to the primary build',
     );
   }
-  const { authority, repository } = splitImageRef(imageRepository);
-  const declarations = loadRegistryCredentialDeclarations(distributionsRoot);
-  const credential = resolveRegistryCredential({ authority, declarations, env });
-  const client = registryFor
-    ? registryFor({ authority, credential })
-    : new OrasRegistry({ credential, fetchImpl });
-  const coordinate = `${imageRepository}:${sourceTreeHash}`;
-  const top = await client.getManifestByTag(repository, sourceTreeHash);
-  if (top.digest !== manifestDigest) {
+}
+
+/** The artifact evidence of the manifest `read` names (exactly one of `{tag}` or `{digest}`), which must be `expectedDigest`. */
+async function publishedArtifactEvidence({
+  client,
+  repository,
+  imageRepository,
+  read,
+  expectedDigest,
+  coordinate,
+  referenceProvenance,
+}) {
+  const top =
+    read.tag === undefined
+      ? await client.getManifestByDigest(repository, read.digest)
+      : await client.getManifestByTag(repository, read.tag);
+  if (top.digest !== expectedDigest) {
     throw new Error(
-      `${coordinate} serves ${top.digest}, not the caller-declared ${manifestDigest} — ` +
-        'the image was not published from this source identity (wrong build commit, ' +
-        'or the cross-repo record at the build commit differs from the one this source carries)',
+      read.tag === undefined
+        ? `${coordinate} was served as ${top.digest}: the registry returned a manifest that is not the digest it was read by`
+        : `${coordinate} serves ${top.digest}, not the caller-declared ${expectedDigest} — ` +
+            'the image was not published from this source identity (wrong build commit, ' +
+            'or the cross-repo record at the build commit differs from the one this source carries)',
     );
   }
   // Proves EVERY platform by its own hash-verified image config and refuses
@@ -879,7 +944,7 @@ export async function resolveImageArtifactEvidence({
   const published = await resolvePublishedPlatforms({
     client,
     repository,
-    tag: sourceTreeHash,
+    ...read,
     coordinate,
   });
   if (published.indexDigest !== top.digest) {
@@ -944,6 +1009,69 @@ export async function resolveImageArtifactEvidence({
  */
 export const DEFAULT_PRODUCER_TTL_SECONDS = 3 * 24 * 60 * 60;
 
+/** Where the ceiling on a producer lifetime is held: the closed set of producer kinds. */
+export const ProducerTtlCeilingSource = Object.freeze({
+  /** First party: the data root's trust policy `maxProducerTtlSeconds`, read here. */
+  TrustPolicy: 'trust-policy',
+  /**
+   * A third-party publisher on public inputs: the vendor policy's `maxProducerTtlSeconds`, enforced by
+   * the third-party pin writer (`index runtime-image-source --trusted-write --third-party`) and `verify-evidence`.
+   */
+  VendorAdmission: 'vendor-admission',
+});
+
+/** The latest instant an RFC 3339 `expiresAt` (four-digit year) can name. */
+const LATEST_EXPIRES_AT = Date.UTC(9999, 11, 31, 23, 59, 59);
+
+/** `--ttl-seconds` as given, or undefined when it is not. */
+export const producerTtlSecondsFlag = (value) => (value === undefined ? undefined : Number(value));
+
+/**
+ * The producer lifetime of an input issued at `now`. The default is DEFAULT_PRODUCER_TTL_SECONDS, bowed to the
+ * ceiling when it is read here (`ceiling.source` TrustPolicy, `ceiling.maxTtlSeconds`); an explicit value above that
+ * ceiling is refused. With VendorAdmission the ceiling is the vendor policy's, enforced by the third-party pin writer
+ * (`index runtime-image-source --trusted-write --third-party`) and `verify-evidence`; this CLI holds no second one. Either way a value that is not a positive integer, or whose `expiresAt` is past the last
+ * instant RFC 3339 can name, is refused by name.
+ */
+export function resolveProducerTtlSeconds({ ttlSeconds, now, ceiling }) {
+  let maxTtlSeconds;
+  if (ceiling?.source === ProducerTtlCeilingSource.TrustPolicy) {
+    ({ maxTtlSeconds } = ceiling);
+    if (!Number.isSafeInteger(maxTtlSeconds) || maxTtlSeconds < 1) {
+      throw new Error(`the trust policy's maxProducerTtlSeconds ${String(maxTtlSeconds)} is not a positive integer`);
+    }
+  } else if (ceiling?.source === ProducerTtlCeilingSource.VendorAdmission) {
+    maxTtlSeconds = null;
+  } else {
+    throw new Error(`a producer TTL ceiling source is one of ${Object.values(ProducerTtlCeilingSource).join(', ')}`);
+  }
+  // The DEFAULT bows to the policy ceiling; an EXPLICIT `--ttl-seconds` above
+  // it still fails below. Tightening `maxProducerTtlSeconds` is a legitimate
+  // operator decision, and it must not break every producer until someone
+  // edits a constant in this file — but a caller who NAMES a lifetime the
+  // verifier will reject has made a mistake, and gets told so.
+  const effective =
+    ttlSeconds ?? (maxTtlSeconds === null ? DEFAULT_PRODUCER_TTL_SECONDS : Math.min(DEFAULT_PRODUCER_TTL_SECONDS, maxTtlSeconds));
+  if (maxTtlSeconds !== null && (!Number.isSafeInteger(effective) || effective < 1 || effective > maxTtlSeconds)) {
+    throw new Error(
+      `--ttl-seconds must be an integer between 1 and the trust policy's maxProducerTtlSeconds (${maxTtlSeconds})`,
+    );
+  }
+  if (!Number.isSafeInteger(effective) || effective < 1) {
+    throw new Error(
+      `--ttl-seconds must be a positive integer number of seconds (got ${String(ttlSeconds)}); the vendor policy's ` +
+        'maxProducerTtlSeconds is its ceiling, enforced by the pin writer and verify-evidence',
+    );
+  }
+  if (now + effective * 1000 > LATEST_EXPIRES_AT) {
+    throw new Error(
+      `--ttl-seconds ${effective} puts expiresAt past ${new Date(LATEST_EXPIRES_AT).toISOString()}, the last instant an ` +
+        'RFC 3339 time can name',
+    );
+  }
+  return effective;
+}
+
 function readProducerTtlSeconds(distributionsRoot) {
   const declared = editionWorkspaceConfig().evidenceTrustPolicy.policy;
   if (declared === null) {
@@ -1011,9 +1139,7 @@ export async function assembleProducerInput({
       `--subject-kind "${String(subjectKind)}" must be one of ${subjectKinds.join(', ')}`,
     );
   }
-  if (!CANONICAL_IDENTIFIER_PATTERN.test(subjectId ?? '')) {
-    throw new Error('--subject-id is not a canonical identifier');
-  }
+  assertCanonicalSubjectId(subjectId);
   if (!SOURCE_REPO_PATTERN.test(sourceRepo ?? '')) {
     throw new Error(
       `--source-repo "${String(sourceRepo)}" must be an aggregator-plane repository (repos/<name> or submodules/<name>)`,
@@ -1090,24 +1216,42 @@ export async function assembleProducerInput({
     fetchImpl,
     registryFor,
   });
-  const maxTtlSeconds = readProducerTtlSeconds(distributionsRoot);
-  // The DEFAULT bows to the policy ceiling; an EXPLICIT `--ttl-seconds` above
-  // it still fails below. Tightening `maxProducerTtlSeconds` is a legitimate
-  // operator decision, and it must not break every producer until someone
-  // edits a constant in this file — but a caller who NAMES a lifetime the
-  // verifier will reject has made a mistake, and gets told so.
-  const effectiveTtlSeconds =
-    ttlSeconds ?? Math.min(DEFAULT_PRODUCER_TTL_SECONDS, maxTtlSeconds);
-  if (
-    !Number.isSafeInteger(effectiveTtlSeconds) ||
-    effectiveTtlSeconds < 1 ||
-    effectiveTtlSeconds > maxTtlSeconds
-  ) {
-    throw new Error(
-      `--ttl-seconds must be an integer between 1 and the trust policy's maxProducerTtlSeconds (${maxTtlSeconds})`,
-    );
-  }
-  const input = {
+  const effectiveTtlSeconds = resolveProducerTtlSeconds({
+    ttlSeconds,
+    now,
+    ceiling: { source: ProducerTtlCeilingSource.TrustPolicy, maxTtlSeconds: readProducerTtlSeconds(distributionsRoot) },
+  });
+  const input = producerInputDocument({
+    contractAuthority,
+    context,
+    builder,
+    now,
+    ttlSeconds: effectiveTtlSeconds,
+    subject: {
+      kind: subjectKind,
+      id: subjectId,
+      repositoryUrl: source.repositoryUrl,
+      repo: sourceRepo,
+      path: sourcePath,
+      sourceCommit,
+      sourceManifestHash: source.sourceManifestHash,
+      sourceTreeHash: source.sourceTreeHash,
+      imageRepository,
+      ...artifact,
+    },
+  });
+  assertAssembledProducerInput({ input, schemas, contractAuthority, context });
+  return input;
+}
+
+/**
+ * The producer input of ONE subject, in the exact shape
+ * `produce-image-source-evidence.mjs` accepts. `context` is
+ * {@link assertWorkflowContext}'s and `builder` {@link deriveBuilder}'s; the
+ * subject carries every per-subject field (source identity and artifact).
+ */
+export function producerInputDocument({ contractAuthority, context, builder, now, ttlSeconds, subject }) {
+  return {
     schemaVersion: 1,
     contractAuthority: { ...contractAuthority },
     sourceHashAlgorithm: imageInputSourceHashAlgorithm(),
@@ -1131,31 +1275,36 @@ export async function assembleProducerInput({
     runId: context.runId,
     runAttempt: context.runAttempt,
     issuedAt: rfc3339(now),
-    expiresAt: rfc3339(now + effectiveTtlSeconds * 1000),
-    expectedSubjects: [`${subjectKind}:${subjectId}`],
+    expiresAt: rfc3339(now + ttlSeconds * 1000),
+    expectedSubjects: [`${subject.kind}:${subject.id}`],
     subjects: [
       {
-        kind: subjectKind,
-        id: subjectId,
-        repositoryUrl: source.repositoryUrl,
-        repo: sourceRepo,
-        path: sourcePath,
-        sourceCommit,
-        sourceManifestHash: source.sourceManifestHash,
-        sourceTreeHash: source.sourceTreeHash,
-        imageRepository,
-        manifestDigest: artifact.manifestDigest,
-        manifestMediaType: artifact.manifestMediaType,
-        platforms: artifact.platforms,
-        sbomDigest: artifact.sbomDigest,
-        provenanceDigest: artifact.provenanceDigest,
+        kind: subject.kind,
+        id: subject.id,
+        repositoryUrl: subject.repositoryUrl,
+        repo: subject.repo,
+        path: subject.path,
+        sourceCommit: subject.sourceCommit,
+        sourceManifestHash: subject.sourceManifestHash,
+        sourceTreeHash: subject.sourceTreeHash,
+        imageRepository: subject.imageRepository,
+        manifestDigest: subject.manifestDigest,
+        manifestMediaType: subject.manifestMediaType,
+        platforms: subject.platforms,
+        sbomDigest: subject.sbomDigest,
+        provenanceDigest: subject.provenanceDigest,
       },
     ],
   };
-  // Prove the output satisfies the producer BEFORE anything reads it: the
-  // exact field contract, then the kernel statement schema the producer builds
-  // (the same parse produce-image-source-evidence.mjs runs before signing),
-  // then the GitHub context the producer action compares against.
+}
+
+/**
+ * Prove an assembled input satisfies the producer BEFORE anything reads it:
+ * the exact field contract, then the kernel statement schema the producer
+ * builds (the same parse produce-image-source-evidence.mjs runs before
+ * signing), then the GitHub context the producer compares against.
+ */
+export function assertAssembledProducerInput({ input, schemas, contractAuthority, context }) {
   assertProducerInput(input, contractAuthority);
   buildImageSourceStatements(input, schemas, contractAuthority);
   assertGitHubProducerContext(input, {
@@ -1164,23 +1313,13 @@ export async function assembleProducerInput({
     sha: context.sha,
     workflowRef: context.workflowRef,
   });
-  return input;
 }
 
-function requireValue(flags, name) {
-  const value = flags.get(name);
-  if (value === undefined) {
-    throw new Error(`--${name} is required`);
-  }
-  return value;
-}
-
-async function main() {
-  const args = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
-    WorkspaceRoot.Data,
-    WorkspaceRoot.Sources,
-    WorkspaceRoot.Kernel,
-  ]);
+/**
+ * The `--name value` pairs of an assembler's argv: each flag once, each with a
+ * value, none outside `known`.
+ */
+export function readAssemblerFlags(args, known) {
   const flags = new Map();
   for (let index = 0; index < args.length; index += 2) {
     const flag = args[index];
@@ -1197,6 +1336,39 @@ async function main() {
     }
     flags.set(name, value);
   }
+  for (const name of flags.keys()) {
+    if (!known.has(name)) {
+      throw new Error(`unknown option "--${name}"`);
+    }
+  }
+  return flags;
+}
+
+/**
+ * Write an assembled input to `output`. The output directory is caller scratch
+ * space — created deterministically (the producer action's input-manifest
+ * must be repository-relative, so the caller cannot sidestep this by pointing
+ * at RUNNER_TEMP). `wx` refuses to overwrite an existing manifest.
+ */
+export function writeProducerInputFile(output, input) {
+  mkdirSync(dirname(output), { recursive: true });
+  writeFileSync(output, serializeJson(input), { flag: 'wx', mode: 0o600 });
+}
+
+function requireValue(flags, name) {
+  const value = flags.get(name);
+  if (value === undefined) {
+    throw new Error(`--${name} is required`);
+  }
+  return value;
+}
+
+async function main() {
+  const args = configureEditionWorkspaceFromArgv(process.argv.slice(2), [
+    WorkspaceRoot.Data,
+    WorkspaceRoot.Sources,
+    WorkspaceRoot.Kernel,
+  ]);
   const known = new Set([
     'output',
     'image-repository',
@@ -1211,11 +1383,7 @@ async function main() {
     'provenance',
     'ttl-seconds',
   ]);
-  for (const name of flags.keys()) {
-    if (!known.has(name)) {
-      throw new Error(`unknown option "--${name}"`);
-    }
-  }
+  const flags = readAssemblerFlags(args, known);
   const output = resolve(requireValue(flags, 'output'));
   const input = await assembleProducerInput({
     imageRepository: requireValue(flags, 'image-repository'),
@@ -1228,16 +1396,9 @@ async function main() {
     provenancePath: resolve(requireValue(flags, 'provenance')),
     sourceManifestHash: flags.get('source-manifest-hash'),
     sourceTreeHash: flags.get('source-tree-hash'),
-    ttlSeconds: flags.has('ttl-seconds')
-      ? Number(flags.get('ttl-seconds'))
-      : undefined,
+    ttlSeconds: producerTtlSecondsFlag(flags.get('ttl-seconds')),
   });
-  // The output directory is caller scratch space — create it deterministically
-  // (the producer action's input-manifest must be repository-relative, so the
-  // caller cannot sidestep this by pointing at RUNNER_TEMP). `wx` below still
-  // refuses to overwrite an existing manifest.
-  mkdirSync(dirname(output), { recursive: true });
-  writeFileSync(output, serializeJson(input), { flag: 'wx', mode: 0o600 });
+  writeProducerInputFile(output, input);
   console.log(
     `[assemble-producer-input] wrote ${output} for subject ` +
       `${input.subjects[0].kind}:${input.subjects[0].id} ` +