@xemahq/xema 0.26.0 → 0.28.0

package/edition/resolve-customer-edition.mjs

@@ -0,0 +1,288 @@
+// resolve-customer-edition — resolve a CUSTOMER edition against a catalogue.
+//
+//   resolve-edition.mjs <root flags> --definition <file> --catalogue oci://<repo>@sha256:<digest>
+//       --channel release|develop --out <dir> [--source-image <source>=<registry>/<prefix>]...
+//       [--catalogue-username <name> --catalogue-token-env <VAR>]
+//
+// The catalogue (catalogue.mjs) is the CEILING: it supplies availability, pins,
+// image digests, chart-set rows and the contract authority, and never adds a
+// component. The resolved set is the customer's positive selections, every
+// installationClass core entry of the catalogue and the transitive declared
+// dependencies; a component the offering gains later stays out unless selected.
+// Vendor image rows are COPIED from the catalogue (re-homed under the declared
+// imageRegistryMirror, digests untouched); the customer's own sources resolve
+// as they always have.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { AUTHORIZATION_LOCK_FILENAME, writeAuthorizationLock } from './authorization-base.mjs';
+import { CATALOGUE_FILE, CatalogueError } from './catalogue.mjs';
+import {
+  assertTrustCeilingAssignsCustomerBiomes,
+  mirrorVendorSubjects,
+  parseCustomerDefinition,
+  parseImageRegistryMirror,
+} from './customer-definition.mjs';
+import { assertRosteredChartSetLock } from './edition-chart-set.mjs';
+import { EditionLockFile } from './edition-constants.mjs';
+import { editionsRoot } from './edition-workspace.mjs';
+import { validateKernelContractAuthorityFromGit } from './kernel-contract-authority.mjs';
+import { compareStrings, loadKernelDistributionSchemas, serializeJson, validateImmutableImageLock } from './lib.mjs';
+import { pinnedSource, snapshotPinSource } from './pin-source.mjs';
+import { composeAuthorizationBase, composeManifest, resolveDistributionWithIndex, UnknownSelectionError } from './resolve-distribution.mjs';
+import { resolveImages } from './resolve-images.mjs';
+
+/** A selection or dependency the catalogue does not offer: the catalogue is the ceiling. */
+export class CatalogueCeilingError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CatalogueCeilingError';
+  }
+}
+
+/**
+ * The catalogue's declared ceiling, read by the kernel's two grammars: `trustPolicy` is the
+ * offering's origin allow list, `trustCeiling` its trust-domain assignments. `null` states none.
+ */
+function catalogueCeiling(catalogue, schemas) {
+  const read = (key, schema) => {
+    const value = catalogue.ceiling[key];
+    if (value === null) {return undefined;}
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+      throw new CatalogueError(
+        `${CATALOGUE_FILE}: ceiling.${key} of "${catalogue.offeringId}" is not the kernel's shape: ` +
+          parsed.error.issues.map((issue) => `[${issue.path.join('.')}] ${issue.message}`).join('; '),
+      );
+    }
+    return parsed.data;
+  };
+  return { trustPolicy: read('trustPolicy', schemas.DistributionTrustPolicySchema), trustCeiling: read('trustCeiling', schemas.ProcessTrustPolicySchema) };
+}
+
+/**
+ * The ceiling policy the customer's lock is written under: the catalogue's assignments, then
+ * the definition's for what the catalogue leaves open. An assignment of the definition that
+ * names a domain the catalogue assigns, or a biome the catalogue places, is not carried: the
+ * catalogue's reading stands, and `assertWithinCatalogueCeiling` refuses the difference.
+ */
+function ceilingUnderCatalogue(catalogueTrustCeiling, definitionTrustCeiling) {
+  if (catalogueTrustCeiling === undefined) {return definitionTrustCeiling;}
+  const domains = new Set(catalogueTrustCeiling.assignments.map((assignment) => assignment.domain));
+  const placed = new Set(catalogueTrustCeiling.assignments.flatMap((assignment) => assignment.biomes));
+  const open = (definitionTrustCeiling?.assignments ?? [])
+    .filter((assignment) => !domains.has(assignment.domain))
+    .map((assignment) => ({ domain: assignment.domain, biomes: assignment.biomes.filter((biome) => !placed.has(biome)) }))
+    .filter((assignment) => assignment.biomes.length > 0);
+  return { assignments: [...catalogueTrustCeiling.assignments, ...open] };
+}
+
+/**
+ * Every customer-source biome sits in the domain its definition names, and that is the domain
+ * the catalogue's ceiling admits for it: the lock row carries the kernel's derivation
+ * (`deriveTrustCeiling`) under `ceilingUnderCatalogue`, so a definition that reaches into a
+ * domain the catalogue assigns, or moves a biome the catalogue places, differs from it here.
+ */
+function assertWithinCatalogueCeiling({ catalogue, definition, lock, schemas }) {
+  const stated = new Map((definition.trustCeiling?.assignments ?? []).flatMap((assignment) => assignment.biomes.map((biome) => [biome, assignment.domain])));
+  for (const biome of lock.biomes.filter((candidate) => candidate.source !== undefined)) {
+    const admitted = biome.trustCeiling ?? schemas.defaultTrustDomain(biome.id, biome.origin);
+    if (stated.get(biome.id) !== admitted) {
+      throw new CatalogueCeilingError(
+        `catalogue "${catalogue.offeringId}" (${catalogue.channel}): "${definition.id}" assigns biome "${biome.id}" to trust domain ` +
+          `"${stated.get(biome.id)}", and the catalogue's trustCeiling admits "${admitted}" for it`,
+      );
+    }
+  }
+}
+
+/** `{name -> {imageRegistry, imageNamePrefix}}` from repeated `<source>=<registry>/<prefix>` values; the prefix is the text after the last "/". */
+export function parseSourceImages(values) {
+  const byName = new Map();
+  for (const value of values) {
+    const eq = value.indexOf('=');
+    const slash = value.lastIndexOf('/');
+    if (eq <= 0 || slash < eq + 2) {
+      throw new Error(`--source-image ${JSON.stringify(value)} is not <source>=<registry>/<prefix> (the prefix may be empty: "<source>=<registry>/")`);
+    }
+    const name = value.slice(0, eq);
+    if (byName.has(name)) {throw new Error(`--source-image names source "${name}" twice`);}
+    byName.set(name, { imageRegistry: value.slice(eq + 1, slash), imageNamePrefix: value.slice(slash + 1) });
+  }
+  return byName;
+}
+
+/**
+ * The definition's sources with the configured registry/prefix injected; every declared source needs its --source-image.
+ * With `pins` (a develop customer edition) each source's ref is the frozen commit of its `sources/<name>` pin.
+ */
+function withSourceImages(definition, sourceImages, pins) {
+  const declared = new Set((definition.sources ?? []).map((source) => source.name));
+  for (const name of sourceImages.keys()) {
+    if (!declared.has(name)) {throw new Error(`--source-image names source "${name}", which the definition does not declare (declared: ${[...declared].join(', ') || 'none'})`);}
+  }
+  return (definition.sources ?? []).map((source) => {
+    const image = sourceImages.get(source.name);
+    if (image === undefined) {throw new Error(`source "${source.name}" has no --source-image ${source.name}=<registry>/<prefix>: the registry is configuration and has no default`);}
+    const pinned = pins === undefined ? source : pinnedSource(source, snapshotPinSource(pins));
+    return { ...pinned, ...image };
+  });
+}
+
+/** The composition of a customer definition over the catalogue. */
+export function composeCustomerEdition({ schemas, definition, mirror, catalogue, sourceImages, pins }) {
+  const ceiling = catalogueCeiling(catalogue, schemas);
+  const manifest = schemas.parseDistribution({ ...definition, ...(definition.sources === undefined ? {} : { sources: withSourceImages(definition, sourceImages, pins) }) });
+  if (definition.sources === undefined && sourceImages.size > 0) {
+    throw new Error('--source-image given, but the definition declares no sources');
+  }
+  const composed = composeManifest(manifest);
+  return {
+    ...composed,
+    // The catalogue is the ceiling: its origin allow list is the one this resolve applies
+    // (a definition states none), and its domain assignments come before the definition's.
+    trustPolicy: ceiling.trustPolicy,
+    trustCeiling: ceilingUnderCatalogue(ceiling.trustCeiling, composed.trustCeiling),
+    platformServices: new Map(
+      catalogue.platformServices.map((row) => [row.name, { name: row.name, tier: row.tier, installationClass: row.installationClass }]),
+    ),
+    webProducerRepos: [...new Set(catalogue.images.webBiomes.map((biome) => biome.repo))],
+    mirror: parseImageRegistryMirror(mirror),
+  };
+}
+
+const subjectKey = (subject) => `${subject.kind}\0${subject.id}`;
+const compareSubjects = (a, b) => compareStrings(a.kind, b.kind) || compareStrings(a.id, b.id);
+
+/** The vendor image rows of the customer's lock: copied from the catalogue, owners narrowed to the selection. */
+export function projectVendorImages(catalogue, lock, enums) {
+  const biomes = new Set(lock.biomes.filter((biome) => biome.source === undefined).map((biome) => biome.id));
+  const services = new Set(lock.platformServices.map((service) => service.name));
+  const subjects = [];
+  for (const subject of catalogue.images.subjects) {
+    const owners = subject.owners.filter((owner) =>
+      owner.kind === enums.RuntimeImageOwnerKind.Biome ? biomes.has(owner.biomeId) : services.has(owner.platformService),
+    );
+    if (owners.length > 0) {subjects.push({ ...subject, owners });}
+  }
+  const have = new Set(subjects.filter((s) => s.owners.some((o) => o.kind === enums.RuntimeImageOwnerKind.Biome)).flatMap((s) => s.owners.map((o) => `${o.biomeId}\0${s.kind}\0${s.id}`)));
+  for (const biome of lock.biomes.filter((b) => b.source === undefined && b.target !== 'web')) {
+    const shared = new Set(Object.keys(biome.workerImages ?? {}));
+    const wanted = [
+      ...(biome.services ?? []).filter((id) => !shared.has(id)).map((id) => [enums.RuntimeImageSubjectKind.Service, id]),
+      ...(biome.runtimeComponents ?? []).map((id) => [enums.RuntimeImageSubjectKind.RuntimeComponent, id]),
+    ];
+    for (const [kind, id] of wanted) {
+      if (!have.has(`${biome.id}\0${kind}\0${id}`)) {
+        throw new CatalogueCeilingError(`the catalogue carries no image row for ${kind}:${id} of selected biome "${biome.id}"`);
+      }
+    }
+  }
+  return {
+    subjects,
+    platformServiceBindings: catalogue.images.platformServiceBindings.filter((binding) => services.has(binding.platformService)),
+    webBiomes: catalogue.images.webBiomes.filter((biome) => biomes.has(biome.biomeId)),
+  };
+}
+
+/** The customer's image lock: vendor rows copied (and mirrored), own rows resolved. */
+export async function resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn }) {
+  const vendor = projectVendorImages(catalogue, lock, schemas);
+  const vendorSubjects = mirrorVendorSubjects(vendor.subjects, composed.mirror);
+  const ownBiomes = lock.biomes.filter((biome) => biome.source !== undefined);
+  let own = { subjects: [], platformServiceBindings: [], webBiomes: [] };
+  if (ownBiomes.length > 0) {
+    const ownLock = { ...lock, biomes: ownBiomes, platformServices: [] };
+    const runtimeImageSourceIndex = {
+      contractAuthority: catalogue.contractAuthority,
+      repositoryPins: [],
+      platformServiceBindings: [],
+      supplementalSubjects: [],
+      crossRepoBuildInputs: [],
+      buildStepContextDirectories: [],
+    };
+    own = (await resolveImages(id, { inputs: { ...inputs, runtimeImageSourceIndex, composed }, lock: ownLock })).imageLock;
+    if (sealOwn !== undefined) {own = await sealOwn(own);}
+  }
+  const seen = new Set(vendorSubjects.map(subjectKey));
+  const clash = own.subjects.find((subject) => seen.has(subjectKey(subject)));
+  if (clash !== undefined) {throw new Error(`the customer's own image ${clash.kind}:${clash.id} collides with a catalogue image of the same identity`);}
+  return validateImmutableImageLock(
+    schemas.parseImageLock({
+      schemaVersion: 3,
+      sourceHashAlgorithm: catalogue.images.sourceHashAlgorithm,
+      distributionId: id,
+      contractAuthority: catalogue.contractAuthority,
+      subjects: [...vendorSubjects, ...own.subjects].sort(compareSubjects),
+      platformServiceBindings: [...vendor.platformServiceBindings, ...own.platformServiceBindings].sort((a, b) => compareStrings(a.platformService, b.platformService)),
+      webBiomes: [...vendor.webBiomes, ...own.webBiomes].sort((a, b) => compareStrings(a.biomeId, b.biomeId)),
+    }),
+    schemas,
+  );
+}
+
+/** The kernel at --kernel must carry the contract the catalogue's offering was resolved under. */
+export async function assertKernelAtCatalogueAuthority(catalogue, schemas) {
+  await validateKernelContractAuthorityFromGit({ authority: catalogue.contractAuthority, schemas, requireHeadMatch: false });
+}
+
+/**
+ * The distribution and authorization locks of the customer edition `rawDefinition`
+ * against `catalogue`. `catalogueDigest` is the digest of `catalogue`, written into the lock. `verifyAuthority` and `materialize` are injectable for the test suites.
+ */
+export async function resolveCustomerDistribution({
+  rawDefinition,
+  catalogue,
+  catalogueDigest,
+  sourceImages,
+  pins,
+  materialize,
+  verifyAuthority = assertKernelAtCatalogueAuthority,
+}) {
+  if (catalogueDigest === undefined) {throw new CatalogueError('a customer resolve names the digest of its catalogue');}
+  const schemas = await loadKernelDistributionSchemas();
+  const { definition, mirror } = parseCustomerDefinition(schemas, rawDefinition);
+  const composed = composeCustomerEdition({ schemas, definition, mirror, catalogue, sourceImages, pins });
+  const id = composed.leaf.id;
+  const inputs = { composed, biomeIndex: catalogue.biomes, platformServiceIndex: { schemaVersion: 1, services: catalogue.platformServices } };
+  let resolved;
+  try {
+    resolved = await resolveDistributionWithIndex(id, { inputs, ...(materialize === undefined ? {} : { materialize }) });
+  } catch (error) {
+    if (error instanceof UnknownSelectionError) {
+      throw new CatalogueCeilingError(`catalogue "${catalogue.offeringId}" (${catalogue.channel}) does not offer what "${id}" needs: ${error.message}`);
+    }
+    throw error;
+  }
+  const { lock, index } = resolved;
+  assertTrustCeilingAssignsCustomerBiomes(schemas, definition, lock.biomes.filter((biome) => biome.source !== undefined).map((biome) => biome.id));
+  assertWithinCatalogueCeiling({ catalogue, definition, lock, schemas });
+  await verifyAuthority(catalogue, schemas);
+  const authorizationLock = await composeAuthorizationBase(id, lock, index);
+  // A customer lock names the catalogue it was resolved against; seal and verify refuse any other.
+  return { id, schemas, composed, inputs, lock: { ...lock, catalogueDigest }, authorizationLock };
+}
+
+/** Resolve the customer edition of `channel` against `catalogue`; returns the four locks. `sealOwn` seals the customer's OWN image rows only (a develop edition); vendor rows arrive sealed. */
+export async function resolveCustomerEdition(request) {
+  const { id, schemas, composed, inputs, lock, authorizationLock } = await resolveCustomerDistribution(request);
+  const { catalogue } = request;
+  const imageLock = await resolveCustomerImages({ id, catalogue, lock, composed, schemas, inputs, sealOwn: request.sealOwn });
+  // The chart-set is copied whole, so it carries the coordinates of the channel it was published on:
+  // the edition being written states its channel, and a chart-set of the other one is refused here.
+  const chartSetLock = assertRosteredChartSetLock(catalogue.chartSet, `the catalogue's chart-set of "${catalogue.offeringId}"`, request.channel);
+  return { id, distributionLock: lock, imageLock, authorizationLock, chartSetLock };
+}
+
+/** Write the four locks to `<out>/<id>/` (the layout of an editions root). */
+export function writeCustomerEdition(out, { id, distributionLock, imageLock, authorizationLock, chartSetLock }) {
+  if (out !== editionsRoot()) {throw new CatalogueError(`the customer edition is written into the editions root (${editionsRoot()}), not ${out}`);}
+  const dir = join(out, id);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, EditionLockFile.Distribution), serializeJson(distributionLock));
+  writeFileSync(join(dir, EditionLockFile.Images), serializeJson(imageLock));
+  writeFileSync(join(dir, EditionLockFile.ChartSet), serializeJson(chartSetLock));
+  writeAuthorizationLock(dir, authorizationLock, serializeJson);
+  return { dir, authorization: AUTHORIZATION_LOCK_FILENAME };
+}