@xemahq/xema 0.59.0 → 0.60.1

package/edition/locked-bundle-signer.mjs

@@ -1,297 +0,0 @@
-// The ONE place the edition CLI selects and checks the signer of an OCI bundle row (XEMA-1631).
-//
-// Every `bundleSource: {kind: 'oci'}` row of a lock (a biome's, or one of its host modules') states WHO signs its bundle:
-// `bundleSigner: {policyId, signer}`, the kernel's `lockedBundleSignerOf` projection of ONE row of the data root's evidence
-// trust policy. The row is selected, never defaulted:
-//   - a git-sourced row (one with a lock `source`) carries no OCI bundle, and a lock stating one is refused, EXCEPT in a
-//     selection made for a vendor develop edition (`GitSourcedBundle.DevelopVerified`, XEMA-2456): there a git-sourced
-//     biome row may carry the bundle the develop resolve verified (`develop-git-bundles.mjs`), signed by the ONE
-//     `develop` row of the source's repository;
-//   - a third-party row (no `source`, `isThirdPartyOciRow`) by its pin (`third-party-source-pins.json`), whose `bundle.signerPolicyId` names an
-//     `oidc-certificate` row held to the checks `thirdPartySignerRow` makes;
-//   - a first-party row by the data root's `firstPartyBundleSigner.policyId`, a `public-key` row whose key is bound to
-//     no other row.
-// A resolve fills the signer; a seal and a verify re-derive the selection and refuse a lock that states anything else.
-//
-// The kernel exports are loaded lazily, from the built kernel's `distribution` module as `kernel-signer-kind.mjs` does,
-// never through lib.mjs (whose imports must stay loadable by v28-v31 kernels): a lock with no OCI row never touches them.
-
-import { createRequire } from 'node:module';
-
-import { canonicalPublicHttpsRepositoryUrl, repositoryOwnerName } from './canonical-repository-url.mjs';
-import { KernelRefusalName, RefusalError, collectRefusals, isRefusal, joinRefusalMessages } from './collected-refusals.mjs';
-import { EditionChannel } from './edition-channel.mjs';
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import { assertKernelEditionProtocol } from './edition-protocol.mjs';
-import { dataRoot, kernelDistPath, kernelPackageDir } from './edition-workspace.mjs';
-import { loadPinnedDeclaredTrustPolicy } from './evidence-trust-pin.mjs';
-import { loadTrustedThirdPartySourcePins } from './third-party-pins-trusted.mjs';
-import { bundleSignerRowFor, thirdPartySignerRow } from './third-party-source-evidence.mjs';
-import { OCI_BUNDLE_SOURCE_KIND, isThirdPartyOciRow } from './third-party-subjects.mjs';
-
-const requireFromHere = createRequire(import.meta.url);
-
-const OIDC_CERTIFICATE_KIND = 'oidc-certificate';
-const PUBLIC_KEY_KIND = 'public-key';
-
-const KERNEL_EXPORTS = Object.freeze(['lockedBundleSignerOf', 'assertLockedBundleSignerMatches', 'LockedBundleSignerUnknownPolicyError', 'LockedBundleSignerAmbiguousPolicyError']);
-
-/**
- * Whether a selection admits an OCI bundle on a git-sourced row. `Refused` is every release, customer and dist-check
- * selection, unchanged; `DevelopVerified` only a vendor develop edition's resolve, seal and verify, whose git bundles
- * the develop resolve verified against the source commit (`develop-git-bundles.mjs`).
- */
-export const GitSourcedBundle = Object.freeze({ Refused: 'refused', DevelopVerified: 'develop-verified' });
-
-/** A named refusal of the bundle signer plane. */
-export class BundleSignerError extends RefusalError {
-  constructor(message) {
-    super(message);
-    this.name = new.target.name;
-  }
-}
-
-/** Whether `error` is a refusal of the bundle signer plane: this module's own, or one the kernel's signer projection throws. */
-export const isBundleSignerRefusal = (error) => error instanceof BundleSignerError || (isRefusal(error) && Object.values(KernelRefusalName).includes(error.name));
-
-/** No trust policy row can be selected for the subject: no pin, no `firstPartyBundleSigner`, or no policy at all. */
-export class BundleSignerPolicyAbsentError extends BundleSignerError {}
-/** The selected row is not of the kind its origin requires. */
-export class BundleSignerKindMismatchError extends BundleSignerError {}
-/** A first-party bundle key is also carried by another policy row. */
-export class BundleSignerKeyBoundElsewhereError extends BundleSignerError {}
-/** The lock names a policy that exists but is not the one selection picks for the subject. */
-export class BundleSignerPolicyNotSelectedError extends BundleSignerError {}
-/** An OCI row of a lock states no `bundleSigner`. */
-export class BundleSignerMissingError extends BundleSignerError {}
-/** A lock row drawn from a git `source` states an OCI `bundleSource`: a git-sourced biome is built from that source, never pulled as a bundle. */
-export class BundleSourceOnGitRowError extends BundleSignerError {}
-/** A resolve found an OCI host-module bundle on a git-sourced biome: such a bundle reaches an edition only through an `oci` source. */
-export class GitSourcedHostModuleBundleError extends BundleSignerError {}
-/** A develop resolve could not verify the OCI bundle a git-sourced biome declares (no develop row, cosign, or the content binding refused it). */
-export class DevelopGitBundleError extends BundleSignerError {}
-/** The loaded kernel does not export what the bundle signer plane needs. */
-export class BundleSignerKernelUnsupportedError extends BundleSignerError {}
-/** Several OCI rows were refused in one pass; `.errors` holds each row's own refusal. */
-export class BundleSignerRefusedError extends BundleSignerError {
-  /** @param {readonly Error[]} errors */
-  constructor(errors) {
-    super(`${errors.length} OCI bundle rows are refused:\n\n${joinRefusalMessages(errors)}`);
-    this.errors = errors;
-  }
-}
-
-/** What the kernel must export, validated once: `module` is the loaded kernel `distribution` module. */
-export function bundleSignerKernelFrom(module, location) {
-  const missing = KERNEL_EXPORTS.filter((name) => module?.[name] === undefined);
-  if (missing.length > 0) {
-    throw new BundleSignerKernelUnsupportedError(
-      `an OCI bundle row needs a kernel speaking edition protocol v33 or later; the kernel distribution module at ${location} lacks ${missing.join(', ')}`,
-    );
-  }
-  return Object.freeze(Object.fromEntries(KERNEL_EXPORTS.map((name) => [name, module[name]])));
-}
-
-/** The kernel's bundle signer exports, from the built kernel; refuses a kernel that speaks an older protocol. */
-export function loadBundleSignerKernel() {
-  assertKernelEditionProtocol(kernelPackageDir());
-  const location = kernelDistPath('distribution', 'index.js');
-  return bundleSignerKernelFrom(requireFromHere(location), location);
-}
-
-const describeSubject = ({ biomeId, componentKey }) =>
-  componentKey === undefined ? `biome "${biomeId}"` : `host module "${componentKey}" of biome "${biomeId}"`;
-
-/** A git-sourced row carries no OCI bundle (resolve omits it), so no signer is selected for one; a lock stating one is refused. */
-function assertNotGitSourced(subject) {
-  if (subject.source !== undefined) {
-    throw new BundleSourceOnGitRowError(
-      `${describeSubject(subject)} is drawn from git source "${subject.source?.name ?? subject.source}" and states an OCI bundleSource; a git-sourced biome carries none ` +
-        '(a third-party biome is an OCI bundle only as an `oci` source with a third-party pin)',
-    );
-  }
-}
-
-/** Refuses a git-sourced subject unless the selection admits develop git bundles and the subject is a biome row. */
-function assertGitSourceAdmitted(subject, gitSourcedBundle) {
-  if (subject.source === undefined) {return;}
-  if (gitSourcedBundle === GitSourcedBundle.DevelopVerified && subject.componentKey === undefined) {return;}
-  assertNotGitSourced(subject);
-}
-
-const rowsOf = (policy, policyId) => policy.policies.filter((row) => row.policyId === policyId);
-
-/**
- * @param {{policy: {policies: readonly object[]}|null, thirdPartyPins: {byRepository: (repository: string) => object|undefined}|undefined,
- *   firstPartyPolicyId: string|undefined, schemas: object, kernel?: object}} options
- * @returns {{policyIdFor: (subject: object) => string, signerFor: (subject: object) => object, assertSealed: (subject: object, stated: object|undefined) => void}}
- */
-export function createBundleSignerSelection({ policy, thirdPartyPins, firstPartyPolicyId, schemas, kernel, gitSourcedBundle = GitSourcedBundle.Refused }) {
-  let loaded = kernel;
-  const kernelExports = () => (loaded ??= loadBundleSignerKernel());
-
-  function onlyRow(policyId) {
-    const { LockedBundleSignerUnknownPolicyError, LockedBundleSignerAmbiguousPolicyError } = kernelExports();
-    const rows = rowsOf(policy, policyId);
-    if (rows.length === 0) {throw new LockedBundleSignerUnknownPolicyError(policyId);}
-    if (rows.length > 1) {throw new LockedBundleSignerAmbiguousPolicyError(policyId, rows.length);}
-    return rows[0];
-  }
-
-  function requireKind(subject, row, kind) {
-    if (row.kind !== kind) {
-      throw new BundleSignerKindMismatchError(
-        `${describeSubject(subject)}: trust policy row "${row.policyId}" is of kind ${JSON.stringify(row.kind)}, but a ${isThirdPartyOciRow(subject) ? 'third-party' : 'first-party'} bundle is signed by a "${kind}" row`,
-      );
-    }
-  }
-
-  function thirdPartyRow(subject) {
-    const pin = thirdPartyPins?.byRepository(subject.repo);
-    if (pin === undefined) {
-      throw new BundleSignerPolicyAbsentError(
-        `${describeSubject(subject)} is a third-party OCI bundle, but no third-party source pin names repository "${subject.repo}" to select its bundle signer`,
-      );
-    }
-    const policyId = pin.bundle.signerPolicyId;
-    const row = onlyRow(policyId);
-    requireKind(subject, row, OIDC_CERTIFICATE_KIND);
-    return thirdPartySignerRow({ policy, policyId, source: pin, schemas, label: `${describeSubject(subject)} bundle signer` });
-  }
-
-  function firstPartyRow(subject) {
-    if (firstPartyPolicyId === undefined) {
-      throw new BundleSignerPolicyAbsentError(
-        `${describeSubject(subject)} is a first-party OCI bundle, but the data root declares no "firstPartyBundleSigner" to select its bundle signer`,
-      );
-    }
-    const row = onlyRow(firstPartyPolicyId);
-    requireKind(subject, row, PUBLIC_KEY_KIND);
-    const bound = policy.policies.find((other) => other !== row && other.publicKey?.sha256 === row.publicKey.sha256);
-    if (bound !== undefined) {
-      throw new BundleSignerKeyBoundElsewhereError(
-        `${describeSubject(subject)}: the bundle key of row "${row.policyId}" is also carried by row "${bound.policyId}"; the bundle key must be bound to exactly one row, the bundle-signing one`,
-      );
-    }
-    return row;
-  }
-
-  // A git-sourced biome's develop bundle: the ONE develop row of the source's repository (a host module never reaches here:
-  // the resolve refuses an OCI host module on a git-sourced biome in every channel).
-  function developGitRow(subject) {
-    const label = `${describeSubject(subject)} develop bundle signer`;
-    const repository = repositoryOwnerName(canonicalPublicHttpsRepositoryUrl(subject.source.url, `${label} source url`), `${label} source url`);
-    let row;
-    try {
-      row = bundleSignerRowFor({ policy, repository, channel: EditionChannel.Develop, schemas, label });
-    } catch (error) {
-      throw new BundleSignerPolicyAbsentError(error.message);
-    }
-    requireKind(subject, row, OIDC_CERTIFICATE_KIND);
-    return onlyRow(row.policyId);
-  }
-
-  /** Refuses a git-sourced subject this selection does not admit; any other subject passes. */
-  const assertAdmitted = (subject) => assertGitSourceAdmitted(subject, gitSourcedBundle);
-
-  function requirePolicy(subject) {
-    if (policy === null) {
-      throw new BundleSignerPolicyAbsentError(
-        `${describeSubject(subject)} is an OCI bundle, but the data root declares no evidenceTrustPolicy, so there is no row to select its bundle signer from`,
-      );
-    }
-  }
-
-  function selectedRow(subject) {
-    assertAdmitted(subject);
-    requirePolicy(subject);
-    if (subject.source !== undefined) {return developGitRow(subject);}
-    return isThirdPartyOciRow(subject) ? thirdPartyRow(subject) : firstPartyRow(subject);
-  }
-
-  const signerFor = (subject) => {
-    const row = selectedRow(subject);
-    const { lockedBundleSignerOf, assertLockedBundleSignerMatches } = kernelExports();
-    const bundleSigner = lockedBundleSignerOf(row);
-    assertLockedBundleSignerMatches(bundleSigner, policy);
-    return bundleSigner;
-  };
-
-  return {
-    assertAdmitted,
-    policyIdFor: (subject) => selectedRow(subject).policyId,
-    signerFor,
-    assertSealed(subject, stated) {
-      if (stated === undefined) {
-        throw new BundleSignerMissingError(`${describeSubject(subject)} is an OCI bundle row and states no bundleSigner`);
-      }
-      requirePolicy(subject);
-      const row = kernelExports().assertLockedBundleSignerMatches(stated, policy);
-      const expected = selectedRow(subject).policyId;
-      if (row.policyId !== expected) {
-        throw new BundleSignerPolicyNotSelectedError(
-          `${describeSubject(subject)} states bundle signer policy "${row.policyId}", but its bundle signer is selected from policy "${expected}"`,
-        );
-      }
-    },
-  };
-}
-
-/**
- * The data root's selection, LAZY: nothing is read until the first OCI subject asks, so a lock with no OCI row never
- * needs a policy, a pin or a kernel that speaks v33.
- */
-export function loadBundleSignerSelection({ dataRoot, schemas, gitSourcedBundle = GitSourcedBundle.Refused }) {
-  let selection;
-  const resolved = () => {
-    if (selection === undefined) {
-      const config = editionWorkspaceConfig();
-      const declaration = config.evidenceTrustPolicy;
-      selection = createBundleSignerSelection({
-        policy: declaration.policy === null ? null : loadPinnedDeclaredTrustPolicy({ dataRoot, declaration, schemas }),
-        thirdPartyPins: loadTrustedThirdPartySourcePins(dataRoot),
-        firstPartyPolicyId: config.firstPartyBundleSigner?.policyId,
-        schemas,
-        gitSourcedBundle,
-      });
-    }
-    return selection;
-  };
-  return Object.freeze({
-    // Refusing an unadmitted git-sourced row needs no data root, so it reads none.
-    assertAdmitted: (subject) => assertGitSourceAdmitted(subject, gitSourcedBundle),
-    policyIdFor: (subject) => resolved().policyIdFor(subject),
-    signerFor: (subject) => resolved().signerFor(subject),
-    assertSealed: (subject, stated) => resolved().assertSealed(subject, stated),
-  });
-}
-
-const isOci = (row) => row.bundleSource?.kind === OCI_BUNDLE_SOURCE_KIND;
-
-/** Every OCI subject of a lock: each biome and each host module whose `bundleSource` is OCI, with the biome's origin and repo. */
-export function lockBundleSubjects(lock) {
-  return lock.biomes.flatMap((biome) => [
-    ...(isOci(biome) ? [{ row: biome, subject: { biomeId: biome.id, origin: biome.origin, repo: biome.repo, source: biome.source, bundleSource: biome.bundleSource } }] : []),
-    ...(biome.hostModules ?? [])
-      .filter(isOci)
-      .map((hostModule) => ({
-        row: hostModule,
-        subject: { biomeId: biome.id, componentKey: hostModule.componentKey, origin: biome.origin, repo: biome.repo, source: biome.source, bundleSource: hostModule.bundleSource },
-      })),
-  ]);
-}
-
-/**
- * Refuse a lock whose OCI rows do not state exactly the bundle signer the selection picks for them. A lock with no OCI
- * row is never checked and never resolves a data root: `selection` is used when given, else the data root's is loaded
- * on the first OCI subject.
- */
-export function assertLockBundleSigners({ lock, selection, schemas, gitSourcedBundle = GitSourcedBundle.Refused }) {
-  const subjects = lockBundleSubjects(lock);
-  if (subjects.length === 0) {return;}
-  const chosen = selection ?? loadBundleSignerSelection({ dataRoot: dataRoot(), schemas, gitSourcedBundle });
-  collectRefusals(subjects, ({ row, subject }) => {
-    chosen.assertAdmitted(subject);
-    chosen.assertSealed(subject, row.bundleSigner);
-  }, isRefusal, BundleSignerRefusedError);
-}

