@xemahq/xema 0.48.0 → 0.49.1

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

@@ -0,0 +1,134 @@
+// The flags of `xema edition index runtime-image-source --trusted-write --third-party <name>` and of
+// `--check-third-party` (XEMA-1611 design section 3). The writer takes DECLARED facts and proves them; nothing here
+// is derived from a clone of the third-party repository.
+
+import { isAbsolute } from 'node:path';
+
+import { COMMIT_PATTERN, GITHUB_REPOSITORY_PATTERN, SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
+
+export const THIRD_PARTY_FLAG = '--third-party';
+export const CHECK_THIRD_PARTY_FLAG = '--check-third-party';
+export const COSIGN_FLAG = '--cosign';
+/** The environment variable `dist-check` reads the cosign binary of the third-party check from (an absolute path). */
+export const COSIGN_BIN_ENV = 'XEMA_COSIGN_BIN';
+
+const WRITER_FLAGS = Object.freeze({
+  repository: '--repository',
+  repositoryId: '--repository-id',
+  repositoryOwnerId: '--repository-owner-id',
+  sourceCommit: '--source-commit',
+  bundle: '--bundle',
+  biomeId: '--biome-id',
+});
+const IMAGE_FLAG = '--image';
+
+export const THIRD_PARTY_WRITER_USAGE =
+  `${THIRD_PARTY_FLAG} <name> --repository <owner/name> --repository-id <github id> --repository-owner-id <github id> ` +
+  '--source-commit <40-hex> --bundle <oci repository>@sha256:<64-hex> --biome-id <id> ' +
+  `${IMAGE_FLAG} <image repository>@sha256:<64-hex> [${IMAGE_FLAG} ...] ${COSIGN_FLAG} <absolute cosign path>`;
+
+/** Remove every `flag value` pair named `flag` from argv; the values in order, and the argv without them. */
+function take(argv, flag) {
+  const values = [];
+  const remaining = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== flag) {
+      remaining.push(argv[index]);
+      continue;
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new Error(`${flag} requires a value`);
+    }
+    values.push(value);
+    index += 1;
+  }
+  return { values, remaining };
+}
+
+function single(argv, flag) {
+  const { values, remaining } = take(argv, flag);
+  if (values.length > 1) {
+    throw new Error(`${flag} was given more than once`);
+  }
+  return { value: values[0], remaining };
+}
+
+function matching(flag, value, pattern, expectation) {
+  if (!pattern.test(value)) {
+    throw new Error(`${flag} must be ${expectation}; got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+const OCI_REPOSITORY_AT_DIGEST = /^[^@\s]+@sha256:[a-f0-9]{64}$/u;
+const NUMERIC_ID = /^[1-9][0-9]*$/u;
+
+function parseImage(value) {
+  matching(IMAGE_FLAG, value, OCI_REPOSITORY_AT_DIGEST, '<image repository>@sha256:<64-hex>');
+  const at = value.indexOf('@');
+  const manifestDigest = value.slice(at + 1);
+  matching(IMAGE_FLAG, manifestDigest, SHA256_DIGEST_PATTERN, 'a sha256 digest');
+  return { imageRef: value.slice(0, at), manifestDigest };
+}
+
+/**
+ * Take the third-party flags out of `argv`. `writer` is the parsed write request (or `undefined` when `--third-party`
+ * is absent, in which case any writer-only flag is refused); `cosignBinary` is `--cosign` (absolute) or `undefined`.
+ */
+export function takeThirdPartyFlags(argv) {
+  let rest = argv;
+  const name = single(rest, THIRD_PARTY_FLAG);
+  rest = name.remaining;
+  const cosign = single(rest, COSIGN_FLAG);
+  rest = cosign.remaining;
+  const taken = {};
+  for (const [key, flag] of Object.entries(WRITER_FLAGS)) {
+    const result = single(rest, flag);
+    rest = result.remaining;
+    taken[key] = result.value;
+  }
+  const images = take(rest, IMAGE_FLAG);
+  rest = images.remaining;
+  if (cosign.value !== undefined && !isAbsolute(cosign.value)) {
+    throw new Error(`${COSIGN_FLAG} must be an absolute path to the cosign binary`);
+  }
+  const writerFlagsGiven = Object.values(taken).some((value) => value !== undefined) || images.values.length > 0;
+  if (name.value === undefined) {
+    if (writerFlagsGiven) {
+      throw new Error(`the writer flags (${[...Object.values(WRITER_FLAGS), IMAGE_FLAG].join(', ')}) belong to ${THIRD_PARTY_FLAG} <name>`);
+    }
+    return { writer: undefined, cosignBinary: cosign.value, remaining: rest };
+  }
+  const require = (key) => {
+    if (taken[key] === undefined) {
+      throw new Error(`${THIRD_PARTY_FLAG} requires ${WRITER_FLAGS[key]}\nusage: ${THIRD_PARTY_WRITER_USAGE}`);
+    }
+    return taken[key];
+  };
+  if (images.values.length === 0) {
+    throw new Error(`${THIRD_PARTY_FLAG} requires ${IMAGE_FLAG} at least once\nusage: ${THIRD_PARTY_WRITER_USAGE}`);
+  }
+  if (cosign.value === undefined) {
+    throw new Error(`${THIRD_PARTY_FLAG} requires ${COSIGN_FLAG}\nusage: ${THIRD_PARTY_WRITER_USAGE}`);
+  }
+  const parsedImages = images.values.map(parseImage);
+  if (new Set(parsedImages.map((image) => image.imageRef)).size !== parsedImages.length) {
+    throw new Error(`${IMAGE_FLAG} names an image repository more than once`);
+  }
+  const bundle = matching(WRITER_FLAGS.bundle, require('bundle'), OCI_REPOSITORY_AT_DIGEST, '<oci repository>@sha256:<64-hex>');
+  return {
+    writer: {
+      name: name.value,
+      repository: matching(WRITER_FLAGS.repository, require('repository'), GITHUB_REPOSITORY_PATTERN, 'owner/name'),
+      repositoryId: matching(WRITER_FLAGS.repositoryId, require('repositoryId'), NUMERIC_ID, 'a decimal GitHub repository id'),
+      repositoryOwnerId: matching(WRITER_FLAGS.repositoryOwnerId, require('repositoryOwnerId'), NUMERIC_ID, 'a decimal GitHub owner id'),
+      sourceCommit: matching(WRITER_FLAGS.sourceCommit, require('sourceCommit'), COMMIT_PATTERN, 'an exact 40-hex commit'),
+      bundleOciRef: bundle,
+      biomeId: require('biomeId'),
+      images: parsedImages,
+    },
+    cosignBinary: cosign.value,
+    remaining: rest,
+  };
+}

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();}
+  }
+}