@xemahq/xema 0.48.0 → 0.49.0

package/edition/resolve-distribution.mjs

@@ -78,7 +78,7 @@ import { resolveDispatchedRuntimeComponents } from './dispatched-runtime-compone
 import { fleetChartSetLockPath, writeEditionChartSet } from './edition-chart-set.mjs';
 import { workspaceSection } from './edition-config.mjs';
 import { editionPinnedInputs } from './edition-pinned-inputs.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule, kernelPackageDir } from './edition-workspace.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, dataRoot, editionsRoot, isEntryModule, kernelPackageDir } from './edition-workspace.mjs';
 import { walkDeclaredSources } from './external-source-walk.mjs';
 import {
   biomeTierOrder,
@@ -95,6 +95,7 @@ import {
   validateImmutableDistributionLock,
   validateServiceDependencyOwnerParity,
 } from './lib.mjs';
+import { BundleSignerPolicyAbsentError, loadBundleSignerSelection } from './locked-bundle-signer.mjs';
 import {
   assertInstalledOperationCeilingAdmitted,
   assertOperationGrantsAdmitted,
@@ -112,6 +113,7 @@ import { commandFor } from './remedy-command.mjs';
 import { soleResourceProvider } from './required-resource-provider.mjs';
 import { readStorePublisherTrust } from './store-publisher-trust.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
+import { isThirdPartyOciEntry } from './third-party-subjects.mjs';
 import { RuntimeSubjectKind } from './workspace-sections.mjs';
 
 /**
@@ -254,7 +256,14 @@ export function loadEditionManifest(parseDistribution, id) {
   if (!existsSync(path)) {
     throw new Error(`distribution "${id}" not found: ${path} does not exist`);
   }
-  const raw = readStrictJsonFile(path);
+  return parseEditionManifest(parseDistribution, id, readStrictJsonFile(path), path);
+}
+
+/**
+ * The edition model's checks on one raw definition read from `source` (a file path, or a Git object): the refused
+ * fields, the kernel's validation and the id match. The one parse of a definition, whoever read the bytes.
+ */
+export function parseEditionManifest(parseDistribution, id, raw, source) {
   if (raw !== null && typeof raw === 'object' && Object.hasOwn(raw, REFUSED_EXTENDS_FIELD)) {
     throw new EditionModelError(
       `edition "${id}": "${REFUSED_EXTENDS_FIELD}" is not part of the edition model; ` +
@@ -271,7 +280,7 @@ export function loadEditionManifest(parseDistribution, id) {
   // `sourcePins` reaches the kernel unchanged: its Distribution schema validates it.
   const manifest = parseDistribution(raw);
   if (manifest.id !== id) {
-    throw new Error(`distribution at ${path} declares id "${manifest.id}", but it was addressed as "${id}"`);
+    throw new Error(`distribution at ${source} declares id "${manifest.id}", but it was addressed as "${id}"`);
   }
   return manifest;
 }
@@ -618,6 +627,11 @@ export function mergeExternalSourceEntries(
  * emitting `source: undefined` would make it read as first-party — so this
  * fails rather than choosing either.
  */
+/** A stamped entry of a declared OCI source: third-party, an OCI bundle source and no git record. */
+function isThirdPartyOciSourceEntry(entry, sourceRecords) {
+  return !sourceRecords.has(entry.source) && isThirdPartyOciEntry(entry);
+}
+
 function requireSourceRecord(entry, sourceRecords) {
   const record = sourceRecords.get(entry.source);
   if (record === undefined) {
@@ -1780,6 +1794,23 @@ export function resolveDistributionFromInputs(
   // shipped provider. See `nexusBinder`.
   const nexusBindings = nexusBinder(id, [...selected.values()], schemas);
 
+  // (5c') Bundle signers — every OCI bundle row (a biome's, a host module's) states the signer the data root's
+  // trust policy selects for it. See `locked-bundle-signer.mjs`.
+  const bundleSignerOf = (e, bundleSource, componentKey) => {
+    const subject = { biomeId: e.id, ...(componentKey === undefined ? {} : { componentKey }), origin: e.origin, repo: e.repo, bundleSource };
+    if (composed?.bundleSigners === undefined) {
+      throw new BundleSignerPolicyAbsentError(
+        `${componentKey === undefined ? `biome "${e.id}"` : `host module "${componentKey}" of biome "${e.id}"`} is an OCI bundle, but this resolve was given no bundle signer selection`,
+      );
+    }
+    return composed.bundleSigners.signerFor(subject);
+  };
+  const bundleSignerFor = (e) => (e.bundleSource?.kind === 'oci' ? { bundleSigner: bundleSignerOf(e, e.bundleSource) } : {});
+  const hostModulesOf = (e) =>
+    (Array.isArray(e.hostModules) ? e.hostModules : []).map((hostModule) =>
+      hostModule.bundleSource?.kind === 'oci' ? { ...hostModule, bundleSigner: bundleSignerOf(e, hostModule.bundleSource, hostModule.componentKey) } : hostModule,
+    );
+
   // (5d) Dispatched runtime components — every `runtime-image` edge of a
   // shipped biome must resolve to a runtime component of a biome in the index.
   // The target biome is not rostered (it enters no `biomes[]`, `requires` or
@@ -1950,7 +1981,7 @@ export function resolveDistributionFromInputs(
       // (the connector adapters loaded by `biome-adapter-host`). Projected
       // verbatim from the index, which resolved each component's bundle source
       // against the biome manifest.
-      hostModules: Array.isArray(e.hostModules) ? e.hostModules : [],
+      hostModules: hostModulesOf(e),
       // The BIOME-LEVEL bundle source, for a biome whose bundle no host module
       // above names — the field a `installPolicy: required` service-only
       // biome needs for the runtime's required-biome reconciler to fetch,
@@ -1964,6 +1995,7 @@ export function resolveDistributionFromInputs(
       // fact none of their entries carries. A lock in which SOME biome carries
       // it still is the one v5 grammar once sealed.
       ...(e.bundleSource === undefined ? {} : { bundleSource: e.bundleSource }),
+      ...bundleSignerFor(e),
       serviceDependencies: Array.isArray(e.serviceDependencies)
         ? e.serviceDependencies
         : [],
@@ -2125,7 +2157,11 @@ export function resolveDistributionFromInputs(
       // scopes on — and the lock records the full pinned `LockedBiomeSource`,
       // so a reader of the artifact never has to resolve a handle against a
       // manifest it does not have.
-      ...(e.source === undefined
+      //
+      // A third-party OCI biome is stamped too (the edition fence keys on the stamp) but is NOT in `sourceRecords`:
+      // the lock's `LockedBiomeSource` is git-only, so such a row carries no `source` and is held to its pin instead
+      // (`third-party-subjects.mjs`).
+      ...(e.source === undefined || isThirdPartyOciSourceEntry(e, sourceRecords)
         ? {}
         : { source: requireSourceRecord(e, sourceRecords) }),
     }))
@@ -2353,7 +2389,12 @@ export async function resolveDistributionWithIndex(id, { materialize, inputs, re
     id,
     index,
     schemas,
-    { ...composed, sourceRecords, storePublisherTrust },
+    {
+      ...composed,
+      sourceRecords,
+      storePublisherTrust,
+      bundleSigners: inputs?.bundleSigners ?? loadBundleSignerSelection({ dataRoot: dataRoot(), schemas }),
+    },
     new Date().toISOString(),
     platformServiceIndex,
   );

package/edition/resolve-edition.mjs

@@ -7,7 +7,7 @@
 //   node resolve-edition.mjs <root flags> <edition-id> --trusted-write-v3
 //       write the whole lock set into the editions root. The flag is the
 //       operator's explicit acknowledgement that the images lock is rewritten
-//       UNSEALED (a resolve never produces an `imageDigest`; `xema edition seal`
+//       UNSEALED (a resolve never produces an `imageDigest`; `xema edition resolve-digests`
 //       writes them afterwards). Without it nothing is written.
 //   node resolve-edition.mjs <root flags> <edition-id> --check
 //       resolve the whole lock set into a scratch copy of the editions root and

package/edition/resolve-images.mjs

@@ -72,6 +72,14 @@ import {
 } from './lib.mjs';
 import { assertReleaseContent } from './release-channel-guard.mjs';
 import { composeEdition } from './resolve-distribution.mjs';
+import { loadThirdPartySourcePins } from './third-party-source-pins.mjs';
+import {
+  assertOciBundleSourceOrigin,
+  attestedContentHash,
+  isThirdPartyOciRow,
+  thirdPartyPinForRow,
+  thirdPartySubjectCandidates,
+} from './third-party-subjects.mjs';
 
 if (isEntryModule(import.meta.url)) {
   configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel, WorkspaceRoot.Cache]);
@@ -418,7 +426,7 @@ export function resolveImageStructure(
   enums,
   requiredPlatforms,
   declaredSources,
-  { biomeIndex, supplementalSources } = {},
+  { biomeIndex, supplementalSources, thirdPartyPins } = {},
 ) {
   if (!Array.isArray(requiredPlatforms) || requiredPlatforms.length === 0) {
     throw new Error(
@@ -440,6 +448,9 @@ export function resolveImageStructure(
     );
   }
   const subjects = new Map();
+  // Third-party OCI subjects come from their pin and are never built, hashed or read from a checkout, so they are kept
+  // apart from every git-backed subject (see `third-party-subjects.mjs`).
+  const thirdPartySubjects = new Map();
   const webBiomes = [];
   const platformServiceBindings = [];
   const repositoryPins = new Map(
@@ -479,6 +490,15 @@ export function resolveImageStructure(
   };
 
   for (const biome of lock.biomes) {
+    const biomeLabel = `distribution "${lock.distributionId}" biome "${biome.id}"`;
+    assertOciBundleSourceOrigin(biome, biomeLabel);
+    if (isThirdPartyOciRow(biome)) {
+      const pin = thirdPartyPinForRow({ row: biome, pins: thirdPartyPins, declaredSources, label: biomeLabel });
+      for (const candidate of thirdPartySubjectCandidates({ row: biome, pin, enums, requiredPlatforms, label: biomeLabel })) {
+        addSubject(thirdPartySubjects, candidate);
+      }
+      continue;
+    }
     // WHERE THIS BIOME'S IMAGES LIVE, and WHICH COMMIT THEY ARE BUILT FROM.
     // Both answers move together when a biome is drawn from an external source,
     // because both are facts about that source rather than about this fleet.
@@ -662,7 +682,7 @@ export function resolveImageStructure(
   // distribution resolve if it dispatches, and the first-party index carries
   // none, so it is not looked up here.
   const dispatchers = lock.biomes
-    .filter((biome) => biome.source === undefined && biome.target === 'server')
+    .filter((biome) => biome.source === undefined && !isThirdPartyOciRow(biome) && biome.target === 'server')
     .map((biome) => {
       const entries = biomeIndex.filter(
         (entry) =>
@@ -892,13 +912,29 @@ export function resolveImageStructure(
   platformServiceBindings.sort((left, right) =>
     compareStrings(left.platformService, right.platformService),
   );
+  const orderedThirdPartySubjects = [...thirdPartySubjects.values()]
+    .map((subject) => ({ ...subject, owners: subject.owners.sort(compareOwner) }))
+    .sort(compareSubject);
+  for (const subject of orderedThirdPartySubjects) {
+    if (subjects.has(subjectKey(subject))) {
+      throw new Error(
+        `third-party runtime image subject "${subject.kind}:${subject.id}" has the identity of another subject of distribution "${lock.distributionId}"`,
+      );
+    }
+  }
   return {
     subjects: orderedSubjects,
+    thirdPartySubjects: orderedThirdPartySubjects,
     webBiomes,
     platformServiceBindings,
   };
 }
 
+/** Every image subject of a structure, first-party and third-party, in the lock's order. */
+export function structureSubjects(structure) {
+  return [...structure.subjects, ...structure.thirdPartySubjects].sort(compareSubject);
+}
+
 /**
  * THE COMPOSED-PROCESS IMAGE OF ONE BUILD — where a producing repository
  * declares it, and how an edition addresses it.
@@ -1775,7 +1811,11 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed } = {
       schemas,
       requiredPlatforms,
       declaredSources,
-      { biomeIndex, supplementalSources: supplementalSourcesFor(runtimeSourceIndex) },
+      {
+        biomeIndex,
+        supplementalSources: supplementalSourcesFor(runtimeSourceIndex),
+        thirdPartyPins: loadThirdPartySourcePins(dataRoot()),
+      },
     ),
     schemas,
     requiredPlatforms,
@@ -1909,8 +1949,11 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed } = {
       'refusing image-lock write: a source repository commit changed while hashing',
     );
   }
+  // After the ledger check and the hashing: a third-party subject has no ledger row and no checkout, and its
+  // `contentHash` is the publisher's statement, so none of the above read it.
   return {
-    subjects,
+    subjects: structure.thirdPartySubjects.length === 0 ? subjects : [...subjects, ...structure.thirdPartySubjects].sort(compareSubject),
+    thirdPartySubjects: structure.thirdPartySubjects,
     platformServiceBindings: structure.platformServiceBindings,
     webBiomes,
     contractAuthority: runtimeSourceIndex.contractAuthority,
@@ -1920,7 +1963,7 @@ export async function resolveImageRows(id, { inputs, lock, onSubjectHashed } = {
 
 /** One edition's COMPLETE image lock: its rows, parsed and validated as the kernel's image lock. */
 export async function resolveImages(id, { inputs, lock, onSubjectHashed } = {}) {
-  const { subjects, platformServiceBindings, webBiomes, contractAuthority, commits } = await resolveImageRows(id, { inputs, lock, onSubjectHashed });
+  const { subjects, thirdPartySubjects, platformServiceBindings, webBiomes, contractAuthority, commits } = await resolveImageRows(id, { inputs, lock, onSubjectHashed });
   const schemas = await loadKernelDistributionSchemas();
   const imageLock = validateImmutableImageLock(
     schemas.parseImageLock({
@@ -1934,7 +1977,7 @@ export async function resolveImages(id, { inputs, lock, onSubjectHashed } = {})
     }),
     schemas,
   );
-  return { imageLock, commits };
+  return { imageLock, commits, thirdPartySubjects };
 }
 
 /**
@@ -1954,7 +1997,7 @@ export async function writeResolvedImages(
   }
   // The RELEASE lock is published-only: a develop edition resolves through
   // `develop-edition.mjs` and never reaches this writer.
-  const { imageLock, commits } = await resolveImages(id);
+  const { imageLock, commits, thirdPartySubjects } = await resolveImages(id);
   const outPath = distributionOutputPath(
     editionsRoot(),
     id,
@@ -1969,6 +2012,9 @@ export async function writeResolvedImages(
     for (const [repo, commit] of commits) {
       console.log(`  source ${repo}@${commit}`);
     }
+    for (const subject of thirdPartySubjects) {
+      console.log(`  third-party ${subject.kind}:${subject.id} ${subject.imageRef} ${attestedContentHash(subject)}`);
+    }
   }
   return { imageLock, commits };
 }

package/edition/seal-image-digests.mjs

@@ -121,7 +121,7 @@ import { parseCustomerDefinition } from './customer-definition.mjs';
 import { CATALOGUE_TOKEN_ENV_FLAG, CATALOGUE_USERNAME_FLAG, DEFINITION_FLAG } from './customer-flags.mjs';
 import { EditionChannel } from './edition-constants.mjs';
 import { editionPinnedInputs } from './edition-pinned-inputs.mjs';
-import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, editionsRoot, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
+import { WorkspaceRoot, biomeIndexPath, configureEditionWorkspaceFromProcess, dataRoot, editionsRoot, isEntryModule, runtimeImageSourceIndexPath } from './edition-workspace.mjs';
 import {
   assertCoordinatesFinal,
   collectFleetPlatformRequirements,
@@ -137,6 +137,8 @@ import { externalSourceTrees, sourceTreeLocator } from './resolve-images.mjs';
 import { readSealedDistributionLock } from './sealed-distribution-lock.mjs';
 import { committedRepositoryPins, createPinnedSourceAuthority } from './source-authority.mjs';
 import { readStrictJsonFile } from './strict-json.mjs';
+import { pinnedManifestDigests, thirdPartyImagePins } from './third-party-image-pins.mjs';
+import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs';
 import {
   loadImageLockForVerification,
   verifyDistributionPlatforms,
@@ -569,14 +571,14 @@ export async function sealEditionLocks({ distributionId, root, digests = new Map
  * The decision, with no files: an UNSEALED lock is sealed (refused under `check`); a SEALED lock is VERIFIED -
  * every hash recomputed, a mismatch refused naming the biome.
  */
-export async function sealOrVerifyLock({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, check = false, lockPath = 'distribution.lock.json' }) {
+export async function sealOrVerifyLock({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, bundleSigners, check = false, lockPath = 'distribution.lock.json' }) {
   if ('unsealedSchema' in lock) {
     if (check) {
-      throw new Error(`${lockPath} is unsealed (no biomeContentHash); run \`xema edition seal ${lock.distributionId}\``);
+      throw new Error(`${lockPath} is unsealed (no biomeContentHash); run \`xema edition resolve-digests ${lock.distributionId}\``);
     }
-    return { sealed: true, lock: await sealLock({ schemas, unsealed: lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys }) };
+    return { sealed: true, lock: await sealLock({ schemas, unsealed: lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, bundleSigners }) };
   }
-  await verifyBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys });
+  await verifyBiomeContentHashes({ schemas, lock, imageLock, locate, vendoredCommit, catalogue, catalogueDigest, storePublisherAnchorKeys, bundleSigners });
   return { sealed: false, lock };
 }
 
@@ -586,7 +588,7 @@ async function main() {
     parseSealArgs(args);
   if (!distributionId || rest.length > 0) {
     throw new Error(
-      'usage: xema edition seal <distributionId> ' +
+      'usage: xema edition resolve-digests <distributionId> ' +
         `[--check | --if-published | --publication-verdict] ` +
         `[--definition <file> [--catalogue-username <name> --catalogue-token-env <VAR>]]`,
     );
@@ -700,12 +702,16 @@ async function main() {
       ? undefined
       : parseCustomerDefinition(await adoptCatalogueKernel(catalogue), readStrictJsonFile(catalogueFlags.get(DEFINITION_FLAG))).definition.storePublisherAnchorKeys;
   const imageLock = await loadImageLockForVerification(distributionId, root);
+  // A pinned third-party subject (its repository is in the data root's third-party source pins) is verified and sealed
+  // BY the pin's manifest digest: its contentHash is publisher-attested and is not a tag.
+  const thirdPartyPins = loadTrustedThirdPartySourcePins(dataRoot());
+  const pinnedImages = thirdPartyImagePins({ pins: thirdPartyPins, subjects: imageLock.subjects });
 
   // Throws on ANY unresolvable subject or missing required platform, before a
   // single byte of the lock is touched.
   let report;
   try {
-    report = await verifyDistributionPlatforms({ imageLock, distributionsRoot: root });
+    report = await verifyDistributionPlatforms({ imageLock, distributionsRoot: root, pinnedDigests: pinnedManifestDigests(pinnedImages) });
   } catch (error) {
     // RECONCILE: a coordinate this pass just re-pinned has not been built yet.
     // Skip the EDITION — never some of its subjects — and leave the lock
@@ -839,14 +845,19 @@ async function main() {
   // introduced and the repository holding every edition's lock is where the
   // question is answerable at all.
   const { editions, withoutLock } = readFleetImageLocks(root);
-  const fleetRequirements = collectFleetPlatformRequirements({ editions });
+  const fleetRequirements = collectFleetPlatformRequirements({ editions, isThirdPartySubject: (subject) => thirdPartyPins.byRepository(subject.repo) !== undefined });
   try {
     const finality = assertCoordinatesFinal({
       distributionId,
       writes,
       verified: report.subjects,
       fleetRequirements,
+      thirdPartyKeys: new Set(pinnedImages.keys()),
     });
+    // Third-party subjects are NOT graded by the first-party fleet verdict, and are named here rather than skipped silently.
+    for (const key of finality.thirdParty) {
+      console.log(`[${label}] finality: ${key} third-party (pinned by digest), not a first-party fleet coordinate.`);
+    }
     // The CORPUS, not a confirmation: how many coordinates were graded against
     // how many editions, and which editions made no claim. Without the
     // denominators a pass cannot be told from a pass over nothing, and the

package/edition/sealed-distribution-lock.mjs

@@ -1,5 +1,5 @@
 // sealed-distribution-lock — the one predicate for "this committed distribution.lock.json is the SEALED grammar".
-// `xema edition artifact` and the `xema edition seal --publication-verdict` gate both ask it, so the verdict can
+// `xema edition artifact` and the `xema edition resolve-digests --publication-verdict` gate both ask it, so the verdict can
 // never say PUBLISHABLE for a lock the artifact verb then refuses.
 
 import { readFileSync } from 'node:fs';
@@ -15,7 +15,7 @@ export function readSealedDistributionLock({ schemas, lockPath, distributionId }
   } catch (error) {
     throw new Error(
       `${lockPath} is not a sealed distribution lock, so nothing is published from it. ` +
-        `Run \`xema edition seal ${distributionId}\` first. (${error.message})`,
+        `Run \`xema edition resolve-digests ${distributionId}\` first. (${error.message})`,
       { cause: error },
     );
   }

package/edition/third-party-admission.mjs

@@ -0,0 +1,91 @@
+// Admission of third-party image subjects (XEMA-1611 design section 4), beside `externalSourceRepositoryPins` and
+// `verifyDistributionImageEvidenceSet` of `image-evidence.mjs`. Pure over data: the pins come from the data root's
+// `third-party-source-pins.json` (held to the evidence trust pin by the entry), the statement and bundle from a
+// descriptor `verifySigstoreEvidenceDescriptor` has just verified.
+
+import { assertCertificateExtensions } from './third-party-certificate-extensions.mjs';
+
+/** The declared source kind that names a third-party pin. */
+const OCI_SOURCE_KIND = 'oci';
+const FIRST_PARTY_LAYOUT_PREFIX = /^(?:repos|submodules)\//u;
+
+const repositoryPathOf = (repositoryUrl) => new URL(repositoryUrl).pathname.replace(/^\//u, '').replace(/\.git$/u, '');
+
+/**
+ * The repository pins of the edition's declared OCI sources, derived from their third-party source pins:
+ * `repo` (the pinned `owner/name`), `repositoryUrl` and `sourceCommit`. Every declared OCI source must be pinned (a
+ * missing or empty pin file refuses, with the loader's reason), and the pin must not collide with an index pin or a git
+ * source, nor sit under the first-party layout (`repos/`, `submodules/`). A declared source that ships no image yields no
+ * pin; every subject of a source must agree on the pinned commit.
+ *
+ * @returns {Map<string, {repo: string, repositoryUrl: string, sourceCommit: string}>}
+ */
+export function thirdPartySourceRepositoryPins({ distribution, imageLock, repositoryPins, thirdPartyPins }) {
+  const sources = distribution.sources ?? [];
+  const derived = new Map();
+  for (const source of sources) {
+    if (source.kind !== OCI_SOURCE_KIND) {continue;}
+    const pin = thirdPartyPins.byName(source.name);
+    if (pin === undefined) {
+      throw new Error(
+        `edition source "${source.name}" is kind "${OCI_SOURCE_KIND}", but ${thirdPartyPins.reason ?? `the data root's third-party source pins hold no pin named "${source.name}"`}`,
+      );
+    }
+    if (FIRST_PARTY_LAYOUT_PREFIX.test(pin.repository)) {
+      throw new Error(`third-party source "${pin.name}" pins repository "${pin.repository}", which is under the first-party layout (repos/ or submodules/)`);
+    }
+    if (repositoryPins.has(pin.repository)) {
+      throw new Error(`third-party source "${pin.name}" repository "${pin.repository}" shadows a repository pin the runtime image source index already commits`);
+    }
+    const shadowed = sources.find((candidate) => candidate.kind === 'git' && (candidate.name === pin.repository || candidate.name === pin.name));
+    if (shadowed !== undefined) {
+      throw new Error(`third-party source "${pin.name}" (${pin.repository}) collides with the git source "${shadowed.name}" of the same edition`);
+    }
+    const subjects = imageLock.subjects.filter((subject) => subject.repo === pin.repository);
+    if (subjects.length === 0) {continue;}
+    const wrong = subjects.filter((subject) => subject.sourceCommit !== pin.sourceCommit);
+    if (wrong.length > 0) {
+      throw new Error(
+        `third-party source "${pin.name}" is pinned at ${pin.sourceCommit}, but images.lock.json builds ${wrong.map((subject) => `${subject.kind}:${subject.id}`).join(', ')} at ${[...new Set(wrong.map((subject) => subject.sourceCommit))].join(', ')}`,
+      );
+    }
+    derived.set(pin.repository, { repo: pin.repository, repositoryUrl: pin.repositoryUrl, sourceCommit: pin.sourceCommit });
+  }
+  return derived;
+}
+
+/** The pins behind `thirdPartySourceRepositoryPins`, by repository. */
+export const thirdPartySourcesByRepository = (derived, thirdPartyPins) =>
+  new Map([...derived.keys()].map((repo) => [repo, thirdPartyPins.byRepository(repo)]));
+
+/**
+ * What a third-party subject must satisfy beyond a first-party one, after its evidence has verified:
+ *  * [d9-1] the signing row's workflow repository, the subject's `repo` and the path of the predicate's
+ *    `source.repositoryUrl` are one repository;
+ *  * the subject is the pinned image (reference, content hash, sealed digest when sealed);
+ *  * (d) the leaf certificate states the pinned repository id, owner id and a GitHub-hosted runner.
+ */
+export function assertThirdPartySubjectAdmission({ subject, source, statement, identityPolicy, bundle }) {
+  const label = `third-party subject "${subject.kind}:${subject.id}" (source "${source.name}")`;
+  const claimedRepository = repositoryPathOf(statement.predicate.source.repositoryUrl);
+  const signerRepository = identityPolicy.githubWorkflow.repository;
+  if (signerRepository !== subject.repo || claimedRepository !== subject.repo) {
+    throw new Error(
+      `${label}: the signing row's workflow repository (${signerRepository}), the subject repo (${subject.repo}) and the predicate source.repositoryUrl repository (${claimedRepository}) must be one repository`,
+    );
+  }
+  const image = source.images.find((candidate) => candidate.subjectKind === subject.kind && candidate.subjectId === subject.id);
+  if (image === undefined) {
+    throw new Error(`${label}: the pin pins no image for it`);
+  }
+  if (subject.imageRef !== image.imageRef) {
+    throw new Error(`${label}: images.lock.json names ${subject.imageRef}, but the pin pins ${image.imageRef}`);
+  }
+  if (subject.contentHash !== image.sourceTreeHash) {
+    throw new Error(`${label}: images.lock.json has contentHash ${subject.contentHash}, but the pin records sourceTreeHash ${image.sourceTreeHash}`);
+  }
+  if (subject.imageDigest !== undefined && subject.imageDigest !== image.manifestDigest) {
+    throw new Error(`${label}: images.lock.json seals ${subject.imageDigest}, but the pin records manifestDigest ${image.manifestDigest}`);
+  }
+  assertCertificateExtensions({ bundle, source, label });
+}

package/edition/third-party-bundle-registry.mjs

@@ -0,0 +1,147 @@
+// The registry side of the third-party writer (XEMA-1611 design section 3 (a)): the biome bundle, by digest, and the
+// sigstore bundle of its SLSA provenance, read as an OCI referrer. Nothing here is trusted: every byte it returns is
+// verified by cosign (`third-party-source-evidence.mjs`) before it is committed.
+
+import { execFileSync } from 'node:child_process';
+
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
+import { COSIGN_ENV, decodeExactUtf8, sha256Digest, validatePinnedTrustedRoot } from './image-evidence.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+import { SLSA_PROVENANCE_V1, decodeJsonStatement, digestOfOciRef } from './third-party-source-evidence.mjs';
+import { assertPreparedExecutable } from './trusted-executable.mjs';
+
+const BIOME_MANIFEST_FILE = 'xema-biome.json';
+const BIOME_GENERATED_INDEX_FILE = 'xema-biome.index.json';
+const OCI_TITLE_ANNOTATION = 'org.opencontainers.image.title';
+const MAX_BIOME_MANIFEST_BYTES = 4 * 1024 * 1024;
+const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
+const REGISTRY_COSIGN_TIMEOUT_MS = 120_000;
+/** What `cosign verify-attestation --type` calls the SLSA v1 provenance predicate. */
+const COSIGN_SLSA_PROVENANCE_ALIAS = 'slsaprovenance1';
+
+const repositoryOf = (ociRef) => splitImageRef(ociRef.slice(0, ociRef.indexOf('@')));
+
+/**
+ * The biome bundle manifest JSON (`xema-biome.json`) of an OCI artifact, fetched by digest.
+ *
+ * @returns {Promise<{manifest: object, bytes: Buffer}>}
+ */
+export async function fetchBundleManifest({ clientFor, ociRef }) {
+  const bytes = await fetchTitledLayer({ clientFor, ociRef, title: BIOME_MANIFEST_FILE });
+  return { manifest: decodeJsonStatement(bytes, `${ociRef} ${BIOME_MANIFEST_FILE}`), bytes };
+}
+
+/**
+ * The committed generated index (`xema-biome.index.json`) of an OCI biome bundle, fetched by digest: the authority for
+ * the biomes the bundle requires, read from the same bundle bytes as its manifest, so it cannot describe another revision.
+ */
+export async function fetchBundleGeneratedIndex({ clientFor, ociRef }) {
+  const bytes = await fetchTitledLayer({ clientFor, ociRef, title: BIOME_GENERATED_INDEX_FILE });
+  return decodeJsonStatement(bytes, `${ociRef} ${BIOME_GENERATED_INDEX_FILE}`);
+}
+
+/** The one layer of the bundle manifest at `ociRef` (by digest) annotated with `title`. */
+async function fetchTitledLayer({ clientFor, ociRef, title }) {
+  const { authority, repository } = repositoryOf(ociRef);
+  const client = clientFor(authority);
+  const { document } = await client.getManifestByDigest(repository, digestOfOciRef(ociRef));
+  const layers = (document.layers ?? []).filter((layer) => layer.annotations?.[OCI_TITLE_ANNOTATION] === title);
+  if (layers.length !== 1) {
+    throw new Error(`${ociRef} has ${layers.length} layers titled ${title}; a biome bundle has exactly one`);
+  }
+  const bytes = await client.getBlob(repository, layers[0].digest, MAX_BIOME_MANIFEST_BYTES);
+  if (sha256Digest(bytes) !== layers[0].digest) {
+    throw new Error(`${ociRef} layer titled ${title} does not match its descriptor`);
+  }
+  return bytes;
+}
+
+/**
+ * The image names a biome manifest ships: its service and worker components with an `oci-image` artifact, named the way
+ * the index builder names them (a service by `protocol.serviceName`, a worker by its component `key`).
+ */
+export function bundleImageNames(manifest) {
+  const components = Array.isArray(manifest?.xema?.components) ? manifest.xema.components : [];
+  return new Set(
+    components
+      .filter((component) => (component?.kind === 'service' || component?.kind === 'worker') && component.artifact?.kind === 'oci-image')
+      .map((component) => (component.kind === 'service' ? component.protocol?.serviceName : component.key)),
+  );
+}
+
+function provenanceOf(bundleBytes, bundleDigest) {
+  const bundle = JSON.parse(decodeExactUtf8(bundleBytes, 'sigstore bundle'));
+  if (bundle?.dsseEnvelope === undefined) {
+    return null; // a message-signature bundle (the artifact signature): not an attestation
+  }
+  const payload = Buffer.from(bundle.dsseEnvelope.payload, 'base64');
+  const statement = decodeJsonStatement(payload, 'DSSE payload');
+  if (statement.predicateType !== SLSA_PROVENANCE_V1) {
+    return null;
+  }
+  if (`sha256:${statement.subject?.[0]?.digest?.sha256}` !== bundleDigest) {
+    throw new Error(`a SLSA provenance referrer attests ${statement.subject?.[0]?.digest?.sha256}, not ${bundleDigest}`);
+  }
+  return { statementBytes: payload, bundleBytes };
+}
+
+/**
+ * The SLSA provenance attestation of the bundle: the one sigstore-bundle referrer of `ociRef` whose DSSE statement is a
+ * `https://slsa.dev/provenance/v1` attestation over exactly this digest. None, or more than one, is refused.
+ *
+ * @returns {Promise<{statementBytes: Buffer, bundleBytes: Buffer}>}
+ */
+export async function fetchBundleProvenance({ clientFor, ociRef }) {
+  const { authority, repository } = repositoryOf(ociRef);
+  const client = clientFor(authority);
+  const subjectDigest = digestOfOciRef(ociRef);
+  const referrers = await client.listReferrers(repository, subjectDigest, BUNDLE_MEDIA_TYPE);
+  const found = [];
+  for (const referrer of referrers) {
+    const { document } = await client.getManifestByDigest(repository, referrer.digest);
+    for (const layer of document.layers ?? []) {
+      if (layer.mediaType !== BUNDLE_MEDIA_TYPE) {continue;}
+      const bytes = await client.getBlob(repository, layer.digest, MAX_BUNDLE_BYTES);
+      if (sha256Digest(bytes) !== layer.digest) {
+        throw new Error(`${ociRef} referrer ${referrer.digest} layer does not match its descriptor`);
+      }
+      const provenance = provenanceOf(bytes, subjectDigest);
+      if (provenance !== null) {found.push(provenance);}
+    }
+  }
+  if (found.length === 0) {
+    throw new Error(`${ociRef} has no SLSA provenance attestation (${SLSA_PROVENANCE_V1}) among its ${referrers.length} sigstore-bundle referrers; the bundle must be published with provenance`);
+  }
+  if (found.length > 1) {
+    throw new Error(`${ociRef} has ${found.length} SLSA provenance attestations; exactly one is required, so the evidence is unambiguous`);
+  }
+  return found[0];
+}
+
+const tail = (error) => String(error?.stderr ?? error?.message ?? error).trim().split('\n').slice(-4).join(' | ').slice(0, 1024);
+
+/**
+ * (a) against the registry: keyless `cosign verify` and `cosign verify-attestation --type slsaprovenance1` of the bundle
+ * artifact under EXACTLY the signer row's identity and issuer, the row's workflow repository, ref and the stated
+ * commit, the pinned trusted root and the trusted cosign binary. `--offline` verifies the tlog inclusion proof carried
+ * with the signature; the tlog is never ignored. The registry credential is the operator's (HOME / DOCKER_CONFIG).
+ */
+export function verifyBundleOnRegistry({ trustedCosign, policy, policyRoot, row, workflowSha, ociRef, env = process.env }) {
+  const root = validatePinnedTrustedRoot(policyRoot, policy);
+  const common = ['--offline', '--trusted-root', root.path, ...certificateConstraintArgs(row, workflowSha)];
+  const environment = {
+    ...COSIGN_ENV,
+    ...(env.HOME === undefined ? {} : { HOME: env.HOME }),
+    ...(env.DOCKER_CONFIG === undefined ? {} : { DOCKER_CONFIG: env.DOCKER_CONFIG }),
+  };
+  const run = (command, args) => {
+    try {
+      execFileSync(assertPreparedExecutable(trustedCosign, 'cosign'), [command, ...args], { env: environment, stdio: ['ignore', 'ignore', 'pipe'], timeout: REGISTRY_COSIGN_TIMEOUT_MS });
+    } catch (error) {
+      throw new Error(`cosign ${command} refused ${ociRef} under row "${row.policyId}": ${tail(error)}`);
+    }
+  };
+  run('verify', [...common, ociRef]);
+  run('verify-attestation', ['--type', COSIGN_SLSA_PROVENANCE_ALIAS, ...common, ociRef]);
+}

package/edition/third-party-certificate-extensions.mjs

@@ -0,0 +1,21 @@
+// (d) of the third-party checks: the Fulcio extensions of a bundle's leaf certificate, held to a source pin. Its own module
+// (it imports no evidence module) because admission in `image-evidence.mjs` and the pin verifier both use it.
+
+import { FulcioExtensionOid, GITHUB_HOSTED_RUNNER_ENVIRONMENT, readFulcioExtensionsFromBundle } from './fulcio-certificate-extensions.mjs';
+
+/** The leaf certificate of a parsed Sigstore `bundle` states the pinned repository id, owner id and a GitHub-hosted runner. */
+export function assertCertificateExtensions({ bundle, source, label }) {
+  const read = readFulcioExtensionsFromBundle(bundle);
+  const expectations = [
+    [FulcioExtensionOid.SourceRepositoryIdentifier, 'Source Repository Identifier', read.sourceRepositoryIdentifier, source.repositoryId, 'repositoryId'],
+    [FulcioExtensionOid.SourceRepositoryOwnerIdentifier, 'Source Repository Owner Identifier', read.sourceRepositoryOwnerIdentifier, source.repositoryOwnerId, 'repositoryOwnerId'],
+    [FulcioExtensionOid.RunnerEnvironment, 'Runner Environment', read.runnerEnvironment, GITHUB_HOSTED_RUNNER_ENVIRONMENT, GITHUB_HOSTED_RUNNER_ENVIRONMENT],
+  ];
+  for (const [oid, name, actual, expected, pinned] of expectations) {
+    if (actual !== expected) {
+      throw new Error(
+        `${label} certificate ${name} (${oid}) is ${JSON.stringify(actual)}, but the pin requires ${JSON.stringify(expected)} (${pinned})`,
+      );
+    }
+  }
+}