@xemahq/xema 0.47.1 → 0.49.0

package/edition/evidence-trust-pin.mjs

@@ -30,6 +30,8 @@ import {
 } from './image-evidence.mjs';
 import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 import { parseStrictJson } from './strict-json.mjs';
+import { THIRD_PARTY_SOURCE_PINS_FILE, thirdPartySourcePinsDigest } from './third-party-source-pins.mjs';
+import { assertTrustPolicyImageOwnership, firstPartyOwnersFromIndex } from './trust-policy-image-ownership.mjs';
 
 export const EVIDENCE_TRUST_PIN_SCHEMA_VERSION = 2;
 export const RUNTIME_IMAGE_SOURCE_INDEX_FILE = 'runtime-image-source-index.json';
@@ -59,11 +61,17 @@ const PIN_KEYS = Object.freeze([
   'trustedOrasBinaryDigests',
   'verifier',
 ]);
+/**
+ * Present iff the data root holds `third-party-source-pins.json`. Optional so a pin written before third-party
+ * sources existed, for a data root without that file, keeps loading unchanged (the schemaVersion stays 2).
+ */
+const THIRD_PARTY_SOURCE_PINS_DIGEST_KEY = 'thirdPartySourcePinsDigest';
 const VERIFIER_KEYS = Object.freeze(['bundleDigest', 'provenanceDigest']);
 const AUTHORITY_PIN_KEYS = Object.freeze(['digest', 'sourceCommit']);
 const PIN_SHAPE =
   '{schemaVersion, policyDigest, verifier: {bundleDigest, provenanceDigest}, ' +
-  'kernelContractAuthority: {sourceCommit, digest} | null, trustedOrasBinaryDigests: [sha256:…, …]}';
+  'kernelContractAuthority: {sourceCommit, digest} | null, trustedOrasBinaryDigests: [sha256:…, …], ' +
+  `[${THIRD_PARTY_SOURCE_PINS_DIGEST_KEY}: sha256:… (only when the data root holds ${THIRD_PARTY_SOURCE_PINS_FILE})]}`;
 
 const exactKeys = (value, keys) =>
   value !== null &&
@@ -103,6 +111,10 @@ export function loadDeclaredTrustPolicy({ dataRoot, declaration, schemas }) {
     ),
   );
   validatePinnedTrustedRoot(dataRoot, policy);
+  assertTrustPolicyImageOwnership({
+    policy,
+    firstPartyOwners: hasRuntimeImageSourceIndex(dataRoot) ? firstPartyOwnersFromIndex(readRuntimeImageSourceIndexDocument(dataRoot)) : null,
+  });
   return Object.freeze({ policy, policyDigest: trustPolicyDigest(policy) });
 }
 
@@ -116,8 +128,9 @@ export function readEvidenceTrustPin({ dataRoot, declaration }) {
     MAX_PIN_BYTES,
   );
   const pin = parseStrictJson(bytes.toString('utf8'), declaration.pin);
+  const hasSourcePinsDigest = pin !== null && typeof pin === 'object' && THIRD_PARTY_SOURCE_PINS_DIGEST_KEY in pin;
   if (
-    !exactKeys(pin, PIN_KEYS) ||
+    !exactKeys(pin, hasSourcePinsDigest ? [...PIN_KEYS, THIRD_PARTY_SOURCE_PINS_DIGEST_KEY].sort() : PIN_KEYS) ||
     !exactKeys(pin.verifier, VERIFIER_KEYS) ||
     !(pin.kernelContractAuthority === null || exactKeys(pin.kernelContractAuthority, AUTHORITY_PIN_KEYS)) ||
     !Array.isArray(pin.trustedOrasBinaryDigests)
@@ -147,9 +160,41 @@ export function readEvidenceTrustPin({ dataRoot, declaration }) {
             digest: requireDigest(pin.kernelContractAuthority.digest, 'kernelContractAuthority.digest'),
           }),
     trustedOrasBinaryDigests: requireOrasDigests(pin.trustedOrasBinaryDigests),
+    thirdPartySourcePinsDigest: hasSourcePinsDigest
+      ? requireDigest(pin[THIRD_PARTY_SOURCE_PINS_DIGEST_KEY], THIRD_PARTY_SOURCE_PINS_DIGEST_KEY)
+      : null,
   });
 }
 
