@deeeed/metamask-harness 0.36.0 → 0.37.0

package/adapters/extension/snapshot-dist.sh

@@ -9,9 +9,12 @@
 #
 # Inputs (flags):
 #   --dist <dir>           source dist (required, e.g. <repo>/dist/chrome)
+#   --target <dir>         absolute checkout containment root
+#   --runtime-root <dir>   absolute directory that owns the snapshot
 #   --runtime-dist <dir>   snapshot destination (required, recreated)
 #   --wait-iterations <n>  manifest wait loop length, 2s each (default 180)
 #   --summary <file>       optional standard summary.json
+#   --exact                preserve every source entry (release artifacts)
 #
 # Outputs:
 #   <runtime-dist>/ snapshot (excludes _metadata); optional --summary file
@@ -24,24 +27,32 @@
 set -euo pipefail
 
 DIST=""
+TARGET_ROOT=""
+RUNTIME_ROOT=""
 RUNTIME_DIST=""
 WAIT_ITERATIONS=180
 SUMMARY=""
+EXACT=false
 require_value() { [ "$#" -ge 2 ] || { echo "Missing value for $1" >&2; exit 2; }; }
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --dist) require_value "$@"; DIST="$2"; shift 2 ;;
+    --target) require_value "$@"; TARGET_ROOT="$2"; shift 2 ;;
+    --runtime-root) require_value "$@"; RUNTIME_ROOT="$2"; shift 2 ;;
     --runtime-dist) require_value "$@"; RUNTIME_DIST="$2"; shift 2 ;;
     --wait-iterations) require_value "$@"; WAIT_ITERATIONS="$2"; shift 2 ;;
     --summary) require_value "$@"; SUMMARY="$2"; shift 2 ;;
+    --exact) EXACT=true; shift ;;
     -h|--help)
-      echo "Usage: snapshot-dist.sh --dist <dir> --runtime-dist <dir> [--wait-iterations <n>] [--summary <file>]"
+      echo "Usage: snapshot-dist.sh --dist <dir> --target <dir> --runtime-root <dir> --runtime-dist <dir> [--wait-iterations <n>] [--summary <file>]"
       exit 0
       ;;
     *) echo "Unknown arg: $1" >&2; exit 2 ;;
   esac
 done
 [ -n "$DIST" ] || { echo "Missing --dist" >&2; exit 2; }
+[ -n "$TARGET_ROOT" ] || { echo "Missing --target" >&2; exit 2; }
+[ -n "$RUNTIME_ROOT" ] || { echo "Missing --runtime-root" >&2; exit 2; }
 [ -n "$RUNTIME_DIST" ] || { echo "Missing --runtime-dist" >&2; exit 2; }
 case "$WAIT_ITERATIONS" in ''|*[!0-9]*) echo "Invalid --wait-iterations (must be numeric): $WAIT_ITERATIONS" >&2; exit 2 ;; esac
 
@@ -73,8 +84,82 @@ done
 test -f "$DIST/manifest.json" || { echo "snapshot-dist: no manifest at $DIST/manifest.json" >&2; exit 1; }
 
 echo "[recipe-harness] snapshotting dist -> runtime-dist: $RUNTIME_DIST" >&2
