@xemahq/xema 0.48.0 → 0.49.0

package/edition/third-party-source-pins.mjs

@@ -0,0 +1,259 @@
+// The third-party source pin file (`third-party-source-pins.json`, XEMA-1611 design section 3).
+//
+// ONE reviewed record per third-party image source: the explicit grant that lets a biome from an
+// organisation outside the vendor fleet enter an edition with sealed, fully evidenced images. It
+// is validated here (the CLI), not by a kernel contract, and it is written only by the trusted
+// writer. The file lives at the root of the data root in use, beside the evidence trust policy;
+// there is no vendor path and no vendor key.
+//
+//   * A MISSING, EMPTY or UNPARSABLE (not JSON) file means "no third-party source": the loader
+//     returns an empty set and a reason every consumer puts in its refusal.
+//   * A file that parses but is not canonical JSON or does not match the schema THROWS: it is a
+//     reviewed record, and a record that is present but wrong is never read as "no sources".
+//   * The file's sha256 joins the evidence trust pin (`thirdPartySourcePinsDigest`).
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { parseCanonicalJsonBytes, sha256Digest } from './canonical-evidence-json.mjs';
+import {
+  CANONICAL_IDENTIFIER,
+  COMMIT_PATTERN,
+  GITHUB_REPOSITORY_PATTERN,
+  SHA256_DIGEST_PATTERN,
+  SHA256_HEX_PATTERN,
+} from './evidence-grammars.mjs';
+import { readBoundedNoFollowFile } from './no-follow-file.mjs';
+
+export const THIRD_PARTY_SOURCE_PINS_FILE = 'third-party-source-pins.json';
+export const THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION = 1;
+
+const MAX_PINS_BYTES = 2 * 1024 * 1024;
+const LABEL = THIRD_PARTY_SOURCE_PINS_FILE;
+
+const SOURCE_NAME = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const RUNTIME_IDENTITY = /^[a-z0-9](?:[a-z0-9._-]{0,254}[a-z0-9])?$/;
+const GITHUB_NUMERIC_ID = /^[1-9][0-9]*$/;
+const OCI_REPOSITORY = /^[a-z0-9]+(?:[.-][a-z0-9]+)*(?::[0-9]+)?(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)+$/;
+const OCI_REF_BY_DIGEST = new RegExp(`${OCI_REPOSITORY.source.slice(0, -1)}@sha256:[a-f0-9]{64}$`);
+const WORKFLOW_PATH = /^\.github\/workflows\/[A-Za-z0-9._-]+\.ya?ml$/;
+const SUBJECT_KINDS = Object.freeze(['service', 'platform', 'host', 'runtime-component', 'composed-process']);
+const SOURCE_HASH_ALGORITHMS = Object.freeze([
+  'xema-image-input-sha256-v1',
+  'xema-image-input-sha256-v2',
+  'xema-image-input-sha256-v3',
+]);
+
+const SOURCE_KEYS = Object.freeze([
+  'bundle',
+  'images',
+  'name',
+  'producerWorkflow',
+  'repository',
+  'repositoryId',
+  'repositoryOwnerId',
+  'repositoryUrl',
+  'sourceCommit',
+]);
+const BUNDLE_KEYS = Object.freeze([
+  'biomeId',
+  'bundleDigest',
+  'ociRef',
+  'signerPolicyId',
+  'sourceManifestHash',
+  'statementDigest',
+]);
+const WORKFLOW_KEYS = Object.freeze(['path', 'sha']);
+const IMAGE_KEYS = Object.freeze([
+  'bundleDigest',
+  'imageRef',
+  'manifestDigest',
+  'policyId',
+  'sourceHashAlgorithm',
+  'sourceTreeHash',
+  'statementDigest',
+  'subjectId',
+  'subjectKind',
+]);
+
+/** Why a data root has no third-party source. */
+export const ThirdPartyPinsAbsence = Object.freeze({
+  Missing: 'missing',
+  Empty: 'empty',
+  Unparsable: 'unparsable',
+});
+
+const exactKeys = (value, keys) =>
+  value !== null &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  Object.keys(value).sort().join() === keys.join();
+
+function field(path, value, test, expectation) {
+  if (typeof value !== 'string' || !test(value)) {
+    throw new Error(`${LABEL}: ${path} must be ${expectation}`);
+  }
+  return value;
+}
+const matching = (pattern) => (value) => pattern.test(value);
+
+function requireKeys(value, keys, path) {
+  if (!exactKeys(value, keys)) {
+    throw new Error(`${LABEL}: ${path} must have exactly the keys {${keys.join(', ')}}`);
+  }
+}
+
+function parseImage(image, path) {
+  requireKeys(image, IMAGE_KEYS, path);
+  const oneOf = (list) => (value) => list.includes(value);
+  return Object.freeze({
+    subjectKind: field(`${path}.subjectKind`, image.subjectKind, oneOf(SUBJECT_KINDS), `one of ${SUBJECT_KINDS.join(', ')}`),
+    subjectId: field(`${path}.subjectId`, image.subjectId, matching(CANONICAL_IDENTIFIER), 'a canonical identifier'),
+    imageRef: field(`${path}.imageRef`, image.imageRef, matching(OCI_REPOSITORY), 'an OCI repository reference without tag or digest'),
+    manifestDigest: field(`${path}.manifestDigest`, image.manifestDigest, matching(SHA256_DIGEST_PATTERN), 'sha256:<64 hex>'),
+    sourceTreeHash: field(`${path}.sourceTreeHash`, image.sourceTreeHash, matching(SHA256_HEX_PATTERN), '64 lowercase hex digits'),
+    sourceHashAlgorithm: field(`${path}.sourceHashAlgorithm`, image.sourceHashAlgorithm, oneOf(SOURCE_HASH_ALGORITHMS), `one of ${SOURCE_HASH_ALGORITHMS.join(', ')}`),
+    statementDigest: field(`${path}.statementDigest`, image.statementDigest, matching(SHA256_DIGEST_PATTERN), 'sha256:<64 hex>'),
+    bundleDigest: field(`${path}.bundleDigest`, image.bundleDigest, matching(SHA256_DIGEST_PATTERN), 'sha256:<64 hex>'),
+    policyId: field(`${path}.policyId`, image.policyId, matching(CANONICAL_IDENTIFIER), 'a canonical policy id'),
+  });
+}
+
+function parseSource(source, path) {
+  requireKeys(source, SOURCE_KEYS, path);
+  const name = field(`${path}.name`, source.name, matching(SOURCE_NAME), 'a lowercase source name');
+  const repository = field(`${path}.repository`, source.repository, matching(GITHUB_REPOSITORY_PATTERN), 'owner/name');
+  const repositoryUrl = field(
+    `${path}.repositoryUrl`,
+    source.repositoryUrl,
+    (value) => value === `https://github.com/${repository}` || value === `https://github.com/${repository}.git`,
+    `https://github.com/${repository}[.git] (the URL of repository)`,
+  );
+  requireKeys(source.producerWorkflow, WORKFLOW_KEYS, `${path}.producerWorkflow`);
+  requireKeys(source.bundle, BUNDLE_KEYS, `${path}.bundle`);
+  const sourceCommit = field(`${path}.sourceCommit`, source.sourceCommit, matching(COMMIT_PATTERN), 'an exact 40-hex commit');
+  const producerWorkflow = Object.freeze({
+    path: field(`${path}.producerWorkflow.path`, source.producerWorkflow.path, matching(WORKFLOW_PATH), 'a .github/workflows/*.yml|yaml path'),
+    sha: field(`${path}.producerWorkflow.sha`, source.producerWorkflow.sha, matching(COMMIT_PATTERN), 'an exact 40-hex commit'),
+  });
+  if (producerWorkflow.sha !== sourceCommit) {
+    throw new Error(`${LABEL}: ${path}.producerWorkflow.sha ${producerWorkflow.sha} must equal sourceCommit ${sourceCommit}`);
+  }
+  const bundle = Object.freeze({
+    ociRef: field(`${path}.bundle.ociRef`, source.bundle.ociRef, matching(OCI_REF_BY_DIGEST), '<repository>@sha256:<64 hex> (pinned by digest)'),
+    biomeId: field(`${path}.bundle.biomeId`, source.bundle.biomeId, matching(RUNTIME_IDENTITY), 'a lowercase biome id'),
+    sourceManifestHash: field(`${path}.bundle.sourceManifestHash`, source.bundle.sourceManifestHash, matching(SHA256_HEX_PATTERN), '64 lowercase hex digits'),
+    signerPolicyId: field(`${path}.bundle.signerPolicyId`, source.bundle.signerPolicyId, matching(CANONICAL_IDENTIFIER), 'a canonical policy id'),
+    statementDigest: field(`${path}.bundle.statementDigest`, source.bundle.statementDigest, matching(SHA256_DIGEST_PATTERN), 'sha256:<64 hex>'),
+    bundleDigest: field(`${path}.bundle.bundleDigest`, source.bundle.bundleDigest, matching(SHA256_DIGEST_PATTERN), 'sha256:<64 hex>'),
+  });
+  if (!Array.isArray(source.images) || source.images.length === 0) {
+    throw new Error(`${LABEL}: ${path}.images must list at least one image`);
+  }
+  const images = source.images.map((image, index) => parseImage(image, `${path}.images[${index}]`));
+  return Object.freeze({
+    name,
+    repository,
+    repositoryUrl,
+    repositoryId: field(`${path}.repositoryId`, source.repositoryId, matching(GITHUB_NUMERIC_ID), 'a decimal GitHub repository id'),
+    repositoryOwnerId: field(`${path}.repositoryOwnerId`, source.repositoryOwnerId, matching(GITHUB_NUMERIC_ID), 'a decimal GitHub owner id'),
+    sourceCommit,
+    producerWorkflow,
+    bundle,
+    images: Object.freeze(images),
+  });
+}
+
+function assertUnique(sources, pick, what) {
+  const seen = new Map();
+  sources.forEach((source, index) => {
+    for (const value of pick(source)) {
+      if (seen.has(value)) {
+        throw new Error(`${LABEL}: ${what} "${value}" is pinned by sources[${seen.get(value)}] and sources[${index}]`);
+      }
+      seen.set(value, index);
+    }
+  });
+}
+
+/** Validate a parsed pin document. Throws on the first violation, naming the key. */
+export function parseThirdPartySourcePins(document) {
+  requireKeys(document, ['schemaVersion', 'sources'], 'the document');
+  if (document.schemaVersion !== THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION) {
+    throw new Error(`${LABEL}: schemaVersion must be ${THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION}`);
+  }
+  if (!Array.isArray(document.sources)) {
+    throw new Error(`${LABEL}: sources must be an array`);
+  }
+  const sources = document.sources.map((source, index) => parseSource(source, `sources[${index}]`));
+  assertUnique(sources, (source) => [source.name], 'source name');
+  assertUnique(sources, (source) => [source.repository], 'repository');
+  assertUnique(sources, (source) => [source.repositoryId], 'repositoryId');
+  assertUnique(sources, (source) => [source.bundle.biomeId], 'biomeId');
+  assertUnique(sources, (source) => source.images.map((image) => image.imageRef), 'imageRef');
+  sources.forEach((source, index) => {
+    const ids = source.images.map((image) => image.subjectId);
+    if (new Set(ids).size !== ids.length) {
+      throw new Error(`${LABEL}: sources[${index}].images repeats a subjectId`);
+    }
+  });
+  return Object.freeze(sources);
+}
+
+/** The pinned sources, with lookups. An empty set carries the `reason` consumers put in their refusal. */
+function sourceSet(sources, absence) {
+  const byName = new Map(sources.map((source) => [source.name, source]));
+  const byRepository = new Map(sources.map((source) => [source.repository, source]));
+  const reason =
+    absence === null
+      ? null
+      : `${THIRD_PARTY_SOURCE_PINS_FILE} is ${absence} in the data root, so no third-party source is pinned`;
+  return Object.freeze({
+    sources,
+    absence,
+    reason,
+    byName: (name) => byName.get(name),
+    byRepository: (repository) => byRepository.get(repository),
+  });
+}
+
+/**
+ * Read the pin file's exact bytes from the data root: `null` when the file does not exist.
+ * This is what the evidence trust pin digests.
+ */
+export function readThirdPartySourcePinsBytes(dataRoot) {
+  if (!existsSync(join(dataRoot, THIRD_PARTY_SOURCE_PINS_FILE))) {
+    return null;
+  }
+  return readBoundedNoFollowFile(dataRoot, THIRD_PARTY_SOURCE_PINS_FILE, LABEL, MAX_PINS_BYTES).bytes;
+}
+
+/** sha256 of the pin file's bytes, or `null` when the data root has no such file. */
+export function thirdPartySourcePinsDigest(dataRoot) {
+  const bytes = readThirdPartySourcePinsBytes(dataRoot);
+  return bytes === null ? null : sha256Digest(bytes);
+}
+
+/**
+ * Load the third-party source pins of the data root in use.
+ *
+ * @param {string} dataRoot
+ * @returns {{sources: readonly object[], absence: string|null, reason: string|null,
+ *   byName: (name: string) => object|undefined, byRepository: (repository: string) => object|undefined}}
+ */
+export function loadThirdPartySourcePins(dataRoot) {
+  const bytes = readThirdPartySourcePinsBytes(dataRoot);
+  if (bytes === null) {
+    return sourceSet([], ThirdPartyPinsAbsence.Missing);
+  }
+  if (bytes.length === 0) {
+    return sourceSet([], ThirdPartyPinsAbsence.Empty);
+  }
+  try {
+    JSON.parse(bytes.toString('utf8'));
+  } catch {
+    return sourceSet([], ThirdPartyPinsAbsence.Unparsable);
+  }
+  const document = parseCanonicalJsonBytes(bytes, LABEL);
+  return sourceSet(parseThirdPartySourcePins(document), null);
+}

