feat: Ekklesia Module Package v1, the canonical packager and verifier (ADR 0049)

A separately versioned module is now distributed as one deterministic
.tar.gz and its SHA-256, produced by an Ekklesia-owned packager and checked by
Core before anything is installed. This slice implements the portable `any`
target, with the module template as the end-to-end proof. ADR 0049 is
accepted.

@ekklesia/contracts: the Module Package v1 contract. The strict
ekklesia.package.json schema (packageFormat 1, identity, target, runtime,
provenance, incorporated Ekklesia packages, strict transitional facts, an
exact byte-wise-sorted file list with size and SHA-256), target names, and the
generated runtime package.json.

@ekklesia/module-pack (new, tooling): `ekklesia-pack-module --module <dir>
--target any --out <dir> --source-revision <commit>`.
- Bundles server, schema, and jobs with esbuild, SDK, contracts, and Drizzle
  included; only Node built-ins remain imports. Any warning, unresolved
  import, external dependency, or native or platform-specific package fails.
- Copies browser artifacts as built, after proving them current, and the
  migrations; generates package.json and ekklesia.package.json; never ships
  src, tests, declarations, source maps, or workspace ranges.
- THIRD_PARTY_NOTICES: every third-party package traced from the bundles'
  own inputs, credited once with its declared licence and every licence,
  copying, copyright, and notice file it ships. A missing licence fails; a
  missing text fails unless its standard text is complete without copyright
  lines (Apache-2.0, vendored, needed by drizzle-orm).
- Deterministic ustar and gzip: sorted paths, uid/gid 0, empty names, mtime
  0, 0755/0644, no links. Byte-identical across runs and machines.
- Writes only the archive and its .sha256; never deploys, links, or installs,
  so the workspace's install state is untouched.

Core: verifyModulePackage and `verify-module-package.js <archive>
[--sha256 | --sha256-file] [--extract-to <new dir>]`. Reads the archive in
memory and refuses links, special entries, setuid/setgid/sticky modes, unsafe
or escaping paths, and a second top-level directory; checks metadata, every
file, identity, target, Node.js range, SDK, and the transitional Drizzle
agreement; runs the platform's module and migration discovery; loads the
backend once in a forked process with an empty environment; only then
extracts, with normalized modes, into a new directory. Errors are sanitized.

@ekklesia/module-ui-build: analyzeModuleUi reports each artifact's inputs
and whether the built file is current. The nested stylesheet build now works
from the module directory, so artifacts no longer depend on the caller's
working directory.

The split deploy smoke builds the package with the canonical packager
(scripts/lib/build-module-package.Dockerfile replaces the test-only pnpm
deploy packaging), verifies it with the same generic image, installs the
verified tree, removes it, and reinstalls the exact same archive.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

core/src/modules/module-package-verification.ts

