@xemahq/xema 0.48.0 → 0.49.1

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

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

package/edition/third-party-subjects.mjs

@@ -0,0 +1,128 @@
+// Third-party OCI biomes on the resolve side (XEMA-1611 design section 4).
+//
+// A biome from an organisation outside the vendor fleet reaches an edition as a lock row with NO `source` (the lock's
+// `LockedBiomeSource` is git-only), an OCI `bundleSource` and `origin: third-party`. That triple is the whole key; the
+// pin file (`third-party-source-pins.json`, written only by the trusted writer) is what the row is then held to. The
+// image subjects of such a row take `imageRef`, `sourceCommit` and `contentHash` from the pin and are never built,
+// hashed or probed by this plane: there is no checkout to hash.
+//
+// `contentHash` of such a subject is the PUBLISHER'S statement (`sourceTreeHash` of its image-source evidence), never
+// a hash this plane computed. It is therefore labelled `contentHash (publisher-attested)` wherever it is printed and
+// is not used as an image tag, a cache key or a reproducibility check by any path that serves third-party subjects.
+
+import { loadKernelBiomeContracts } from './lib.mjs';
+
+export const PUBLISHER_ATTESTED_LABEL = 'publisher-attested';
+
+export const OCI_BUNDLE_SOURCE_KIND = 'oci';
+
+const hasOciBundleSource = (row) => row.bundleSource?.kind === OCI_BUNDLE_SOURCE_KIND;
+const isThirdPartyOrigin = (row) => row.origin === loadKernelBiomeContracts().BiomeOrigin.ThirdParty;
+
+/**
+ * The lock key of a third-party OCI biome: no `source`, an OCI `bundleSource`, `origin: third-party`.
+ * A lock row and a walked index entry both carry these fields; an index entry's `source` is the walk's stamp, so it
+ * is dropped by the caller that tests an entry (`isThirdPartyOciEntry`).
+ */
+export const isThirdPartyOciRow = (row) => row.source === undefined && hasOciBundleSource(row) && isThirdPartyOrigin(row);
+
+/** A walked index entry that is a third-party OCI biome: its `source` is the walk's stamp, not a lock source. */
+export const isThirdPartyOciEntry = (entry) => hasOciBundleSource(entry) && isThirdPartyOrigin(entry);
+
+/**
+ * Refuse an OCI `bundleSource` on a row whose origin is not third-party: only a third-party biome is pulled from an OCI
+ * bundle by digest, so the vendor's origin on such a row would place an unevidenced bundle in the vendor's trust domain.
+ * A row drawn from a git `source` is not this key and carries no OCI `bundleSource` at all: resolve omits the manifest's
+ * (it names a release artifact not built from the pinned commit), and a lock stating one is refused (`locked-bundle-signer.mjs`).
+ */
+export function assertOciBundleSourceOrigin(row, label) {
+  if (row.source === undefined && hasOciBundleSource(row) && !isThirdPartyOrigin(row)) {
+    throw new Error(
+      `${label} carries an OCI bundleSource (${row.bundleSource.ociRef}) but its origin is "${row.origin}": an OCI ` +
+        `biome bundle is admitted only as origin "${loadKernelBiomeContracts().BiomeOrigin.ThirdParty}", with a pin of the data root's third-party source pins`,
+    );
+  }
+}
+
+/**
+ * The third-party source pin a third-party OCI row is held to, by the row's `repo` (the pinned repository). Refuses a
+ * row with no pin (naming why the data root has none when it has none), a pin for another biome, another bundle
+ * reference or another manifest hash, and a pin the distribution does not declare as an `oci` source of that name.
+ *
+ * @param {{row: object, declaredSources: readonly object[]|undefined, pins: {sources: readonly object[], reason: string|null, byRepository: (repository: string) => object|undefined}|undefined, label: string}} options
+ */
+export function thirdPartyPinForRow({ row, pins, declaredSources, label }) {
+  if (pins === undefined) {
+    throw new Error(`${label} is a third-party OCI biome, but this resolve was given no third-party source pins to hold it to`);
+  }
+  const pin = pins.byRepository(row.repo);
+  if (pin === undefined) {
+    throw new Error(
+      `${label} is a third-party OCI biome with neither a source nor a pin: ${pins.reason ?? `no third-party source pin names repository "${row.repo}"`}`,
+    );
+  }
+  if (row.id !== pin.bundle.biomeId) {
+    throw new Error(`${label} has biome id "${row.id}", but the third-party pin "${pin.name}" is for biome "${pin.bundle.biomeId}"`);
+  }
+  if (row.bundleSource.ociRef !== pin.bundle.ociRef) {
+    throw new Error(`${label} names bundle ${row.bundleSource.ociRef}, but the third-party pin "${pin.name}" pins ${pin.bundle.ociRef}`);
+  }
+  if (row.sourceManifestHash !== pin.bundle.sourceManifestHash) {
+    throw new Error(
+      `${label} has sourceManifestHash ${row.sourceManifestHash}, but the third-party pin "${pin.name}" pins ${pin.bundle.sourceManifestHash}`,
+    );
+  }
+  if (!Array.isArray(declaredSources) || !declaredSources.some((source) => source.kind === OCI_BUNDLE_SOURCE_KIND && source.name === pin.name)) {
+    throw new Error(`${label} is drawn from the third-party pin "${pin.name}", which the distribution does not declare as a sources[] entry of kind "${OCI_BUNDLE_SOURCE_KIND}"`);
+  }
+  return pin;
+}
+
+/**
+ * The image subjects of one third-party OCI row, from its pin and nothing else: one per service and runtime
+ * component the row ships (a worker that runs its sibling's image has none). Every pinned image must be one of them and
+ * every shipped image must be pinned, so the pin and the lock describe the same images.
+ *
+ * `contentHash` is the publisher's `sourceTreeHash` (publisher-attested); `sourceCommit` is the pin's.
+ */
+export function thirdPartySubjectCandidates({ row, pin, enums, requiredPlatforms, label }) {
+  if (row.target === 'web') {
+    throw new Error(`${label} is a third-party OCI biome with target "web": a bundled web biome of a third party is not admitted (it has no pinned image)`);
+  }
+  const sharedImageWorkers = new Set(Object.keys(row.workerImages ?? {}));
+  const wanted = [
+    ...(row.services ?? []).filter((service) => !sharedImageWorkers.has(service)).map((id) => [enums.RuntimeImageSubjectKind.Service, id]),
+    ...(row.runtimeComponents ?? []).map((id) => [enums.RuntimeImageSubjectKind.RuntimeComponent, id]),
+  ];
+  const byKey = new Map(pin.images.map((image) => [`${image.subjectKind}\0${image.subjectId}`, image]));
+  const used = new Set();
+  const candidates = wanted.map(([kind, id]) => {
+    const image = byKey.get(`${kind}\0${id}`);
+    if (image === undefined) {
+      throw new Error(`${label} ships ${kind} "${id}", which the third-party pin "${pin.name}" pins no image for`);
+    }
+    used.add(`${kind}\0${id}`);
+    return {
+      kind,
+      id,
+      imageRef: image.imageRef,
+      repo: row.repo,
+      path: row.path,
+      sourceCommit: pin.sourceCommit,
+      sourceManifestHash: row.sourceManifestHash,
+      requiredPlatforms,
+      owners: [{ kind: enums.RuntimeImageOwnerKind.Biome, biomeId: row.id }],
+      contentHash: image.sourceTreeHash,
+    };
+  });
+  const unused = [...byKey.keys()].filter((key) => !used.has(key));
+  if (unused.length > 0) {
+    throw new Error(
+      `the third-party pin "${pin.name}" pins image(s) ${unused.map((key) => key.replace('\0', ':')).join(', ')} that ${label} does not ship`,
+    );
+  }
+  return candidates;
+}
+
+/** A third-party subject's content hash, as every CLI output prints it. */
+export const attestedContentHash = (subject) => `contentHash (${PUBLISHER_ATTESTED_LABEL}) ${subject.contentHash}`;

