@xemahq/xema 0.59.0 → 0.60.1

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

@@ -1,259 +0,0 @@
-// 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

@@ -1,54 +0,0 @@
-// 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

@@ -1,115 +0,0 @@
-// 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

@@ -1,213 +0,0 @@
-// 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,
-  THIRD_PARTY_EVIDENCE_CHANNEL,
-  bundleSignerRowFor,
-  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 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 = bundleSignerRowFor({ policy, repository: request.repository, channel: THIRD_PARTY_EVIDENCE_CHANNEL, schemas, label: `third-party source "${request.name}" bundle signer` });
-  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`
-  );
-}