package/edition/third-party-source-uniqueness.mjs

@@ -0,0 +1,54 @@
+// Check (e) of a third-party source pin (XEMA-1611 design section 3): who may be pinned next to whom.
+//
+// It reuses the pin loader's uniqueness (names, repositories, repository ids, biome ids, image references) and the
+// trust policy's image ownership (one publisher per image repository, no first-party namespace for a foreign owner),
+// and adds what only the data root's own indexes can answer: the third-party repository owner is not a first-party
+// owner, the biome id does not collide with a biome, platform service or supplemental subject, and the name and
+// repository are not repositories of the runtime image source index.
+
+import { parseThirdPartySourcePins, THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION } from './third-party-source-pins.mjs';
+import { assertTrustPolicyImageOwnership, firstPartyOwnersFromIndex, isFirstPartyImageNamespace } from './trust-policy-image-ownership.mjs';
+
+const repositoryPathOf = (repositoryUrl) => new URL(repositoryUrl).pathname.replace(/^\//u, '').replace(/\.git$/u, '');
+
+/**
+ * Refuse a set of pinned sources that breaks (e). Throws naming the source and the collision.
+ *
+ * @param {{sources: readonly object[], policy: object, runtimeSourceIndex: object, biomeIndex: object[], platformServiceIndex: {services: object[]}}} data
+ */
+export function assertThirdPartyUniqueness({ sources, policy, runtimeSourceIndex, biomeIndex, platformServiceIndex }) {
+  parseThirdPartySourcePins({ schemaVersion: THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION, sources });
+  const firstPartyOwners = firstPartyOwnersFromIndex(runtimeSourceIndex);
+  assertTrustPolicyImageOwnership({ policy, firstPartyOwners });
+  const biomeIds = new Set(biomeIndex.map((biome) => biome.id));
+  const subjectIds = new Set([
+    ...platformServiceIndex.services.map((service) => service.name),
+    ...runtimeSourceIndex.supplementalSubjects.map((subject) => subject.id),
+  ]);
+  const indexRepositories = new Set(runtimeSourceIndex.repositoryPins.flatMap((pin) => [pin.repo, repositoryPathOf(pin.repositoryUrl).toLowerCase()]));
+  const indexRepositoryNames = new Set(runtimeSourceIndex.repositoryPins.map((pin) => pin.repo.split('/').at(-1)));
+  for (const source of sources) {
+    const where = `third-party source "${source.name}"`;
+    const owner = source.repository.split('/')[0].toLowerCase();
+    if (firstPartyOwners.has(owner)) {
+      throw new Error(`${where}: repository ${source.repository} is owned by "${owner}", a first-party owner (the owner of an index repository pin, or xemahq)`);
+    }
+    if (indexRepositories.has(source.repository.toLowerCase())) {
+      throw new Error(`${where}: repository ${source.repository} is a repository of the runtime image source index`);
+    }
+    if (indexRepositories.has(source.name) || indexRepositoryNames.has(source.name)) {
+      throw new Error(`${where}: the name collides with a repository of the runtime image source index`);
+    }
+    if (biomeIds.has(source.bundle.biomeId)) {
+      throw new Error(`${where}: biomeId "${source.bundle.biomeId}" collides with a biome of the biome index`);
+    }
+    if (subjectIds.has(source.bundle.biomeId)) {
+      throw new Error(`${where}: biomeId "${source.bundle.biomeId}" collides with a platform service or supplemental subject of the data root`);
+    }
+    for (const image of source.images) {
+      if (isFirstPartyImageNamespace(image.imageRef, firstPartyOwners)) {
+        throw new Error(`${where}: image ${image.imageRef} is in a first-party namespace (<registry>/<first-party owner>/<any>)`);
+      }
+    }
+  }
+}

package/edition/third-party-source-walk.mjs

@@ -0,0 +1,115 @@
+// The `kind: oci` branch of the edition source walk (XEMA-1611 design section 4).
+//
+// A declared OCI source names a pin of the data root's `third-party-source-pins.json` (written only by the trusted
+// writer). Walking it pulls the pinned bundle BY DIGEST, holds its manifest to the pinned `sourceManifestHash`, re-runs
+// checks (a) to (d) of the writer from the evidence COMMITTED under the data root (`verifyThirdPartySourceEvidence`, the
+// one verifier the writer and `--check-third-party` use), and projects the manifest into an index entry through
+// `manifestToIndexEntry`. It reads no git repository and writes no lock `source`: the lock's `LockedBiomeSource` is
+// git-only, so the row is held to its pin by the image plane instead (`third-party-subjects.mjs`).
+
+import { dataRoot as configuredDataRoot } from './edition-workspace.mjs';
+import { loadKernelBiomeContracts, loadKernelDistributionSchemas, manifestToIndexEntry } from './lib.mjs';
+import { createRegistryClientResolver } from './oci-image-source-evidence.mjs';
+import { disposeRegistrySessions } from './oras.mjs';
+import { fetchBundleGeneratedIndex, fetchBundleManifest } from './third-party-bundle-registry.mjs';
+import { loadThirdPartySourceContext } from './third-party-source-context.mjs';
+import { verifyThirdPartySourceEvidence } from './third-party-source-evidence.mjs';
+import { COSIGN_BIN_ENV } from './third-party-source-flags.mjs';
+import { loadThirdPartySourcePins } from './third-party-source-pins.mjs';
+import { OCI_BUNDLE_SOURCE_KIND } from './third-party-subjects.mjs';
+
+/**
+ * @param {object} options
+ * @param {{name: string, kind: string, registry: string}} options.source the declared `oci` source
+ * @param {{reason: string|null, byName: (name: string) => object|undefined}} options.pins
+ * @param {string} options.dataRoot the evidence under it is the committed evidence of the pin
+ * @param {object} options.context `loadThirdPartySourceContext`
+ * @param {(authority: string) => object} options.clientFor
+ * @param {(value: unknown) => object} options.parseBundleSource the kernel's bundle source schema
+ * @returns {Promise<object>} the (unstamped) index entry of the bundle's biome
+ */
+async function walkThirdPartySource({ source, pin, dataRoot, context, clientFor, parseBundleSource }) {
+  const where = `source "${source.name}"`;
+  if (!pin.bundle.ociRef.startsWith(`${source.registry}/`)) {
+    throw new Error(`${where} declares registry ${source.registry}, but its pinned bundle ${pin.bundle.ociRef} is not served from it`);
+  }
+  // (a) to (d) from the committed evidence: the signature, the provenance subject (= the pinned bundle digest), the
+  // certificate extensions and every image's evidence.
+  const evidence = verifyThirdPartySourceEvidence({ source: pin, evidenceRoot: dataRoot, context });
+  const path = biomeDirectory(pin, evidence.images, where);
+
+  const { manifest } = await fetchBundleManifest({ clientFor, ociRef: pin.bundle.ociRef });
+  const actualHash = await context.schemas.computeBiomeSourceManifestHash(manifest);
+  if (actualHash !== pin.bundle.sourceManifestHash) {
+    throw new Error(`${where}: bundle ${pin.bundle.ociRef} hashes its manifest to ${actualHash}, but the pin records ${pin.bundle.sourceManifestHash}`);
+  }
+  if (manifest?.xema?.id !== pin.bundle.biomeId) {
+    throw new Error(`${where}: bundle ${pin.bundle.ociRef} declares biome ${JSON.stringify(manifest?.xema?.id)}, but the pin is for "${pin.bundle.biomeId}"`);
+  }
+  const generatedIndex = await fetchBundleGeneratedIndex({ clientFor, ociRef: pin.bundle.ociRef });
+  const entry = await manifestToIndexEntry({
+    raw: manifest,
+    generatedIndex,
+    rel: `${source.name}/${pin.bundle.ociRef}`,
+    repo: pin.repository,
+    path,
+  });
+  if ((entry.hostModules ?? []).length > 0) {
+    throw new Error(`${where}: biome "${entry.id}" ships host modules, which a third-party OCI bundle is not admitted to carry`);
+  }
+  // Where the bundle lives is the pin's statement, never the manifest's: a manifest that names another bundle source is refused.
+  const bundleSource = parseBundleSource({ kind: OCI_BUNDLE_SOURCE_KIND, ociRef: pin.bundle.ociRef });
+  if (entry.bundleSource !== undefined && JSON.stringify(entry.bundleSource) !== JSON.stringify(bundleSource)) {
+    throw new Error(`${where}: biome "${entry.id}" declares bundleSource ${JSON.stringify(entry.bundleSource)}, which is not the pinned bundle ${pin.bundle.ociRef}`);
+  }
+  return { ...entry, bundleSource };
+}
+
+/**
+ * The biome's directory in the publisher's repository: the `source.path` its verified image statements all state (a
+ * subject's `path` must equal it at admission). A pin with no image has no subject to bind, so the repository root.
+ */
+function biomeDirectory(pin, statements, where) {
+  const paths = [...new Set(statements.map((statement) => statement.predicate.source.path))];
+  if (paths.length > 1) {
+    throw new Error(`${where}: the pinned images' evidence states different source paths (${paths.join(', ')}), so the biome has no one directory`);
+  }
+  return paths[0] ?? pin.repository;
+}
+
+/** The pin of a declared OCI source, or the refusal that names why there is none (a missing or empty pin file included). */
+function requirePin(pins, source) {
+  const pin = pins.byName(source.name);
+  if (pin === undefined) {
+    throw new Error(`source "${source.name}" is kind "oci", but ${pins.reason ?? `the data root's third-party source pins hold no pin named "${source.name}"`}`);
+  }
+  return pin;
+}
+
+/**
+ * Walk every declared OCI source: `{source, entry}` per source, the index entry of its bundle unstamped (the caller stamps it). The data
+ * root, schemas, cosign binary, registry client and verification context are the process's unless `thirdParty` injects
+ * them (the contract suite drives a fixture registry and a digest-pinned cosign double).
+ *
+ * @param {object[]} sources declared sources of kind `oci`
+ * @param {{env?: NodeJS.ProcessEnv, thirdParty?: {dataRoot?: string, schemas?: object, cosignBinary?: string, clientFor?: Function, context?: object}}} options
+ */
+export async function walkOciSources(sources, { env = process.env, thirdParty = {} } = {}) {
+  const root = thirdParty.dataRoot ?? configuredDataRoot();
+  const pins = loadThirdPartySourcePins(root);
+  const pinned = sources.map((source) => [source, requirePin(pins, source)]);
+  const schemas = thirdParty.schemas ?? (await loadKernelDistributionSchemas());
+  const context = thirdParty.context ?? loadThirdPartySourceContext({ dataRoot: root, schemas, cosignBinary: thirdParty.cosignBinary ?? env[COSIGN_BIN_ENV] });
+  const clientFor = thirdParty.clientFor ?? createRegistryClientResolver({ dataRoot: root });
+  const parseBundleSource = (value) => loadKernelBiomeContracts().BiomeBundleSourceSpecSchema.parse(value);
+  try {
+    const entries = [];
+    for (const [source, pin] of pinned) {
+      entries.push({ source, entry: await walkThirdPartySource({ source, pin, dataRoot: root, context, clientFor, parseBundleSource }) });
+    }
+    return entries;
+  } finally {
+    if (thirdParty.context === undefined) {context.dispose();}
+    if (thirdParty.clientFor === undefined) {disposeRegistrySessions();}
+  }
+}

package/edition/third-party-source-writer.mjs

@@ -0,0 +1,229 @@
+// The trusted writer of a third-party source pin (XEMA-1611 design section 3): `xema edition index runtime-image-source
+// --trusted-write --third-party <name> ...`. It PLANS the write: reads the bundle and the evidence from the registry,
+// runs checks (a) to (e) on the exact bytes it would commit, and returns the files, the pin record and the candidate
+// index. `commitThirdPartySourceWrite` then writes them. The third-party repository is never cloned.
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { REPIN_COMMAND } from './evidence-trust-pin.mjs';
+import { canonicalJsonBytes, evidenceDirectoryForDigest, policyCandidates, sha256Digest } from './image-evidence.mjs';
+import { resolveImageSourceEvidenceReferrer } from './oci-image-source-evidence.mjs';
+import { PRODUCER_EVIDENCE_INDEX_FILE } from './producer-evidence-index-file.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { bundleImageNames, fetchBundleManifest, fetchBundleProvenance, verifyBundleOnRegistry } from './third-party-bundle-registry.mjs';
+import {
+  PROVENANCE_BUNDLE_FILE,
+  PROVENANCE_STATEMENT_FILE,
+  SLSA_PROVENANCE_V1,
+  THIRD_PARTY_EVIDENCE_CHANNEL,
+  digestOfOciRef,
+  provenanceDirectoryForDigest,
+  thirdPartySignerRow,
+  verifyThirdPartySourceEvidence,
+} from './third-party-source-evidence.mjs';
+import { THIRD_PARTY_SOURCE_PINS_FILE, THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION, loadThirdPartySourcePins } from './third-party-source-pins.mjs';
+import { assertThirdPartyUniqueness } from './third-party-source-uniqueness.mjs';
+
+const compare = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+/** The one release-channel row that signs the biome bundle's provenance for `repository`. */
+function bundleSignerRow(policy, repository) {
+  const rows = policy.policies.filter(
+    (row) =>
+      row.channel === THIRD_PARTY_EVIDENCE_CHANNEL &&
+      row.predicateTypes.includes(SLSA_PROVENANCE_V1) &&
+      row.githubWorkflow?.repository === repository,
+  );
+  if (rows.length !== 1) {
+    throw new Error(
+      `the trust policy has ${rows.length} ${THIRD_PARTY_EVIDENCE_CHANNEL} rows authorizing ${SLSA_PROVENANCE_V1} for ${repository}; exactly one bundle-signer row is required`,
+    );
+  }
+  return rows[0];
+}
+
+/** The one release-channel row whose imageRepositories lists `imageRef`. */
+function imageSignerRow(policy, schemas, imageRef) {
+  const rows = policyCandidates(policy, schemas.IMAGE_PRODUCER_PREDICATE_TYPE, THIRD_PARTY_EVIDENCE_CHANNEL, imageRef);
+  if (rows.length !== 1) {
+    throw new Error(
+      `${rows.length} ${THIRD_PARTY_EVIDENCE_CHANNEL} trust policy rows list ${imageRef} in their imageRepositories for image-source evidence; exactly one is required`,
+    );
+  }
+  return rows[0];
+}
+
+async function collectImage({ image, request, context, clientFor, services }) {
+  const { schemas, expectedContractAuthority, policy } = context;
+  const label = `image ${image.imageRef}@${image.manifestDigest}`;
+  const row = imageSignerRow(policy, schemas, image.imageRef);
+  const { authority } = splitImageRef(image.imageRef);
+  const skipped = [];
+  const evidence = await resolveImageSourceEvidenceReferrer({
+    client: clientFor(authority),
+    imageRepository: image.imageRef,
+    subjectDigest: image.manifestDigest,
+    schemas,
+    expectedContractAuthority,
+    onInvalidReferrer: (report) => skipped.push(`${report.artifactDigest}: ${report.reason}`),
+  });
+  if (evidence === null) {
+    throw new Error(`${label} has no valid image-source evidence referrer${skipped.length === 0 ? '' : ` (skipped: ${skipped.join('; ')})`}`);
+  }
+  if (evidence.records.length !== 1) {
+    throw new Error(`${label}: the evidence referrer carries ${evidence.records.length} statements; a third-party image has exactly one`);
+  }
+  const [record] = evidence.records;
+  const { source } = record.statement.predicate;
+  if (!services.has(source.id)) {
+    throw new Error(`${label}: its statement attests ${source.kind}:${source.id}, which is not an oci-image service of bundle ${request.bundleOciRef} (${[...services].join(', ')})`);
+  }
+  const directory = evidenceDirectoryForDigest(image.manifestDigest);
+  return {
+    pin: {
+      subjectKind: source.kind,
+      subjectId: source.id,
+      imageRef: image.imageRef,
+      manifestDigest: image.manifestDigest,
+      sourceTreeHash: source.sourceTreeHash,
+      sourceHashAlgorithm: source.sourceHashAlgorithm,
+      statementDigest: record.descriptor.statementDigest,
+      bundleDigest: record.descriptor.bundleDigest,
+      policyId: row.policyId,
+    },
+    files: [
+      [`${directory}/${PRODUCER_EVIDENCE_INDEX_FILE}`, evidence.indexBytes],
+      [`${directory}/${record.descriptor.statementPath}`, record.statementBytes],
+      [`${directory}/${record.descriptor.bundlePath}`, record.bundleBytes],
+    ],
+  };
+}
+
+/**
+ * Plan the write of one third-party source. Throws on the first violated check; writes nothing to the data root.
+ *
+ * @param {object} options
+ * @param {{name, repository, repositoryId, repositoryOwnerId, sourceCommit, bundleOciRef, biomeId, images: {imageRef, manifestDigest}[]}} options.request
+ * @param {object} options.context `loadThirdPartySourceContext`
+ * @param {(authority: string) => object} options.clientFor the registry client of an authority
+ * @param {(request: {committedIndex: object, pin: {repository: string, workflowCommit: string}}) => object} options.withProducerWorkflowPin
+ *   the committed runtime image source index with the pin merged in, built by the index generator
+ * @param {string} options.dataRoot
+ * @param {(options: object) => void} [options.verifyOnRegistry]
+ */
+export async function planThirdPartySourceWrite({ request, context, clientFor, withProducerWorkflowPin, dataRoot, verifyOnRegistry = verifyBundleOnRegistry }) {
+  const { policy, schemas } = context;
+  const repositoryUrl = `https://github.com/${request.repository}`;
+  const row = bundleSignerRow(policy, request.repository);
+  const workflowPath = row.githubWorkflow.path;
+  // The row must be exact (release channel, refs/heads/main, the GitHub issuer, its own workflow identity) before cosign runs.
+  thirdPartySignerRow({ policy, policyId: row.policyId, source: { repository: request.repository, producerWorkflow: { path: workflowPath } }, schemas, label: `third-party source "${request.name}" bundle signer` });
+
+  // (a) the bundle: the registry's signature and provenance under exactly this row, then its bytes.
+  verifyOnRegistry({
+    trustedCosign: context.trustedCosign,
+    policy,
+    policyRoot: context.policyRoot,
+    row,
+    workflowSha: request.sourceCommit,
+    ociRef: request.bundleOciRef,
+  });
+  const { manifest } = await fetchBundleManifest({ clientFor, ociRef: request.bundleOciRef });
+  if (manifest?.xema?.id !== request.biomeId) {
+    throw new Error(`bundle ${request.bundleOciRef} declares xema.id ${JSON.stringify(manifest?.xema?.id)}, but --biome-id is ${JSON.stringify(request.biomeId)}`);
+  }
+  const sourceManifestHash = await schemas.computeBiomeSourceManifestHash(manifest);
+  const services = bundleImageNames(manifest);
+  const provenance = await fetchBundleProvenance({ clientFor, ociRef: request.bundleOciRef });
+  const provenanceDirectory = provenanceDirectoryForDigest(digestOfOciRef(request.bundleOciRef));
+
+  // (b) each image's image-source/v2 evidence, as an OCI referrer of imageRef@digest.
+  const images = [];
+  const files = [
+    [`${provenanceDirectory}/${PROVENANCE_STATEMENT_FILE}`, provenance.statementBytes],
+    [`${provenanceDirectory}/${PROVENANCE_BUNDLE_FILE}`, provenance.bundleBytes],
+  ];
+  for (const image of request.images) {
+    const collected = await collectImage({ image, request, context, clientFor, services });
+    images.push(collected.pin);
+    files.push(...collected.files);
+  }
+
+  const source = {
+    name: request.name,
+    repository: request.repository,
+    repositoryUrl,
+    repositoryId: request.repositoryId,
+    repositoryOwnerId: request.repositoryOwnerId,
+    sourceCommit: request.sourceCommit,
+    producerWorkflow: { path: workflowPath, sha: request.sourceCommit },
+    bundle: {
+      ociRef: request.bundleOciRef,
+      biomeId: request.biomeId,
+      sourceManifestHash,
+      signerPolicyId: row.policyId,
+      statementDigest: sha256Digest(provenance.statementBytes),
+      bundleDigest: sha256Digest(provenance.bundleBytes),
+    },
+    images: images.sort((left, right) => compare(left.imageRef, right.imageRef)),
+  };
+  const committed = loadThirdPartySourcePins(dataRoot).sources.filter((candidate) => candidate.name !== request.name);
+  const sources = [...committed, source].sort((left, right) => compare(left.name, right.name));
+
+  // (e) uniqueness, over the pins as they would be committed.
+  assertThirdPartyUniqueness({ sources, policy, runtimeSourceIndex: context.runtimeSourceIndex, biomeIndex: context.biomeIndex, platformServiceIndex: context.platformServiceIndex });
+
+  // (a) offline over the exact bytes to commit, (b) to (d): the very verification `--check-third-party` repeats.
+  const candidateIndex = schemas.parseRuntimeImageSourceIndex(
+    withProducerWorkflowPin({ committedIndex: context.runtimeSourceIndex, pin: { repository: request.repository, workflowCommit: request.sourceCommit } }),
+  );
+  const staging = mkdtempSync(join(tmpdir(), 'xema-third-party-write-'));
+  try {
+    for (const [path, bytes] of files) {
+      const target = join(staging, path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, bytes, { flag: 'wx' });
+    }
+    verifyThirdPartySourceEvidence({ source, evidenceRoot: staging, context: { ...context, runtimeSourceIndex: candidateIndex } });
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+  return { source, sources, files, candidateIndex };
+}
+
+function writeNewOrIdentical(dataRoot, path, bytes) {
+  const target = join(dataRoot, path);
+  try {
+    writeFileSync(target, bytes, { flag: 'wx', mode: 0o644 });
+  } catch (error) {
+    if (error.code !== 'EEXIST') {throw error;}
+    if (!readFileSync(target).equals(bytes)) {
+      throw new Error(`${path} already exists with different bytes; evidence is content-addressed and is never overwritten`);
+    }
+  }
+}
+
+/**
+ * Write a planned source: the evidence files (content-addressed, never overwritten), then the pin file, then the
+ * index. The evidence trust pin is NOT repinned: reviewing the pin file and running `xema edition repin-evidence-trust`
+ * is the intended next step, and until then the pin load refuses.
+ *
+ * @returns {string} the next step to print
+ */
+export function commitThirdPartySourceWrite({ dataRoot, plan, indexPath, indexText }) {
+  for (const [path, bytes] of plan.files) {
+    mkdirSync(dirname(join(dataRoot, path)), { recursive: true });
+    writeNewOrIdentical(dataRoot, path, bytes);
+  }
+  writeFileSync(
+    join(dataRoot, THIRD_PARTY_SOURCE_PINS_FILE),
+    canonicalJsonBytes({ schemaVersion: THIRD_PARTY_SOURCE_PINS_SCHEMA_VERSION, sources: plan.sources }),
+  );
+  writeFileSync(indexPath, indexText);
+  return (
+    `pinned third-party source "${plan.source.name}" (${plan.source.repository}@${plan.source.sourceCommit}, ${plan.source.images.length} image(s)); ` +
+    `run \`${REPIN_COMMAND}\` after reviewing ${THIRD_PARTY_SOURCE_PINS_FILE}: the evidence trust pin does not yet record it, so the pin load refuses until then`
+  );
+}