cinatra 0.1.0

package/src/prod-extension-acquisition.mjs

@@ -0,0 +1,679 @@
+// Production required-extension acquisition.
+//
+// The prod base image needs the full "bootable set" of extension packages on
+// disk at build time: every package declared in `cinatra.extensions`
+// (root package.json). That set is the union of the genuine system packages
+// and every extension package the host source still value-imports — see the
+// coverage gate (scripts/audit/required-extensions-cover-host-imports.mjs),
+// which keeps the declaration honest against the real import graph.
+//
+// Dev acquires those packages as tracking git clones (cinatra-dev-extensions);
+// PROD must not depend on a git/gh binary or movable refs. This module
+// downloads each package as a GitHub codeload tarball pinned to an immutable
+// commit SHA — which removes the git-binary dependency, NOT the dependency on
+// reaching github.com: a genuinely air-gapped build still needs a vendored
+// bundle or a private mirror. Each tarball is verified against a committed
+// lockfile,
+// `cinatra-required-extensions.lock.json` (regenerated by
+// scripts/extensions/update-required-extension-lock.mjs). Prod consumes ONLY
+// the lock — never `main`/`latest`, never the version ranges.
+//
+// Integrity model (deliberately NOT `dist.cinatraSignature` — that signature
+// covers the npm registry tarball used by the runtime marketplace install
+// pipeline, a different artifact and a separate path that stays separate):
+//   1. the download URL embeds the pinned commit SHA (an immutable ref);
+//   2. the whole archive is inspected IN MEMORY before anything touches disk:
+//      entry types, paths, and sizes are validated (see below) and a
+//      deterministic content hash of the delivered file tree is computed and
+//      compared against the lock's `treeSha256`;
+//   3. the extracted `package.json` must carry the locked `name` + `version`;
+//   4. only then is the verified archive extracted (to a temp dir, renamed
+//      into place atomically, and stamped with a marker that later runs
+//      RE-VERIFY rather than trust).
+//
+// Archive hardening (fail-closed, never silently dropped): an entry that is
+// not a plain file or directory (symlink, hardlink, FIFO, device), an
+// absolute path, a `..` traversal segment, an entry outside the single
+// archive root directory, or a reserved marker filename is a hard failure.
+// Bounded resources: compressed size, decompressed size, per-file size, and
+// entry count are all capped before extraction, so a hostile response cannot
+// fill the disk.
+//
+// This module is data-driven end to end: package identities come from the
+// lockfile, never from code (no host->extension coupling is added here).
+// `tar` (a root dependency) is imported lazily AFTER the entry guards so
+// `cinatra setup prod` inside the standalone runtime image — detected
+// POSITIVELY by `server.js` + `.next/` at the root (Next's file tracing
+// copies pnpm-workspace.yaml into the standalone output, so "no workspace
+// file" alone is NOT a reliable standalone signal), where the `tar`
+// dependency may not exist — skips cleanly.
+
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { createGunzip } from "node:zlib";
+
+import { destDirForExtension } from "./cinatra-dev-extensions.mjs";
+
+export const LOCK_FILENAME = "cinatra-required-extensions.lock.json";
+export const ACQUISITION_MARKER_FILENAME = ".cinatra-acquired.json";
+
+// Resource bounds. Extension repos are small (single-digit MiB); these caps
+// are generous headroom, not tuning knobs — they exist so a compromised or
+// malfunctioning endpoint cannot exhaust memory/disk before the integrity
+// check fails the run.
+export const MAX_COMPRESSED_BYTES = 64 * 1024 * 1024;
+export const MAX_DECOMPRESSED_BYTES = 256 * 1024 * 1024;
+export const MAX_FILE_BYTES = 64 * 1024 * 1024;
+export const MAX_ENTRY_COUNT = 20_000;
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+
+const SCOPED_PKG_RE = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+const REPO_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const COMMIT_SHA_RE = /^[0-9a-f]{40}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const CONCRETE_VERSION_RE = /^\d+\.\d+\.\d+$/;
+
+/**
+ * Read + strictly validate the committed lock. Every entry must carry a
+ * well-formed scoped package name, an `owner/repo` slug, a 40-hex commit SHA,
+ * a concrete x.y.z version, and a 64-hex tree hash; duplicates are rejected.
+ * Throws (listing every defect) rather than skipping — prod consumes ONLY
+ * this file, so a malformed lock must never half-acquire.
+ */
+export function readRequiredExtensionsLock(lockPath) {
+  if (!existsSync(lockPath)) {
+    throw new Error(
+      `[prod-extension-acquisition] lockfile not found: ${lockPath}. The committed ` +
+        `${LOCK_FILENAME} is the ONLY source prod acquires from — regenerate it with ` +
+        `\`node scripts/extensions/update-required-extension-lock.mjs\` and commit it.`,
+    );
+  }
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync(lockPath, "utf8"));
+  } catch (err) {
+    throw new Error(`[prod-extension-acquisition] lockfile ${lockPath} is not valid JSON: ${err.message}`);
+  }
+  const packages = Array.isArray(doc?.packages) ? doc.packages : null;
+  if (!packages || packages.length === 0) {
+    throw new Error(
+      `[prod-extension-acquisition] lockfile ${lockPath} has no "packages" entries — refusing to continue.`,
+    );
+  }
+  const defects = [];
+  const seen = new Set();
+  for (const [i, p] of packages.entries()) {
+    const tag = `packages[${i}]${p && typeof p.packageName === "string" ? ` (${p.packageName})` : ""}`;
+    if (!p || typeof p !== "object") {
+      defects.push(`${tag}: not an object`);
+      continue;
+    }
+    if (typeof p.packageName !== "string" || !SCOPED_PKG_RE.test(p.packageName)) {
+      defects.push(`${tag}: packageName must be a lowercase @scope/name`);
+    } else if (seen.has(p.packageName)) {
+      defects.push(`${tag}: duplicate packageName`);
+    } else {
+      seen.add(p.packageName);
+    }
+    if (typeof p.repo !== "string" || !REPO_SLUG_RE.test(p.repo) || p.repo.includes("..")) {
+      defects.push(`${tag}: repo must be an "owner/name" GitHub slug`);
+    }
+    if (typeof p.resolvedSha !== "string" || !COMMIT_SHA_RE.test(p.resolvedSha)) {
+      defects.push(`${tag}: resolvedSha must be a 40-hex lowercase commit SHA`);
+    }
+    if (typeof p.packageVersion !== "string" || !CONCRETE_VERSION_RE.test(p.packageVersion)) {
+      defects.push(`${tag}: packageVersion must be a concrete x.y.z version`);
+    }
+    if (typeof p.treeSha256 !== "string" || !SHA256_RE.test(p.treeSha256)) {
+      defects.push(`${tag}: treeSha256 must be a 64-hex lowercase sha256`);
+    }
+  }
+  if (defects.length > 0) {
+    throw new Error(
+      `[prod-extension-acquisition] lockfile ${lockPath} failed validation:\n  - ${defects.join("\n  - ")}`,
+    );
+  }
+  return { schemaVersion: doc.schemaVersion ?? null, packages };
+}
+
+/**
+ * The declared `cinatra.extensions` package NAMES (ranges stripped —
+ * the same last-`@` split as the canonical host parser in
+ * packages/extensions/src/required-in-prod.ts). Returns an empty set when the
+ * manifest or block is absent/unreadable (the caller treats that as
+ * "nothing to cross-check", never as an acquisition failure).
+ */
+export function readDeclaredRequiredExtensionNames(packageJsonPath) {
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    const raw = Array.isArray(pkg?.cinatra?.extensions) ? pkg.cinatra.extensions : [];
+    const names = new Set();
+    for (const entry of raw) {
+      if (typeof entry !== "string" || entry.trim().length === 0) continue;
+      const trimmed = entry.trim();
+      const at = trimmed.lastIndexOf("@");
+      names.add(at <= 0 ? trimmed : trimmed.slice(0, at));
+    }
+    return names;
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Canonical tree-hash fold shared by every producer (archive inspection,
+ * disk re-verification, the lock regenerator). Input records are
+ * `{ relPath, executable, sha256 }` for REGULAR FILES ONLY; the fold sorts by
+ * relPath and hashes `<relPath>\n<gitMode>\n<contentSha256>\n` per file, so
+ * the result is independent of archive entry order and filesystem walk order.
+ * Modes are normalized to git's two file modes (100755 when the owner-exec
+ * bit is set, else 100644) so umask differences cannot shift the hash.
+ * Directories (incl. empty ones) are not hashed — git archives do not
+ * meaningfully carry them.
+ */
+export function foldTreeHash(records) {
+  const sorted = [...records].sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+  const hash = createHash("sha256");
+  for (const r of sorted) {
+    hash.update(`${r.relPath}\n${r.executable ? "100755" : "100644"}\n${r.sha256}\n`);
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * Compute the canonical tree hash of an on-disk package directory (the
+ * marker-hit RE-VERIFICATION path). The acquisition marker at the package
+ * root is excluded (it is written by us after verification, never part of
+ * the upstream tree). Any directory entry that is not a regular file or a
+ * directory (e.g. a symlink introduced after acquisition) is a hard error —
+ * a verified tree never contains one.
+ */
+export function computeTreeSha256FromDir(rootDir) {
+  const records = [];
+  const walk = (dir) => {
+    for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, dirent.name);
+      const rel = path.relative(rootDir, full).split(path.sep).join("/");
+      if (rel === ACQUISITION_MARKER_FILENAME) continue;
+      if (dirent.isDirectory()) {
+        walk(full);
+      } else if (dirent.isFile()) {
+        const st = statSync(full);
+        if (st.size > MAX_FILE_BYTES) {
+          throw new Error(`[prod-extension-acquisition] ${rel} exceeds the per-file size bound`);
+        }
+        records.push({
+          relPath: rel,
+          executable: (st.mode & 0o100) !== 0,
+          sha256: createHash("sha256").update(readFileSync(full)).digest("hex"),
+        });
+      } else {
+        throw new Error(
+          `[prod-extension-acquisition] unexpected non-regular entry in acquired tree: ${rel} ` +
+            `(symlinks/devices are never part of a verified acquisition)`,
+        );
+      }
+    }
+  };
+  walk(rootDir);
+  return foldTreeHash(records);
+}
+
+/** Decompress a gzip buffer with a hard output bound (zip-bomb guard). */
+export function gunzipBounded(gzBuffer, maxBytes = MAX_DECOMPRESSED_BYTES) {
+  return new Promise((resolvePromise, reject) => {
+    const gunzip = createGunzip();
+    const chunks = [];
+    let total = 0;
+    gunzip.on("data", (chunk) => {
+      total += chunk.length;
+      if (total > maxBytes) {
+        gunzip.destroy();
+        reject(
+          new Error(`[prod-extension-acquisition] decompressed archive exceeds the ${maxBytes}-byte bound`),
+        );
+        return;
+      }
+      chunks.push(chunk);
+    });
+    gunzip.on("error", (err) => reject(new Error(`[prod-extension-acquisition] gunzip failed: ${err.message}`)));
+    gunzip.on("end", () => resolvePromise(Buffer.concat(chunks)));
+    gunzip.end(gzBuffer);
+  });
+}
+
+/** Download a URL into a buffer with a size bound and timeout; fail loud. */
+export async function downloadBounded(url, { fetchImpl = globalThis.fetch, maxBytes = MAX_COMPRESSED_BYTES } = {}) {
+  let res;
+  try {
+    res = await fetchImpl(url, { redirect: "follow", signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+  } catch (err) {
+    throw new Error(`[prod-extension-acquisition] fetch ${url} failed: ${err.message}`);
+  }
+  if (!res.ok || !res.body) {
+    throw new Error(
+      `[prod-extension-acquisition] fetch ${url} failed: HTTP ${res.status} ${res.statusText ?? ""}`.trim(),
+    );
+  }
+  const declared = Number(res.headers?.get?.("content-length") ?? 0);
+  if (declared > maxBytes) {
+    throw new Error(`[prod-extension-acquisition] ${url}: declared size ${declared} exceeds the ${maxBytes}-byte bound`);
+  }
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of res.body) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += buf.length;
+    if (total > maxBytes) {
+      throw new Error(`[prod-extension-acquisition] ${url}: download exceeds the ${maxBytes}-byte bound`);
+    }
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks);
+}
+
+/**
+ * Validate one raw tar entry path against the hardening rules. Returns
+ * `{ stripped }` (the path with the single archive-root directory removed,
+ * "" for the root directory itself) or records a violation. Exported for
+ * direct unit testing of the path rules.
+ */
+export function classifyEntryPath(rawPath) {
+  const normalized = String(rawPath).replace(/^\.\//, "");
+  if (normalized.startsWith("/") || /^[A-Za-z]:[\\/]/.test(normalized) || normalized.startsWith("\\")) {
+    return { violation: "absolute path" };
+  }
+  const segments = normalized.split("/").filter((s) => s.length > 0);
+  if (segments.some((s) => s === "..")) {
+    return { violation: "path traversal (`..` segment)" };
+  }
+  if (segments.length === 0) {
+    return { violation: "empty path" };
+  }
+  return { stripped: segments.slice(1).join("/") };
+}
+
+/**
+ * PASS 1 — inspect the (already size-bounded, decompressed) tar buffer
+ * entirely in memory: enforce the entry hardening rules, compute the
+ * canonical tree hash, and capture the root `package.json` bytes. Nothing is
+ * written to disk; a violation list (never a silent drop) comes back to the
+ * caller, which must treat ANY violation as fatal.
+ */
+export async function inspectTarball(tarBuffer, { tar }) {
+  const violations = [];
+  const records = [];
+  let entryCount = 0;
+  let packageJsonRaw = null;
+
+  const parser = tar.t({
+    onReadEntry: (entry) => {
+      entryCount += 1;
+      if (entryCount > MAX_ENTRY_COUNT) {
+        violations.push(`entry count exceeds ${MAX_ENTRY_COUNT}`);
+        return;
+      }
+      const { stripped, violation } = classifyEntryPath(entry.path);
+      if (violation) {
+        violations.push(`${entry.path}: ${violation}`);
+        return;
+      }
+      // Mode hardening. Git stores only the owner-exec distinction; the
+      // archive writer's umask decides the rest (GitHub codeload emits
+      // 664/775). setuid/setgid/sticky bits, however, can NEVER come from a
+      // git tree — an archive carrying one is hostile and is rejected here;
+      // everything else is NORMALIZED to the canonical 0644/0755 at
+      // extraction (see extractVerifiedTarball), so the applied metadata is
+      // exactly what the tree hash describes.
+      const perms = (entry.mode ?? 0) & 0o7777;
+      if ((perms & 0o7000) !== 0) {
+        violations.push(
+          `${entry.path}: forbidden special mode bits in ${perms.toString(8)} ` +
+            `(setuid/setgid/sticky can never originate from a git tree)`,
+        );
+        return;
+      }
+      if (entry.type === "Directory") {
+        return; // directories (incl. the single archive root) carry no content
+      }
+      if (stripped === "") {
+        violations.push(`${entry.path}: non-directory entry at the archive root`);
+        return;
+      }
+      if (entry.type !== "File") {
+        violations.push(`${entry.path}: forbidden entry type "${entry.type}" (symlink/hardlink/device/FIFO)`);
+        return;
+      }
+      if (stripped === ACQUISITION_MARKER_FILENAME) {
+        violations.push(`${entry.path}: reserved acquisition-marker filename in archive`);
+        return;
+      }
+      if (typeof entry.size === "number" && entry.size > MAX_FILE_BYTES) {
+        violations.push(`${entry.path}: file exceeds the per-file size bound`);
+        return;
+      }
+      const contentHash = createHash("sha256");
+      const wantPackageJson = stripped === "package.json";
+      const packageJsonChunks = wantPackageJson ? [] : null;
+      entry.on("data", (chunk) => {
+        contentHash.update(chunk);
+        if (packageJsonChunks) packageJsonChunks.push(Buffer.from(chunk));
+      });
+      entry.on("end", () => {
+        records.push({
+          relPath: stripped,
+          executable: ((entry.mode ?? 0) & 0o100) !== 0,
+          sha256: contentHash.digest("hex"),
+        });
+        if (packageJsonChunks) packageJsonRaw = Buffer.concat(packageJsonChunks).toString("utf8");
+      });
+    },
+  });
+
+  await new Promise((resolvePromise, reject) => {
+    parser.on("error", (err) => reject(new Error(`[prod-extension-acquisition] tar parse failed: ${err.message}`)));
+    // node-tar list/parse streams emit "end"; "finish" is not reliably emitted.
+    parser.on("end", resolvePromise);
+    parser.end(tarBuffer);
+  });
+
+  return { records, entryCount, packageJsonRaw, violations };
+}
+
+/**
+ * PASS 2 — extract the ALREADY-VERIFIED tar buffer into `destDir`. The same
+ * entry rules are enforced again as defense in depth (filter excludes; pass 1
+ * is the authority that FAILS the run).
+ */
+export async function extractVerifiedTarball(tarBuffer, destDir, { tar }) {
+  mkdirSync(destDir, { recursive: true });
+  await new Promise((resolvePromise, reject) => {
+    const extractor = tar.x({
+      cwd: destDir,
+      strip: 1,
+      // Never apply archive uid/gid: node-tar PRESERVES ownership when the
+      // process runs as root (the Docker build does) unless told otherwise.
+      preserveOwner: false,
+      // Normalize every applied mode to the canonical git pair (0755 dirs,
+      // 0644/0755 files keyed on the owner-exec bit) — the archive writer's
+      // umask (codeload emits 664/775) and any other permission noise never
+      // reach disk, so the applied metadata is exactly what the tree hash
+      // describes. Special bits were already rejected during inspection.
+      onReadEntry: (entry) => {
+        entry.mode = entry.type === "Directory" ? 0o755 : ((entry.mode ?? 0) & 0o100) !== 0 ? 0o755 : 0o644;
+      },
+      filter: (entryPath, entry) => {
+        const { stripped, violation } = classifyEntryPath(entryPath);
+        if (violation) return false;
+        if (((entry.mode ?? 0) & 0o7000) !== 0) return false;
+        if (entry.type === "Directory") return true;
+        return entry.type === "File" && stripped !== "" && stripped !== ACQUISITION_MARKER_FILENAME;
+      },
+    });
+    extractor.on("error", (err) => reject(new Error(`[prod-extension-acquisition] extraction failed: ${err.message}`)));
+    extractor.on("finish", resolvePromise);
+    extractor.end(tarBuffer);
+  });
+  // node-tar applies the process umask at file creation, so the normalized
+  // entry modes can land narrower on disk (e.g. 0600 under umask 077) —
+  // harmless but not canonical. Walk the extracted tree once and chmod every
+  // node to the exact git pair keyed on the (umask-surviving) owner-exec
+  // bit, so the applied modes are deterministic for any builder umask.
+  // (A umask hostile enough to strip owner bits changes the exec-bit hash
+  // input and fails the re-hash that follows extraction — fail closed.)
+  const normalizeModes = (dir) => {
+    for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, dirent.name);
+      if (dirent.isDirectory()) {
+        chmodSync(full, 0o755);
+        normalizeModes(full);
+      } else if (dirent.isFile()) {
+        chmodSync(full, (statSync(full).mode & 0o100) !== 0 ? 0o755 : 0o644);
+      }
+    }
+  };
+  normalizeModes(destDir);
+}
+
+function readMarker(destDir) {
+  const markerPath = path.join(destDir, ACQUISITION_MARKER_FILENAME);
+  if (!existsSync(markerPath)) return null;
+  try {
+    const m = JSON.parse(readFileSync(markerPath, "utf8"));
+    return m && typeof m === "object" ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+function verifyPackageManifest(rawPackageJson, lockEntry, label) {
+  if (typeof rawPackageJson !== "string" || rawPackageJson.length === 0) {
+    throw new Error(`[prod-extension-acquisition] ${label}: archive carries no root package.json`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(rawPackageJson);
+  } catch (err) {
+    throw new Error(`[prod-extension-acquisition] ${label}: root package.json is not valid JSON: ${err.message}`);
+  }
+  if (manifest.name !== lockEntry.packageName) {
+    throw new Error(
+      `[prod-extension-acquisition] ${label}: package.json name "${manifest.name}" does not match the locked ` +
+        `packageName "${lockEntry.packageName}"`,
+    );
+  }
+  if (manifest.version !== lockEntry.packageVersion) {
+    throw new Error(
+      `[prod-extension-acquisition] ${label}: package.json version "${manifest.version}" does not match the ` +
+        `locked packageVersion "${lockEntry.packageVersion}"`,
+    );
+  }
+}
+
+/**
+ * Acquire every package in the committed lock into `extensions/<scope>/<name>`.
+ *
+ * - In a non-workspace root (the Next standalone runtime image, where the
+ *   extension source was baked in at image build), returns
+ *   `{ skipped: true, reason: "not-a-workspace" }` without importing `tar`.
+ * - Idempotent: a directory stamped by a marker matching the lock is
+ *   RE-VERIFIED (tree hash + manifest) and skipped; a marker that matches a
+ *   STALE lock entry triggers a clean re-acquisition; a directory WITHOUT a
+ *   marker (e.g. a dev git clone) is a hard error — this routine never
+ *   clobbers a tree it does not own.
+ * - Fail-fast and loud on network errors, HTTP failures, unsafe archives,
+ *   hash/manifest mismatches. A failed run leaves previously verified
+ *   packages in place (markers make a re-run resume cheaply).
+ *
+ * Returns `{ results: [{ pkgName, action, changed, dest }] }`, the shape
+ * `installAfterExtensionSync` consumes ("downloaded" counts as materially
+ * changed; "verified-existing" does not).
+ */
+export async function acquireProdRequiredExtensions({
+  repoRoot,
+  lockPath,
+  fetchImpl = globalThis.fetch,
+  log = console.log,
+} = {}) {
+  if (!repoRoot) throw new Error("[prod-extension-acquisition] repoRoot is required");
+  // Standalone runtime image — POSITIVE detection, checked FIRST. Next's
+  // output-file tracing mirrors the project root into .next/standalone
+  // INCLUDING pnpm-workspace.yaml (so "workspace file absent" is NOT a
+  // reliable standalone detector) and INCLUDING the host-imported extension
+  // sources WITHOUT their acquisition markers (tracing copies only the
+  // imported files) — running the acquisition there would refuse on
+  // "exists but is not acquisition-managed" and brick `setup prod` on a
+  // perfectly good image (caught by scripts/ci/prod-boot-e2e.sh). The
+  // standalone root is identified by the traced server entry `server.js`
+  // sitting NEXT TO `.next/` — true only for the standalone output (a real
+  // repo root has no root-level server.js; the build stage's standalone
+  // output lives nested under .next/standalone/, not at the build root).
+  if (
+    existsSync(path.join(repoRoot, "server.js")) &&
+    existsSync(path.join(repoRoot, ".next"))
+  ) {
+    log(
+      "- Required-extension acquisition: skipped (standalone runtime image — the extension " +
+        "source was baked and verified at image build time).",
+    );
+    return { skipped: true, reason: "standalone-runtime-image" };
+  }
+  if (!existsSync(path.join(repoRoot, "pnpm-workspace.yaml"))) {
+    log(
+      "- Required-extension acquisition: skipped (no pnpm workspace at this root — the standalone " +
+        "runtime image bakes the extension source at image build time).",
+    );
+    return { skipped: true, reason: "not-a-workspace" };
+  }
+
+  const lock = readRequiredExtensionsLock(lockPath ?? path.join(repoRoot, LOCK_FILENAME));
+
+  // The lock must match the declaration it was generated from. Enforcing the
+  // bijection HERE (not only in the CI coverage gate) means the image build
+  // itself fails on a drifted lock — the publish path cannot outrun a
+  // forgotten `update-required-extension-lock` regeneration. Only a root with
+  // NO package.json at all skips the cross-check (unit-test scratch roots);
+  // a real workspace manifest that declares nothing while the lock pins
+  // packages is itself drift and fails loud.
+  const rootManifestPath = path.join(repoRoot, "package.json");
+  if (existsSync(rootManifestPath)) {
+    const declared = readDeclaredRequiredExtensionNames(rootManifestPath);
+    const lockedNames = new Set(lock.packages.map((p) => p.packageName));
+    const missingFromLock = [...declared].filter((n) => !lockedNames.has(n)).sort();
+    const staleInLock = [...lockedNames].filter((n) => !declared.has(n)).sort();
+    if (missingFromLock.length > 0 || staleInLock.length > 0) {
+      throw new Error(
+        `[prod-extension-acquisition] the acquisition lock does not match cinatra.extensions:` +
+          (missingFromLock.length ? `\n  declared but not locked: ${missingFromLock.join(", ")}` : "") +
+          (staleInLock.length ? `\n  locked but not declared: ${staleInLock.join(", ")}` : "") +
+          `\nRegenerate with \`node scripts/extensions/update-required-extension-lock.mjs\` and commit the lock.`,
+      );
+    }
+  }
+
+  // Lazy: `tar` is a root workspace dependency, intentionally not resolvable
+  // in the standalone runtime image (the guard above returns first there).
+  const tar = await import("tar");
+
+  const results = [];
+  let downloaded = 0;
+  let verified = 0;
+  log(`- Required-extension acquisition: ${lock.packages.length} locked package(s)…`);
+
+  for (const entry of lock.packages) {
+    const dest = destDirForExtension(entry.packageName, {}, repoRoot);
+    const label = `${entry.packageName}@${entry.packageVersion} (${entry.repo}#${entry.resolvedSha.slice(0, 12)})`;
+
+    if (existsSync(dest)) {
+      const marker = readMarker(dest);
+      if (!marker) {
+        throw new Error(
+          `[prod-extension-acquisition] ${dest} exists but is not acquisition-managed (no ` +
+            `${ACQUISITION_MARKER_FILENAME}). Refusing to overwrite — if this is a dev checkout, use the dev ` +
+            `setup flow; otherwise remove the directory and re-run.`,
+        );
+      }
+      if (marker.resolvedSha === entry.resolvedSha && marker.treeSha256 === entry.treeSha256) {
+        // Marker hit is a CLAIM, not proof — re-verify content before trusting.
+        const actualTreeSha = computeTreeSha256FromDir(dest);
+        if (actualTreeSha !== entry.treeSha256) {
+          throw new Error(
+            `[prod-extension-acquisition] ${label}: on-disk tree hash ${actualTreeSha} does not match the ` +
+              `locked treeSha256 ${entry.treeSha256} (content changed after acquisition). Remove ${dest} and re-run.`,
+          );
+        }
+        const manifestPath = path.join(dest, "package.json");
+        verifyPackageManifest(existsSync(manifestPath) ? readFileSync(manifestPath, "utf8") : "", entry, label);
+        results.push({ pkgName: entry.packageName, action: "verified-existing", changed: false, dest });
+        verified += 1;
+        continue;
+      }
+      // Acquisition-managed but pinned elsewhere: the lock moved — re-acquire.
+      // The stale tree is NOT removed yet: it stays in place until the
+      // replacement has been fully downloaded and verified, so a transient
+      // network/integrity failure cannot leave the slot empty.
+    }
+
+    const url = `https://codeload.github.com/${entry.repo}/tar.gz/${entry.resolvedSha}`;
+    log(`  - ${label}: downloading…`);
+    const gzBuffer = await downloadBounded(url, { fetchImpl });
+    const tarBuffer = await gunzipBounded(gzBuffer);
+    const { records, packageJsonRaw, violations } = await inspectTarball(tarBuffer, { tar });
+    if (violations.length > 0) {
+      throw new Error(
+        `[prod-extension-acquisition] ${label}: unsafe archive from ${url}:\n  - ${violations.join("\n  - ")}`,
+      );
+    }
+    const treeSha = foldTreeHash(records);
+    if (treeSha !== entry.treeSha256) {
+      throw new Error(
+        `[prod-extension-acquisition] ${label}: tree hash mismatch for ${url}\n  expected ${entry.treeSha256}\n` +
+          `  actual   ${treeSha}\nThe pinned content changed or the response was tampered with — refusing to install.`,
+      );
+    }
+    verifyPackageManifest(packageJsonRaw, entry, label);
+
+    // Verified in memory — now (and only now) touch disk: extract to a temp
+    // sibling, RE-HASH what actually landed (closes any divergence between
+    // inspection and extraction), stamp the marker, then swap into place.
+    const tmpDir = path.join(repoRoot, "extensions", `.acquire-tmp-${process.pid}-${downloaded}`);
+    rmSync(tmpDir, { recursive: true, force: true });
+    try {
+      await extractVerifiedTarball(tarBuffer, tmpDir, { tar });
+      const extractedTreeSha = computeTreeSha256FromDir(tmpDir);
+      if (extractedTreeSha !== entry.treeSha256) {
+        throw new Error(
+          `[prod-extension-acquisition] ${label}: extracted tree hash ${extractedTreeSha} does not match the ` +
+            `locked treeSha256 ${entry.treeSha256} — refusing to install.`,
+        );
+      }
+      writeFileSync(
+        path.join(tmpDir, ACQUISITION_MARKER_FILENAME),
+        JSON.stringify(
+          { resolvedSha: entry.resolvedSha, treeSha256: entry.treeSha256, acquiredAt: new Date().toISOString() },
+          null,
+          2,
+        ) + "\n",
+      );
+      mkdirSync(path.dirname(dest), { recursive: true });
+      // Swap. The previously verified (now stale-pinned) tree is renamed
+      // ASIDE — not deleted — so a failed rename into place restores it: a
+      // failed replacement can never leave the slot empty. The aside dir is
+      // dot-prefixed (like the tmp dir) so workspace globs never see it as a
+      // package; it is removed once the new tree is in place.
+      const asideDir = path.join(repoRoot, "extensions", `.acquire-old-${process.pid}-${downloaded}`);
+      rmSync(asideDir, { recursive: true, force: true });
+      let movedOldAside = false;
+      if (existsSync(dest)) {
+        renameSync(dest, asideDir);
+        movedOldAside = true;
+      }
+      try {
+        renameSync(tmpDir, dest);
+      } catch (renameErr) {
+        if (movedOldAside) renameSync(asideDir, dest); // restore the old verified tree
+        throw renameErr;
+      }
+      if (movedOldAside) rmSync(asideDir, { recursive: true, force: true });
+    } catch (err) {
+      rmSync(tmpDir, { recursive: true, force: true });
+      throw err;
+    }
+    results.push({ pkgName: entry.packageName, action: "downloaded", changed: true, dest });
+    downloaded += 1;
+  }
+
+  log(`- Required-extension acquisition: OK (${downloaded} downloaded, ${verified} verified in place).`);
+  return { results };
+}