package/edition/trust-policy-image-ownership.mjs

@@ -0,0 +1,85 @@
+// Who may name which image repository in the evidence trust policy (XEMA-1611 design section 3(e)).
+//
+// Checked when the declared policy is LOADED, so every consumer of the policy sees it:
+//   (a) an `imageRepositories` entry listed by rows whose `githubWorkflow.repository` OWNERS differ is
+//       refused: one repository, one publisher;
+//   (b) a row whose owner is not a first-party owner and that names a first-party namespace
+//       (`<registry>/<first-party owner>/<any>`) is refused.
+// First-party owners are the owners of the runtime-image-source index `repositoryPins` URLs, plus the kernel scope owner.
+
+import { KERNEL_PACKAGE_NAME } from './kernel-package.mjs';
+
+/**
+ * The vendor's publishing owner: the npm scope of the kernel package (`@<scope>/contracts`), read from the package name
+ * the CLI already pins, not written here. It is a first-party owner on purpose, beside the owners of the index's
+ * `repositoryPins`: the vendor publishes its kernel-scoped images under that owner, which no repository pin names, so
+ * without it a vendor row for them would be refused by rule (b) as a third party.
+ */
+export const KERNEL_SCOPE_OWNER = KERNEL_PACKAGE_NAME.replace(/^@/u, '').split('/')[0];
+
+/** The lowercase owners of the `repositoryPins[].repositoryUrl` entries of a parsed runtime image source index, plus the kernel scope owner. */
+export function firstPartyOwnersFromIndex(indexDocument) {
+  const pins = indexDocument?.repositoryPins;
+  if (!Array.isArray(pins)) {
+    throw new Error('runtime image source index has no repositoryPins array to derive the first-party owners from');
+  }
+  const owners = new Set([KERNEL_SCOPE_OWNER]);
+  for (const pin of pins) {
+    let url;
+    try {
+      url = new URL(pin?.repositoryUrl);
+    } catch {
+      throw new Error(`runtime image source index repositoryPins entry ${JSON.stringify(pin?.repo)} has no parsable repositoryUrl`);
+    }
+    const owner = url.pathname.split('/').filter(Boolean)[0];
+    if (owner === undefined) {
+      throw new Error(`runtime image source index repositoryUrl ${url.href} names no owner`);
+    }
+    owners.add(owner.toLowerCase());
+  }
+  return owners;
+}
+
+/**
+ * Whether an image repository sits in a first-party namespace: `<registry>/<first-party owner>/<any>`, an owner being
+ * one of `firstPartyOwners` (the data root's own, from `firstPartyOwnersFromIndex`). The registry is whatever the first
+ * path segment is; no registry or organisation is named here.
+ */
+export function isFirstPartyImageNamespace(imageRepository, firstPartyOwners) {
+  const segments = imageRepository.toLowerCase().split('/');
+  return segments.slice(1, -1).some((segment) => firstPartyOwners.has(segment));
+}
+
+const rowOwner = (row) => row.githubWorkflow?.repository?.split('/')[0]?.toLowerCase();
+
+/**
+ * Refuse a policy that breaks (a) or (b). `firstPartyOwners` is `null` when the data root has no runtime image source
+ * index (a customer data root): (b) cannot be judged there and is not applied; (a) always is.
+ *
+ * @param {{policy: {policies: object[]}, firstPartyOwners: Set<string>|null}} options
+ */
+export function assertTrustPolicyImageOwnership({ policy, firstPartyOwners }) {
+  const ownersByRepository = new Map();
+  for (const row of policy.policies) {
+    const owner = rowOwner(row);
+    if (owner === undefined || !Array.isArray(row.imageRepositories)) {
+      continue;
+    }
+    for (const imageRepository of row.imageRepositories) {
+      const seen = ownersByRepository.get(imageRepository);
+      if (seen !== undefined && seen.owner !== owner) {
+        throw new Error(
+          `evidence trust policy: image repository ${imageRepository} is listed by rows of two publishers ` +
+            `(${seen.policyId} owned by ${seen.owner}, ${row.policyId} owned by ${owner}); one image repository has one publisher`,
+        );
+      }
+      ownersByRepository.set(imageRepository, { owner, policyId: row.policyId });
+      if (firstPartyOwners !== null && !firstPartyOwners.has(owner) && isFirstPartyImageNamespace(imageRepository, firstPartyOwners)) {
+        throw new Error(
+          `evidence trust policy: row ${row.policyId} (owner ${owner}, not a first-party owner) names image repository ` +
+            `${imageRepository} in a first-party namespace (<registry>/<first-party owner>/<any>)`,
+        );
+      }
+    }
+  }
+}