-rm -rf "$RUNTIME_DIST" && mkdir -p "$RUNTIME_DIST" \
-  && rsync -a --delete --exclude _metadata "$DIST/" "$RUNTIME_DIST/" || exit 1
+node - "$DIST" "$TARGET_ROOT" "$RUNTIME_ROOT" "$RUNTIME_DIST" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+
+const [sourceInput, targetInput, rootInput, destinationInput] = process.argv.slice(2);
+const source = path.resolve(sourceInput);
+const target = path.resolve(targetInput);
+const root = path.resolve(rootInput);
+const destination = path.resolve(destinationInput);
+
+function refuse(message) {
+  throw new Error(`snapshot-dist: ${message}`);
+}
+
+if (![targetInput, rootInput, destinationInput].every(path.isAbsolute)) {
+  refuse('--target, --runtime-root, and --runtime-dist must be absolute paths.');
+}
+const targetStat = fs.lstatSync(target, { throwIfNoEntry: false });
+if (!targetStat?.isDirectory() || targetStat.isSymbolicLink()) {
+  refuse(`target is not a regular directory: ${target}.`);
+}
+const rootRelative = path.relative(target, root);
+if (!rootRelative || rootRelative === '..' || rootRelative.startsWith(`..${path.sep}`) || path.isAbsolute(rootRelative)) {
+  refuse(`runtime root must be a child of ${target}.`);
+}
+const relative = path.relative(root, destination);
+if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+  refuse(`runtime destination must be a child of ${root}.`);
+}
+if (
+  source === destination ||
+  source.startsWith(`${destination}${path.sep}`) ||
+  destination.startsWith(`${source}${path.sep}`)
+) {
+  refuse('source and runtime destination must be separate directory trees.');
+}
+
+function ensureDirectoryTree(base, relativePath) {
+  let current = base;
+  const components = relativePath.split(path.sep).filter(Boolean);
+  for (const component of components) {
+    current = path.join(current, component);
+    const stat = fs.lstatSync(current, { throwIfNoEntry: false });
+    if (!stat) {
+      fs.mkdirSync(current, { mode: 0o700 });
+      continue;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      refuse(`runtime path contains an unsafe entry: ${current}.`);
+    }
+  }
+}
+
+ensureDirectoryTree(target, rootRelative);
+ensureDirectoryTree(root, path.relative(root, path.dirname(destination)));
+const realTarget = fs.realpathSync(target);
+const realRoot = fs.realpathSync(root);
+const realParent = fs.realpathSync(path.dirname(destination));
+if (
+  !realRoot.startsWith(`${realTarget}${path.sep}`) ||
+  (realParent !== realRoot && !realParent.startsWith(`${realRoot}${path.sep}`))
+) {
+  refuse(`runtime destination escapes ${root}.`);
+}
+const destinationStat = fs.lstatSync(destination, { throwIfNoEntry: false });
+if (destinationStat && (!destinationStat.isDirectory() || destinationStat.isSymbolicLink())) {
+  refuse(`runtime destination is not a regular directory: ${destination}.`);
+}
+if (destinationStat) fs.rmSync(destination, { recursive: true });
+fs.mkdirSync(destination, { mode: 0o700 });
+NODE
+if $EXACT; then
+  rsync -a --delete "$DIST/" "$RUNTIME_DIST/" || exit 1
+else
+  rsync -a --delete --exclude _metadata "$DIST/" "$RUNTIME_DIST/" || exit 1
+fi
 echo "[recipe-harness] runtime-dist snapshot complete" >&2
 
 # Freshness guard: the loaded runtime-dist must match dist/chrome's git id. A

package/adapters/extension/verify.sh

@@ -344,14 +344,18 @@ let r = {};
 try { r = JSON.parse(fs.readFileSync(dir + "/runtime-decision.json", "utf8")); } catch {}
 const c = r.checks || {};
 const dist = c.dist || { status: "unknown" };
-const distMsg = dist.status === "fresh" ? "dist id matches HEAD; no uncommitted source."
+const distMsg = dist.source === "release-artifact"
+  ? ("release artifact " + (dist.manifestVersion || "?") + " sha256=" + (dist.artifactSha256 || "?") + " matches the loaded runtime snapshot.")
+  : dist.status === "fresh" ? "dist id matches HEAD; no uncommitted source."
   : dist.status === "stale" ? (dist.reason === "uncommitted-source"
       ? ((dist.modified ? dist.modified.length : "some") + " uncommitted source file(s); rebuild or commit.")
       : ("dist id " + (dist.distGitId || "?") + " != HEAD " + (dist.head || "?") + "; rebuild."))
   : dist.status === "no-build" ? "no dist/chrome build."
   : "no git id in dist or not a git checkout; cannot prove parity.";
 fs.writeFileSync(dir + "/dist-freshness.json", JSON.stringify({ ...dist, message: distMsg }));
-const bl = c.buildLog || { status: "unknown" };
+const bl = c.releaseArtifact?.status === "valid"
+  ? { status: "no-watch", source: "release-artifact" }
+  : (c.buildLog || { status: "unknown" });
 const blMsg = bl.status === "ok" ? "webpack compiled."
   : bl.status === "no-watch" ? "no webpack watch log; build-health n/a (e.g. one-shot build)."
   : bl.status === "building" ? "webpack has not reported a successful compile yet."