+/**
+ * Hold the data root's `third-party-source-pins.json` to the pin: when the file exists the pin must record its sha256
+ * (and it must be the file's); when the file does not exist the pin must record none.
+ */
+export function assertPinnedThirdPartySourcePins({ pin, dataRoot }) {
+  const actual = thirdPartySourcePinsDigest(dataRoot);
+  if (actual === null) {
+    if (pin.thirdPartySourcePinsDigest !== null) {
+      throw new Error(
+        `the pin records ${THIRD_PARTY_SOURCE_PINS_FILE} at ${pin.thirdPartySourcePinsDigest} but the data root holds no such file; ` +
+          `review the removal, then re-pin with \`${REPIN_COMMAND}\``,
+      );
+    }
+    return;
+  }
+  if (pin.thirdPartySourcePinsDigest === null) {
+    throw new Error(
+      `the data root holds ${THIRD_PARTY_SOURCE_PINS_FILE} (${actual}) but the pin records none; ` +
+        `review the third-party source pins, then re-pin with \`${REPIN_COMMAND}\``,
+    );
+  }
+  if (pin.thirdPartySourcePinsDigest !== actual) {
+    throw new Error(
+      `${THIRD_PARTY_SOURCE_PINS_FILE} hashes to ${actual} but the pin records ${pin.thirdPartySourcePinsDigest}; ` +
+        `review the third-party source pin change, then re-pin with \`${REPIN_COMMAND}\``,
+    );
+  }
+}
+
 function requireCommit(value) {
   if (typeof value !== 'string' || !COMMIT_PATTERN.test(value)) {
     throw new Error('evidence trust pin: kernelContractAuthority.sourceCommit must be an exact 40-hex commit');
@@ -188,18 +233,23 @@ export function hasRuntimeImageSourceIndex(dataRoot) {
   return existsSync(join(dataRoot, RUNTIME_IMAGE_SOURCE_INDEX_FILE));
 }
 
-/** The kernel contract authority the data root's runtime image source index STATES; nothing is trusted yet. */
-export function readStatedKernelContractAuthority({ dataRoot, schemas }) {
-  if (!schemas?.parseRuntimeImageSourceIndex) {
-    throw new Error('trusted kernel distribution schemas are required');
-  }
+/** The data root's runtime image source index as parsed JSON (not schema-validated here). */
+function readRuntimeImageSourceIndexDocument(dataRoot) {
   const { bytes } = readBoundedNoFollowFile(
     dataRoot,
     RUNTIME_IMAGE_SOURCE_INDEX_FILE,
     'runtime image source index',
     MAX_INDEX_BYTES,
   );
-  return schemas.parseRuntimeImageSourceIndex(JSON.parse(bytes.toString('utf8'))).contractAuthority;
+  return JSON.parse(bytes.toString('utf8'));
+}
+
+/** The kernel contract authority the data root's runtime image source index STATES; nothing is trusted yet. */
+export function readStatedKernelContractAuthority({ dataRoot, schemas }) {
+  if (!schemas?.parseRuntimeImageSourceIndex) {
+    throw new Error('trusted kernel distribution schemas are required');
+  }
+  return schemas.parseRuntimeImageSourceIndex(readRuntimeImageSourceIndexDocument(dataRoot)).contractAuthority;
 }
 
 /** Refuse an authority that is not the one the pin records. */
@@ -270,7 +320,9 @@ export function loadPinnedDeclaredTrustPolicy({ dataRoot, declaration, schemas }
     );
   }
   const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot, declaration, schemas });
-  assertPinnedPolicy({ pin: readEvidenceTrustPin({ dataRoot, declaration }), policyDigest });
+  const pin = readEvidenceTrustPin({ dataRoot, declaration });
+  assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot });
   return policy;
 }
 
@@ -287,7 +339,7 @@ export function assertPinnedVerifier({ pin, actual }) {
   }
 }
 