package/edition/verify-catalogue-evidence.mjs

@@ -24,6 +24,7 @@ import { EDITION_CONTRACT } from './edition-constants.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromArgv, dataRoot } from './edition-workspace.mjs';
 import {
   assertPinnedPolicy,
+  assertPinnedThirdPartySourcePins,
   assertPinnedVerifier,
   loadDeclaredTrustPolicy,
   readEvidenceTrustPin,
@@ -143,6 +144,7 @@ async function armedAnchors({ channel, env, bundlePath }) {
   const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot: dataRoot(), declaration, schemas });
   const pin = readEvidenceTrustPin({ dataRoot: dataRoot(), declaration });
   assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot: dataRoot() });
   assertPinnedVerifier({ pin, actual: verifierDigests(running) });
   const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue: true });
   if (state !== TrustPolicyArmingState.ARMED) {

package/edition/verify-image-evidence.mjs

@@ -45,6 +45,7 @@ import {
   RUNTIME_IMAGE_SOURCE_INDEX_FILE,
   assertPinnedKernelContractAuthority,
   assertPinnedPolicy,
+  assertPinnedThirdPartySourcePins,
   assertPinnedVerifier,
   readStatedKernelContractAuthority,
   loadDeclaredTrustPolicy,
@@ -264,6 +265,7 @@ function readTrustAnchors({ schemas, running }) {
   });
   const pin = readEvidenceTrustPin({ dataRoot: dataRoot(), declaration });
   assertPinnedPolicy({ pin, policyDigest });
+  assertPinnedThirdPartySourcePins({ pin, dataRoot: dataRoot() });
   assertPinnedVerifier({ pin, actual: verifierDigests(running) });
   // The authority the producer statements are held to is read from the data
   // root's index downstream; it is the pinned one, or nothing is verified.

package/edition/verify-image-platforms.mjs

@@ -55,6 +55,7 @@ import {
   splitImageRef,
 } from './registry-credentials.mjs';
 import { assertReleaseContent, assertReleaseEditionTree } from './release-channel-guard.mjs';
+import { imageSubjectKey } from './third-party-image-pins.mjs';
 
 if (isEntryModule(import.meta.url)) {
   configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Kernel]);