package/edition/map-with-concurrency.mjs

@@ -1,19 +0,0 @@
-// map-with-concurrency — run an async worker over a list with a bounded number in flight.
-
-/**
- * `worker(item, index)` for every item, at most `limit` at a time; the results
- * keep the items' order. The first rejection rejects the whole call.
- */
-export async function mapWithConcurrency(items, limit, worker) {
-  const results = new Array(items.length);
-  let cursor = 0;
-  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
-    while (cursor < items.length) {
-      const index = cursor;
-      cursor += 1;
-      results[index] = await worker(items[index], index);
-    }
-  });
-  await Promise.all(runners);
-  return results;
-}

package/edition/no-follow-file.mjs

@@ -1,94 +0,0 @@
-// Read one file under a root as exact bytes: contained in the root after
-// realpath, opened no-follow and non-blocking (a FIFO cannot stall the open),
-// in a parent directory that is the one the containment check resolved, a
-// regular file within a size bound, and unchanged while it was read. Shared by
-// every reader of operator-stated or evidence inputs; it imports nothing from
-// the library, so any module may use it.
-
-import {
-  closeSync,
-  constants as fsConstants,
-  fstatSync,
-  openSync,
-  readSync,
-  realpathSync,
-  statSync,
-} from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-
-export function readBoundedNoFollowFile(root, candidate, label, maxBytes) {
-  if (
-    typeof candidate !== 'string' ||
-    candidate.length === 0 ||
-    isAbsolute(candidate)
-  ) {
-    throw new Error(`${label} must be a repository-relative path`);
-  }
-  const rootReal = realpathSync(root);
-  const lexicalPath = resolve(rootReal, candidate);
-  const directoryReal = realpathSync(dirname(lexicalPath));
-  const rel = relative(rootReal, directoryReal);
-  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-    throw new Error(`${label} escapes its evidence root`);
-  }
-  const path = join(directoryReal, basename(lexicalPath));
-  const directoryChecked = statSync(directoryReal);
-  let descriptor;
-  try {
-    descriptor = openSync(
-      path,
-      fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK,
-    );
-  } catch (error) {
-    if (error?.code === 'ELOOP') {
-      throw new Error(
-        `${label} escapes its evidence root or is not a no-follow file`,
-      );
-    }
-    throw error;
-  }
-  try {
-    // The containment check resolved `directoryReal`; a directory swapped in
-    // under that path between the check and the open is not the one checked.
-    const directoryOpened = statSync(directoryReal);
-    if (
-      directoryOpened.dev !== directoryChecked.dev ||
-      directoryOpened.ino !== directoryChecked.ino ||
-      realpathSync(directoryReal) !== directoryReal
-    ) {
-      throw new Error(`${label}'s directory changed while it was opened`);
-    }
-    const before = fstatSync(descriptor);
-    if (!before.isFile()) {
-      throw new Error(`${label} must be a no-follow regular file`);
-    }
-    if (before.size > maxBytes) {
-      throw new Error(`${label} exceeds ${maxBytes} bytes`);
-    }
-    const bytes = Buffer.alloc(before.size);
-    let offset = 0;
-    while (offset < bytes.length) {
-      const count = readSync(
-        descriptor,
-        bytes,
-        offset,
-        bytes.length - offset,
-        offset,
-      );
-      if (count === 0) {throw new Error(`${label} was truncated while reading`);}
-      offset += count;
-    }
-    if (readSync(descriptor, Buffer.alloc(1), 0, 1, offset) !== 0) {
-      throw new Error(`${label} grew while reading`);
-    }
-    const after = fstatSync(descriptor);
-    for (const field of ['dev', 'ino', 'size', 'mtimeMs', 'ctimeMs']) {
-      if (after[field] !== before[field]) {
-        throw new Error(`${label} changed while reading`);
-      }
-    }
-    return { path, bytes };
-  } finally {
-    closeSync(descriptor);
-  }
-}