-/** Write the pin for the declared policy, the verifier digests, the kernel contract authority and the oras digests. */
+/** Write the pin for the declared policy, the verifier digests, the kernel contract authority, the oras digests and (when the data root holds the file) the third-party source pins' digest. */
 export function writeEvidenceTrustPin({
   dataRoot,
   declaration,
@@ -295,6 +347,7 @@ export function writeEvidenceTrustPin({
   verifier,
   kernelContractAuthority,
   trustedOrasBinaryDigests,
+  thirdPartySourcePinsDigest: sourcePinsDigest = null,
 }) {
   const pin = {
     schemaVersion: EVIDENCE_TRUST_PIN_SCHEMA_VERSION,
@@ -305,6 +358,9 @@ export function writeEvidenceTrustPin({
     },
     kernelContractAuthority: kernelContractAuthority === null ? null : { ...kernelContractAuthorityPin(kernelContractAuthority) },
     trustedOrasBinaryDigests: [...requireOrasDigests(trustedOrasBinaryDigests)].sort(),
+    ...(sourcePinsDigest === null
+      ? {}
+      : { [THIRD_PARTY_SOURCE_PINS_DIGEST_KEY]: requireDigest(sourcePinsDigest, THIRD_PARTY_SOURCE_PINS_DIGEST_KEY) }),
   };
   const text = `${JSON.stringify(pin, null, 2)}\n`;
   const descriptor = openSync(

package/edition/evidence-trust-policy.mjs

@@ -5,11 +5,13 @@
 // pin}` in `edition-workspace.json`) or states that it declares none (`null`).
 // No switch admits an ungated release:
 //
-//   * a RELEASE edition is written only against a policy ARMED on the release
-//     channel. No policy, UNARMED or PARTIALLY ARMED there -> refused
-//     (EvidenceTrustRequiredError, code EVIDENCE_TRUST_REQUIRED_UNARMED);
-//   * a DEVELOP edition admits not-armed and says so in one line; a policy
-//     PARTIALLY ARMED on the develop channel is refused;
+//   * a SEALED edition (either channel) and a RESOLVED RELEASE edition are
+//     written only against a policy ARMED on the edition's channel. No policy,
+//     UNARMED or PARTIALLY ARMED there -> refused (EvidenceTrustRequiredError,
+//     code EVIDENCE_TRUST_REQUIRED_UNARMED); edition-contract.json
+//     evidenceTrust.statesByKind is the one statement of this rule;
+//   * a RESOLVED DEVELOP edition admits not-armed and says so in one line; a
+//     policy PARTIALLY ARMED on the develop channel is refused;
 //   * `xema edition check` FAILS when the editions tree holds a release
 //     edition (an edition directory holding a release lock) and the policy is
 //     not ARMED on the release channel (none declared, UNARMED or PARTIAL):
@@ -29,10 +31,11 @@ import { join } from 'node:path';
 
 import { locateBuiltVerifier, readBuiltVerifierDigests } from './built-verifier.mjs';
 import { EDITION_WORKSPACE_CONFIG_FILE, editionWorkspaceConfig } from './edition-config.mjs';
-import { EDITION_CONTRACT, EditionChannel, EvidenceTrustState } from './edition-constants.mjs';
+import { EDITION_CONTRACT, EditionChannel, EditionKind, EvidenceTrustState, admittedEvidenceTrustStates } from './edition-constants.mjs';
 import { dataRoot as configuredDataRoot, editionsRoot as configuredEditionsRoot } from './edition-workspace.mjs';
 import {
   assertPinnedPolicy,
+  assertPinnedThirdPartySourcePins,
   assertPinnedVerifier,
   loadDeclaredTrustPolicy,
   readEvidenceTrustPin,
@@ -109,11 +112,14 @@ function notArmedOnReleaseVerdict(what, repair) {
  * refused with this error; a release edition never records `not-armed`.
  */
 export class EvidenceTrustRequiredError extends Error {
-  /** @param {string} dataRoot @param {string} reason what is not armed, in words */
-  constructor(dataRoot, reason) {
+  /**
+   * @param {string} dataRoot @param {string} reason what is not armed, in words
+   * @param {{ edition: string, channel: string }} subject the edition that requires it (e.g. "release edition", "sealed release edition") and its channel
+   */
+  constructor(dataRoot, reason, { edition, channel }) {
     super(
-      `a release edition requires an armed evidence trust policy, but ${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} ${reason}: ` +
-        'declare a policy ({"policy": ..., "pin": ...}) and arm it on the release channel (`xema edition check` says what is unmet).',
+      `a ${edition} requires an armed evidence trust policy, but ${join(dataRoot, EDITION_WORKSPACE_CONFIG_FILE)} ${reason}: ` +
+        `declare a policy ({"policy": ..., "pin": ...}) and arm it on the ${channel} channel (\`xema edition check\` says what is unmet).`,
     );
     this.name = 'EvidenceTrustRequiredError';
     this.code = EVIDENCE_TRUST_REQUIRED_UNARMED;
@@ -129,6 +135,7 @@ function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
   const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot, declaration, schemas });
   const pin = readEvidenceTrustPin({ dataRoot, declaration });
   assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot });
   assertPinnedVerifier({ pin, actual: readBuiltVerifierDigests(locateVerifier) });
   return { policy, policyDigest };
 }
@@ -151,7 +158,9 @@ export async function loadDeclaredPinnedPolicy() {
   }
   const schemas = await loadKernelDistributionSchemas();
   const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot: root, declaration, schemas });
-  assertPinnedPolicy({ pin: readEvidenceTrustPin({ dataRoot: root, declaration }), policyDigest });
+  const pin = readEvidenceTrustPin({ dataRoot: root, declaration });
+  assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot: root });
   return { policy, dataRoot: root };
 }
 