package/adapters/manifest.json

@@ -186,6 +186,14 @@
       "inputs": "--target --runtime-dist; optional --runtime-dir",
       "outputs": "home.html and sidepanel.html titles updated in the isolated runtime only; exit 0/1"
     },
+    {
+      "id": "extension/artifact-runtime-state",
+      "entry": "adapters/extension/artifact-runtime-state.cjs",
+      "kind": "node",
+      "purpose": "Record or clear the acquired release artifact identity bound to the loaded runtime snapshot.",
+      "inputs": "set|clear --target --runtime-dir; set also requires --source-dir --runtime-dist --provenance",
+      "outputs": "<runtime-dir>/extension-release-artifact.json or removal; exit 0/1/2"
+    },
     {
       "id": "extension/stop-viewers",
       "entry": "adapters/extension/stop-viewers.sh",
@@ -207,7 +215,7 @@
       "entry": "adapters/extension/snapshot-dist.sh",
       "kind": "bash",
       "purpose": "Runtime-dist snapshot (rsync, excludes _metadata) with from-git-id freshness guard.",
-      "inputs": "--dist --runtime-dist --wait-iterations --summary",
+      "inputs": "--dist --target --runtime-root --runtime-dist --wait-iterations --summary",
       "outputs": "<runtime-dist>/ snapshot; optional summary; exit 0/1/2"
     },
     {

package/adapters/shared/log-tui.mjs

@@ -236,7 +236,7 @@ async function watchLog(options) {
       renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
       if (mode !== 'quiet') {
         const elapsed = Math.round((Date.now() - started) / 1000);
-        process.stderr.write(`${color('label', 'mm-harness', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('ok', `build complete (${elapsed}s)`, { stream: process.stderr })}\n`);
+        process.stderr.write(`${color('label', 'mm-harness', { stream: process.stderr })} ${color('dim', '|', { stream: process.stderr })} ${color('ok', `${label} complete (${elapsed}s)`, { stream: process.stderr })}\n`);
       }
       return 0;
     }

package/dist/adapters/extension/artifact-integrity.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+function extensionTreeSha256(root) {
+  const resolvedRoot = path.resolve(root);
+  const rootStat = fs.lstatSync(resolvedRoot);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new Error(`Extension artifact root must be a regular directory: ${resolvedRoot}`);
+  }
+  const digest = createHash("sha256");
+  walk(resolvedRoot, "");
+  return digest.digest("hex");
+  function walk(directory, relativeDirectory) {
+    const entries = fs.readdirSync(directory, { withFileTypes: true }).sort((left, right) => Buffer.compare(Buffer.from(left.name), Buffer.from(right.name)));
+    for (const entry of entries) {
+      const absolute = path.join(directory, entry.name);
+      const relative = relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name;
+      const stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`Extension artifact tree contains a symbolic link: ${relative}`);
+      }
+      if (stat.isDirectory()) {
+        digest.update(`directory\0${relative}\0`);
+        walk(absolute, relative);
+        continue;
+      }
+      if (!stat.isFile()) {
+        throw new Error(`Extension artifact tree contains an unsupported entry: ${relative}`);
+      }
+      digest.update(`file\0${relative}\0${stat.size}\0`);
+      digest.update(fs.readFileSync(absolute));
+      digest.update("\0");
+    }
+  }
+}
+export {
+  extensionTreeSha256
+};

package/dist/adapters/extension/extension-id.js

@@ -1,6 +1,8 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { recipeRuntimeDir } from "../../paths.js";
+import { releaseArtifactState, runtimeDistCheck } from "./runtime-decision.js";
 const DIST_MANIFEST = "dist/chrome/manifest.json";
 function extensionIdFromKey(keyBase64) {
   const der = Buffer.from(keyBase64, "base64");
@@ -12,8 +14,8 @@ function extensionIdFromKey(keyBase64) {
   }
   return id;
 }
