@blamejs/core 0.12.6 → 0.12.7

package/lib/archive.js

@@ -538,9 +538,21 @@ function zip() {
   };
 }
 
+// Read primitive — random-access ZIP reader composes the same wire-
+// format constants as the write side. Lives in a sibling file to keep
+// this module under the line-budget the @primitive validator + the
+// codebase-patterns "single-concern file" pattern prefer.
+var archiveRead = require("./archive-read");
+
 module.exports = {
   zip:           zip,
   ArchiveError:  ArchiveError,
+  read: {
+    zip:                 archiveRead.zip,
+    ArchiveReadError:    archiveRead.ArchiveReadError,
+    DEFAULT_BOMB_POLICY: archiveRead.DEFAULT_BOMB_POLICY,
+    DEFAULT_ENTRY_TYPE_POLICY: archiveRead.DEFAULT_ENTRY_TYPE_POLICY,
+  },
   // Test-only export — operators don't call this; it's here for unit-testing
   // the CRC implementation against known vectors.
   _crc32ForTest: _crc32,

package/lib/backup/index.js

@@ -992,6 +992,7 @@ function runInWorker(opts) {
 module.exports = {
   create:                    create,
   diskStorage:               diskStorage,
+  bundleAdapterStorage:      bundleAdapterStorage,
   recommendedFiles:          recommendedFiles,
   runInWorker:               runInWorker,
   verifyManifestSignature:   verifyManifestSignature,
@@ -999,3 +1000,247 @@ module.exports = {
   BackupError:               BackupError,
   BUNDLE_ID_RE:              BUNDLE_ID_RE,
 };
+
+// ---- v0.12.7: bundleAdapterStorage ---------------------------------------
+
+/**
+ * @primitive b.backup.bundleAdapterStorage
+ * @signature b.backup.bundleAdapterStorage(opts)
+ * @since     0.12.7
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.backup.diskStorage, b.backup.create
+ *
+ * Adapter-driven storage backend. Wraps the bundle directory's file
+ * tree into per-file key-value pairs routed through an operator-
+ * supplied byte-store adapter so backup bundles can land anywhere
+ * that exposes the contract (local fs is the v0.12.7 default; tar
+ * folding lands v0.12.8, tar.gz v0.12.9, S3/MinIO/Azure/GCS
+ * objectStore v0.12.11).
+ *
+ * The adapter contract (small surface; an `fs` implementation is the
+ * default + ships in `lib/backup/_adapter-fs.js`):
+ *
+ *   adapter.writeFile(key, bytes): Promise<void>
+ *   adapter.readFile(key): Promise<Buffer>
+ *   adapter.listKeys(prefix): Promise<string[]>
+ *   adapter.deleteKey(key): Promise<void>
+ *   adapter.hasKey(key): Promise<boolean>
+ *
+ * Keys are `<bundleId>/<relative/path/within/bundle>`. Operators
+ * pointing at an objectStore implementation pass an adapter that
+ * routes keys to S3 paths; pointing at an HTTP-backed store, ditto.
+ *
+ * @opts
+ *   adapter:   { writeFile, readFile, listKeys, deleteKey, hasKey },
+ *
+ * @example
+ *   var storage = b.backup.bundleAdapterStorage({
+ *     adapter: b.backup.bundleAdapterStorage.fsAdapter({ root: "/var/backups" }),
+ *   });
+ *   storage.name;       // → "adapter"
+ *   typeof storage.writeBundle;   // → "function"
+ */
+function bundleAdapterStorage(opts) {
+  opts = opts || {};
+  if (!opts.adapter || typeof opts.adapter !== "object") {
+    throw new BackupError("backup/bad-adapter",
+      "bundleAdapterStorage: opts.adapter is required (an object with writeFile/readFile/listKeys/deleteKey/hasKey)");
+  }
+  var adapter = opts.adapter;
+  var required = ["writeFile", "readFile", "listKeys", "deleteKey", "hasKey"];
+  for (var i = 0; i < required.length; i += 1) {
+    if (typeof adapter[required[i]] !== "function") {
+      throw new BackupError("backup/bad-adapter",
+        "bundleAdapterStorage: adapter missing method '" + required[i] + "'");
+    }
+  }
+
+  function _ensureBundleId(bundleId) {
+    if (!_isValidBundleId(bundleId)) {
+      throw new BackupError("backup/bad-bundle-id",
+        "bundleId must match the framework's timestamp+suffix format");
+    }
+  }
+
+  function _walkDirSync(rootDir, out, rel) {
+    rel = rel || "";
+    var entries = nodeFs.readdirSync(nodePath.join(rootDir, rel), { withFileTypes: true });
+    for (var i = 0; i < entries.length; i += 1) {
+      var name = entries[i].name;
+      var relPath = rel ? (rel + "/" + name) : name;
+      if (entries[i].isDirectory()) {
+        _walkDirSync(rootDir, out, relPath);
+      } else if (entries[i].isFile()) {
+        out.push(relPath);
+      }
+    }
+    return out;
+  }
+
+  return {
+    name: "adapter",
+    async writeBundle(bundleId, sourceDir) {
+      _ensureBundleId(bundleId);
+      if (!nodeFs.existsSync(sourceDir)) {
+        throw new BackupError("backup/no-source",
+          "writeBundle: sourceDir does not exist: " + sourceDir);
+      }
+      var alreadyHas = await adapter.hasKey(bundleId + "/manifest.json");
+      if (alreadyHas) {
+        throw new BackupError("backup/bundle-exists",
+          "writeBundle: bundle '" + bundleId + "' already exists in storage");
+      }
+      var relPaths = _walkDirSync(sourceDir, []);
+      for (var i = 0; i < relPaths.length; i += 1) {
+        var rel = relPaths[i];
+        var bytes = nodeFs.readFileSync(nodePath.join(sourceDir, rel));
+        await adapter.writeFile(bundleId + "/" + rel, bytes);
+      }
+    },
+    async readBundle(bundleId, destDir) {
+      _ensureBundleId(bundleId);
+      if (nodeFs.existsSync(destDir)) {
+        throw new BackupError("backup/dest-exists",
+          "readBundle: destDir already exists: " + destDir);
+      }
+      var keys = await adapter.listKeys(bundleId + "/");
+      if (keys.length === 0) {
+        throw new BackupError("backup/bundle-not-found",
+          "readBundle: '" + bundleId + "' not in storage");
+      }
+      atomicFile.ensureDir(destDir);
+      for (var i = 0; i < keys.length; i += 1) {
+        var key = keys[i];
+        var prefix = bundleId + "/";
+        if (key.indexOf(prefix) !== 0) continue;
+        var rel = key.slice(prefix.length);
+        // Path-safety: rel must not escape destDir. Reuse the
+        // verifyExtractionPath dual-check primitive when the dest
+        // already exists (writeable directory just created).
+        var destPath = nodePath.join(destDir, rel);
+        var resolvedDest = nodePath.resolve(destPath);
+        var resolvedRoot = nodePath.resolve(destDir);
+        if (resolvedDest !== resolvedRoot &&
+            resolvedDest.indexOf(resolvedRoot + nodePath.sep) !== 0) {
+          throw new BackupError("backup/bad-key",
+            "readBundle: storage key " + JSON.stringify(rel) +
+            " escapes destDir " + JSON.stringify(destDir));
+        }
+        atomicFile.ensureDir(nodePath.dirname(destPath));
+        var bytes = await adapter.readFile(key);
+        nodeFs.writeFileSync(destPath, bytes);
+      }
+    },
+    async listBundles() {
+      // Get every key, partition by bundleId prefix, return sorted.
+      var allKeys = await adapter.listKeys("");
+      var byBundle = new Map();
+      for (var i = 0; i < allKeys.length; i += 1) {
+        var key = allKeys[i];
+        var slash = key.indexOf("/");
+        if (slash <= 0) continue;
+        var bid = key.slice(0, slash);
+        if (!_isValidBundleId(bid)) continue;
+        var stats = byBundle.get(bid);
+        if (!stats) {
+          stats = { count: 0, size: 0 };
+          byBundle.set(bid, stats);
+        }
+        stats.count += 1;
+        // Note: size is approximate — we'd need a stat-per-key here,
+        // and many adapter implementations don't expose a fast stat
+        // primitive. listBundles is best-effort; operators wanting
+        // exact size do their own walk.
+      }
+      var out = [];
+      var entries = Array.from(byBundle.entries());
+      for (var j = 0; j < entries.length; j += 1) {
+        var bidJ = entries[j][0];
+        out.push({
+          bundleId:  bidJ,
+          createdAt: null,    // adapter may not expose mtime
+          size:      null,    // best-effort
+        });
+      }
+      out.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
+      return out;
+    },
+    async deleteBundle(bundleId) {
+      _ensureBundleId(bundleId);
+      var keys = await adapter.listKeys(bundleId + "/");
+      for (var i = 0; i < keys.length; i += 1) {
+        await adapter.deleteKey(keys[i]);
+      }
+    },
+    async hasBundle(bundleId) {
+      _ensureBundleId(bundleId);
+      return adapter.hasKey(bundleId + "/manifest.json");
+    },
+  };
+}
+
+// fsAdapter — default adapter for bundleAdapterStorage backed by the
+// local filesystem. Provides the same on-disk layout as diskStorage
+// (bundle directories under a root path) but via the adapter contract
+// so v0.12.8+ can swap the implementation transparently.
+bundleAdapterStorage.fsAdapter = function (fsOpts) {
+  fsOpts = fsOpts || {};
+  validateOpts.requireNonEmptyString(fsOpts.root,
+    "bundleAdapterStorage.fsAdapter: opts.root", BackupError, "backup/no-storage-root");
+  var root = fsOpts.root;
+  atomicFile.ensureDir(root);
+
+  function _keyPath(key) {
+    // Refuse keys with traversal segments — defense in depth even
+    // though the storage layer also checks.
+    if (key.indexOf("..") !== -1 || key.indexOf("\0") !== -1) {
+      throw new BackupError("backup/bad-key",
+        "fsAdapter: key contains invalid characters: " + JSON.stringify(key));
+    }
+    return nodePath.join(root, key);
+  }
+
+  return {
+    async writeFile(key, bytes) {
+      var path = _keyPath(key);
+      atomicFile.ensureDir(nodePath.dirname(path));
+      nodeFs.writeFileSync(path, bytes);
+    },
+    async readFile(key) {
+      var path = _keyPath(key);
+      if (!nodeFs.existsSync(path)) {
+        throw new BackupError("backup/no-key", "fsAdapter: key not found: " + JSON.stringify(key));
+      }
+      return nodeFs.readFileSync(path);
+    },
+    async listKeys(prefix) {
+      var out = [];
+      if (!nodeFs.existsSync(root)) return out;
+      function _walk(rel) {
+        var entries = nodeFs.readdirSync(nodePath.join(root, rel || "."), { withFileTypes: true });
+        for (var i = 0; i < entries.length; i += 1) {
+          var name = entries[i].name;
+          var nextRel = rel ? (rel + "/" + name) : name;
+          if (entries[i].isDirectory()) {
+            _walk(nextRel);
+          } else if (entries[i].isFile()) {
+            if (!prefix || nextRel.indexOf(prefix) === 0) {
+              out.push(nextRel);
+            }
+          }
+        }
+      }
+      _walk("");
+      return out;
+    },
+    async deleteKey(key) {
+      var path = _keyPath(key);
+      try { nodeFs.rmSync(path); } catch (_e) { /* drop-silent — key already gone */ }
+    },
+    async hasKey(key) {
+      try { return nodeFs.existsSync(_keyPath(key)); }
+      catch (_e) { return false; }
+    },
+  };
+};

package/lib/guard-archive.js

@@ -71,6 +71,7 @@ var gateContract = require("./gate-contract");
 var C = require("./constants");
 var numericBounds = require("./numeric-bounds");
 var guardFilename = require("./guard-filename");
+var archiveRead = lazyRequire(function () { return require("./archive-read"); });
 var { GuardArchiveError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -898,4 +899,143 @@ module.exports = {
   ARCHIVE_EXTENSIONS:  ARCHIVE_EXTENSIONS,
   MAGIC_SIGNATURES:    MAGIC_SIGNATURES,
   GuardArchiveError:   GuardArchiveError,
+  inspect:             inspect,
+  zipBombPolicy:       zipBombPolicy,
+  entryTypePolicy:     entryTypePolicy,
 };
+
+// ---- v0.12.7 extensions ---------------------------------------------------
+
+/**
+ * @primitive b.guardArchive.inspect
+ * @signature b.guardArchive.inspect(adapter, opts?)
+ * @since     0.12.7
+ * @status    stable
+ * @related   b.archive.read.zip, b.guardArchive.validateEntries
+ *
+ * Bridge primitive: runs `b.archive.read.zip(adapter).inspect()` to
+ * enumerate the entry list (no decompression), then hands the list to
+ * `validateEntries` for the full posture-aware gate. Returns
+ * `{ entries, issues, decisions }` so the caller decides whether to
+ * proceed.
+ *
+ * Operators using the lower-level read primitive directly call this
+ * to combine the metadata pass with the guard pass; `b.safeArchive.
+ * extract` does the same composition inline under the hood.
+ *
+ * @opts
+ *   profile:        "strict" | "balanced" | "permissive" | "hipaa" | ...,
+ *   format:         "zip" (v0.12.7 — tar v0.12.8, gz v0.12.9),
+ *   audit:          b.audit,
+ *
+ * @example
+ *   var adapter = b.archive.adapters.fs("/var/uploads/payload.zip");
+ *   var summary = await b.guardArchive.inspect(adapter, { profile: "strict" });
+ *   if (summary.issues.length > 0) refuse(summary.issues);
+ */
+async function inspect(adapter, opts) {
+  opts = opts || {};
+  var format = opts.format || "zip";
+  if (format !== "zip") {
+    throw new GuardArchiveError("archive/format-unsupported",
+      "guardArchive.inspect: format=" + JSON.stringify(format) +
+      " — v0.12.7 ships ZIP only (tar v0.12.8, gz v0.12.9)");
+  }
+  var reader = archiveRead().zip(adapter, { audit: opts.audit });
+  var rawEntries = await reader.inspect();
+  // Project the read-primitive's entry shape into validateEntries'
+  // expected `{ name, size, compressedSize, isSymlink, ... }` shape.
+  var guardEntries = rawEntries.map(function (e) {
+    return {
+      name:           e.name,
+      size:           e.size,
+      compressedSize: e.compressedSize,
+      isSymlink:      e.entryType === "symlink",
+      isHardlink:     false,
+      linkTarget:     null,
+      isDirectory:    e.entryType === "directory",
+      isEncrypted:    e.isEncrypted,
+      attrs:          { externalAttrs: e.externalAttrs },
+    };
+  });
+  var profile = opts.profile || "balanced";
+  var result = validateEntries(guardEntries, { profile: profile });
+  return {
+    entries:   rawEntries,
+    issues:    (result && result.issues) || [],
+    decisions: (result && result.decisions) || {},
+  };
+}
+
+/**
+ * @primitive b.guardArchive.zipBombPolicy
+ * @signature b.guardArchive.zipBombPolicy(opts)
+ * @since     0.12.7
+ * @status    stable
+ * @related   b.archive.read.zip, b.safeArchive.extract
+ *
+ * Policy-object builder for decompression-bomb caps. Operators
+ * declare the cap set once + reuse it across `b.archive.read.zip` /
+ * `b.safeArchive.extract` call sites. Defaults match the cap shape
+ * in `lib/archive-read.js` `DEFAULT_BOMB_POLICY`.
+ *
+ * @opts
+ *   maxEntries:                65535,
+ *   maxEntryDecompressedBytes: 128 * MiB,
+ *   maxTotalDecompressedBytes: 4 * GiB,
+ *   maxExpansionRatio:         100,
+ *
+ * @example
+ *   var policy = b.guardArchive.zipBombPolicy({
+ *     maxTotalDecompressedBytes: 256 * 1024 * 1024,
+ *     maxExpansionRatio: 50,
+ *   });
+ *   await b.safeArchive.extract({ source, destination, bombPolicy: policy });
+ */
+function zipBombPolicy(opts) {
+  opts = opts || {};
+  return Object.freeze({
+    maxEntries:                opts.maxEntries                || 65535,
+    maxEntryDecompressedBytes: opts.maxEntryDecompressedBytes || C.BYTES.mib(128),
+    maxTotalDecompressedBytes: opts.maxTotalDecompressedBytes || C.BYTES.gib(4),
+    maxExpansionRatio:         opts.maxExpansionRatio         || 100,
+  });
+}
+
+/**
+ * @primitive b.guardArchive.entryTypePolicy
+ * @signature b.guardArchive.entryTypePolicy(opts)
+ * @since     0.12.7
+ * @status    stable
+ * @related   b.archive.read.zip, b.safeArchive.extract
+ *
+ * Policy-object builder for entry-type allowlist. Defaults refuse
+ * every "interesting" entry type (symlink / hardlink / device / fifo
+ * / socket); operators opt in per-type and route through the
+ * additional realpath-on-target check in `b.guardFilename.
+ * verifyExtractionPath`.
+ *
+ * Symlinks + hardlinks under default settings are refused
+ * unconditionally — CVE-2025-11001 / 11002 / 26960 class.
+ *
+ * @opts
+ *   symlinks:   false,
+ *   hardlinks:  false,
+ *   devices:    false,
+ *   fifos:      false,
+ *   sockets:    false,
+ *
+ * @example
+ *   var policy = b.guardArchive.entryTypePolicy({ symlinks: true });
+ *   await b.safeArchive.extract({ source, destination, entryTypePolicy: policy });
+ */
+function entryTypePolicy(opts) {
+  opts = opts || {};
+  return Object.freeze({
+    symlinks:  opts.symlinks  === true,
+    hardlinks: opts.hardlinks === true,
+    devices:   opts.devices   === true,
+    fifos:     opts.fifos     === true,
+    sockets:   opts.sockets   === true,
+  });
+}

package/lib/guard-filename.js

@@ -923,6 +923,210 @@ var _filenameRulePacks = gateContract.makeRulePackLoader(GuardFilenameError, "fi
  */
 var loadRulePack = _filenameRulePacks.load;
 
+// ---- verifyExtractionPath -------------------------------------------------
+
+var nodePath = require("node:path");
+var nodeFs   = require("node:fs");
+
+// CVE-2025-4517 PATH_MAX threshold — Python's tarfile filter relied on
+// os.path.realpath which silently stops resolving symlinks once the
+// resolved path exceeds PATH_MAX (4096 on Linux). The kernel keeps
+// resolving past that, so the filter's safety check + the kernel's
+// extraction diverge. We refuse paths whose pre-resolve length already
+// exceeds PATH_MAX so the operator's realpath behavior is never the
+// gating factor.
+var PATH_MAX_BYTES = 4096;
+
+/**
+ * @primitive b.guardFilename.verifyExtractionPath
+ * @signature b.guardFilename.verifyExtractionPath(entryName, extractionRoot, opts?)
+ * @since     0.12.7
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.guardArchive.checkExtractionPath, b.guardArchive.validateEntries, b.archive.read.zip
+ *
+ * Dual-check extraction path safety: string-check (refuses `..`, leading
+ * `/` / `\\`, drive-letter prefix, null byte, PATH_MAX overflow) followed
+ * by `fs.realpath` agreement check (the resolved path on disk must
+ * land inside the realpath of the extraction root). Returns the
+ * resolved absolute path on success; throws `GuardFilenameError` on
+ * any refusal.
+ *
+ * Companion to `b.guardArchive.checkExtractionPath` (the string-only
+ * portable gate the guard-archive primitive keeps fs-free for use as
+ * a posture cascade member). `verifyExtractionPath` deliberately
+ * couples to `node:fs` — the deeper realpath check defends the
+ * CVE-2025-4517 PATH_MAX TOCTOU class where the operator's path
+ * resolution and the kernel's diverge silently past PATH_MAX.
+ *
+ * `b.archive.read.zip.extract` composes this on every entry; operators
+ * extracting via the safeArchive orchestrator never call it directly.
+ * Operators rolling their own extract loop call it per entry.
+ *
+ * @opts
+ *   followSymlinks:  boolean,       // default false — symlink in the
+ *                                   //   resolved path refuses unless set
+ *
+ * @example
+ *   var resolved = b.guardFilename.verifyExtractionPath(
+ *     "docs/readme.txt",
+ *     "/var/quarantine"
+ *   );
+ *   // → "/var/quarantine/docs/readme.txt"
+ *
+ *   // ../ refuses
+ *   b.guardFilename.verifyExtractionPath("../etc/passwd", "/var/quarantine");
+ *   // throws GuardFilenameError("filename.extraction-traversal")
+ *
+ *   // PATH_MAX-overflow refuses BEFORE realpath truncation hits
+ *   b.guardFilename.verifyExtractionPath(longName, "/var/quarantine");
+ *   // throws GuardFilenameError("filename.extraction-path-max")
+ */
+function verifyExtractionPath(entryName, extractionRoot, opts) {
+  opts = opts || {};
+  if (typeof entryName !== "string" || entryName.length === 0) {
+    throw new GuardFilenameError("filename.extraction-empty",
+      "verifyExtractionPath: entryName must be non-empty string");
+  }
+  if (typeof extractionRoot !== "string" || extractionRoot.length === 0) {
+    throw new GuardFilenameError("filename.extraction-bad-root",
+      "verifyExtractionPath: extractionRoot must be non-empty string");
+  }
+  // PATH_MAX defense — refuse oversize names BEFORE any path operation
+  // (mkdir / realpath / open) can truncate silently.
+  if (entryName.length > PATH_MAX_BYTES) {
+    throw new GuardFilenameError("filename.extraction-path-max",
+      "verifyExtractionPath: entryName length " + entryName.length +
+      " exceeds PATH_MAX=" + PATH_MAX_BYTES +
+      " (CVE-2025-4517 class — operator realpath truncation defense)");
+  }
+  // String-check first — these checks are portable + don't touch fs.
+  // Null byte — POSIX path APIs treat it as a string terminator.
+  if (entryName.indexOf("\u0000") !== -1) {
+    throw new GuardFilenameError("filename.extraction-null-byte",
+      "verifyExtractionPath: entryName contains null byte");
+  }
+  // Normalize separators so the `..` walk catches Windows-style too.
+  var normalized = entryName.replace(/\\/g, "/");
+  // Leading-slash absolute path refuses.
+  if (normalized.length > 0 && normalized[0] === "/") {
+    throw new GuardFilenameError("filename.extraction-absolute",
+      "verifyExtractionPath: entryName is an absolute path");
+  }
+  // Drive-letter prefix (Windows) refuses.
+  if (/^[A-Za-z]:[/\\]/.test(entryName)) {
+    throw new GuardFilenameError("filename.extraction-drive-prefix",
+      "verifyExtractionPath: entryName starts with a drive-letter prefix");
+  }
+  // UNC path (Windows) refuses.
+  if (entryName.indexOf("\\\\") === 0 || entryName.indexOf("//") === 0) {
+    throw new GuardFilenameError("filename.extraction-unc",
+      "verifyExtractionPath: entryName starts with a UNC prefix");
+  }
+  // `..` segment refuses — walk path components.
+  var segs = normalized.split("/");
+  for (var si = 0; si < segs.length; si += 1) {
+    if (segs[si] === ".." || segs[si] === "..\\" || segs[si] === "..%2f" || segs[si] === "..%5c") {
+      throw new GuardFilenameError("filename.extraction-traversal",
+        "verifyExtractionPath: entryName contains .. segment");
+    }
+    // URL-encoded variants — explicit refusal so operators don't
+    // need to percent-decode before passing the entry name in.
+    if (/%2e%2e/i.test(segs[si]) || /%c0%ae/i.test(segs[si])) {
+      throw new GuardFilenameError("filename.extraction-traversal-encoded",
+        "verifyExtractionPath: entryName contains encoded .. segment");
+    }
+  }
+  // Resolve the destination path against the root via path.resolve
+  // (string-level computation; no fs hits).
+  var stringResolved = nodePath.resolve(extractionRoot, normalized);
+  var rootResolved = nodePath.resolve(extractionRoot);
+  // String-level containment check — the resolved path must start
+  // with the root + separator (or equal the root for the directory
+  // entry itself). path.resolve normalizes separators platform-aware.
+  var sep = nodePath.sep;
+  if (stringResolved !== rootResolved &&
+      stringResolved.indexOf(rootResolved + sep) !== 0) {
+    throw new GuardFilenameError("filename.extraction-escape",
+      "verifyExtractionPath: resolved path " + JSON.stringify(stringResolved) +
+      " escapes extraction root " + JSON.stringify(rootResolved));
+  }
+  // Realpath-agreement check (fs-coupled). The CVE-2025-4517 class
+  // exploits a divergence between the operator's path.resolve view
+  // and the kernel's symlink-resolution. We resolve the longest
+  // existing ancestor + verify the realpath agrees with our string
+  // view.
+  if (nodeFs.existsSync(rootResolved)) {
+    var realRoot;
+    try {
+      realRoot = nodeFs.realpathSync(rootResolved);
+    } catch (e) {
+      throw new GuardFilenameError("filename.extraction-root-realpath",
+        "verifyExtractionPath: cannot realpath extractionRoot " +
+        JSON.stringify(rootResolved) + ": " + (e && e.message));
+    }
+    // Walk up from the target until we find an existing parent —
+    // every ancestor that EXISTS must realpath inside realRoot. Once
+    // we hit a non-existent path, the create-and-extract step will
+    // populate it; the operator-supplied target name doesn't pre-
+    // exist, so the deepest existing ancestor is the boundary check.
+    var probe = nodePath.dirname(stringResolved);
+    var safetyCounter = 0;
+    var SAFETY_LIMIT = 4096;     // guards against probe walking past root forever
+    while (probe.length >= rootResolved.length && safetyCounter < SAFETY_LIMIT) {
+      safetyCounter += 1;
+      if (nodeFs.existsSync(probe)) {
+        var realProbe;
+        try { realProbe = nodeFs.realpathSync(probe); }
+        catch (e2) {
+          throw new GuardFilenameError("filename.extraction-realpath",
+            "verifyExtractionPath: cannot realpath probe " +
+            JSON.stringify(probe) + ": " + (e2 && e2.message));
+        }
+        // Two cases for the realpath comparison:
+        //   a) The probe's realpath stays inside realRoot — the symlink
+        //      (if any) is OS-level filesystem layout (macOS /var →
+        //      /private/var, Linux /tmp -> tmpfs mount) and the
+        //      ancestor was already canonicalized when we hashed
+        //      realRoot at the top. Accept.
+        //   b) The probe's realpath escapes realRoot — the symlink
+        //      resolves outside the trust boundary. Refuse (this is
+        //      the actual CVE-2025-4517 PATH_MAX TOCTOU class
+        //      defense).
+        // Also normalize probe through path.resolve(realRoot, relative
+        // -- to -- realRoot) so we compare against the SAME canonicalized
+        // root, not the operator-supplied form. Computing `probeRealRel`
+        // via the realRoot prefix avoids treating OS-level /var -> /private
+        // /var as an escape just because realProbe doesn't textually share
+        // the rootResolved prefix.
+        var probeInsideRoot = (realProbe === realRoot) ||
+                              (realProbe.indexOf(realRoot + sep) === 0);
+        if (!probeInsideRoot) {
+          throw new GuardFilenameError("filename.extraction-realpath-escape",
+            "verifyExtractionPath: realpath of " + JSON.stringify(probe) +
+            " (" + JSON.stringify(realProbe) + ") escapes realpath of root " +
+            JSON.stringify(realRoot) +
+            " — CVE-2025-4517 PATH_MAX TOCTOU class");
+        }
+        // Symlink-anywhere-in-chain refusal was removed: macOS /
+        // *BSD filesystems carry OS-level symlinks in standard paths
+        // (/var → /private/var, /tmp → /private/tmp) that legitimate
+        // operator usage routinely crosses. The realpath-agreement
+        // check above is the load-bearing defense; if the resolved
+        // chain STAYS inside realRoot, the symlinks resolved within
+        // the trust boundary and the extraction is safe. Hostile
+        // symlinks that escape are caught by the escape branch.
+        void opts.followSymlinks;
+        break;
+      }
+      var parent = nodePath.dirname(probe);
+      if (parent === probe) break;   // hit fs root
+      probe = parent;
+    }
+  }
+  return stringResolved;
+}
+
 module.exports = {
   // ---- guard-* family identity ----
   // Filename is a different axis from content-bytes (operators
@@ -953,4 +1157,5 @@ module.exports = {
   WIN_RESERVED_NAMES:  WIN_RESERVED_NAMES,
   SHELL_EXEC_EXTS:     SHELL_EXEC_EXTS,
   GuardFilenameError:  GuardFilenameError,
+  verifyExtractionPath: verifyExtractionPath,
 };