@@ -198,21 +207,22 @@ export class CatalogueEvidenceUnverifiableError extends Error {
 }
 
 /**
- * The evidence state an edition of `channel` records in its descriptor. Arming
+ * The evidence state an edition of `kind` on `channel` records in its descriptor. Arming
  * is judged for that ONE channel (`assessTrustPolicyArming`): the signers of
- * the other channel count for nothing.
+ * the other channel count for nothing. Which states the kind may record on the
+ * channel is the contract's (`evidenceTrust.statesByKind`, admittedEvidenceTrustStates):
  *
  *   * `armed`      - the data root declares a policy, the policy is pinned (the
  *                    policy and this CLI's verifier match the data-root pin) and
  *                    ARMED on `channel`;
- *   * `not-armed`  - a DEVELOP edition only: its channel is not armed (no
+ *   * `not-armed`  - a RESOLVED DEVELOP edition only: its channel is not armed (no
  *                    policy, or UNARMED there), and it says so in one stderr line.
  *
- * Every other state is refused. A RELEASE edition that is not ARMED on the
- * release channel (no policy, UNARMED or PARTIAL there) throws
- * EvidenceTrustRequiredError: this function never returns `not-armed` for it.
- * A policy edited after pinning, a drifted verifier, and a policy PARTIALLY
- * ARMED on `channel` are refused on either channel.
+ * Every other state is refused. A SEALED edition (either channel) and a RESOLVED
+ * RELEASE edition that is not ARMED on its channel (no policy, UNARMED or PARTIAL
+ * there) throw EvidenceTrustRequiredError: this function never returns `not-armed`
+ * for them. A policy edited after pinning, a drifted verifier, and a policy
+ * PARTIALLY ARMED on `channel` are refused for every edition.
  *
  * `consumesCatalogue` (a customer edition consumes a catalogue): on RELEASE it adds the edition-catalogue (E4) row to the
  * required ones, and the catalogue's E4 evidence is verified before it is parsed. A DEVELOP catalogue carries no E4
@@ -220,22 +230,23 @@ export class CatalogueEvidenceUnverifiableError extends Error {
  * row is required and nothing can verify the catalogue: a customer develop edition is never written `armed`. A policy
  * ARMED on develop throws CatalogueEvidenceUnverifiableError instead of recording a claim nothing checked.
  *
- * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string}, consumesCatalogue?: boolean }} options
+ * @param {{ kind: string, channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string}, consumesCatalogue?: boolean }} options
  */