-function idFromDistManifest(target) {
-  const manifestPath = path.join(target, DIST_MANIFEST);
+function idFromManifest(manifestPath) {
+  if (!manifestPath) return null;
   if (!fs.existsSync(manifestPath)) return null;
   try {
     const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
@@ -39,7 +41,24 @@ async function cdpExtensionIds(cdpPort) {
 }
 async function resolveExtensionId(target, options = {}) {
   const resolved = path.resolve(target);
-  const fromKey = idFromDistManifest(resolved);
+  const runtimeSnapshot = runtimeDistCheck(resolved, releaseArtifactState(resolved));
+  const releaseArtifact = runtimeSnapshot.source === "release-artifact";
+  if (releaseArtifact && runtimeSnapshot.status !== "fresh") {
+    return {
+      adapter: "extension",
+      target: resolved,
+      extensionId: null,
+      source: "none",
+      verified: false
+    };
+  }
+  const manifestPath = releaseArtifact ? runtimeSnapshot.status === "fresh" ? path.join(
+    resolved,
+    recipeRuntimeDir(),
+    process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist",
+    "manifest.json"
+  ) : null : path.join(resolved, DIST_MANIFEST);
+  const fromKey = idFromManifest(manifestPath);
   let cdpIds = null;
   if (options.cdpPort) cdpIds = await cdpExtensionIds(options.cdpPort);
   if (fromKey) {
@@ -47,7 +66,7 @@ async function resolveExtensionId(target, options = {}) {
       adapter: "extension",
       target: resolved,
       extensionId: fromKey,
-      source: "manifest-key",
+      source: releaseArtifact ? "release-manifest-key" : "manifest-key",
       verified: cdpIds ? cdpIds.includes(fromKey) : null
     };
   }

package/dist/adapters/extension/release-artifact.js

@@ -0,0 +1,386 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { inflateRawSync } from "node:zlib";
+import { extensionTreeSha256 } from "./artifact-integrity.js";
+const MAX_ARCHIVE_BYTES = 768 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 512 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_ENTRIES = 1e5;
+async function acquireExtensionReleaseArtifact(options) {
+  const source = localSource(options.file);
+  const expectedVersion = expectedArtifactVersion(options.expectedVersion);
+  const expectedSha256 = expectedArtifactSha256(options.expectedSha256);
+  const requestedCacheRoot = path.resolve(
+    options.cacheRoot ?? path.join(os.homedir(), ".cache", "mm-harness", "extension-artifacts")
+  );
+  await fsp.mkdir(requestedCacheRoot, { recursive: true, mode: 448 });
+  const cacheRoot = await fsp.realpath(requestedCacheRoot);
+  const acquired = await inspectLocalArchive(source.path, cacheRoot);
+  if (acquired.sha256 !== expectedSha256) {
+    if (acquired.temporary) await fsp.rm(path.dirname(acquired.archivePath), { recursive: true });
+    throw new Error(`Extension artifact SHA-256 ${acquired.sha256} does not match expected ${expectedSha256}.`);
+  }
+  const artifactRoot = path.join(cacheRoot, expectedVersion, acquired.sha256);
+  const provenancePath = path.join(artifactRoot, "provenance.json");
+  const cached = await readCachedArtifact(artifactRoot, provenancePath, acquired.sha256, expectedVersion);
+  if (cached) {
+    if (acquired.temporary) {
+      await fsp.rm(path.dirname(acquired.archivePath), { recursive: true });
+    }
+    return {
+      ...cached,
+      source,
+      archiveBytes: acquired.bytes,
+      cache: "hit"
+    };
+  }
+  if (await pathExists(artifactRoot)) {
+    await assertRegularTree(artifactRoot);
+    await assertContainedDirectory(artifactRoot, cacheRoot);
+    await fsp.rm(artifactRoot, { recursive: true });
+  }
+  const versionRoot = path.dirname(artifactRoot);
+  await fsp.mkdir(versionRoot, { recursive: true, mode: 448 });
+  await assertContainedDirectory(versionRoot, cacheRoot);
+  const temporaryRoot = await fsp.mkdtemp(path.join(versionRoot, ".extract-"));
+  try {
+    const contentRoot = path.join(temporaryRoot, "content");
+    await fsp.mkdir(contentRoot, { mode: 448 });
+    const extensionDir = await extractExtensionArchive(acquired.archivePath, contentRoot);
+    const manifestVersion = await validateManifestVersion(extensionDir, expectedVersion);
+    const treeSha256 = extensionTreeSha256(extensionDir);
+    const relativeExtensionDir = path.relative(temporaryRoot, extensionDir) || ".";
+    const provenance = {
+      schemaVersion: 1,
+      source,
+      expectedVersion,
+      manifestVersion,
+      sha256: acquired.sha256,
+      treeSha256,
+      archiveBytes: acquired.bytes,
+      extensionDir: relativeExtensionDir,
+      acquiredAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await fsp.writeFile(
+      path.join(temporaryRoot, "provenance.json"),
+      `${JSON.stringify(provenance, null, 2)}
+`,
+      { mode: 384 }
+    );
+    try {
+      await fsp.rename(temporaryRoot, artifactRoot);
+    } catch (error) {
+      if (!isAlreadyExists(error)) throw error;
+      await fsp.rm(temporaryRoot, { recursive: true });
+    }
+    const ready = await readCachedArtifact(artifactRoot, provenancePath, acquired.sha256, expectedVersion);
+    if (!ready) throw new Error(`Extension artifact cache could not be validated at ${artifactRoot}.`);
+    return {
+      ...ready,
+      source,
+      archiveBytes: acquired.bytes,
+      cache: "miss"
+    };
+  } catch (error) {
+    if (await pathExists(temporaryRoot)) await fsp.rm(temporaryRoot, { recursive: true });
+    throw error;
+  } finally {
+    if (acquired.temporary) {
+      await fsp.rm(path.dirname(acquired.archivePath), { recursive: true });
+    }
+  }
+}
+function expectedArtifactSha256(requested) {
+  if (!/^[a-f0-9]{64}$/u.test(requested)) {
+    throw new Error("--artifact-sha256 must be 64 lowercase hexadecimal characters.");
+  }
+  return requested;
+}
+async function inspectLocalArchive(archive, cacheRoot) {
+  const sourcePath = path.resolve(archive);
+  const downloadRoot = path.join(cacheRoot, ".downloads");
+  await fsp.mkdir(downloadRoot, { recursive: true, mode: 448 });
+  const temporaryRoot = await fsp.mkdtemp(path.join(downloadRoot, "artifact-"));
+  const archivePath = path.join(temporaryRoot, "artifact.zip");
+  let source;
+  try {
+    source = await fsp.open(sourcePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const stat = await source.stat();
+    if (!stat.isFile()) throw new Error(`Extension artifact archive must be a regular file: ${sourcePath}`);
+    if (stat.size > MAX_ARCHIVE_BYTES) {
+      throw new Error(`Extension artifact exceeds the ${MAX_ARCHIVE_BYTES}-byte archive limit.`);
+    }
+    const destination = await fsp.open(archivePath, "wx", 384);
+    const digest = createHash("sha256");
+    let bytes = 0;
+    try {
+      const stream = source.createReadStream({ autoClose: false });
+      for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > MAX_ARCHIVE_BYTES) {
+          throw new Error(`Extension artifact exceeds the ${MAX_ARCHIVE_BYTES}-byte archive limit.`);
+        }
+        digest.update(buffer);
+        await destination.write(buffer);
+      }
+    } finally {
+      await destination.close();
+    }
+    return { archivePath, sha256: digest.digest("hex"), bytes, temporary: true };
+  } catch (error) {
+    await fsp.rm(temporaryRoot, { recursive: true });
+    throw error;
+  } finally {
+    await source?.close();
+  }
+}
+function localSource(archive) {
+  return { kind: "local", path: path.resolve(archive) };
+}
+function expectedArtifactVersion(requested) {
+  if (!/^\d+\.\d+\.\d+$/u.test(requested)) {
+    throw new Error("--artifact-version must use X.Y.Z.");
+  }
+  return requested;
+}
+async function extractExtensionArchive(archivePath, outputRoot) {
+  const archive = await fsp.readFile(archivePath);
+  const entries = readZipEntries(archive);
+  const manifestEntries = entries.filter((entry) => !entry.directory && path.posix.basename(entry.name) === "manifest.json");
+  if (manifestEntries.length !== 1) {
+    throw new Error(`Extension artifact must contain exactly one manifest.json; found ${manifestEntries.length}.`);
+  }
+  const extensionPrefix = path.posix.dirname(manifestEntries[0].name);
+  if (extensionPrefix !== ".") {
+    const prefix = `${extensionPrefix}/`;
+    const outside = entries.find((entry) => entry.name !== extensionPrefix && !entry.name.startsWith(prefix));
+    if (outside) {
+      throw new Error(`Extension artifact has content outside its manifest root: ${outside.name}.`);
+    }
+  }
+  for (const entry of entries) {
+    const destination = path.join(outputRoot, ...entry.name.split("/"));
+    if (entry.directory) {
+      await fsp.mkdir(destination, { recursive: true, mode: 493 });
+      continue;
+    }
+    await fsp.mkdir(path.dirname(destination), { recursive: true, mode: 493 });
+    const compressedStart = localEntryDataOffset(archive, entry);
+    const compressed = archive.subarray(compressedStart, compressedStart + entry.compressedSize);
+    const content = entry.method === 0 ? compressed : inflateRawSync(compressed, { maxOutputLength: entry.uncompressedSize });
+    if (content.length !== entry.uncompressedSize || crc32(content) !== entry.crc32) {
+      throw new Error(`Extension artifact entry failed integrity validation: ${entry.name}.`);
+    }
+    await fsp.writeFile(destination, content, { flag: "wx", mode: 420 });
+  }
+  return extensionPrefix === "." ? outputRoot : path.join(outputRoot, ...extensionPrefix.split("/"));
+}
+function readZipEntries(archive) {
+  const eocdOffset = findEndOfCentralDirectory(archive);
+  const disk = archive.readUInt16LE(eocdOffset + 4);
+  const centralDisk = archive.readUInt16LE(eocdOffset + 6);
+  const entriesOnDisk = archive.readUInt16LE(eocdOffset + 8);
+  const entryCount = archive.readUInt16LE(eocdOffset + 10);
+  const centralSize = archive.readUInt32LE(eocdOffset + 12);
+  const centralOffset = archive.readUInt32LE(eocdOffset + 16);
+  if (disk !== 0 || centralDisk !== 0 || entriesOnDisk !== entryCount) {
+    throw new Error("Multi-disk ZIP archives are not supported.");
+  }
+  if (entryCount === 65535 || centralSize === 4294967295 || centralOffset === 4294967295) {
+    throw new Error("ZIP64 extension artifacts are not supported.");
+  }
+  if (entryCount === 0 || entryCount > MAX_ENTRIES || centralOffset + centralSize > eocdOffset) {
+    throw new Error("Extension artifact has an invalid central directory.");
+  }
+  const entries = [];
+  const names = /* @__PURE__ */ new Set();
+  const offsets = /* @__PURE__ */ new Set();
+  let expandedBytes = 0;
+  let offset = centralOffset;
+  for (let index = 0; index < entryCount; index += 1) {
+    if (offset + 46 > archive.length || archive.readUInt32LE(offset) !== 33639248) {
+      throw new Error("Extension artifact has a malformed central directory entry.");
+    }
+    const flags = archive.readUInt16LE(offset + 8);
+    const method = archive.readUInt16LE(offset + 10);
+    const crc = archive.readUInt32LE(offset + 16);
+    const compressedSize = archive.readUInt32LE(offset + 20);
+    const uncompressedSize = archive.readUInt32LE(offset + 24);
+    const nameLength = archive.readUInt16LE(offset + 28);
+    const extraLength = archive.readUInt16LE(offset + 30);
+    const commentLength = archive.readUInt16LE(offset + 32);
+    const madeBy = archive.readUInt16LE(offset + 4) >>> 8;
+    const externalAttributes = archive.readUInt32LE(offset + 38);
+    const localOffset = archive.readUInt32LE(offset + 42);
+    const nextOffset = offset + 46 + nameLength + extraLength + commentLength;
+    if (nextOffset > archive.length) throw new Error("Extension artifact has a truncated central directory entry.");
+    const name = archive.subarray(offset + 46, offset + 46 + nameLength).toString("utf8");
+    validateEntryName(name);
+    const directory = name.endsWith("/");
+    const unixMode = madeBy === 3 ? externalAttributes >>> 16 : 0;
+    if ((unixMode & 61440) === 40960) {
+      throw new Error(`Extension artifact contains a symbolic link: ${name}.`);
+    }
+    if ((flags & 1) !== 0 || method !== 0 && method !== 8) {
+      throw new Error(`Extension artifact entry uses unsupported ZIP features: ${name}.`);
+    }
+    if (names.has(name) || offsets.has(localOffset)) {
+      throw new Error(`Extension artifact contains a duplicate entry: ${name}.`);
+    }
+    if (uncompressedSize > MAX_ENTRY_BYTES || compressedSize > MAX_ENTRY_BYTES) {
+      throw new Error(`Extension artifact entry is too large: ${name}.`);
+    }
+    if (compressedSize > 0 && uncompressedSize / compressedSize > 1e3) {
+      throw new Error(`Extension artifact entry has an unsafe compression ratio: ${name}.`);
+    }
+    expandedBytes += uncompressedSize;
+    if (expandedBytes > MAX_EXPANDED_BYTES) {
+      throw new Error(`Extension artifact exceeds the ${MAX_EXPANDED_BYTES}-byte expansion limit.`);
+    }
+    names.add(name);
+    offsets.add(localOffset);
+    entries.push({ name, directory, method, compressedSize, uncompressedSize, crc32: crc, localOffset });
+    offset = nextOffset;
+  }
+  if (offset !== centralOffset + centralSize) throw new Error("Extension artifact central directory size does not match.");
+  return entries;
+}
+function validateEntryName(name) {
+  const withoutSlash = name.endsWith("/") ? name.slice(0, -1) : name;
+  const segments = withoutSlash.split("/");
+  if (!withoutSlash || name.includes("\\") || name.includes("\0") || name.includes("\uFFFD") || name.startsWith("/") || /^[A-Za-z]:/u.test(name) || segments.some((segment) => !segment || segment === "." || segment === "..") || path.posix.normalize(withoutSlash) !== withoutSlash) {
+    throw new Error(`Extension artifact contains an unsafe path: ${JSON.stringify(name)}.`);
+  }
+}
+function localEntryDataOffset(archive, entry) {
+  const offset = entry.localOffset;
+  if (offset + 30 > archive.length || archive.readUInt32LE(offset) !== 67324752) {
+    throw new Error(`Extension artifact has a malformed local entry: ${entry.name}.`);
+  }
+  const flags = archive.readUInt16LE(offset + 6);
+  const method = archive.readUInt16LE(offset + 8);
+  const nameLength = archive.readUInt16LE(offset + 26);
+  const extraLength = archive.readUInt16LE(offset + 28);
+  const localName = archive.subarray(offset + 30, offset + 30 + nameLength).toString("utf8");
+  const dataOffset = offset + 30 + nameLength + extraLength;
+  if (localName !== entry.name || method !== entry.method || (flags & 1) !== 0 || dataOffset + entry.compressedSize > archive.length) {
+    throw new Error(`Extension artifact local entry does not match its directory record: ${entry.name}.`);
+  }
+  return dataOffset;
+}
+function findEndOfCentralDirectory(archive) {
+  const start = Math.max(0, archive.length - 65557);
+  for (let offset = archive.length - 22; offset >= start; offset -= 1) {
+    if (archive.readUInt32LE(offset) === 101010256) {
+      const commentLength = archive.readUInt16LE(offset + 20);
+      if (offset + 22 + commentLength === archive.length) return offset;
+    }
+  }
+  throw new Error("Extension artifact is not a valid ZIP archive.");
+}
+async function validateManifestVersion(extensionDir, expectedVersion) {
+  await assertRegularTree(extensionDir);
+  const manifestPath = path.join(extensionDir, "manifest.json");
+  const manifestStat = await fsp.lstat(manifestPath).catch(() => null);
+  if (!manifestStat?.isFile() || manifestStat.isSymbolicLink() || manifestStat.size > 2 * 1024 * 1024) {
+    throw new Error("Extension artifact manifest.json must be a regular file smaller than 2 MiB.");
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+  } catch {
+    throw new Error("Extension artifact manifest.json is not valid JSON.");
+  }
+  const version = typeof manifest === "object" && manifest !== null && "version" in manifest ? manifest.version : void 0;
+  if (typeof version !== "string" || normalizeManifestVersion(version) !== expectedVersion) {
+    throw new Error(`Extension artifact manifest version ${String(version ?? "missing")} does not match expected ${expectedVersion}.`);
+  }
+  return version;
+}
+function normalizeManifestVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:\.\d+)?$/u.test(version)) return null;
+  const parts = version.split(".");
+  if (parts.length === 4 && parts[3] !== "0") return null;
+  return parts.slice(0, 3).join(".");
+}
+async function assertRegularTree(root) {
+  const rootStat = await fsp.lstat(root).catch(() => null);
+  if (!rootStat?.isDirectory() || rootStat.isSymbolicLink()) {
+    throw new Error(`Extension artifact root must be a regular directory: ${root}`);
+  }
+  const entries = await fsp.readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const child = path.join(root, entry.name);
+    const stat = await fsp.lstat(child);
+    if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile()) {
+      throw new Error(`Extension artifact cache contains an unsupported entry: ${child}`);
+    }
+    if (stat.isDirectory()) await assertRegularTree(child);
+  }
+}
+async function assertContainedDirectory(directory, root) {
+  const resolvedRoot = await fsp.realpath(root);
+  const resolvedDirectory = await fsp.realpath(directory);
+  if (resolvedDirectory !== resolvedRoot && !resolvedDirectory.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`Extension artifact cache path escapes its root: ${directory}`);
+  }
+  let current = resolvedDirectory;
+  while (current !== resolvedRoot) {
+    const stat = await fsp.lstat(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new Error(`Extension artifact cache path is not a regular directory: ${current}`);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error(`Extension artifact cache path escapes its root: ${directory}`);
+    current = parent;
+  }
+}
+async function readCachedArtifact(artifactRoot, provenancePath, sha256, expectedVersion) {
+  try {
+    const provenanceStat = await fsp.lstat(provenancePath);
+    if (!provenanceStat.isFile() || provenanceStat.isSymbolicLink() || provenanceStat.size > 64 * 1024) return null;
+    const provenance = JSON.parse(await fsp.readFile(provenancePath, "utf8"));
+    if (provenance.schemaVersion !== 1 || provenance.sha256 !== sha256 || provenance.expectedVersion !== expectedVersion || typeof provenance.treeSha256 !== "string" || !/^[a-f0-9]{64}$/u.test(provenance.treeSha256) || typeof provenance.extensionDir !== "string" || path.isAbsolute(provenance.extensionDir) || provenance.extensionDir.split(path.sep).includes("..")) return null;
+    const extensionDir = path.resolve(artifactRoot, provenance.extensionDir);
+    if (extensionDir !== artifactRoot && !extensionDir.startsWith(`${artifactRoot}${path.sep}`)) return null;
+    const manifestVersion = await validateManifestVersion(extensionDir, expectedVersion);
+    const treeSha256 = extensionTreeSha256(extensionDir);
+    if (treeSha256 !== provenance.treeSha256) return null;
+    return {
+      schemaVersion: 1,
+      expectedVersion,
+      manifestVersion,
+      sha256,
+      treeSha256,
+      extensionDir,
+      provenancePath
+    };
+  } catch {
+    return null;
+  }
+}
+function isAlreadyExists(error) {
+  return Boolean(
+    error && typeof error === "object" && "code" in error && ["EEXIST", "ENOTEMPTY"].includes(String(error.code))
+  );
+}
+async function pathExists(file) {
+  return fsp.access(file).then(() => true, () => false);
+}
+const CRC_TABLE = Array.from({ length: 256 }, (_, initial) => {
+  let value = initial;
+  for (let bit = 0; bit < 8; bit += 1) value = (value & 1) !== 0 ? 3988292384 ^ value >>> 1 : value >>> 1;
+  return value >>> 0;
+});
+function crc32(buffer) {
+  let value = 4294967295;
+  for (const byte of buffer) value = CRC_TABLE[(value ^ byte) & 255] ^ value >>> 8;
+  return (value ^ 4294967295) >>> 0;
+}
+export {
+  acquireExtensionReleaseArtifact
+};