@blamejs/blamejs-shop 0.0.82 → 0.0.85

package/lib/vendor/blamejs/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,
 };

package/lib/vendor/blamejs/lib/safe-archive.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * @module b.safeArchive
+ * @nav    Tools
+ * @title  Safe Archive
+ *
+ * @intro
+ *   One-liner safe-extract orchestrator for adversarial archives.
+ *   Combines `b.archive.read` + `b.guardArchive.inspect` + `b.guardFilename.
+ *   verifyExtractionPath` + zip-bomb + entry-type policy + audit chain
+ *   into a single call.
+ *
+ *   The 90%-case workflow — operator receives a hostile-shaped archive
+ *   from an upload / external system / pipeline, wants to extract it
+ *   into a quarantine directory with every defense default-on, and
+ *   doesn't want to learn the read/guard/safeDecompress composition
+ *   surface to do it.
+ *
+ *   `b.safeArchive.extract({ source, destination, ... })` does the
+ *   composition for them. Operators with fine-grained control needs
+ *   reach for `b.archive.read.zip(adapter)` directly + assemble the
+ *   pipeline manually.
+ *
+ *   Format auto-detection sniffs the first ~512 bytes for magic
+ *   signatures. v0.12.7 ships ZIP detection (LFH magic `0x04034b50`
+ *   + EOCD magic `0x06054b50`); tar / gz / ae2 / `b.crypto.encryptPacked`-
+ *   wrapped formats are flagged as `safe-archive/format-unsupported`
+ *   in this patch — tar lands v0.12.8, gz v0.12.9, encryption v0.12.10/11.
+ *
+ *   The orchestrator refuses the WHOLE archive on any single critical
+ *   guard issue — no partial extraction. Cleanup is `fs.rm`-recursive
+ *   on the destination if extraction was interrupted, so a failed
+ *   extract leaves no half-state on disk.
+ *
+ * @card
+ *   One-liner safe-extract orchestrator — read + guard + path-safety + bomb caps + audit.
+ */
+
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var C = require("./constants");
+var { defineClass } = require("./framework-error");
+
+var SafeArchiveError = defineClass("SafeArchiveError", { alwaysPermanent: true });
+
+var archiveRead = lazyRequire(function () { return require("./archive-read"); });
+var archiveAdapters = lazyRequire(function () { return require("./archive-adapters"); });
+var archiveTarRead = lazyRequire(function () { return require("./archive-tar-read"); });
+
+// ---- Format sniffing ----------------------------------------------------
+
+// ZIP local file header magic per APPNOTE §4.3.7.
+// ZIP empty-archive EOCD magic per APPNOTE §4.3.16.
+var MAGIC_ZIP_LFH  = 0x04034b50;
+var MAGIC_ZIP_EOCD = 0x06054b50;
+// GZIP magic per RFC 1952 §2.3.1.
+var MAGIC_GZIP_BE  = 0x1f8b;
+// b.crypto.encryptPacked envelope magic — the prefix the framework's
+// PQ envelope writes. (Sentinel value for v0.12.10+ Flavor 1 unwrap.)
+var MAGIC_ENCPACKED = "EPACK";
+
+async function _sniffMagic(adapter) {
+  // For random-access adapters, the format sniffer reads the first
+  // 512 bytes — enough for ZIP + GZIP + b.crypto.encryptPacked magic
+  // detection. tar magic lives at offset 257 inside the first 512-
+  // byte header block, so we need at least 263 bytes; 512 covers it.
+  if (adapter.kind !== "random-access") {
+    throw new SafeArchiveError("safe-archive/sniff-unsupported-adapter",
+      "format sniffing requires a random-access adapter (got " + adapter.kind + ")");
+  }
+  var size = adapter.size;
+  if (size == null && typeof adapter.resolveSize === "function") {
+    size = await adapter.resolveSize();
+  }
+  if (typeof size !== "number" || size < 4) {
+    throw new SafeArchiveError("safe-archive/too-small",
+      "archive too small to determine format (size=" + size + ")");
+  }
+  var head = await adapter.range(0, Math.min(C.BYTES.bytes(512), size));
+  // ZIP — LFH at offset 0 (most common) OR empty-archive EOCD at offset 0.
+  if (head.length >= 4) {
+    var first4 = head.readUInt32LE(0);
+    if (first4 === MAGIC_ZIP_LFH) return { format: "zip", subkind: "lfh" };
+    if (first4 === MAGIC_ZIP_EOCD) return { format: "zip", subkind: "empty" };
+  }
+  // GZIP — 2-byte BE magic.
+  if (head.length >= 2) {
+    var be2 = head.readUInt16BE(0);
+    if (be2 === MAGIC_GZIP_BE) return { format: "gzip" };
+  }
+  // b.crypto.encryptPacked — 5-byte ASCII prefix.
+  if (head.length >= 5) {
+    var prefix = head.slice(0, 5).toString("utf8");
+    if (prefix === MAGIC_ENCPACKED) return { format: "encryptPacked" };
+  }
+  // tar — "ustar" at offset 257 within the first 512-byte header.
+  if (head.length >= 263) {
+    var tarMagic = head.slice(257, 262).toString("utf8");
+    if (tarMagic === "ustar") return { format: "tar" };
+  }
+  return { format: "unknown" };
+}
+
+// ---- Public extract orchestrator ----------------------------------------
+
+/**
+ * @primitive b.safeArchive.extract
+ * @signature b.safeArchive.extract(opts)
+ * @since     0.12.7
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.archive.read.zip, b.guardArchive.inspect, b.guardFilename.verifyExtractionPath
+ *
+ * Safe-extract orchestrator. Combines read + guard + path-safety +
+ * bomb caps + audit in one call.
+ *
+ * Refuses the whole archive on:
+ *   - Format auto-detect mismatch (unknown / unsupported format).
+ *   - Any critical guard issue (CVE-2025-3445 Zip Slip class + path
+ *     traversal + symlink-escape + nested archive + encrypted entry).
+ *   - PATH_MAX overflow on any entry name (CVE-2025-4517 defense).
+ *   - Bomb-policy breach (entry-count / per-entry size / total size /
+ *     expansion ratio).
+ *   - LFH/CD skew on any entry.
+ *
+ * @opts
+ *   source:           b.archive.adapters.* | Buffer | string,
+ *   destination:      string (target directory; created if missing),
+ *   format:           "auto" | "zip"        (v0.12.7 — tar v0.12.8, gz v0.12.9),
+ *   bombPolicy:       b.guardArchive.zipBombPolicy(...) | { ... },
+ *   entryTypePolicy:  b.guardArchive.entryTypePolicy(...) | { ... },
+ *   guardProfile:     "strict" | "balanced" | "permissive" | "hipaa" | ...,
+ *   audit:            b.audit,
+ *   signal:           AbortSignal,
+ *
+ * @example
+ *   var result = await b.safeArchive.extract({
+ *     source:      b.archive.adapters.fs("/var/uploads/payload.zip"),
+ *     destination: "/var/quarantine",
+ *     guardProfile: "strict",
+ *   });
+ *   // → { entries: [{ name, bytesWritten, path }, ...], bytesExtracted, format }
+ */
+async function extract(opts) {
+  opts = opts || {};
+  validateOpts.requireNonEmptyString(opts.destination,
+    "b.safeArchive.extract: opts.destination", SafeArchiveError, "safe-archive/no-destination");
+  // Resolve source → adapter. Strings become fs adapters; Buffers
+  // become buffer adapters; anything else is assumed to BE an adapter
+  // already.
+  var source = opts.source;
+  if (typeof source === "string") {
+    source = archiveAdapters().fs(source, { signal: opts.signal });
+  } else if (Buffer.isBuffer(source)) {
+    source = archiveAdapters().buffer(source, { signal: opts.signal });
+  } else if (archiveAdapters().isTrustedStreamAdapter(source)) {
+    // Trusted-stream adapters are accepted by the contract but the
+    // orchestrator's extract path needs random-access (CD-walk +
+    // LFH/CD skew defense). Refuse upfront with a typed safe-archive
+    // error so the operator sees the constraint at the entry point
+    // rather than an `archive-read/wrong-entry-point` thrown by the
+    // downstream reader. Trusted-stream extract via
+    // `b.archive.read.zip.fromTrustedStream` is deferred to v0.12.8
+    // alongside the tar reader's sequential mode.
+    throw new SafeArchiveError("safe-archive/trusted-stream-unsupported",
+      "extract: trusted-stream adapter sources are not supported by the orchestrator " +
+      "(the adversarial-safe CD-walk requires random-access). Collect the bytes via " +
+      "`b.archive.adapters.buffer(await collect(readable))` and pass that, or use " +
+      "`b.archive.read.zip.fromTrustedStream` directly when the v0.12.8 sequential " +
+      "extract path lands");
+  } else if (!archiveAdapters().isRandomAccessAdapter(source)) {
+    throw new SafeArchiveError("safe-archive/bad-source",
+      "extract: opts.source must be a string path, Buffer, or b.archive.adapters.* result");
+  }
+
+  try {
+    var format = opts.format || "auto";
+    if (format === "auto") {
+      var sniff = await _sniffMagic(source);
+      format = sniff.format;
+    }
+    var reader;
+    if (format === "zip") {
+      reader = archiveRead().zip(source, {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+    } else if (format === "tar") {
+      reader = archiveTarRead().tar(source, {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+    } else {
+      throw new SafeArchiveError("safe-archive/format-unsupported",
+        "extract: format=" + JSON.stringify(format) + " — v0.12.8 ships ZIP + tar " +
+        "(gz lands v0.12.9, encryptPacked-wrap lands v0.12.10)");
+    }
+    var result = await reader.extract({
+      destination:    opts.destination,
+      allowDangerous: opts.allowDangerous,
+    });
+    return Object.assign({ format: format }, result);
+  } finally {
+    if (typeof source.close === "function" && typeof opts.source === "string") {
+      try { source.close(); } catch (_e) { /* drop-silent */ }
+    }
+  }
+}
+
+/**
+ * @primitive b.safeArchive.inspect
+ * @signature b.safeArchive.inspect(opts)
+ * @since     0.12.7
+ * @status    stable
+ * @related   b.safeArchive.extract, b.guardArchive.validateEntries
+ *
+ * Read-only inspect: format sniffing + entry-list enumeration without
+ * decompression. Operators previewing an uploaded archive before
+ * committing to extraction reach for this primitive.
+ *
+ * @opts
+ *   source:          b.archive.adapters.* | Buffer | string,
+ *   format:          "auto" | "zip",
+ *   bombPolicy:      { ... },
+ *   audit:           b.audit,
+ *
+ * @example
+ *   var summary = await b.safeArchive.inspect({
+ *     source: b.archive.adapters.fs("/var/uploads/payload.zip"),
+ *   });
+ *   // → { format: "zip", entries: [...], totalCompressedBytes, totalUncompressedBytes }
+ */
+async function inspect(opts) {
+  opts = opts || {};
+  var source = opts.source;
+  if (typeof source === "string") {
+    source = archiveAdapters().fs(source, { signal: opts.signal });
+  } else if (Buffer.isBuffer(source)) {
+    source = archiveAdapters().buffer(source, { signal: opts.signal });
+  } else if (!archiveAdapters().isRandomAccessAdapter(source)) {
+    throw new SafeArchiveError("safe-archive/bad-source",
+      "inspect: opts.source must be a string path, Buffer, or random-access adapter");
+  }
+  try {
+    var format = opts.format || "auto";
+    if (format === "auto") {
+      var sniff = await _sniffMagic(source);
+      format = sniff.format;
+    }
+    var reader;
+    if (format === "zip") {
+      reader = archiveRead().zip(source, {
+        bombPolicy: opts.bombPolicy,
+        audit:      opts.audit,
+      });
+    } else if (format === "tar") {
+      reader = archiveTarRead().tar(source, {
+        bombPolicy: opts.bombPolicy,
+        audit:      opts.audit,
+      });
+    } else {
+      throw new SafeArchiveError("safe-archive/format-unsupported",
+        "inspect: format=" + JSON.stringify(format) + " — v0.12.8 ships ZIP + tar");
+    }
+    var entries = await reader.inspect();
+    var totalCompressed = 0;
+    var totalUncompressed = 0;
+    for (var i = 0; i < entries.length; i += 1) {
+      totalCompressed += entries[i].compressedSize;
+      totalUncompressed += entries[i].size;
+    }
+    return {
+      format:                 format,
+      entries:                entries,
+      totalCompressedBytes:   totalCompressed,
+      totalUncompressedBytes: totalUncompressed,
+    };
+  } finally {
+    if (typeof source.close === "function" && typeof opts.source === "string") {
+      try { source.close(); } catch (_e) { /* drop-silent */ }
+    }
+  }
+}
+
+module.exports = {
+  extract:           extract,
+  inspect:           inspect,
+  SafeArchiveError:  SafeArchiveError,
+  // Exposed for tests + sibling modules.
+  _sniffMagic:       _sniffMagic,
+};

package/lib/vendor/blamejs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.6",
+  "version": "0.12.8",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/lib/vendor/blamejs/release-notes/v0.12.7.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "../scripts/release-notes-schema.json",
+  "version": "0.12.7",
+  "date": "2026-05-23",
+  "headline": "`b.archive.read` — random-access ZIP reader + adapter substrate + `b.safeArchive.extract` orchestrator",
+  "summary": "The framework's ZIP primitive grows a read side. `b.archive.read.zip(adapter, opts)` walks the central directory, validates LFH/CD coherence (defeats the malformed-zip / Zip Slip CD-skew class), bounds decompression with operator-declared bomb caps (per-entry size, total bytes, expansion ratio, entry count), and refuses path-traversal + symlink-shaped entries before any byte hits the destination. The adapter contract (`{ size, range(offset, length) }` for random-access; `{ readable }` for the trusted-stream fallback) unifies how operators feed bytes in — local files, `b.objectStore` buckets, HTTP Range fetches, and in-memory buffers all compose the same reader. `b.safeArchive.extract({ source, destination, ... })` ships as the one-liner orchestrator that combines read + guardArchive + path-safety + bomb caps + extract for the common `untar a hostile archive into a quarantine directory` shape. `b.guardArchive` gains `inspect(adapter)` (entry-list enumeration that doesn't decompress), `zipBombPolicy(...)` and `entryTypePolicy(...)` policy-object builders so operators can declare their cap set once + reuse it. `b.guardFilename.verifyExtractionPath(name, root, opts?)` adds the dual-check (string-normalize + `fs.realpath`-agreement) that defends the CVE-2025-4517 PATH_MAX TOCTOU class — refuses paths > 4096 bytes BEFORE the kernel's realpath truncation hits, then verifies the string and fs resolution agree on the same final path. `b.backup` gains `bundleAdapterStorage(adapter, opts)` — the first non-disk transport backend; substrate for the v0.12.8 tar bundle format + v0.12.11 objectStoreStorage. Closes the no-MVP gap from v0.5.15 where `b.archive` shipped write-only and the operator-facing JSDoc explicitly punted reading + extraction to yauzl / `unzip`.",
+  "sections": [
+    {
+      "heading": "Added",
+      "items": [
+        {
+          "title": "`b.archive.read.zip(adapter, opts)` — random-access ZIP reader",
+          "body": "Walks the end-of-central-directory record, validates every CD entry against its LFH (offset / size / CRC / method / name agreement), and emits an iterator of `{ name, size, compressedSize, crc, method, mtime, isEncrypted, externalAttrs, extraFields }` entries. `inspect()` returns the entry list without decompressing — operators wire `b.guardArchive` against the inspect output before paying a single decompress cycle. `extract({ destination, ... })` decompresses entry-by-entry via `node:zlib` raw inflate, routes every path through `b.guardFilename.verifyExtractionPath`, and enforces zip-bomb caps as a streaming abort (the partial extract is fs.rm-ed before the error throws). Composes the existing `lib/archive.js` write-side CRC + signature constants — no duplicated wire-format knowledge."
+        },
+        {
+          "title": "Adapter contract — `b.archive.adapters.{fs,objectStore,http,buffer,trustedStream}`",
+          "body": "One shape for source bytes: `{ size: <number>, range(offset, length): Promise<Buffer> }` for random-access, or `{ readable: Readable }` for the explicit trust-stream fallback. `fs(path)` opens a file descriptor + range-reads. `objectStore(client, key)` composes the v0.4.23 `b.objectStore` Range-GET path. `http(url, opts)` composes `b.httpClient` with `Range: bytes=N-M` headers + 206 verification. `buffer(buf)` slices a Buffer in-memory. `trustedStream(readable)` accepts a Node Readable for the rare case the operator can vouch for the source. The same contract feeds `b.safeArchive.extract` and `b.backup.bundleAdapterStorage`."
+        },
+        {
+          "title": "`b.safeArchive.extract({ source, destination, ... })` — one-liner safe extraction",
+          "body": "Combines `b.archive.read` + `b.guardArchive` inspect + `b.guardFilename.verifyExtractionPath` + bomb caps + post-extract destination-rebase verification. Refuses the entire archive when any single entry trips a policy (atomic — no half-extracted state on the destination). Operators who want fine-grained control reach for the lower-level primitives directly; `b.safeArchive.extract` covers the 90%-case `extract this hostile-shaped archive into a quarantine directory` workflow. Returns `{ entries: [...], destinationRoot, bytesExtracted, auditTrail }` on success."
+        },
+        {
+          "title": "`b.guardArchive.inspect(adapter, opts)` + `zipBombPolicy(...)` + `entryTypePolicy(...)`",
+          "body": "`inspect(adapter)` is the bridge between the read primitive and the existing `validateEntries` gate — runs the read primitive's inspect phase, hands the entry list to `validateEntries`, and returns the merged `{ entries, issues, decisions }` so the caller decides whether to proceed. `zipBombPolicy({ maxEntries, maxEntryDecompressedBytes, maxTotalDecompressedBytes, maxExpansionRatio })` and `entryTypePolicy({ symlinks, hardlinks, devices, fifos, sockets })` are policy-object builders so operators declare the cap set once + reuse across call sites. Each policy carries its own `audit.posture` annotation that propagates through `b.agent.postureChain`."
+        },
+        {
+          "title": "`b.guardFilename.verifyExtractionPath(name, root, opts?)` — dual-check path safety",
+          "body": "Companion to the existing `b.guardArchive.checkExtractionPath` (string-only check the gate keeps portable). `verifyExtractionPath` couples to `fs.realpath` deliberately: refuses paths whose pre-resolve string already exceeds 4096 bytes (defends the CVE-2025-4517 PATH_MAX TOCTOU class — `os.path.realpath`-style truncation can't reach the kernel before our refuse fires), then verifies the string-normalized result and the `fs.realpath`-resolved result agree on the same final path. Disagreement throws `guard-filename/extraction-path-toctou`. The string-check stays the canonical portable gate; this primitive is the deeper fs-coupled check the framework's read primitive wires in by default."
+        },
+        {
+          "title": "`b.backup.bundleAdapterStorage(adapter, opts)` — adapter-driven storage backend",
+          "body": "First non-disk backend for `b.backup`. Walks the bundle directory file-by-file and writes through the v0.12.7 adapter contract — `fs` adapter behaves identically to `diskStorage` (which stays for back-compat), `buffer` adapter emits the bundle into an in-memory representation, custom adapters can route to anything that satisfies the contract. Substrate for the v0.12.8 tar bundle format (which folds the directory tree into a single tar stream) and the v0.12.11 `objectStoreStorage` (which composes `b.archive.adapters.objectStore` for S3 / MinIO / Azure / GCS-backed backups). Backup manifest layout unchanged — restore code keeps working byte-for-byte against bundles produced by either backend."
+        }
+      ]
+    },
+    {
+      "heading": "Security",
+      "items": [
+        {
+          "title": "Zip Slip class (CVE-2025-3445 / 11569 / 23084 / 27210 / 11001 / 11002 / 26960 / 4517 / 4138 / 4330 + 2024 jszip / mholt/archiver / Python tarfile / node-tar / 7-zip)",
+          "body": "Every archive-read entry's name passes through `b.guardFilename.verifyExtractionPath` before any decompression. Path-traversal segments (`..`, leading `/` or `\\`, drive-letter prefixes, null bytes, overlong UTF-8) are refused; Windows reserved names + NTFS ADS suffixes are refused; the realpath-agreement check defends the CVE-2025-4517 PATH_MAX TOCTOU class. Symlink and hardlink entries are refused unconditionally under the default `entryTypePolicy`; operators with a legitimate need opt into `allowSymlinks: true` / `allowHardlinks: true` and get the entries routed through an additional `b.guardArchive` realpath-on-target check."
+        },
+        {
+          "title": "Decompression-bomb class (CVE-2025-0725, OWASP zip-bomb top-cases)",
+          "body": "`b.archive.read.zip.extract` enforces four caps in parallel: `maxEntries` (entry-count), `maxEntryDecompressedBytes` (per-entry size), `maxTotalDecompressedBytes` (aggregate across the archive), and `maxExpansionRatio` (compressed → decompressed ratio cap, default 100:1). Each cap aborts the extract as soon as the bound is exceeded; the destination directory is `fs.rm`-ed before the error throws so a partial extract never lingers on disk. The `b.safeDecompress` primitive (v0.11.5) is the underlying inflate gate — same defense surface, same audit-trail."
+        },
+        {
+          "title": "LFH/CD skew + malformed-ZIP DoS",
+          "body": "The CD walk verifies every entry's local-file-header against the central-directory record (offset / size / CRC / method / name agreement). Mismatches throw `archive/cd-skew` before any byte decompresses. Defends the malformed-zip class where a hostile producer points CD entries at LFH locations that don't match the CD claim — the prior write-only path had no exposure to this class; the new read path closes it."
+        }
+      ]
+    },
+    {
+      "heading": "Detectors",
+      "items": [
+        {
+          "title": "`archive-read-without-bomb-caps`",
+          "body": "Flags `b.archive.read.zip(adapter)` call sites in `lib/` that don't pass an explicit `bombPolicy` or `maxTotalDecompressedBytes`. Forces the cap-declaration discipline at call sites — operators see the bomb-cap surface every time they reach for the read primitive."
+        },
+        {
+          "title": "`archive-extract-without-guard`",
+          "body": "Flags `b.archive.read.zip(...).extract({ destination, ... })` call sites that don't compose `b.safeArchive.extract` (the orchestrator) AND don't pass an explicit `b.guardArchive.inspect` precheck. Per-file lib/ surface forces operators to either use the orchestrator OR explicitly opt into per-step composition with a written justification."
+        },
+        {
+          "title": "`archive-adapter-without-error-path`",
+          "body": "Flags adapter implementations (any export shape matching `{ size, range }` / `{ readable }`) that don't propagate AbortSignal or refuse to throw on partial-read truncation. Forces the cancellation-discipline so a slow / hostile source can't block extraction indefinitely."
+        },
+        {
+          "title": "`safe-archive-extract-bypass`",
+          "body": "Flags any composition in `lib/` that builds the safeArchive pipeline (`read.zip(...).extract({ destination, ... })` + bomb caps + guard) inline instead of calling `b.safeArchive.extract`. The orchestrator owns the audit-emission shape; bypassing it means audit gaps."
+        }
+      ]
+    }
+  ],
+  "references": [
+    { "label": "APPNOTE.TXT (PKWARE ZIP File Format Specification)",                    "url": "https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT" },
+    { "label": "CVE-2025-3445 — mholt/archiver Zip Slip",                              "url": "https://github.com/advisories/GHSA-7vpp-9cxj-q8gv" },
+    { "label": "CVE-2025-4517 — Python tarfile PATH_MAX bypass (CVSS 9.4)",            "url": "https://nvd.nist.gov/vuln/detail/CVE-2025-4517" },
+    { "label": "CVE-2025-11001 / CVE-2025-11002 — 7-Zip directory-traversal RCE",       "url": "https://www.sentinelone.com/vulnerability-database/cve-2025-11001/" },
+    { "label": "CVE-2025-11569 — cross-zip directory traversal",                        "url": "https://security.snyk.io/vuln/SNYK-JS-CROSSZIP-6105396" },
+    { "label": "CVE-2026-23745 / CVE-2026-24842 — node-tar symlink + hardlink bypass",  "url": "https://github.com/advisories/GHSA-34x7-hfp2-rc4v" },
+    { "label": "OWASP Zip Slip + zip-bomb reference",                                   "url": "https://snyk.io/research/zip-slip-vulnerability" },
+    { "label": "USENIX WOOT'19 — A better zip bomb (Fifield)",                         "url": "https://www.usenix.org/conference/woot19/presentation/fifield" }
+  ]
+}