-export async function descriptorEvidenceTrust({ channel, locateVerifier = locateBuiltVerifier, consumesCatalogue = false }) {
+export async function descriptorEvidenceTrust({ kind, channel, locateVerifier = locateBuiltVerifier, consumesCatalogue = false }) {
   const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
   const root = configuredDataRoot();
   const schemas = await loadKernelDistributionSchemas();
   assertArmingChannel(schemas, channel);
   const release = channel === EditionChannel.Release;
-  const developNotArmed = () => {
+  const notArmedAdmitted = admittedEvidenceTrustStates(kind, channel).includes(EvidenceTrustState.NotArmed);
+  // A resolved edition is named by its channel ("a release edition"); a seal by its kind and channel.
+  const subject = { edition: kind === EditionKind.Sealed ? `${kind} ${channel} edition` : `${channel} edition`, channel };
+  const notArmed = (reason) => {
+    if (!notArmedAdmitted) {throw new EvidenceTrustRequiredError(root, reason, subject);}
     console.error(DEVELOP_NOT_ARMED_NOTICE);
     return EvidenceTrustState.NotArmed;
   };
-  if (declaration.policy === null) {
-    if (release) {throw new EvidenceTrustRequiredError(root, 'declares no policy');}
-    return developNotArmed();
-  }
+  if (declaration.policy === null) {return notArmed('declares no policy');}
   const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
   const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue: consumesCatalogue && release });
   if (state === TrustPolicyArmingState.ARMED) {
@@ -243,11 +254,10 @@ export async function descriptorEvidenceTrust({ channel, locateVerifier = locate
     return EvidenceTrustState.Armed;
   }
   if (state === TrustPolicyArmingState.PARTIAL) {
-    if (release) {throw new EvidenceTrustRequiredError(root, `declares a policy that is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')})`);}
+    if (!notArmedAdmitted) {throw new EvidenceTrustRequiredError(root, `declares a policy that is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')})`, subject);}
     throw new Error(`the declared evidence trust policy is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')}); an edition cannot be written against it`);
   }
-  if (release) {throw new EvidenceTrustRequiredError(root, `declares a policy that is UNARMED on the ${channel} channel`);}
-  return developNotArmed();
+  return notArmed(`declares a policy that is UNARMED on the ${channel} channel`);
 }
 
 export const UNDECLARED_TRUST_DIRECTORY = 'trust';

package/edition/external-source-walk.mjs

@@ -92,12 +92,16 @@ import {
   readGitJsonAtCommit,
   readGitTextAtCommitOrNull,
 } from './lib.mjs';
+import { walkOciSources } from './third-party-source-walk.mjs';
 
 /** Where fetched sources are cached: a directory under the configured cache root. Never an input to a lock. */
 export const externalSourceCacheDir = () => join(cacheDir(), 'external-sources');
 
 const EXACT_COMMIT = /^[a-f0-9]{40}$/;
 
+/** The declared source kind that names a third-party pin instead of a git repository. */
+const OCI_SOURCE_KIND = 'oci';
+
 /**
  * Directory names never walked for biome manifests in an EXTERNAL source.
  *
@@ -397,24 +401,33 @@ export async function walkDeclaredSources({
   materialize = materializeGitSource,
   env = process.env,
   workspace = undefined,
+  thirdParty = undefined,
 } = {}) {
   const entries = [];
   const sourceRecords = new Map();
   // Every source is held (kind, then credential and URL) before the first is materialised.
   const heldWorkspace = sources.length === 0 ? undefined : (workspace ?? editionWorkspaceConfig());
   for (const source of sources) {
+    if (source.kind === OCI_SOURCE_KIND) {continue;}
     if (source.kind !== 'git') {
       throw new Error(
         `source "${source.name}" declares kind "${source.kind}", which this walk does not ` +
           'resolve. The kernel\'s LockedBiomeSourceSchema can only record a GIT source ' +
-          '(kind is z.literal(Git)), so an oci or npm source has nowhere to be pinned in the ' +
+          '(kind is z.literal(Git)), so an npm source has nowhere to be pinned in the ' +
           'lock — resolving it would produce an edition whose members cannot be traced to a ' +
-          'revision. Refusing rather than resolving.',
+          'revision. Refusing rather than resolving. (An oci source is a third-party pin: it ' +
+          'is held to the data root\'s third-party-source-pins.json and records no lock source.)',
       );
     }
     holdSource(source, heldWorkspace, env);
   }
-  for (const source of sources) {
+  const ociSources = sources.filter((source) => source.kind === OCI_SOURCE_KIND);
+  if (ociSources.length > 0) {
+    for (const { source, entry } of await walkOciSources(ociSources, { env, ...(thirdParty === undefined ? {} : { thirdParty }) })) {
+      entries.push(stampEntry(assertSourceWalkedOrigin(entry, source.name), source.name));
+    }
+  }
+  for (const source of sources.filter((candidate) => candidate.kind !== OCI_SOURCE_KIND)) {
     const { directory, commit } = materialize({ source, env, workspace: heldWorkspace });
     if (!EXACT_COMMIT.test(String(commit))) {
       throw new Error(

package/edition/fleet-coordinate-finality.mjs

@@ -99,7 +99,7 @@ export function coordinateOf(subject) {
  * cannot name who is still waiting sends the reader to look for the reason
  * themselves, and the reason is in another edition's declaration.
  */
-export function collectFleetPlatformRequirements({ editions }) {
+export function collectFleetPlatformRequirements({ editions, isThirdPartySubject = () => false }) {
   if (!Array.isArray(editions) || editions.length === 0) {
     throw new Error(
       'fleet-coordinate-finality: no edition was supplied; a fleet requirement map ' +
@@ -133,6 +133,9 @@ export function collectFleetPlatformRequirements({ editions }) {
             'and silently weaken the refusal for every edition sharing its coordinate.',
         );
       }
+      // A third-party subject is read by its pinned digest, not at `<imageRef>:<contentHash>` (its contentHash is
+      // publisher-attested, not a tag), and no fleet lane supplements it: it contributes no first-party coordinate.
+      if (isThirdPartySubject(subject)) {continue;}
       const coordinate = coordinateOf(subject);
       let platforms = byCoordinate.get(coordinate);
       if (!platforms) {
@@ -242,20 +245,30 @@ export function readFleetImageLocks(editionsRoot) {
  * reconciler permanently red with no action available to clear it, and a gate
  * that cannot be cleared is one people learn to bypass.
  *
+ * THIRD-PARTY SUBJECTS ARE EXCLUDED, NAMED. `thirdPartyKeys` (`kind:id`) are the pinned third-party subjects of this
+ * edition: each is read by its pinned manifest digest (an immutable coordinate no fleet lane supplements), so it has no
+ * first-party fleet coordinate to grade. They are returned as `thirdParty` so the caller prints them.
+ *
  * Throws with `error.notFinal === true` — a PROPERTY, never a message match, so
  * the reconciler's skip cannot silently widen the day this wording changes. Same
  * discipline as `error.status` on the not-published-yet path.
  */
 export function assertCoordinatesFinal({
   distributionId,
-  writes,
+  writes: plannedWrites,
   verified,
   fleetRequirements,
+  thirdPartyKeys = new Set(),
 }) {
   const graded = [];
   const pendingElsewhere = [];
-  if (!Array.isArray(writes) || writes.length === 0) {
-    return { distributionId, graded, coordinateCount: 0, pendingElsewhere };
+  if (!Array.isArray(plannedWrites)) {
+    return { distributionId, graded, coordinateCount: 0, pendingElsewhere, thirdParty: [] };
+  }
+  const thirdParty = plannedWrites.filter((write) => thirdPartyKeys.has(write.key)).map((write) => write.key);
+  const writes = plannedWrites.filter((write) => !thirdPartyKeys.has(write.key));
+  if (writes.length === 0) {
+    return { distributionId, graded, coordinateCount: 0, pendingElsewhere, thirdParty };
   }
   const byKey = new Map(
     verified.map((entry) => [`${entry.subjectKind}:${entry.subjectId}`, entry]),
@@ -337,7 +350,7 @@ export function assertCoordinatesFinal({
     error.blockers = blockers;
     throw error;
   }
-  return { distributionId, graded, coordinateCount: graded.length, pendingElsewhere };
+  return { distributionId, graded, coordinateCount: graded.length, pendingElsewhere, thirdParty };
 }
 
 /**

package/edition/fulcio-certificate-extensions.mjs

@@ -0,0 +1,231 @@
+// The Fulcio v2 certificate extensions cosign has no verification flag for, read from the
+// leaf certificate of a sigstore bundle with a small DER walker (Node's X509Certificate does
+// not expose arbitrary extensions).
+//
+//   1.3.6.1.4.1.57264.1.11  Runner Environment
+//   1.3.6.1.4.1.57264.1.15  Source Repository Identifier
+//   1.3.6.1.4.1.57264.1.17  Source Repository Owner Identifier
+//
+// Each is the v2 form: the extension's OCTET STRING contains a DER UTF8String. The legacy raw
+// forms (.1 to .6, which put the bare bytes in the OCTET STRING) are never read. An absent
+// extension, a repeated one or one that is not a UTF8String is refused naming its OID.
+//
+// The certificate is the one cosign verified: the bytes come from the bundle that was verified
+// (`verificationMaterial.certificate.rawBytes`, else the first
+// `verificationMaterial.x509CertificateChain.certificates[].rawBytes`), never from a second fetch.
+
+const TAG_SEQUENCE = 0x30;
+const TAG_OID = 0x06;
+const TAG_BOOLEAN = 0x01;
+const TAG_OCTET_STRING = 0x04;
+const TAG_UTF8_STRING = 0x0c;
+const TAG_CONTEXT_0 = 0xa0;
+const TAG_CONTEXT_1 = 0xa1;
+const TAG_CONTEXT_2 = 0xa2;
+const TAG_CONTEXT_3 = 0xa3;
+
+export const FulcioExtensionOid = Object.freeze({
+  RunnerEnvironment: '1.3.6.1.4.1.57264.1.11',
+  SourceRepositoryIdentifier: '1.3.6.1.4.1.57264.1.15',
+  SourceRepositoryOwnerIdentifier: '1.3.6.1.4.1.57264.1.17',
+});
+
+/** The Runner Environment value of a GitHub-hosted runner. */
+export const GITHUB_HOSTED_RUNNER_ENVIRONMENT = 'github-hosted';
+
+const OID_FIELDS = Object.freeze([
+  ['runnerEnvironment', FulcioExtensionOid.RunnerEnvironment],
+  ['sourceRepositoryIdentifier', FulcioExtensionOid.SourceRepositoryIdentifier],
+  ['sourceRepositoryOwnerIdentifier', FulcioExtensionOid.SourceRepositoryOwnerIdentifier],
+]);
+
+/** One DER element at `offset`: its tag, content bounds and the offset after it. Indefinite lengths are refused (DER). */
+function readElement(bytes, offset, end, what) {
+  if (offset + 2 > end) {
+    throw new Error(`certificate DER is truncated at ${what}`);
+  }
+  const tag = bytes[offset];
+  if ((tag & 0x1f) === 0x1f) {
+    throw new Error(`certificate DER has a multi-byte tag at ${what}`);
+  }
+  let length = bytes[offset + 1];
+  let contentStart = offset + 2;
+  if (length === 0x80) {
+    throw new Error(`certificate DER has an indefinite length at ${what}`);
+  }
+  if (length > 0x80) {
+    const count = length & 0x7f;
+    if (count > 4 || contentStart + count > end) {
+      throw new Error(`certificate DER has an invalid length at ${what}`);
+    }
+    length = 0;
+    for (let index = 0; index < count; index += 1) {
+      length = length * 256 + bytes[contentStart + index];
+    }
+    contentStart += count;
+  }
+  const contentEnd = contentStart + length;
+  if (contentEnd > end) {
+    throw new Error(`certificate DER overruns its container at ${what}`);
+  }
+  return { tag, contentStart, contentEnd };
+}
+
+function expectElement(bytes, offset, end, tag, what) {
+  const element = readElement(bytes, offset, end, what);
+  if (element.tag !== tag) {
+    throw new Error(`certificate DER: ${what} has tag 0x${element.tag.toString(16)}, expected 0x${tag.toString(16)}`);
+  }
+  return element;
+}
+
+function decodeOid(bytes, start, end) {
+  if (end <= start) {
+    throw new Error('certificate DER has an empty OBJECT IDENTIFIER');
+  }
+  const arcs = [];
+  let value = 0;
+  for (let index = start; index < end; index += 1) {
+    value = value * 128 + (bytes[index] & 0x7f);
+    if ((bytes[index] & 0x80) === 0) {
+      if (arcs.length === 0) {
+        const first = Math.min(Math.floor(value / 40), 2);
+        arcs.push(first, value - first * 40);
+      } else {
+        arcs.push(value);
+      }
+      value = 0;
+    }
+  }
+  return arcs.join('.');
+}
+
+/** The extensions of the certificate: `Map<oid, {critical, value: Buffer}>` where `value` is the OCTET STRING content. */
+function certificateExtensions(der) {
+  const certificate = expectElement(der, 0, der.length, TAG_SEQUENCE, 'Certificate');
+  if (certificate.contentEnd !== der.length) {
+    throw new Error('certificate DER has trailing bytes after the Certificate');
+  }
+  const tbs = expectElement(der, certificate.contentStart, certificate.contentEnd, TAG_SEQUENCE, 'TBSCertificate');
+  let offset = tbs.contentStart;
+  let element = readElement(der, offset, tbs.contentEnd, 'TBSCertificate field');
+  if (element.tag === TAG_CONTEXT_0) {
+    offset = element.contentEnd;
+  }
+  // serialNumber, signature, issuer, validity, subject, subjectPublicKeyInfo
+  for (let field = 0; field < 6; field += 1) {
+    element = readElement(der, offset, tbs.contentEnd, 'TBSCertificate field');
+    offset = element.contentEnd;
+  }
+  let extensionsBlock = null;
+  while (offset < tbs.contentEnd) {
+    element = readElement(der, offset, tbs.contentEnd, 'TBSCertificate trailing field');
+    offset = element.contentEnd;
+    if (element.tag === TAG_CONTEXT_3) {
+      extensionsBlock = element;
+    } else if (element.tag !== TAG_CONTEXT_1 && element.tag !== TAG_CONTEXT_2) {
+      throw new Error(`certificate DER: unexpected TBSCertificate field tag 0x${element.tag.toString(16)}`);
+    }
+  }
+  if (extensionsBlock === null) {
+    throw new Error('certificate has no extensions block');
+  }
+  const list = expectElement(der, extensionsBlock.contentStart, extensionsBlock.contentEnd, TAG_SEQUENCE, 'Extensions');
+  const found = new Map();
+  let cursor = list.contentStart;
+  while (cursor < list.contentEnd) {
+    const extension = expectElement(der, cursor, list.contentEnd, TAG_SEQUENCE, 'Extension');
+    cursor = extension.contentEnd;
+    const oidElement = expectElement(der, extension.contentStart, extension.contentEnd, TAG_OID, 'Extension OID');
+    const oid = decodeOid(der, oidElement.contentStart, oidElement.contentEnd);
+    let next = oidElement.contentEnd;
+    let critical = false;
+    let part = readElement(der, next, extension.contentEnd, 'Extension field');
+    if (part.tag === TAG_BOOLEAN) {
+      critical = der[part.contentStart] !== 0;
+      next = part.contentEnd;
+      part = readElement(der, next, extension.contentEnd, 'Extension value');
+    }
+    if (part.tag !== TAG_OCTET_STRING || part.contentEnd !== extension.contentEnd) {
+      throw new Error(`certificate DER: extension ${oid} value is not a lone OCTET STRING`);
+    }
+    if (found.has(oid)) {
+      throw new Error(`certificate carries extension ${oid} more than once`);
+    }
+    found.set(oid, { critical, value: der.subarray(part.contentStart, part.contentEnd) });
+  }
+  return found;
+}
+
+/** The extension's string: the OCTET STRING content must be exactly one DER UTF8String. */
+function utf8ExtensionValue(extensions, oid) {
+  const extension = extensions.get(oid);
+  if (extension === undefined) {
+    throw new Error(`certificate does not carry Fulcio extension ${oid}`);
+  }
+  const { value } = extension;
+  let element;
+  try {
+    element = readElement(value, 0, value.length, `extension ${oid}`);
+  } catch (error) {
+    throw new Error(`Fulcio extension ${oid} is not a DER UTF8String: ${error.message}`);
+  }
+  if (element.tag !== TAG_UTF8_STRING || element.contentEnd !== value.length) {
+    throw new Error(`Fulcio extension ${oid} is not a DER UTF8String`);
+  }
+  const text = value.subarray(element.contentStart, element.contentEnd);
+  if (text.length === 0) {
+    throw new Error(`Fulcio extension ${oid} is an empty UTF8String`);
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(text);
+  } catch {
+    throw new Error(`Fulcio extension ${oid} is not valid UTF-8`);
+  }
+}
+
+function decodeBase64Der(rawBytes, what) {
+  if (typeof rawBytes !== 'string' || rawBytes.length === 0) {
+    throw new Error(`${what} has no rawBytes`);
+  }
+  return Buffer.from(rawBytes, 'base64');
+}
+
+/**
+ * The DER bytes of the leaf certificate of a parsed sigstore bundle:
+ * `verificationMaterial.certificate.rawBytes`, else the first
+ * `verificationMaterial.x509CertificateChain.certificates[].rawBytes`.
+ */
+export function leafCertificateDerFromBundle(bundle) {
+  const material = bundle?.verificationMaterial;
+  if (material === null || typeof material !== 'object') {
+    throw new Error('sigstore bundle has no verificationMaterial');
+  }
+  if (material.certificate !== undefined) {
+    return decodeBase64Der(material.certificate?.rawBytes, 'verificationMaterial.certificate');
+  }
+  const first = material.x509CertificateChain?.certificates?.[0];
+  if (first === undefined) {
+    throw new Error('sigstore bundle verificationMaterial carries no certificate and no x509CertificateChain');
+  }
+  return decodeBase64Der(first.rawBytes, 'verificationMaterial.x509CertificateChain.certificates[0]');
+}
+
+/**
+ * The runner environment, source repository identifier and source repository owner identifier of a
+ * DER certificate. Throws naming the OID when one is missing or is not a UTF8String.
+ *
+ * @param {Buffer} der
+ * @returns {{runnerEnvironment: string, sourceRepositoryIdentifier: string, sourceRepositoryOwnerIdentifier: string}}
+ */
+export function readFulcioCertificateExtensions(der) {
+  const extensions = certificateExtensions(der);
+  return Object.freeze(
+    Object.fromEntries(OID_FIELDS.map(([field, oid]) => [field, utf8ExtensionValue(extensions, oid)])),
+  );
+}
+
+/** The three extensions of the leaf certificate of a parsed sigstore bundle (the bytes cosign verified). */
+export function readFulcioExtensionsFromBundle(bundle) {
+  return readFulcioCertificateExtensions(leafCertificateDerFromBundle(bundle));
+}