@@ -0,0 +1,479 @@
+import { fork } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  isVersionCompatible,
+  MODULE_PACKAGE_ANY_TARGET,
+  MODULE_PACKAGE_FORMAT,
+  MODULE_PACKAGE_METADATA_FILENAME,
+  type ModuleManifest,
+  type ModulePackageMetadata,
+  safeParseModuleManifest,
+  safeParseModulePackageMetadata,
+  safeParseModulePackageRuntimePackage,
+} from "@ekklesia/contracts";
+import { discoverModules, MODULE_MANIFEST_FILENAME, ModuleDiscoveryError } from "./discovery.js";
+import { discoverModuleMigrations, ModuleMigrationDiscoveryError } from "./migration-discovery.js";
+import {
+  type ModulePackageArchive,
+  ModulePackageArchiveError,
+  type ModulePackageArchiveErrorCode,
+  readModulePackageArchive,
+} from "./module-package-archive.js";
+import { discoverModuleSchemas, ModuleSchemaDiscoveryError } from "./schema-discovery.js";
+
+/**
+ * Verifies an Ekklesia Module Package v1 archive (ADR 0049) against the platform it runs on, without
+ * ever installing it.
+ *
+ * Order matters: everything that can be decided from bytes is decided before anything is written,
+ * and nothing is executed until the package has proven itself well-formed. The archive is read and
+ * checked for safety in memory; its metadata, every payload digest, and every identity statement
+ * are checked next; only then is it written to a fresh temporary directory, validated by the same
+ * discovery the platform uses, and its backend loaded once in a separate, short-lived process with
+ * an empty environment. A caller that asks for extraction gets the verified tree written to a new
+ * directory only after all of that succeeded.
+ *
+ * Errors carry a stable code and a fixed message. Paths, archive entry names, file contents, module
+ * output, and exception messages never appear in them: an archive is untrusted input, and none of
+ * it is ever echoed.
+ */
+
+export type ModulePackageVerificationErrorCode =
+  | ModulePackageArchiveErrorCode
+  | "MODULE_PACKAGE_DATABASE_RUNTIME_INCOMPATIBLE"
+  | "MODULE_PACKAGE_DIGEST_MISMATCH"
+  | "MODULE_PACKAGE_ENTRYPOINT_LOAD_FAILED"
+  | "MODULE_PACKAGE_EXTRACTION_FAILED"
+  | "MODULE_PACKAGE_FILE_MISMATCH"
+  | "MODULE_PACKAGE_FILE_MISSING"
+  | "MODULE_PACKAGE_FILE_UNLISTED"
+  | "MODULE_PACKAGE_FORMAT_UNSUPPORTED"
+  | "MODULE_PACKAGE_IDENTITY_MISMATCH"
+  | "MODULE_PACKAGE_MANIFEST_INVALID"
+  | "MODULE_PACKAGE_METADATA_INVALID"
+  | "MODULE_PACKAGE_METADATA_MISSING"
+  | "MODULE_PACKAGE_MODULE_INVALID"
+  | "MODULE_PACKAGE_NATIVE_FILE"
+  | "MODULE_PACKAGE_RUNTIME_INCOMPATIBLE"
+  | "MODULE_PACKAGE_RUNTIME_PACKAGE_INVALID"
+  | "MODULE_PACKAGE_SDK_INCOMPATIBLE"
+  | "MODULE_PACKAGE_TARGET_INCOMPATIBLE"
+  | "MODULE_PACKAGE_TRANSITIONAL_UNSUPPORTED";
+
+const messages: Readonly<Record<ModulePackageVerificationErrorCode, string>> = Object.freeze({
+  MODULE_PACKAGE_DATABASE_RUNTIME_INCOMPATIBLE:
+    "The package's bundled database runtime does not match this platform's (a transitional constraint).",
+  MODULE_PACKAGE_DIGEST_MISMATCH: "The archive does not match the SHA-256 it was given.",
+  MODULE_PACKAGE_ENTRYPOINT_LOAD_FAILED:
+    "A backend entrypoint could not be loaded from the package alone.",
+  MODULE_PACKAGE_EXTRACTION_FAILED:
+    "The verified package could not be extracted to a new directory.",
+  MODULE_PACKAGE_FILE_MISMATCH: "A payload file does not match its listed size or SHA-256.",
+  MODULE_PACKAGE_FILE_MISSING: "A file listed in the package metadata is missing from the archive.",
+  MODULE_PACKAGE_FILE_UNLISTED: "The archive contains a file the package metadata does not list.",
+  MODULE_PACKAGE_FORMAT_UNSUPPORTED: "The package format is not one this platform implements.",
+  MODULE_PACKAGE_IDENTITY_MISMATCH:
+    "The package metadata, runtime package.json, and manifest disagree about the module's identity.",
+  MODULE_PACKAGE_LAYOUT_INVALID:
+    "The archive must contain exactly one top-level module directory, with each path once.",
+  MODULE_PACKAGE_LINK: "The archive contains a link; module packages may contain none.",
+  MODULE_PACKAGE_MANIFEST_INVALID: "The package's module manifest is missing or invalid.",
+  MODULE_PACKAGE_METADATA_INVALID: "The package metadata is invalid.",
+  MODULE_PACKAGE_METADATA_MISSING: "The archive contains no package metadata.",
+  MODULE_PACKAGE_MODULE_INVALID: "The packaged module failed module validation.",
+  MODULE_PACKAGE_NATIVE_FILE: "An any-target package contains a native file.",
+  MODULE_PACKAGE_RUNTIME_INCOMPATIBLE:
+    "The package needs a Node.js version this host does not run.",
+  MODULE_PACKAGE_RUNTIME_PACKAGE_INVALID:
+    "The package's runtime package.json is not the generated runtime shape.",
+  MODULE_PACKAGE_SDK_INCOMPATIBLE:
+    "The Module SDK bundled into the package is outside the manifest's own moduleSdk range.",
+  MODULE_PACKAGE_SPECIAL_ENTRY:
+    "The archive contains an entry that is neither a directory nor a regular file.",
+  MODULE_PACKAGE_TARGET_INCOMPATIBLE: "The package's target is not one this platform can run.",
+  MODULE_PACKAGE_TOO_LARGE: "The archive exceeds the module package size limits.",
+  MODULE_PACKAGE_TRANSITIONAL_UNSUPPORTED:
+    "The package metadata contains transitional facts this platform does not understand.",
+  MODULE_PACKAGE_UNREADABLE: "The file is not a readable gzip-compressed ustar archive.",
+  MODULE_PACKAGE_UNSAFE_MODE: "The archive contains a setuid, setgid, or sticky entry.",
+  MODULE_PACKAGE_UNSAFE_PATH: "The archive contains an absolute, escaping, or non-portable path.",
+});
+
+export class ModulePackageVerificationError extends Error {
+  readonly code: ModulePackageVerificationErrorCode;
+  /** Stable discovery issue codes, when module validation failed; never their messages. */
+  readonly issueCodes: readonly string[];
+
+  constructor(code: ModulePackageVerificationErrorCode, issueCodes: readonly string[] = []) {
+    super(messages[code]);
+    this.name = "ModulePackageVerificationError";
+    this.code = code;
+    this.issueCodes = Object.freeze([...new Set(issueCodes)].sort());
+    this.stack = `${this.name}: ${this.message}`;
+    Object.freeze(this);
+  }
+}
+
+/** What this platform is, for the checks that compare a package against it. */
+export interface ModulePackagePlatform {
+  readonly platformVersion: string;
+  readonly moduleSdkVersion: string;
+  /** The transitional database runtime facts this platform requires a package to agree with. */
+  readonly databaseRuntime: Readonly<Record<string, string>>;
+  /** Defaults to the running process's Node.js version. */
+  readonly nodeVersion?: string;
+}
+
+export interface VerifyModulePackageOptions {
+  readonly archivePath: string;
+  /** When given, the archive's SHA-256 must equal it (lowercase hexadecimal). */
+  readonly expectedSha256?: string;
+  readonly platform: ModulePackagePlatform;
+  /** A directory that must not exist yet; the verified module directory is written there. */
+  readonly extractTo?: string;
+  readonly loadTimeoutMs?: number;
+}
+
+export interface ModulePackageVerificationResult {
+  readonly archiveSha256: string;
+  /** Payload files, the metadata file not included. */
+  readonly fileCount: number;
+  readonly moduleId: string;
+  readonly target: string;
+  readonly version: string;
+}
+
+function fail(code: ModulePackageVerificationErrorCode, issueCodes?: readonly string[]): never {
+  throw new ModulePackageVerificationError(code, issueCodes);
+}
+
+function sha256(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseJson(data: Buffer | undefined): unknown {
+  if (data === undefined) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(data.toString("utf8")) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The transitional facts this verifier understands, and nothing else (ADR 0049). */
+const UNDERSTOOD_TRANSITIONAL: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  databaseRuntime: Object.freeze(["drizzle-orm"]),
+});
+
+function checkTransitional(raw: Record<string, unknown>): void {
+  const transitional = raw.transitional;
+  if (transitional === undefined) {
+    return;
+  }
+  if (!isRecord(transitional)) {
+    fail("MODULE_PACKAGE_TRANSITIONAL_UNSUPPORTED");
+  }
+  for (const [key, value] of Object.entries(transitional)) {
+    const understood = UNDERSTOOD_TRANSITIONAL[key];
+    if (!understood || !isRecord(value)) {
+      fail("MODULE_PACKAGE_TRANSITIONAL_UNSUPPORTED");
+    }
+    if (Object.keys(value).some((name) => !understood.includes(name))) {
+      fail("MODULE_PACKAGE_TRANSITIONAL_UNSUPPORTED");
+    }
+  }
+}
+
+function readMetadata(files: ReadonlyMap<string, Buffer>): ModulePackageMetadata {
+  const raw = parseJson(files.get(MODULE_PACKAGE_METADATA_FILENAME));
+  if (!files.has(MODULE_PACKAGE_METADATA_FILENAME)) {
+    fail("MODULE_PACKAGE_METADATA_MISSING");
+  }
+  if (!isRecord(raw)) {
+    fail("MODULE_PACKAGE_METADATA_INVALID");
+  }
+  if (raw.packageFormat !== MODULE_PACKAGE_FORMAT) {
+    fail("MODULE_PACKAGE_FORMAT_UNSUPPORTED");
+  }
+  checkTransitional(raw);
+  const parsed = safeParseModulePackageMetadata(raw);
+  if (!parsed.success) {
+    fail("MODULE_PACKAGE_METADATA_INVALID");
+  }
+  return parsed.data;
+}
+
+function checkPayload(metadata: ModulePackageMetadata, files: ReadonlyMap<string, Buffer>): void {
+  const listed = new Set(metadata.files.map((file) => file.path));
+  for (const filePath of files.keys()) {
+    if (filePath !== MODULE_PACKAGE_METADATA_FILENAME && !listed.has(filePath)) {
+      fail("MODULE_PACKAGE_FILE_UNLISTED");
+    }
+  }
+  for (const file of metadata.files) {
+    const data = files.get(file.path);
+    if (data === undefined) {
+      fail("MODULE_PACKAGE_FILE_MISSING");
+    }
+    if (data.length !== file.size || sha256(data) !== file.sha256) {
+      fail("MODULE_PACKAGE_FILE_MISMATCH");
+    }
+  }
+}
+
+function checkIdentity(
+  archive: ModulePackageArchive,
+  metadata: ModulePackageMetadata,
+  files: ReadonlyMap<string, Buffer>,
+): ModuleManifest {
+  const runtimePackage = safeParseModulePackageRuntimePackage(parseJson(files.get("package.json")));
+  if (!runtimePackage.success) {
+    fail("MODULE_PACKAGE_RUNTIME_PACKAGE_INVALID");
+  }
+  const manifest = safeParseModuleManifest(parseJson(files.get(MODULE_MANIFEST_FILENAME)));
+  if (!manifest.success) {
+    fail("MODULE_PACKAGE_MANIFEST_INVALID");
+  }
+  if (
+    archive.topLevel !== metadata.module.id ||
+    manifest.data.id !== metadata.module.id ||
+    manifest.data.version !== metadata.module.version ||
+    runtimePackage.data.version !== metadata.module.version
+  ) {
+    fail("MODULE_PACKAGE_IDENTITY_MISMATCH");
+  }
+  return manifest.data;
+}
+
+function checkCompatibility(
+  metadata: ModulePackageMetadata,
+  manifest: ModuleManifest,
+  files: ReadonlyMap<string, Buffer>,
+  platform: ModulePackagePlatform,
+): void {
+  // This verifier implements the portable target only. Native targets are a later slice.
+  if (metadata.target !== MODULE_PACKAGE_ANY_TARGET) {
+    fail("MODULE_PACKAGE_TARGET_INCOMPATIBLE");
+  }
+  if ([...files.keys()].some((filePath) => filePath.toLowerCase().endsWith(".node"))) {
+    fail("MODULE_PACKAGE_NATIVE_FILE");
+  }
+  if (!isVersionCompatible(platform.nodeVersion ?? process.versions.node, metadata.runtime.node)) {
+    fail("MODULE_PACKAGE_RUNTIME_INCOMPATIBLE");
+  }
+  const sdk = metadata.incorporates["@ekklesia/module-sdk"];
+  if (sdk !== undefined && !isVersionCompatible(sdk, manifest.compatibility.moduleSdk)) {
+    fail("MODULE_PACKAGE_SDK_INCOMPATIBLE");
+  }
+  // Transitional (ADR 0049): today a module's Drizzle copy must be interchangeable with the
+  // platform's, because Core queries the module's tables with its own Drizzle instance. This is an
+  // implementation constraint pending a Module Database ABI, not that ABI.
+  for (const [runtime, version] of Object.entries(metadata.transitional?.databaseRuntime ?? {})) {
+    if (platform.databaseRuntime[runtime] !== version) {
+      fail("MODULE_PACKAGE_DATABASE_RUNTIME_INCOMPATIBLE");
+    }
+  }
+}
+
+/** Writes the archive's directories (`0755`) and files (`0644`) under `root`, which must not exist.
+ * Safe by construction: every path was validated as relative and non-escaping, and only directories
+ * and regular files exist. Ownership is the writing process's, never the archive's. */
+async function writeTree(root: string, archive: ModulePackageArchive): Promise<void> {
+  await mkdir(root, { mode: 0o755 });
+  await chmod(root, 0o755);
+  for (const entry of archive.entries) {
+    const target = path.join(root, ...entry.path.split("/"));
+    if (entry.type === "directory") {
+      await mkdir(target, { mode: 0o755, recursive: true });
+      await chmod(target, 0o755);
+    } else {
+      await mkdir(path.dirname(target), { mode: 0o755, recursive: true });
+      await writeFile(target, entry.data, { flag: "wx", mode: 0o644 });
+      await chmod(target, 0o644);
+    }
+  }
+}
+
+function probeEntrypointPath(): string {
+  // The probe sits beside this file: compiled `.js` in an installation, source `.ts` under a test
+  // runner, which Node runs directly. Either way it is a separate process.
+  const self = fileURLToPath(import.meta.url);
+  return path.join(path.dirname(self), `module-package-probe${path.extname(self)}`);
+}
+
+/** Loads every backend entrypoint in a short-lived child with an empty environment, and reports
+ * only whether each loaded and exported a definition naming this module. */
+async function loadEntrypoints(
+  moduleId: string,
+  version: string,
+  entrypoints: Readonly<Record<string, string>>,
+  timeoutMs: number,
+): Promise<void> {
+  const outcome = await new Promise<"ok" | "failed">((resolve) => {
+    let settled = false;
+    let child: ReturnType<typeof fork> | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (value: "ok" | "failed"): void => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        child?.kill("SIGKILL");
+        resolve(value);
+      }
+    };
+    try {
+      child = fork(probeEntrypointPath(), [JSON.stringify({ entrypoints, moduleId, version })], {
+        cwd: tmpdir(),
+        env: {},
+        execArgv: [],
+        serialization: "json",
+        stdio: ["ignore", "ignore", "ignore", "ipc"],
+      });
+    } catch {
+      finish("failed");
+      return;
+    }
+    timer = setTimeout(() => finish("failed"), timeoutMs);
+    child.on("message", (message: unknown) => {
+      const failures = isRecord(message) ? message.failures : undefined;
+      finish(Array.isArray(failures) && failures.length === 0 ? "ok" : "failed");
+    });
+    child.on("error", () => finish("failed"));
+    child.on("exit", () => finish("failed"));
+  });
+  if (outcome !== "ok") {
+    fail("MODULE_PACKAGE_ENTRYPOINT_LOAD_FAILED");
+  }
+}
+
+function discoveryIssueCodes(error: unknown): readonly string[] {
+  if (
+    error instanceof ModuleDiscoveryError ||
+    error instanceof ModuleMigrationDiscoveryError ||
+    error instanceof ModuleSchemaDiscoveryError
+  ) {
+    return error.issues.map((issue) => issue.code);
+  }
+  return [];
+}
+
+export async function verifyModulePackage(
+  options: VerifyModulePackageOptions,
+): Promise<ModulePackageVerificationResult> {
+  let compressed: Buffer;
+  try {
+    compressed = await readFile(options.archivePath);
+  } catch {
+    fail("MODULE_PACKAGE_UNREADABLE");
+  }
+  const archiveSha256 = sha256(compressed);
+  if (options.expectedSha256 !== undefined && options.expectedSha256 !== archiveSha256) {
+    fail("MODULE_PACKAGE_DIGEST_MISMATCH");
+  }
+
+  let archive: ModulePackageArchive;
+  try {
+    archive = readModulePackageArchive(compressed);
+  } catch (error) {
+    if (error instanceof ModulePackageArchiveError) {
+      fail(error.code);
+    }
+    fail("MODULE_PACKAGE_UNREADABLE");
+  }
+  const files = new Map(
+    archive.entries
+      .filter((entry) => entry.type === "file")
+      .map((entry) => [entry.path, entry.data] as const),
+  );
+
+  const metadata = readMetadata(files);
+  checkPayload(metadata, files);
+  const manifest = checkIdentity(archive, metadata, files);
+  checkCompatibility(metadata, manifest, files, options.platform);
+
+  const scratch = await mkdtemp(path.join(tmpdir(), "ekklesia-package-verify-"));
+  try {
+    // The candidate alone, in a scratch inventory of its own: never module storage.
+    const modulesDirectory = path.join(scratch, "candidates");
+    await mkdir(modulesDirectory, { mode: 0o755 });
+    await writeTree(path.join(modulesDirectory, metadata.module.id), archive);
+
+    const discoveryOptions = {
+      moduleSdkVersion: options.platform.moduleSdkVersion,
+      modulesDirectory,
+      modulesDirectoryRequired: true,
+      platformVersion: options.platform.platformVersion,
+    } as const;
+    let entrypoints: Record<string, string>;
+    try {
+      // The same static validation the platform runs, against this package alone. A module that
+      // requires another module is validated with its dependencies when it is installed.
+      const [discovered] = await discoverModules(discoveryOptions);
+      if (discovered === undefined) {
+        fail("MODULE_PACKAGE_MODULE_INVALID");
+      }
+      await discoverModuleMigrations(discoveryOptions);
+      entrypoints = {
+        server: discovered.entrypoints.server,
+        ...(discovered.entrypoints.schema ? { schema: discovered.entrypoints.schema } : {}),
+        ...(discovered.entrypoints.jobs ? { jobs: discovered.entrypoints.jobs } : {}),
+      };
+    } catch (error) {
+      if (error instanceof ModulePackageVerificationError) {
+        throw error;
+      }
+      fail("MODULE_PACKAGE_MODULE_INVALID", discoveryIssueCodes(error));
+    }
+
+    // Executed only now, and first in isolation: a schema is imported in this process below only
+    // after the probe proved it loads on its own.
+    await loadEntrypoints(
+      metadata.module.id,
+      metadata.module.version,
+      entrypoints,
+      options.loadTimeoutMs ?? 30_000,
+    );
+    try {
+      await discoverModuleSchemas(discoveryOptions);
+    } catch (error) {
+      fail("MODULE_PACKAGE_MODULE_INVALID", discoveryIssueCodes(error));
+    }
+
+    if (options.extractTo !== undefined) {
+      const extractTo = options.extractTo;
+      let created = false;
+      try {
+        await mkdir(extractTo, { mode: 0o755 });
+        created = true;
+        await rm(extractTo, { recursive: true });
+        await writeTree(extractTo, archive);
+      } catch {
+        // Never leave a partial module directory behind; never remove one this call did not create.
+        if (created) {
+          await rm(extractTo, { force: true, recursive: true }).catch(() => undefined);
+        }
+        fail("MODULE_PACKAGE_EXTRACTION_FAILED");
+      }
+    }
+  } finally {
+    await rm(scratch, { force: true, recursive: true });
+  }
+
+  return Object.freeze({
+    archiveSha256,
+    fileCount: metadata.files.length,
+    moduleId: metadata.module.id,
+    target: metadata.target,
+    version: metadata.module.version,
+  });
+}