@xemahq/xema 0.51.0 → 0.52.0

package/edition/assemble-third-party-input.mjs

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+// assemble-third-party-input — the producer input of ONE image of a THIRD-PARTY biome, assembled in the publisher's own
+// GitHub-hosted workflow (XEMA-1611 design section 5).
+//
+//   xema edition evidence assemble-third-party-input \
+//     --bundle <oci repository>@sha256:<64-hex> \
+//     --contract-authority <file> \
+//     --image <image repository>@sha256:<64-hex> \
+//     --subject-id <component image name> \
+//     --provenance <absolute exported BuildKit SLSA v1 predicate> \
+//     --registry-credentials <file> \
+//     --output <path> \
+//     [--ttl-seconds <n>]
+//
+// It runs on PUBLIC inputs only: this CLI and the `@xemahq/contracts` it ships (both from public npm), the publisher's
+// own checkout at GITHUB_WORKSPACE, its own registry credential declaration and the GITHUB_* context of the run. It
+// takes no data root, no kernel checkout and nothing of the vendor's. The checks that need the vendor's trust policy
+// (the producer TTL ceiling, the signer rows, image ownership) run at the vendor's admission, by the trusted writer
+// (`index runtime-image-source --trusted-write --third-party`), never here.
+//
+// Emits the EXACT producer input `produce-image-source-evidence.mjs` accepts, through the first-party assembler's own
+// document builder and gates (`assemble-producer-input.mjs`). Field derivation:
+//   * contractAuthority   — the `--contract-authority` file (the kernel contract authority the vendor's evidence trust
+//                           pin names), proved to be the kernel this CLI ships before anything else is read.
+//   * subject kind and id — the bundle's `xema-biome.json` (`--bundle`, read BY DIGEST): the one service or worker
+//                           component with an `oci-image` artifact whose image name is `--subject-id` (a service by
+//                           `protocol.serviceName`, a worker by its key), kind `runtime-component` for a
+//                           `scheduler: runtime` component and `service` otherwise, as the index builder names it.
+//   * repo, repositoryUrl, sourceCommit, producerWorkflowSha, signer, builderId, runId, runAttempt
+//                         — GITHUB_REPOSITORY, GITHUB_SHA, GITHUB_WORKFLOW_REF, GITHUB_RUN_ID, GITHUB_RUN_ATTEMPT.
+//   * sourceManifestHash  — the kernel hash of the bundle's `xema-biome.json`.
+//   * path                — `<repo>/<biome dir>`: the directory of the ONE `xema-biome.json` of the checkout at
+//                           GITHUB_SHA whose hash is the bundle's (none, or more than one, is refused by name).
+//   * sourceTreeHash      — `hashImageBuildInputs` over the publisher's checkout at GITHUB_SHA, the same algorithm
+//                           first-party images are hashed with, with no cross-repo inputs. It is publisher-attested:
+//                           the vendor never recomputes it.
+//   * builder digests     — the exported BuildKit SLSA v1 predicate (`--provenance`), whose VCS revision must be
+//                           GITHUB_SHA.
+//   * manifest media type, platforms, sbomDigest, provenanceDigest
+//                         — the registry, read BY DIGEST at `--image` (no tag is read), with the publisher's credential.
+//   * issuedAt/expiresAt  — now, plus `--ttl-seconds` or DEFAULT_PRODUCER_TTL_SECONDS (72h). The ceiling is the vendor
+//                           trust policy's maxProducerTtlSeconds, enforced by the vendor's third-party pin writer
+//                           (`index runtime-image-source --trusted-write --third-party`) and `verify-evidence`; this CLI holds
+//                           no second one. A value that is not a positive integer, or whose expiresAt RFC 3339 cannot
+//                           name, is refused by name.
+//
+// It refuses to run unless RUNNER_ENVIRONMENT is `github-hosted` and GITHUB_REF is `refs/heads/main`. Those variables are
+// self-asserted by the run, so this is only a fail-fast mirror: the authority is the vendor's admission, which checks
+// the Fulcio certificate's Runner Environment and Source Repository Ref extensions (a third-party source is admitted
+// only from the release channel of a GitHub-hosted workflow).
+
+import { isAbsolute, resolve } from 'node:path';
+
+import {
+  ProducerTtlCeilingSource,
+  assertAssembledProducerInput,
+  assertCanonicalSubjectId,
+  assertWorkflowContext,
+  deriveBuilder,
+  producerInputDocument,
+  producerTtlSecondsFlag,
+  readAssemblerFlags,
+  resolveImageArtifactEvidenceByDigest,
+  resolveProducerTtlSeconds,
+  writeProducerInputFile,
+} from './assemble-producer-input.mjs';
+import { configureEditionWorkspaceFromArgv, isEntryModule, kernelPackageDir, stateKernelPackageDir } from './edition-workspace.mjs';
+import { readPublicContractAuthority } from './evidence-input-mode.mjs';
+import { shippedKernelPackageDir } from './kernel-package.mjs';
+import {
+  assertGitCommitExists,
+  biomeImageComponents,
+  claimBiomeImageName,
+  hashImageBuildInputs,
+  isRuntimeImageComponent,
+  imageInputSourceHashAlgorithm,
+  readGitJsonAtCommit,
+} from './lib.mjs';
+import { OrasRegistry } from './oras.mjs';
+import { sandboxedGit } from './produce-image-source-evidence.mjs';
+import { loadRegistryCredentialDeclarationsFile, resolveRegistryCredential, splitImageRef } from './registry-credentials.mjs';
+import { subjectServicePath } from './resolve-images.mjs';
+import { fetchBundleManifest } from './third-party-bundle-registry.mjs';
+import { OCI_REPOSITORY_AT_DIGEST } from './third-party-source-flags.mjs';
+import { PUBLISHER_ATTESTED_LABEL } from './third-party-subjects.mjs';
+
+/** The runner a third-party producer input is assembled on. */
+export const THIRD_PARTY_RUNNER_ENVIRONMENT = 'github-hosted';
+/** The only ref a third-party producer input is assembled from (the release channel). */
+export const THIRD_PARTY_PRODUCER_REF = 'refs/heads/main';
+
+const BIOME_MANIFEST_FILE = 'xema-biome.json';
+const OCI_IMAGE_ARTIFACT = 'oci-image';
+
+/** The flags of the verb; every one but `--ttl-seconds` is required. */
+export const THIRD_PARTY_INPUT_FLAGS = Object.freeze({
+  bundle: 'bundle',
+  contractAuthority: 'contract-authority',
+  image: 'image',
+  subjectId: 'subject-id',
+  provenance: 'provenance',
+  registryCredentials: 'registry-credentials',
+  output: 'output',
+  ttlSeconds: 'ttl-seconds',
+});
+
+export const THIRD_PARTY_INPUT_USAGE =
+  'usage: xema edition evidence assemble-third-party-input --bundle <oci repository>@sha256:<64-hex> ' +
+  '--contract-authority <file> --image <image repository>@sha256:<64-hex> --subject-id <component image name> ' +
+  '--provenance <absolute exported SLSA v1 predicate> --registry-credentials <file> --output <path> [--ttl-seconds <n>]';
+
+/**
+ * Refuse a run that is not a GitHub-hosted run of refs/heads/main, before anything else is read. RUNNER_ENVIRONMENT
+ * and GITHUB_REF are self-asserted, so this is a fail-fast mirror only; the authority is the vendor admission's check
+ * of the Fulcio certificate's Runner Environment and Source Repository Ref extensions.
+ */
+export function assertThirdPartyRunner(env) {
+  if (env.RUNNER_ENVIRONMENT !== THIRD_PARTY_RUNNER_ENVIRONMENT) {
+    throw new Error(
+      `a third-party producer input is assembled only on a ${THIRD_PARTY_RUNNER_ENVIRONMENT} runner ` +
+        `(RUNNER_ENVIRONMENT is ${JSON.stringify(env.RUNNER_ENVIRONMENT ?? null)}): the vendor admits only certificates whose ` +
+        'Fulcio Runner Environment extension is github-hosted',
+    );
+  }
+  if (env.GITHUB_REF !== THIRD_PARTY_PRODUCER_REF) {
+    throw new Error(
+      `a third-party producer input is assembled only from ${THIRD_PARTY_PRODUCER_REF} ` +
+        `(GITHUB_REF is ${JSON.stringify(env.GITHUB_REF ?? null)}): the vendor admits only certificates whose Fulcio ` +
+        `Source Repository Ref extension is ${THIRD_PARTY_PRODUCER_REF}, the release channel`,
+    );
+  }
+}
+
+function ociReference(flag, value) {
+  if (!OCI_REPOSITORY_AT_DIGEST.test(value ?? '')) {
+    throw new Error(`--${flag} must be <repository>@sha256:<64-hex>; got ${JSON.stringify(value)}`);
+  }
+  const at = value.indexOf('@');
+  return { repository: value.slice(0, at), digest: value.slice(at + 1) };
+}
+
+/**
+ * The bundle component `subjectId` names, and its runtime image subject kind, by the index builder's own rule
+ * (`biomeImageComponents`, `claimBiomeImageName`, `isRuntimeImageComponent` in lib.mjs): every image component is
+ * named, so a component with no image name, a web biome with an image and a duplicate image name are refused as the
+ * index builder refuses them; the subject is the one with its own `oci-image` artifact named `subjectId`.
+ */
+export function bundleImageSubject({ manifest, subjectId, enums, bundleRef }) {
+  const xema = manifest?.xema;
+  const components = Array.isArray(xema?.components) ? xema.components : [];
+  const rel = `bundle ${bundleRef} ${BIOME_MANIFEST_FILE}`;
+  const taken = new Set();
+  const images = biomeImageComponents(components)
+    .map((component) => ({ component, name: claimBiomeImageName(component, { rel, id: xema?.id, target: xema?.target, taken }) }))
+    .filter(({ component }) => component.artifact?.kind === OCI_IMAGE_ARTIFACT);
+  const match = images.find(({ name }) => name === subjectId);
+  if (match === undefined) {
+    throw new Error(
+      `bundle ${bundleRef} has no ${OCI_IMAGE_ARTIFACT} service or worker component named ${JSON.stringify(subjectId)} ` +
+        `(its images: ${images.map(({ name }) => name).join(', ') || 'none'}); --subject-id names exactly one`,
+    );
+  }
+  const kind = isRuntimeImageComponent(match.component)
+    ? enums.RuntimeImageSubjectKind.RuntimeComponent
+    : enums.RuntimeImageSubjectKind.Service;
+  return { kind, id: subjectId };
+}
+
+/**
+ * The biome directory of the publisher's checkout at `commit`: the directory of the ONE `xema-biome.json` whose kernel
+ * source manifest hash is `sourceManifestHash` (`''` for the repository root). None, or more than one, is refused.
+ */
+export async function biomeDirectoryAtCommit({ checkout, commit, sourceManifestHash, schemas, bundleRef }) {
+  const paths = sandboxedGit(checkout, ['ls-tree', '-r', '-z', '--name-only', commit])
+    .split('\0')
+    .filter((path) => path === BIOME_MANIFEST_FILE || path.endsWith(`/${BIOME_MANIFEST_FILE}`));
+  const matching = [];
+  for (const path of paths) {
+    const hash = await schemas.computeBiomeSourceManifestHash(readGitJsonAtCommit(checkout, path, commit));
+    if (hash === sourceManifestHash) {matching.push(path);}
+  }
+  if (matching.length !== 1) {
+    throw new Error(
+      `the checkout at ${commit} has ${matching.length} ${BIOME_MANIFEST_FILE} files whose source manifest hash is ` +
+        `${sourceManifestHash}, the hash of bundle ${bundleRef} ` +
+        `(${matching.length === 0 ? `its ${BIOME_MANIFEST_FILE} files: ${paths.join(', ') || 'none'}` : matching.join(', ')}); exactly one is required: ` +
+        'the bundle must be published from this commit',
+    );
+  }
+  const [path] = matching;
+  return path === BIOME_MANIFEST_FILE ? '' : path.slice(0, -`/${BIOME_MANIFEST_FILE}`.length);
+}
+
+/**
+ * Assemble the producer input of one third-party image and prove it satisfies the producer's exact contract.
+ *
+ * @param {object} request
+ * @param {string} request.bundle `<oci repository>@sha256:<hex>` of the published biome bundle
+ * @param {string} request.contractAuthorityPath the `--contract-authority` file
+ * @param {string} request.image `<image repository>@sha256:<hex>` of the published image
+ * @param {string} request.subjectId the bundle component's image name
+ * @param {string} request.provenancePath the exported BuildKit SLSA v1 predicate (absolute)
+ * @param {string} request.registryCredentialsPath the publisher's registry credential declaration file
+ * @param {number} [request.ttlSeconds]
+ * @param {string} [request.kernelDir] the kernel package (default: the configured Kernel root)
+ * @param {object} [request.env]
+ * @param {Function} [request.registryFor] `({authority, credential}) => client`, for tests
+ * @param {number} [request.now]
+ */
+export async function assembleThirdPartyInput({
+  bundle,
+  contractAuthorityPath,
+  image,
+  subjectId,
+  provenancePath,
+  registryCredentialsPath,
+  ttlSeconds,
+  kernelDir = kernelPackageDir(),
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  registryFor = null,
+  now = Date.now(),
+}) {
+  assertThirdPartyRunner(env);
+  const context = assertWorkflowContext(env);
+  ociReference(THIRD_PARTY_INPUT_FLAGS.bundle, bundle);
+  const imageRef = ociReference(THIRD_PARTY_INPUT_FLAGS.image, image);
+  assertCanonicalSubjectId(subjectId);
+  const effectiveTtlSeconds = resolveProducerTtlSeconds({ ttlSeconds, now, ceiling: { source: ProducerTtlCeilingSource.VendorAdmission } });
+  const checkout = env.GITHUB_WORKSPACE;
+  if (typeof checkout !== 'string' || !isAbsolute(checkout)) {
+    throw new Error(
+      `GITHUB_WORKSPACE (${JSON.stringify(checkout ?? null)}) is not an absolute path: the publisher's checkout at GITHUB_SHA is hashed there`,
+    );
+  }
+  try {
+    assertGitCommitExists(checkout, context.sha);
+  } catch (error) {
+    throw new Error(`the publisher's checkout at GITHUB_WORKSPACE ${checkout} does not hold GITHUB_SHA ${context.sha}: ${error.message}`);
+  }
+  const { contractAuthority, schemas } = await readPublicContractAuthority({ path: contractAuthorityPath, kernelDir });
+  const builder = deriveBuilder({ provenancePath, sourceCommit: context.sha });
+
+  const declarations = loadRegistryCredentialDeclarationsFile(registryCredentialsPath);
+  const clients = new Map();
+  const clientFor = (authority) => {
+    if (!clients.has(authority)) {
+      const credential = resolveRegistryCredential({ authority, declarations, env });
+      // No vendor data root: the publisher's oras is held to its version, not to a vendor pin. Every byte read is
+      // content-addressed here and re-verified by the vendor's admission.
+      clients.set(authority, registryFor ? registryFor({ authority, credential }) : new OrasRegistry({ credential, trust: () => null, fetchImpl }));
+    }
+    return clients.get(authority);
+  };
+
+  const { manifest } = await fetchBundleManifest({ clientFor, ociRef: bundle });
+  const sourceManifestHash = await schemas.computeBiomeSourceManifestHash(manifest);
+  const subject = bundleImageSubject({ manifest, subjectId, enums: schemas, bundleRef: bundle });
+  const biomeDirectory = await biomeDirectoryAtCommit({ checkout, commit: context.sha, sourceManifestHash, schemas, bundleRef: bundle });
+  const servicePath = subjectServicePath(
+    { kind: subject.kind, id: subject.id, repo: context.repository, path: biomeDirectory === '' ? '.' : biomeDirectory },
+    context.sha,
+    () => ({ dir: checkout, base: checkout }),
+  );
+  const sourceTreeHash = hashImageBuildInputs(
+    { repoDir: checkout, service: subject.id, servicePath, commit: context.sha, crossRepoInputs: [], buildStepDirectories: [] },
+    imageInputSourceHashAlgorithm(),
+  );
+  const artifact = await resolveImageArtifactEvidenceByDigest({
+    client: clientFor(splitImageRef(imageRef.repository).authority),
+    imageRepository: imageRef.repository,
+    manifestDigest: imageRef.digest,
+    referenceProvenance: builder.predicate,
+  });
+  const input = producerInputDocument({
+    contractAuthority,
+    context,
+    builder,
+    now,
+    ttlSeconds: effectiveTtlSeconds,
+    subject: {
+      kind: subject.kind,
+      id: subject.id,
+      repositoryUrl: `https://github.com/${context.repository}`,
+      repo: context.repository,
+      path: biomeDirectory === '' ? context.repository : `${context.repository}/${biomeDirectory}`,
+      sourceCommit: context.sha,
+      sourceManifestHash,
+      sourceTreeHash,
+      imageRepository: imageRef.repository,
+      ...artifact,
+    },
+  });
+  assertAssembledProducerInput({ input, schemas, contractAuthority, context });
+  return input;
+}
+
+function requireFlag(flags, name) {
+  const value = flags.get(name);
+  if (value === undefined) {
+    throw new Error(`--${name} is required\n${THIRD_PARTY_INPUT_USAGE}`);
+  }
+  return value;
+}
+
+async function main() {
+  // No workspace root: the verb runs on public inputs, with the kernel this CLI ships.
+  const args = configureEditionWorkspaceFromArgv(process.argv.slice(2), [], { refuseOthers: true });
+  stateKernelPackageDir(shippedKernelPackageDir());
+  const flags = readAssemblerFlags(args, new Set(Object.values(THIRD_PARTY_INPUT_FLAGS)));
+  const output = resolve(requireFlag(flags, THIRD_PARTY_INPUT_FLAGS.output));
+  const ttl = flags.get(THIRD_PARTY_INPUT_FLAGS.ttlSeconds);
+  const input = await assembleThirdPartyInput({
+    bundle: requireFlag(flags, THIRD_PARTY_INPUT_FLAGS.bundle),
+    contractAuthorityPath: resolve(requireFlag(flags, THIRD_PARTY_INPUT_FLAGS.contractAuthority)),
+    image: requireFlag(flags, THIRD_PARTY_INPUT_FLAGS.image),
+    subjectId: requireFlag(flags, THIRD_PARTY_INPUT_FLAGS.subjectId),
+    provenancePath: requireFlag(flags, THIRD_PARTY_INPUT_FLAGS.provenance),
+    registryCredentialsPath: resolve(requireFlag(flags, THIRD_PARTY_INPUT_FLAGS.registryCredentials)),
+    ttlSeconds: producerTtlSecondsFlag(ttl),
+  });
+  writeProducerInputFile(output, input);
+  const [subject] = input.subjects;
+  console.log(
+    `[assemble-third-party-input] wrote ${output} for subject ${subject.kind}:${subject.id} ` +
+      `(${subject.imageRepository}@${subject.manifestDigest}, ${subject.repo}@${subject.sourceCommit}, ` +
+      `sourceTreeHash (${PUBLISHER_ATTESTED_LABEL}) ${subject.sourceTreeHash})`,
+  );
+}
+
+if (isEntryModule(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`[assemble-third-party-input] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/edition/evidence-input-mode.mjs

@@ -0,0 +1,154 @@
+// evidence-input-mode — where a producer-side evidence verb takes its kernel contract authority and schemas from.
+//
+// Vendor mode (`--data-root <dir> --kernel <dir>`): the authority the data root's evidence-trust pin records, and the
+// schemas of a kernel checkout at that commit. Public-input mode (`--contract-authority <file>`): a third-party
+// publisher's run, on public inputs only. The authority is the file, and the schemas are the `@xemahq/contracts` this
+// CLI bundles, proved to be that authority. There is no data root, no kernel checkout and no vendor trust policy; what
+// needs the vendor's trust policy is checked at the vendor's admission.
+//
+// `readPublicContractAuthority` is the one resolution of a `--contract-authority` file, shared by
+// `evidence assemble-third-party-input`, `statement producer <stage|accept>` and `oci <attach-plan|validate>`.
+
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { readKernelEditionProtocol } from './edition-protocol.mjs';
+import {
+  WorkspaceRoot,
+  configureEditionWorkspaceFromArgv,
+  kernelPackageDir,
+  stateKernelPackageDir,
+} from './edition-workspace.mjs';
+import { KERNEL_PACKAGE_NAME, assertKernelPackageIsCatalogueAuthority, shippedKernelPackageDir } from './kernel-package.mjs';
+import { loadKernelDistributionSchemas } from './lib.mjs';
+
+/** The two closed ways a producer-side evidence verb is given its kernel contract authority. */
+export const EvidenceInputMode = Object.freeze({
+  /** `--data-root` and `--kernel`: the vendor's pinned authority and kernel checkout. */
+  Vendor: 'vendor',
+  /** `--contract-authority`: a publisher's run on public inputs, with the kernel this CLI bundles. */
+  PublicInput: 'public-input',
+});
+
+const CONTRACT_AUTHORITY_FLAG = '--contract-authority';
+const VENDOR_FLAGS = ['--data-root', '--kernel'];
+
+const flagOf = (arg) => {
+  const eq = typeof arg === 'string' ? arg.indexOf('=') : -1;
+  return eq > 0 ? arg.slice(0, eq) : arg;
+};
+
+const readVersion = (packageJsonPath) => {
+  const { version } = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+  if (typeof version !== 'string' || version.length === 0) {throw new Error(`${packageJsonPath} has no "version"`);}
+  return version;
+};
+
+/**
+ * The bundled kernel's own strict `KernelContractAuthoritySchema` (not re-exported by its distribution index), read
+ * from the package this CLI ships.
+ */
+async function loadKernelContractAuthoritySchema(kernelDir) {
+  const module = join(kernelDir, 'dist', 'distribution', 'lib', 'kernel-contract-authority.js');
+  let loaded;
+  try {
+    loaded = await import(pathToFileURL(module).href);
+  } catch (error) {
+    throw new Error(`${KERNEL_PACKAGE_NAME} at ${kernelDir} has no loadable kernel contract authority schema (${module}): ${error.message}`);
+  }
+  const schema = loaded.KernelContractAuthoritySchema ?? loaded.default?.KernelContractAuthoritySchema;
+  if (typeof schema?.safeParse !== 'function') {
+    throw new Error(`${KERNEL_PACKAGE_NAME} at ${kernelDir} exports no KernelContractAuthoritySchema from ${module}`);
+  }
+  return schema;
+}
+
+/**
+ * The contract authority of a `--contract-authority` file, proved to be the kernel this CLI bundles (`kernelDir`),
+ * and that kernel's distribution schemas. An authority whose contracts digest is not the bundled one is refused
+ * first, naming both digests: the publisher installs the xema CLI whose bundled `@xemahq/contracts` is that authority.
+ * The file is then strict-parsed by the kernel's `KernelContractAuthoritySchema` (an unknown or missing field is
+ * refused) and returned in the schema's form, so its key order is never what a later comparison sees.
+ *
+ * `sourceCommit` is held to the schema's shape only: it is provenance, which the bundled package cannot prove. The
+ * vendor holds it, comparing the statement's whole authority with its pinned one at the third-party pin writer
+ * (`assertImageStatementBindsPin`, third-party-source-evidence.mjs).
+ */
+export async function readPublicContractAuthority({ path, kernelDir = kernelPackageDir() }) {
+  let contractAuthority;
+  try {
+    contractAuthority = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`${CONTRACT_AUTHORITY_FLAG} ${path} is not a JSON kernel contract authority: ${error.message}`);
+  }
+  if (typeof contractAuthority !== 'object' || contractAuthority === null || Array.isArray(contractAuthority)) {
+    throw new Error(`${CONTRACT_AUTHORITY_FLAG} ${path} does not hold one kernel contract authority object`);
+  }
+  const bundledDigest = readKernelEditionProtocol(kernelDir).contentDigest;
+  if (contractAuthority.contentDigest !== bundledDigest) {
+    const cli = readVersion(new URL('../package.json', import.meta.url));
+    const contracts = readVersion(join(kernelDir, 'package.json'));
+    throw new Error(
+      `${CONTRACT_AUTHORITY_FLAG} ${path} is kernel contracts digest ${JSON.stringify(contractAuthority.contentDigest)}, ` +
+        `but this CLI (@xemahq/xema ${cli}) bundles ${KERNEL_PACKAGE_NAME} ${contracts}, digest ${bundledDigest}; ` +
+        `install the @xemahq/xema version whose bundled ${KERNEL_PACKAGE_NAME} has digest ${JSON.stringify(contractAuthority.contentDigest)}`,
+    );
+  }
+  const parsed = (await loadKernelContractAuthoritySchema(kernelDir)).safeParse(contractAuthority);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ');
+    throw new Error(`${CONTRACT_AUTHORITY_FLAG} ${path} is not a kernel contract authority: ${issues}`);
+  }
+  contractAuthority = parsed.data;
+  try {
+    const schemas = await assertKernelPackageIsCatalogueAuthority({
+      catalogue: { contractAuthority },
+      kernelPackageDir: kernelDir,
+      loadSchemas: loadKernelDistributionSchemas,
+    });
+    return { contractAuthority, schemas };
+  } catch (error) {
+    throw new Error(
+      `${CONTRACT_AUTHORITY_FLAG} ${path} is not the kernel this CLI ships (${kernelDir}): ${error.message}; ` +
+        `install the xema CLI version whose ${KERNEL_PACKAGE_NAME} is that authority`,
+    );
+  }
+}
+
+/**
+ * Configure a producer-side evidence verb from its argv in exactly one mode. `--contract-authority <file>` together
+ * with `--data-root`/`--kernel`, or neither, is refused by name.
+ *
+ * Vendor mode configures the Data and Kernel roots and returns `{mode, rest}`; the verb reads its pinned authority.
+ * Public-input mode configures no root, states the bundled kernel as the Kernel root and returns
+ * `{mode, rest, contractAuthority, schemas}` from {@link readPublicContractAuthority}.
+ */
+export async function configureEvidenceInputMode(argv, { verb }) {
+  const authorityAt = argv.findIndex((arg) => flagOf(arg) === CONTRACT_AUTHORITY_FLAG);
+  const vendorFlags = VENDOR_FLAGS.filter((flag) => argv.some((arg) => flagOf(arg) === flag));
+  const modes = `${CONTRACT_AUTHORITY_FLAG} <file> (public-input mode) or --data-root <dir> --kernel <dir> (vendor mode)`;
+  if (authorityAt !== -1 && vendorFlags.length > 0) {
+    throw new Error(`${verb}: ${CONTRACT_AUTHORITY_FLAG} and ${vendorFlags.join('/')} are two modes; pass one: ${modes}`);
+  }
+  if (authorityAt === -1 && vendorFlags.length === 0) {
+    throw new Error(`${verb} needs ${modes}`);
+  }
+  if (authorityAt === -1) {
+    return { mode: EvidenceInputMode.Vendor, rest: configureEditionWorkspaceFromArgv(argv, [WorkspaceRoot.Data, WorkspaceRoot.Kernel]) };
+  }
+  const arg = argv[authorityAt];
+  const inline = arg.length > CONTRACT_AUTHORITY_FLAG.length;
+  const path = inline ? arg.slice(CONTRACT_AUTHORITY_FLAG.length + 1) : argv[authorityAt + 1];
+  if (typeof path !== 'string' || path.length === 0 || path.startsWith('--')) {
+    throw new Error(`${CONTRACT_AUTHORITY_FLAG} requires a file path`);
+  }
+  if (argv.some((other, index) => index !== authorityAt && flagOf(other) === CONTRACT_AUTHORITY_FLAG)) {
+    throw new Error(`${CONTRACT_AUTHORITY_FLAG} is given more than once`);
+  }
+  const remaining = argv.filter((_, index) => index !== authorityAt && (inline || index !== authorityAt + 1));
+  const rest = configureEditionWorkspaceFromArgv(remaining, [], { refuseOthers: true });
+  stateKernelPackageDir(shippedKernelPackageDir());
+  const { contractAuthority, schemas } = await readPublicContractAuthority({ path: resolve(path) });
+  return { mode: EvidenceInputMode.PublicInput, rest, contractAuthority, schemas };
+}

package/edition/image-evidence.mjs

@@ -138,11 +138,29 @@ function assertTimeWindow({ issuedAt, expiresAt, now, maxTtlSeconds, label }) {
   if (expires <= instant) {
     throw new Error(`${label} is expired`);
   }
+  assertProducerTtlCeiling({ issuedAt, expiresAt, maxTtlSeconds, label });
+}
+
+/**
+ * The declared lifetime (`expiresAt - issuedAt`) is at most the trust policy's ceiling `maxTtlSeconds`. Held by
+ * `verify-evidence` (through the time window above) and by the third-party pin writer, which has no `now` to hold.
+ */
+export function assertProducerTtlCeiling({ issuedAt, expiresAt, maxTtlSeconds, label }) {
+  if (!Number.isSafeInteger(maxTtlSeconds) || maxTtlSeconds < 1) {
+    throw new Error(`${label}: the trust policy's TTL ceiling ${String(maxTtlSeconds)} is not a positive integer`);
+  }
+  const issued = Date.parse(issuedAt);
+  const expires = Date.parse(expiresAt);
+  if (![issued, expires].every(Number.isFinite)) {
+    throw new Error(`${label} has an invalid time`);
+  }
   if (expires <= issued) {
     throw new Error(`${label} expiresAt must be after issuedAt`);
   }
   if (expires - issued > maxTtlSeconds * 1000) {
-    throw new Error(`${label} exceeds the trusted maximum TTL`);
+    throw new Error(
+      `${label} exceeds the trusted maximum TTL (${(expires - issued) / 1000}s declared, maxProducerTtlSeconds ${maxTtlSeconds})`,
+    );
   }
 }
 

