@githolon/dsl 0.113.4 → 0.114.0

package/src/release_publication.ts

@@ -0,0 +1,298 @@
+// A published domain release, as bytes: its identity and the verification every publisher and the console
+// apply to the uploaded units (architecture/domain_release_lifecycle.md, "Publish candidate").
+//
+// A release is a complete law unit set (architecture/law_units_format.md): framework, composition and the
+// domain units the compiler emitted, each named by its unit hash. Publishing it verifies every byte against
+// the unit hashes the kernel also derives, and names the release by an identity over its series, its
+// predecessor and its exact (key, unit hash) set. Publication installs nothing: each target's kernel
+// admits the same units again, from their content, when it is asked to stage them.
+//
+// Node-free (WebCrypto only), so the console Worker, the CLI and CI verify with this one module. The unit
+// hash and canonical manifest follow `law_units.ts` (`lawUnitHash`, `unitManifestUsda`) and the kernel's
+// `DomainLawUnit`; `release_publication.test.ts` proves agreement on compiled units.
+
+import { lawUnitSetIdentityPreimage } from "./law_unit_set_identity.ts";
+
+export const RELEASE_IDENTITY_TAG = "nomos-domain-release-v1";
+const LAW_UNIT_HASH_TAG = "nomos-law-unit-v1";
+const LAW_UNIT_FORMAT = "nomos.law-unit.v1";
+export const LAW_UNIT_MANIFEST = "unit.usda";
+
+/** The first release of a series names this as its predecessor. Explicit, never an empty default. */
+export const NO_PREDECESSOR = "none";
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const SERIES = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;
+const UNIT_KEY = /^(framework|composition|domain:[A-Za-z_][A-Za-z0-9_.-]{0,127})$/;
+/** Largest single file a release may carry (one upload request; the console's content store holds it in parts). */
+export const MAX_RELEASE_FILE_BYTES = 32_000_000;
+export const MAX_RELEASE_FILES = 4096;
+
+export interface ReleaseFile {
+  /** The file's logical path inside its unit (`unit.usda` is the manifest). */
+  readonly path: string;
+  readonly sha256: string;
+  readonly size: number;
+}
+
+export interface ReleaseUnit {
+  readonly key: string;
+  readonly unitHash: string;
+  /** Every file of the unit, the manifest included, sorted by path. */
+  readonly files: readonly ReleaseFile[];
+}
+
+export interface ReleaseCandidate {
+  /** The published domain identity this release continues: one of its domain keys. */
+  readonly series: string;
+  /** The release identity this one follows, or {@link NO_PREDECESSOR}. */
+  readonly predecessor: string;
+  readonly units: readonly ReleaseUnit[];
+}
+
+/** A refusal with a stable code; a client never parses the message. */
+export class ReleaseVerificationError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const refuse = (code: string, message: string): never => {
+  throw new ReleaseVerificationError(code, message);
+};
+
+const utf8 = (text: string): Uint8Array => new TextEncoder().encode(text);
+const byteOrder = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+const hex = (bytes: ArrayBuffer): string =>
+  [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+
+export async function sha256Hex(input: Uint8Array | string): Promise<string> {
+  const bytes = typeof input === "string" ? utf8(input) : input;
+  return hex(await crypto.subtle.digest("SHA-256", bytes as Uint8Array<ArrayBuffer>));
+}
+
+/** One concatenation of tagged, NUL-separated fields, hashed once. */
+async function taggedHash(parts: readonly string[]): Promise<string> {
+  return sha256Hex(parts.join(""));
+}
+
+/**
+ * The release identity: sha256("nomos-domain-release-v1\0" series "\0" predecessor "\0"
+ * { key "\0" unitHash "\0" }*), units sorted by key in byte order. Two clients that publish the same
+ * set over the same predecessor publish the same release; nothing else (who, when, evidence) moves it.
+ */
+export async function releaseIdentity(candidate: {
+  readonly series: string;
+  readonly predecessor: string;
+  readonly units: readonly { readonly key: string; readonly unitHash: string }[];
+}): Promise<string> {
+  const parts = [`${RELEASE_IDENTITY_TAG}\0`, candidate.series, "\0", candidate.predecessor, "\0"];
+  for (const unit of [...candidate.units].sort((l, r) => byteOrder(l.key, r.key))) {
+    parts.push(unit.key, "\0", unit.unitHash, "\0");
+  }
+  return taggedHash(parts);
+}
+
+/**
+ * THE LAW IDENTITY of a unit set (law_unit_set_identity.ts; the kernel's `law_unit_set_identity`): its sorted
+ * (key, unit hash) pairs and nothing else. A release names it through its units; every target realises it as a
+ * closure that also depends on the target kernel's composer, which is why a receipt records both.
+ */
+export async function lawUnitSetIdentity(units: readonly { readonly key: string; readonly unitHash: string }[]): Promise<string> {
+  return sha256Hex(lawUnitSetIdentityPreimage(units));
+}
+
+/** The unit hash (law_units.ts `lawUnitHash`, the kernel's `DomainLawUnit`), over WebCrypto. */
+export async function lawUnitHashOf(
+  key: string,
+  inventory: readonly { readonly logicalPath: string; readonly sha256: string }[],
+  routes: readonly { readonly selector: string; readonly planSha256: string }[],
+): Promise<string> {
+  const parts = [`${LAW_UNIT_HASH_TAG}\0`, key, "\0", "assets\0"];
+  for (const asset of [...inventory].sort((l, r) => byteOrder(l.logicalPath, r.logicalPath))) {
+    parts.push(asset.logicalPath, "\0", asset.sha256, "\0");
+  }
+  parts.push("routes\0");
+  for (const route of [...routes].sort((l, r) => byteOrder(l.selector, r.selector))) {
+    parts.push(route.selector, "\0", route.planSha256, "\0");
+  }
+  return taggedHash(parts);
+}
+
+interface ParsedManifest {
+  readonly key: string;
+  readonly kind: "domain" | "framework" | "composition";
+  readonly domain?: string;
+  readonly hash: string;
+  readonly assets: readonly { readonly logicalPath: string; readonly sha256: string }[];
+  readonly routes: readonly { readonly selector: string; readonly planSha256: string }[];
+}
+
+/** The compiler's canonical manifest (law_units.ts `unitManifestUsda`), over WebCrypto. */
+async function canonicalManifest(unit: ParsedManifest): Promise<string> {
+  const assetPrims = await Promise.all(unit.assets.map(async (asset) => [
+    `        def NomosLawAsset "a_${await sha256Hex(asset.logicalPath)}"`,
+    "        {",
+    `            custom string nomos:logicalPath = ${JSON.stringify(asset.logicalPath)}`,
+    `            custom string nomos:sha256 = "${asset.sha256}"`,
+    "        }",
+  ]));
+  const routePrims = await Promise.all(unit.routes.map(async (route) => [
+    `        def NomosLawRoute "s_${await sha256Hex(route.selector)}"`,
+    "        {",
+    `            custom string nomos:selector = ${JSON.stringify(route.selector)}`,
+    `            custom string nomos:plan = "${route.planSha256}"`,
+    "        }",
+  ]));
+  return [
+    "#usda 1.0",
+    "(",
+    '    defaultPrim = "__NomosLawUnit_7e9c"',
+    "    customLayerData = {",
+    `        string "nomos:format" = "${LAW_UNIT_FORMAT}"`,
+    "    }",
+    ")",
+    "",
+    'def NomosLawUnit "__NomosLawUnit_7e9c"',
+    "{",
+    `    custom string nomos:unit = ${JSON.stringify(unit.key)}`,
+    `    custom token nomos:unitKind = "${unit.kind}"`,
+    ...(unit.domain === undefined ? [] : [`    custom string nomos:domain = ${JSON.stringify(unit.domain)}`]),
+    `    custom string nomos:unitHash = "${unit.hash}"`,
+    "",
+    '    def Scope "Assets"',
+    "    {",
+    ...assetPrims.flat(),
+    "    }",
+    "",
+    '    def Scope "Routes"',
+    "    {",
+    ...routePrims.flat(),
+    "    }",
+    "}",
+    "",
+  ].join("\n");
+}
+
+const LITERAL = '("(?:[^"\\\\]|\\\\.)*")';
+function attribute(source: string, name: string, where: string): string {
+  const values = [...source.matchAll(new RegExp(`nomos:${name} = ${LITERAL}`, "g"))];
+  if (values.length !== 1) refuse("manifest-invalid", `${where}: expected one nomos:${name}`);
+  return JSON.parse(values[0]![1]!) as string;
+}
+
+/**
+ * Read a unit manifest in the compiler's canonical dialect only (release_inspection.ts
+ * `readInspectionUnits`): the attributes it names, then a byte-for-byte round trip through the canonical
+ * emitter. Any other spelling is refused rather than interpreted.
+ */
+export async function parseUnitManifest(source: string, where: string): Promise<ParsedManifest> {
+  const key = attribute(source, "unit", where);
+  const kind = attribute(source, "unitKind", where) as ParsedManifest["kind"];
+  if (!["domain", "framework", "composition"].includes(kind)) refuse("manifest-invalid", `${where}: unknown unit kind '${kind}'`);
+  const hash = attribute(source, "unitHash", where);
+  const domain = kind === "domain" ? attribute(source, "domain", where) : undefined;
+  if (key !== (domain === undefined ? kind : `domain:${domain}`)) refuse("manifest-invalid", `${where}: unit key and kind disagree`);
+  const assets = [...source.matchAll(/def NomosLawAsset "[^"]+"\s*\{([^}]+)\}/g)].map((match) => ({
+    logicalPath: attribute(match[1]!, "logicalPath", where), sha256: attribute(match[1]!, "sha256", where),
+  }));
+  const routes = [...source.matchAll(/def NomosLawRoute "[^"]+"\s*\{([^}]+)\}/g)].map((match) => ({
+    selector: attribute(match[1]!, "selector", where), planSha256: attribute(match[1]!, "plan", where),
+  }));
+  const parsed: ParsedManifest = { key, kind, ...(domain === undefined ? {} : { domain }), hash, assets, routes };
+  if (await canonicalManifest(parsed) !== source) refuse("manifest-noncanonical", `${where}: the manifest is not in the compiler's canonical form`);
+  return parsed;
+}
+
+const safePath = (path: string): boolean =>
+  path.length > 0 && path.length <= 512 && !path.startsWith("/") && !path.includes("\\")
+  && path.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+
+/** Shape checks that need no bytes: sorted, unique, complete, well-formed. */
+export function checkReleaseShape(candidate: ReleaseCandidate): void {
+  if (!SERIES.test(candidate.series)) refuse("release-invalid", "series must be a domain key");
+  if (candidate.predecessor !== NO_PREDECESSOR && !HEX64.test(candidate.predecessor)) {
+    refuse("release-invalid", `predecessor must be a release identity or '${NO_PREDECESSOR}'`);
+  }
+  const keys = candidate.units.map((unit) => unit.key);
+  if (!keys.every((key) => UNIT_KEY.test(key))) refuse("release-invalid", "every unit key is framework, composition or domain:<key>");
+  if (!keys.every((key, index) => index === 0 || byteOrder(keys[index - 1]!, key) < 0)) {
+    refuse("release-invalid", "units must be sorted by key, without repeats");
+  }
+  for (const required of ["framework", "composition", `domain:${candidate.series}`]) {
+    if (!keys.includes(required)) {
+      refuse("release-incomplete", `a release is a complete unit set; it lacks '${required}' (publish the compiler's whole build/<name>.units)`);
+    }
+  }
+  let files = 0;
+  for (const unit of candidate.units) {
+    if (!HEX64.test(unit.unitHash)) refuse("release-invalid", `${unit.key}: unitHash must be sha256 hex`);
+    const paths = unit.files.map((file) => file.path);
+    if (!paths.every((path, index) => index === 0 || byteOrder(paths[index - 1]!, path) < 0)) {
+      refuse("release-invalid", `${unit.key}: files must be sorted by path, without repeats`);
+    }
+    if (!paths.includes(LAW_UNIT_MANIFEST)) refuse("release-invalid", `${unit.key}: the unit carries no ${LAW_UNIT_MANIFEST}`);
+    for (const file of unit.files) {
+      if (!safePath(file.path)) refuse("release-invalid", `${unit.key}: unsafe file path '${file.path}'`);
+      if (!HEX64.test(file.sha256)) refuse("release-invalid", `${unit.key}/${file.path}: sha256 must be hex`);
+      if (!Number.isSafeInteger(file.size) || file.size < 0 || file.size > MAX_RELEASE_FILE_BYTES) {
+        refuse("release-invalid", `${unit.key}/${file.path}: size must be 0..${MAX_RELEASE_FILE_BYTES} bytes`);
+      }
+    }
+    files += unit.files.length;
+  }
+  if (files > MAX_RELEASE_FILES) refuse("release-invalid", `a release carries at most ${MAX_RELEASE_FILES} files`);
+}
+
+export interface VerifiedRelease {
+  readonly identity: string;
+  /** The law identity of its units ({@link lawUnitSetIdentity}). */
+  readonly unitSet: string;
+  readonly candidate: ReleaseCandidate;
+  /** The domain keys of its domain units, sorted. */
+  readonly serves: readonly string[];
+}
+
+/**
+ * Verify a release candidate against its bytes: every file is present and is exactly the bytes its digest
+ * names, every manifest is canonical and lists exactly the unit's files, and every unit hash re-derives.
+ * `read` answers a digest's bytes from a content store, or undefined when the store lacks it.
+ */
+export async function verifyRelease(
+  candidate: ReleaseCandidate,
+  read: (sha256: string) => Promise<Uint8Array | undefined>,
+): Promise<VerifiedRelease> {
+  checkReleaseShape(candidate);
+  for (const unit of candidate.units) {
+    const where = unit.key;
+    const bytesOf = new Map<string, Uint8Array>();
+    for (const file of unit.files) {
+      const bytes = await read(file.sha256);
+      if (!bytes) refuse("artifact-missing", `${where}/${file.path}: ${file.sha256} has not been uploaded`);
+      if (await sha256Hex(bytes!) !== file.sha256) refuse("artifact-digest-mismatch", `${where}/${file.path}: the stored bytes are not ${file.sha256}`);
+      if (bytes!.byteLength !== file.size) refuse("artifact-size-mismatch", `${where}/${file.path}: ${bytes!.byteLength} bytes, not ${file.size}`);
+      bytesOf.set(file.path, bytes!);
+    }
+    const manifest = await parseUnitManifest(new TextDecoder().decode(bytesOf.get(LAW_UNIT_MANIFEST)!), where);
+    if (manifest.key !== unit.key) refuse("unit-key-mismatch", `${where}: the manifest names unit '${manifest.key}'`);
+    const listed = [...manifest.assets.map((asset) => asset.logicalPath), LAW_UNIT_MANIFEST].sort(byteOrder);
+    const carried = unit.files.map((file) => file.path);
+    if (listed.length !== carried.length || listed.some((path, index) => path !== carried[index])) {
+      refuse("unit-inventory-mismatch", `${where}: the files carried are not exactly the files its manifest lists`);
+    }
+    for (const asset of manifest.assets) {
+      if (unit.files.find((file) => file.path === asset.logicalPath)!.sha256 !== asset.sha256) {
+        refuse("artifact-digest-mismatch", `${where}/${asset.logicalPath}: the manifest names another digest`);
+      }
+    }
+    const derived = await lawUnitHashOf(manifest.key, manifest.assets, manifest.routes);
+    if (derived !== manifest.hash || derived !== unit.unitHash) {
+      refuse("unit-hash-mismatch", `${where}: its content hashes to ${derived}, not ${unit.unitHash}`);
+    }
+  }
+  const serves = candidate.units.filter((unit) => unit.key.startsWith("domain:")).map((unit) => unit.key.slice("domain:".length)).sort(byteOrder);
+  return { identity: await releaseIdentity(candidate), unitSet: await lawUnitSetIdentity(candidate.units), candidate, serves };
+}