@@ -182,9 +183,15 @@ async function readManifestConfigPlatform(client, repository, manifest, label) {
  * Resolve the set of platforms a published coordinate ACTUALLY serves.
  * Every returned platform is proven by a hash-verified image config, never by
  * an index descriptor's self-declaration alone.
+ *
+ * The coordinate is read by exactly one of `tag` (a first-party `<contentHash>` tag) or `digest` (a third-party
+ * subject, read by its pinned manifest digest).
  */
-export async function resolvePublishedPlatforms({ client, repository, tag, coordinate }) {
-  const top = await client.getManifestByTag(repository, tag);
+export async function resolvePublishedPlatforms({ client, repository, tag, digest, coordinate }) {
+  if ((tag === undefined) === (digest === undefined)) {
+    throw new Error(`${coordinate} must be read by exactly one of a tag or a digest (got ${tag === undefined ? 'neither' : 'both'})`);
+  }
+  const top = tag === undefined ? await client.getManifestByDigest(repository, digest) : await client.getManifestByTag(repository, tag);
   const platforms = [];
 
   if (!top.isIndex) {
@@ -340,6 +347,9 @@ export async function verifyDistributionPlatforms({
   collectFailures = false,
   // `(line) => void`: one line per verified subject, with its elapsed ms; null is silent.
   progress = null,
+  // `kind:id` -> manifest digest of the subjects pinned by a third-party source pin: each is read BY that digest, never by
+  // its (publisher-attested) contentHash as a tag.
+  pinnedDigests = new Map(),
 }) {
   const declarations = loadRegistryCredentialDeclarations(distributionsRoot);
 
@@ -369,9 +379,28 @@ export async function verifyDistributionPlatforms({
   );
   const subjects = verified.filter((entry) => entry !== undefined);
 
+  // A pinned image absent at its digest is a broken pin, never "not published yet" (no producer lane is about to build
+  // it): the failure is rethrown without the registry's `status`, so no caller's not-published-yet skip can take it.
+  async function readPublished({ client, repository, subject, pinnedDigest, coordinate }) {
+    if (pinnedDigest === undefined) {
+      return resolvePublishedPlatforms({ client, repository, tag: subject.contentHash, coordinate });
+    }
+    let published;
+    try {
+      published = await resolvePublishedPlatforms({ client, repository, digest: pinnedDigest, coordinate });
+    } catch (error) {
+      throw new Error(`pinned third-party image ${coordinate} (${subject.kind}:${subject.id}) cannot be read: ${error.message}`, { cause: error });
+    }
+    if (published.indexDigest !== pinnedDigest) {
+      throw new Error(`${coordinate} served manifest ${published.indexDigest} for ${subject.kind}:${subject.id}, not the pinned ${pinnedDigest}`);
+    }
+    return published;
+  }
+
   async function verifySubject(subject) {
     const { authority, repository } = splitImageRef(subject.imageRef);
-    const coordinate = `${subject.imageRef}:${subject.contentHash}`;
+    const pinnedDigest = pinnedDigests.get(imageSubjectKey(subject));
+    const coordinate = pinnedDigest === undefined ? `${subject.imageRef}:${subject.contentHash}` : `${subject.imageRef}@${pinnedDigest}`;
     // A subject that requires no platform cannot be verified — every check
     // would pass vacuously and the image would ship unexamined.
     if (
@@ -384,12 +413,7 @@ export async function verifyDistributionPlatforms({
       );
     }
     const client = clients.get(authority);
-    const published = await resolvePublishedPlatforms({
-      client,
-      repository,
-      tag: subject.contentHash,
-      coordinate,
-    });
+    const published = await readPublished({ client, repository, subject, pinnedDigest, coordinate });
     const present = published.platforms.map((entry) =>
       platformIdentity(entry.platform),
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.48.0",
+  "version": "0.49.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-cli.git",
@@ -52,9 +52,9 @@
     "@xemahq/biome-sdk": "^22.0.0",
     "@xemahq/biome-supply-chain": "^0.5.0",
     "@xemahq/distribution-source-hash": "^0.2.2",
-    "@xemahq/dsl": "^0.24.0",
-    "@xemahq/identity-client": "^0.16.0",
-    "@xemahq/contracts": "^0.111.0",
+    "@xemahq/dsl": "^0.28.0",
+    "@xemahq/identity-client": "^0.36.0",
+    "@xemahq/contracts": "^0.112.0",
     "@xemahq/kernel-state-runtime": "^0.8.0",
     "@xemahq/license-verifier": "^0.2.0",
     "@xemahq/service-registry-nest": "^0.12.2",
@@ -92,6 +92,6 @@
     "typecheck": "tsc --noEmit"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:5f6bd75aa0d1bdc9a141a6f9f31be0957f7a8e5aa967695362db0ced936cac5a"
+    "sourceDigest": "sha256:f330048c083619658f4721c67c1c4df25e1a9b64b2664a513e871b970d281639"
   }
 }

package/dist/runtime/auth/client-bootstrap.d.ts

@@ -1,11 +0,0 @@
-import { IdentityApiClient } from '@xemahq/identity-client';
-export interface RegisterCliClientOptions {
-    readonly identityApiUrl: string;
-    readonly internalToken: string;
-    readonly realm: string;
-    readonly identityClient?: Pick<IdentityApiClient, 'registerServiceFull'>;
-}
-export declare const IDENTITY_API_INTERNAL_TOKEN = "IDENTITY_API_INTERNAL_TOKEN";
-export declare function resolveIdentityRegistrationToken(configuredToken: string | undefined, environmentToken: string | undefined): string;
-export declare function registerCliDeviceClient(options: RegisterCliClientOptions): Promise<void>;
-//# sourceMappingURL=client-bootstrap.d.ts.map

package/dist/runtime/auth/client-bootstrap.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client-bootstrap.d.ts","sourceRoot":"","sources":["../../../src/runtime/auth/client-bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EAIlB,MAAM,yBAAyB,CAAC;AAIjC,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,CAAC;CAC1E;AAaD,eAAO,MAAM,2BAA2B,gCAAgC,CAAC;AAQzE,wBAAgB,gCAAgC,CAC9C,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,gBAAgB,EAAE,MAAM,GAAG,SAAS,GACnC,MAAM,CAmBR;AAOD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/runtime/auth/client-bootstrap.js

@@ -1,60 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.IDENTITY_API_INTERNAL_TOKEN = void 0;
-exports.resolveIdentityRegistrationToken = resolveIdentityRegistrationToken;
-exports.registerCliDeviceClient = registerCliDeviceClient;
-const identity_client_1 = require("@xemahq/identity-client");
-const device_flow_1 = require("./device-flow");
-const PUBLIC_DEVICE_SERVICE_TYPE = 'PUBLIC_DEVICE';
-const CLI_REGISTRATION = Object.freeze({
-    name: device_flow_1.DEFAULT_CLI_CLIENT_ID,
-    displayName: 'Xema CLI',
-    description: 'Public device-authorization client for the Xema command-line interface',
-    serviceType: PUBLIC_DEVICE_SERVICE_TYPE,
-    regenerateSecret: false,
-});
-exports.IDENTITY_API_INTERNAL_TOKEN = 'IDENTITY_API_INTERNAL_TOKEN';
-function resolveIdentityRegistrationToken(configuredToken, environmentToken) {
-    const configured = normalizeToken(configuredToken, 'configured secret');
-    const environment = normalizeToken(environmentToken, 'process environment');
-    if (configured !== undefined &&
-        environment !== undefined &&
-        configured !== environment) {
-        throw new Error(`${exports.IDENTITY_API_INTERNAL_TOKEN} differs between the configured secret and process environment. Refusing ambiguous identity authority.`);
-    }
-    const token = configured ?? environment;
-    if (token === undefined) {
-        throw new Error(`${exports.IDENTITY_API_INTERNAL_TOKEN} is required to reconcile the ${device_flow_1.DEFAULT_CLI_CLIENT_ID} public device client. Declare that exact secret or environment variable before launch.`);
-    }
-    return token;
-}
-async function registerCliDeviceClient(options) {
-    const client = options.identityClient ??
-        new identity_client_1.IdentityApiClient({
-            baseUrl: options.identityApiUrl,
-            internalToken: options.internalToken,
-        });
-    const registration = await client.registerServiceFull({
-        ...CLI_REGISTRATION,
-        realm: options.realm,
-    });
-    if (registration.id !== device_flow_1.DEFAULT_CLI_CLIENT_ID) {
-        throw new Error(`identity-api registration response did not identify ${device_flow_1.DEFAULT_CLI_CLIENT_ID}.`);
-    }
-    if (registration.clientSecret !== null) {
-        throw new Error(`identity-api returned a client secret for public client ${device_flow_1.DEFAULT_CLI_CLIENT_ID}.`);
-    }
-}
-function normalizeToken(token, source) {
-    if (token === undefined) {
-        return undefined;
-    }
-    if (token.length === 0 || token.trim().length === 0) {
-        throw new Error(`${exports.IDENTITY_API_INTERNAL_TOKEN} from ${source} is empty.`);
-    }
-    if (token !== token.trim()) {
-        throw new Error(`${exports.IDENTITY_API_INTERNAL_TOKEN} from ${source} has leading or trailing whitespace.`);
-    }
-    return token;
-}
-//# sourceMappingURL=client-bootstrap.js.map