package/edition/kernel-contract-authority.mjs

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
 import { lstatSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { canonicalJson } from './canonical-evidence-json.mjs';
 import { kernelRepoDir } from './edition-workspace.mjs';
 import { COMMIT_PATTERN } from './evidence-grammars.mjs';
 import {
@@ -198,12 +199,19 @@ export function assertSourcePathsMatchCommit(repositoryDirectory, sourceCommit,
   assertSourcePathsEqualSet(sourcePaths, sourcePathSetAtCommit(repositoryDirectory, sourceCommit), sourceCommit);
 }
 
+/** The canonical JSON of an authority (sorted keys), or null for a value canonical evidence JSON cannot hold. */
 function exactAuthorityJson(value) {
-  return JSON.stringify(value);
+  try {
+    return canonicalJson(value);
+  } catch {
+    return null;
+  }
 }
 
+/** `actual` is exactly `expected`, field for field and value for value; key order is not part of an authority. */
 export function assertKernelContractAuthorityEqual(actual, expected, label) {
-  if (exactAuthorityJson(actual) !== exactAuthorityJson(expected)) {
+  const canonical = exactAuthorityJson(actual);
+  if (canonical === null || canonical !== exactAuthorityJson(expected)) {
     throw new Error(
       `${label} does not exactly match kernel contract authority`,
     );

package/edition/kernel-package.mjs

@@ -87,6 +87,19 @@ function shippedPackageDir(name) {
   return undefined;
 }
 
+/**
+ * The `@xemahq/contracts` package this CLI itself ships (installed from public npm with the CLI): the kernel of a
+ * verb that runs with no kernel checkout and no catalogue, such as a third-party publisher's
+ * `evidence assemble-third-party-input`. Refused when the CLI's installation has none.
+ */
+export function shippedKernelPackageDir() {
+  const dir = shippedPackageDir(KERNEL_PACKAGE_NAME);
+  if (dir === undefined) {
+    throw new KernelPackageError(`this CLI's installation ships no ${KERNEL_PACKAGE_NAME}; reinstall the CLI from npm`);
+  }
+  return dir;
+}
+
 function linkRuntimeDependencies(packageDir) {
   const manifest = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
   const nodeModules = dirname(manifest.name.startsWith('@') ? dirname(packageDir) : packageDir);