@blamejs/core 0.14.11 → 0.14.13

package/lib/safe-archive.js

@@ -24,9 +24,9 @@
  *   Format auto-detection sniffs the first ~512 bytes for magic
  *   signatures: ZIP (LFH magic `0x04034b50` + EOCD magic `0x06054b50`),
  *   tar (`ustar` at offset 257), gzip / tar.gz (RFC 1952 magic), and
- *   `b.crypto.encryptPacked`-wrapped envelopes (auto-unwrapped before
- *   format detection). Unrecognized inputs are flagged
- *   `safe-archive/format-unsupported`.
+ *   `b.archive.wrap` recipient (`BAWRP`) / passphrase (`BAWPP`)
+ *   envelopes (auto-unwrapped before format detection). Unrecognized
+ *   inputs are flagged `safe-archive/format-unsupported`.
  *
  *   The orchestrator refuses the WHOLE archive on any single critical
  *   guard issue — no partial extraction. Cleanup is `fs.rm`-recursive
@@ -58,13 +58,10 @@ 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
+  // 512 bytes — enough for ZIP + GZIP + wrap-envelope 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") {
@@ -91,13 +88,13 @@ async function _sniffMagic(adapter) {
     var be2 = head.readUInt16BE(0);
     if (be2 === MAGIC_GZIP_BE) return { format: "gzip" };
   }
-  // b.crypto.encryptPacked — 5-byte ASCII prefix.
+  // archive-wrap envelopes — 5-byte ASCII prefix. BAWRP (recipient) and
+  // BAWPP (passphrase) are the only wrap envelopes the framework produces
+  // (b.archive.wrap / b.archive.wrapWithPassphrase) and the only ones
+  // b.archive.sniffEnvelope recognizes.
   if (head.length >= 5) {
     var prefix = head.slice(0, 5).toString("utf8");
-    if (prefix === MAGIC_ENCPACKED) return { format: "encryptPacked" };
-    // v0.12.15 — archive-wrap recipient envelope (v0.12.10 / BAWRP).
     if (prefix === "BAWRP") return { format: "wrap-recipient" };
-    // v0.12.15 — archive-wrap passphrase envelope (v0.12.11 / BAWPP).
     if (prefix === "BAWPP") return { format: "wrap-passphrase" };
   }
   // tar — "ustar" at offset 257 within the first 512-byte header.
@@ -124,6 +121,82 @@ async function _collectSourceBytes(source) {
   return source.range(0, size);
 }
 
+// Shared source→adapter resolution + envelope auto-unwrap for the three
+// orchestrator entry points (extract / extractToMemory / inspect). Returns
+// { source, format } — `source` is a random-access adapter positioned at the
+// (possibly unwrapped) archive and `format` is the sniffed inner format. The
+// CALLER owns closing the returned source in its own `finally`; this helper
+// performs the pre-unwrap fd-close-before-replace + the signal-forward-to-
+// inner-adapter discipline internally, and closes a string-opened descriptor
+// if it throws mid-resolve so a sniff/unwrap failure can't leak it.
+async function _resolveAndUnwrap(opts, label, refuseTrustedStream) {
+  var openedFromString = typeof opts.source === "string";
+  var source = opts.source;
+  if (openedFromString) {
+    source = archiveAdapters().fs(source, { signal: opts.signal });
+  } else if (Buffer.isBuffer(source)) {
+    source = archiveAdapters().buffer(source, { signal: opts.signal });
+  } else if (refuseTrustedStream && archiveAdapters().isTrustedStreamAdapter(source)) {
+    // Trusted-stream adapters satisfy the adapter contract, but the
+    // orchestrator's adversarial-safe central-directory walk + LFH/CD skew
+    // defense needs random access. Refuse upfront with a typed error so the
+    // operator sees the constraint at the entry point rather than a
+    // downstream `archive-read/wrong-entry-point`.
+    throw new SafeArchiveError("safe-archive/trusted-stream-unsupported",
+      label + ": trusted-stream adapter sources are not supported by the orchestrator " +
+      "(the adversarial-safe central-directory walk requires random access). Collect the " +
+      "bytes into a buffer adapter — `b.archive.adapters.buffer(await collect(readable))` — " +
+      "and pass that, or read with `b.archive.read.zip.fromTrustedStream` directly.");
+  } else if (!archiveAdapters().isRandomAccessAdapter(source)) {
+    throw new SafeArchiveError("safe-archive/bad-source",
+      label + ": opts.source must be a string path, Buffer, or b.archive.adapters.* result");
+  }
+  try {
+    var format = opts.format || "auto";
+    if (format === "auto") {
+      format = (await _sniffMagic(source)).format;
+    }
+    // Auto-unwrap path: when the sniffer identifies a wrap envelope, unwrap
+    // inline + re-sniff the inner bytes so operators get a single call
+    // regardless of envelope shape. Operator supplies opts.recipient or
+    // opts.passphrase matching the envelope kind.
+    if (format === "wrap-recipient" || format === "wrap-passphrase") {
+      var sealedBytes = await _collectSourceBytes(source);
+      var inner;
+      if (format === "wrap-recipient") {
+        if (!opts.recipient) {
+          throw new SafeArchiveError("safe-archive/no-recipient-for-wrap",
+            label + ": source is a wrap-recipient envelope (BAWRP) but opts.recipient was not supplied. " +
+            "Pass `{ recipient: { privateKey, ecPrivateKey } }` (or peer-cert form) to unwrap inline.");
+        }
+        inner = archiveWrap().unwrap(sealedBytes, { recipient: opts.recipient });
+      } else {
+        if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
+          throw new SafeArchiveError("safe-archive/no-passphrase-for-wrap",
+            label + ": source is a wrap-passphrase envelope (BAWPP) but opts.passphrase was not supplied. " +
+            "Pass `{ passphrase: <string|Buffer> }` to unwrap inline.");
+        }
+        inner = await archiveWrap().unwrapWithPassphrase(sealedBytes, { passphrase: opts.passphrase });
+      }
+      // Close the original string-opened descriptor BEFORE replacing the
+      // source reference (overwriting it would leak the fd across repeated
+      // calls → EMFILE under load), then forward opts.signal to the inner
+      // buffer adapter so abort propagation survives the unwrap boundary.
+      if (typeof source.close === "function" && openedFromString) {
+        try { source.close(); } catch (_e) { /* drop-silent */ }
+      }
+      source = archiveAdapters().buffer(inner, { signal: opts.signal });
+      format = (await _sniffMagic(source)).format;
+    }
+    return { source: source, format: format };
+  } catch (e) {
+    if (typeof source.close === "function" && openedFromString) {
+      try { source.close(); } catch (_e2) { /* drop-silent */ }
+    }
+    throw e;
+  }
+}
+
 // ---- Public extract orchestrator ----------------------------------------
 
 /**
@@ -168,84 +241,10 @@ 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");
-  }
-
+  var resolved = await _resolveAndUnwrap(opts, "extract", true);
+  var source = resolved.source;
+  var format = resolved.format;
   try {
-    var format = opts.format || "auto";
-    if (format === "auto") {
-      var sniff = await _sniffMagic(source);
-      format = sniff.format;
-    }
-    // v0.12.15 — auto-unwrap path. When the sniffer identifies a
-    // wrap envelope, unwrap inline + re-sniff the inner bytes so
-    // operators get a single extract() call regardless of envelope
-    // shape. Operator must supply opts.recipient or opts.passphrase
-    // matching the envelope kind.
-    if (format === "wrap-recipient" || format === "wrap-passphrase") {
-      var sealedBytes = await _collectSourceBytes(source);
-      var inner;
-      if (format === "wrap-recipient") {
-        if (!opts.recipient) {
-          throw new SafeArchiveError("safe-archive/no-recipient-for-wrap",
-            "extract: source is a wrap-recipient envelope (BAWRP) but opts.recipient was not supplied. " +
-            "Pass `{ recipient: { privateKey, ecPrivateKey } }` (or peer-cert form) to unwrap inline.");
-        }
-        inner = archiveWrap().unwrap(sealedBytes, { recipient: opts.recipient });
-      } else {
-        if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
-          throw new SafeArchiveError("safe-archive/no-passphrase-for-wrap",
-            "extract: source is a wrap-passphrase envelope (BAWPP) but opts.passphrase was not supplied. " +
-            "Pass `{ passphrase: <string|Buffer> }` to unwrap inline.");
-        }
-        inner = await archiveWrap().unwrapWithPassphrase(sealedBytes, { passphrase: opts.passphrase });
-      }
-      // Close the original source
-      // adapter BEFORE replacing it. When opts.source was a string
-      // path, the fs adapter opened a file descriptor; overwriting
-      // `source` loses the close reference and the descriptor
-      // leaks across repeated extract() calls (eventually EMFILE
-      // under load). The outer finally still closes whatever
-      // `source` points at, but the original handle needs explicit
-      // release here.
-      if (typeof source.close === "function" && typeof opts.source === "string") {
-        try { source.close(); } catch (_e) { /* drop-silent */ }
-      }
-      // Forward opts.signal to the
-      // inner buffer adapter so abort propagation stays intact
-      // across the unwrap boundary. Without it, an abort raised
-      // after unwrapping would no longer cancel inner range()
-      // calls, breaking the documented signal contract for
-      // large wrapped archives.
-      source = archiveAdapters().buffer(inner, { signal: opts.signal });
-      var innerSniff = await _sniffMagic(source);
-      format = innerSniff.format;
-    }
     var reader;
     if (format === "zip") {
       reader = archiveRead().zip(source, {
@@ -277,7 +276,7 @@ async function extract(opts) {
     } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
         "extract: format=" + JSON.stringify(format) + " — supported formats are " +
-        "zip, tar, tar.gz; b.crypto.encryptPacked-wrapped archives are auto-unwrapped first");
+        "zip, tar, tar.gz; b.archive.wrap recipient/passphrase envelopes are auto-unwrapped first");
     }
     var result = await reader.extract({
       destination:    opts.destination,
@@ -291,6 +290,109 @@ async function extract(opts) {
   }
 }
 
+/**
+ * @primitive b.safeArchive.extractToMemory
+ * @signature b.safeArchive.extractToMemory(opts)
+ * @since     0.14.13
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.safeArchive.extract, b.archive.read.zip, b.archive.read.tar
+ *
+ * In-memory counterpart to `b.safeArchive.extract` for read-only /
+ * serverless filesystems. Resolves the source, sniffs the format,
+ * auto-unwraps recipient (`BAWRP`) / passphrase (`BAWPP`) envelopes, and
+ * dispatches to the zip / tar / tar.gz reader's in-memory `extractEntries`
+ * — an async generator that yields each regular file entry's decompressed
+ * bytes without ever writing to disk. Takes no `destination`; the caller
+ * owns where, if anywhere, the bytes land.
+ *
+ * Every defense the disk `extract` runs applies unchanged: the zip-bomb
+ * caps (entry-count / per-entry / total / expansion-ratio), the
+ * `b.guardArchive` metadata cascade (Zip-Slip / path-traversal / symlink-
+ * escape / encrypted-entry refusal — CVE-2025-3445 class), and the
+ * entry-type policy. Directory entries carry no bytes and are skipped. The
+ * disk-only realpath-agreement check (CVE-2025-4517 PATH_MAX TOCTOU
+ * defense) is intentionally absent — there is no extraction root — so the
+ * archive-level name refusals carry the containment guarantee here.
+ *
+ * Trusted-stream adapter sources are refused upfront: the adversarial-safe
+ * central-directory walk requires random access. Collect the bytes into a
+ * buffer adapter, or read with `b.archive.read.zip.fromTrustedStream`
+ * directly.
+ *
+ * @opts
+ *   source:           b.archive.adapters.* | Buffer | string,
+ *   format:           "auto" | "zip" | "tar" | "tar.gz",
+ *   bombPolicy:       b.guardArchive.zipBombPolicy(...) | { ... },
+ *   entryTypePolicy:  b.guardArchive.entryTypePolicy(...) | { ... },
+ *   guardProfile:     "strict" | "balanced" | "permissive" | "hipaa" | ...,
+ *   recipient:        { privateKey, ecPrivateKey },  // for BAWRP envelopes
+ *   passphrase:       string | Buffer,               // for BAWPP envelopes
+ *   audit:            b.audit,
+ *   signal:           AbortSignal,
+ *
+ * @example
+ *   for await (var entry of b.safeArchive.extractToMemory({
+ *     source:       b.archive.adapters.fs("/var/uploads/payload.zip"),
+ *     guardProfile: "strict",
+ *   })) {
+ *     // entry → { name, bytes, size } — never touches disk
+ *     await store.put(entry.name, entry.bytes);
+ *   }
+ */
+async function* extractToMemory(opts) {
+  opts = opts || {};
+  var resolved = await _resolveAndUnwrap(opts, "extractToMemory", true);
+  var source = resolved.source;
+  var format = resolved.format;
+  var extractOpts = { allowDangerous: opts.allowDangerous, allowEncrypted: opts.allowEncrypted };
+  try {
+    if (format === "zip") {
+      var zr = archiveRead().zip(source, {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+      for await (var ze of zr.extractEntries(extractOpts)) { yield ze; }
+    } else if (format === "tar") {
+      var tr = archiveTarRead().tar(source, {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+      for await (var te of tr.extractEntries(extractOpts)) { yield te; }
+    } else if (format === "tar.gz") {
+      // The gz reader's asTar() shim exposes inspect + extract but NOT
+      // extractEntries, so materialize the gz layer to a Buffer (the gz
+      // bomb caps still run during toBuffer()) and walk a fresh tar reader
+      // over it — the tar bomb / guard / entry-type caps run on the inner
+      // walk, so no defense is dropped.
+      var tarBytes = await archiveGz().read.gz(source, {
+        maxDecompressedBytes: opts.maxDecompressedBytes,
+        maxExpansionRatio:    opts.maxExpansionRatio,
+        audit:                opts.audit,
+      }).toBuffer();
+      var gtr = archiveTarRead().tar(archiveAdapters().buffer(tarBytes, { signal: opts.signal }), {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+      for await (var ge of gtr.extractEntries(extractOpts)) { yield ge; }
+    } else {
+      throw new SafeArchiveError("safe-archive/format-unsupported",
+        "extractToMemory: format=" + JSON.stringify(format) + " — supported formats are " +
+        "zip, tar, tar.gz; b.archive.wrap recipient/passphrase envelopes are auto-unwrapped first");
+    }
+  } 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)
@@ -316,53 +418,10 @@ async function extract(opts) {
  */
 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");
-  }
+  var resolved = await _resolveAndUnwrap(opts, "inspect", false);
+  var source = resolved.source;
+  var format = resolved.format;
   try {
-    var format = opts.format || "auto";
-    if (format === "auto") {
-      var sniff = await _sniffMagic(source);
-      format = sniff.format;
-    }
-    // v0.12.16 — auto-unwrap path for inspect, parallel to the
-    // v0.12.15 extract path. Wrap envelopes (BAWRP / BAWPP) are
-    // unwrapped inline + re-sniffed so operators can enumerate
-    // entries of a sealed archive in a single inspect() call.
-    if (format === "wrap-recipient" || format === "wrap-passphrase") {
-      var sealedBytes = await _collectSourceBytes(source);
-      var inner;
-      if (format === "wrap-recipient") {
-        if (!opts.recipient) {
-          throw new SafeArchiveError("safe-archive/no-recipient-for-wrap",
-            "inspect: source is a wrap-recipient envelope (BAWRP) but opts.recipient was not supplied. " +
-            "Pass `{ recipient: { privateKey, ecPrivateKey } }` (or peer-cert form) to unwrap inline.");
-        }
-        inner = archiveWrap().unwrap(sealedBytes, { recipient: opts.recipient });
-      } else {
-        if (typeof opts.passphrase !== "string" && !Buffer.isBuffer(opts.passphrase)) {
-          throw new SafeArchiveError("safe-archive/no-passphrase-for-wrap",
-            "inspect: source is a wrap-passphrase envelope (BAWPP) but opts.passphrase was not supplied. " +
-            "Pass `{ passphrase: <string|Buffer> }` to unwrap inline.");
-        }
-        inner = await archiveWrap().unwrapWithPassphrase(sealedBytes, { passphrase: opts.passphrase });
-      }
-      // v0.12.15 P1 — close the original fs adapter (if string-
-      // backed) BEFORE replacing the source reference. v0.12.15 P2
-      // — forward opts.signal to the inner buffer adapter.
-      if (typeof source.close === "function" && typeof opts.source === "string") {
-        try { source.close(); } catch (_e) { /* drop-silent */ }
-      }
-      source = archiveAdapters().buffer(inner, { signal: opts.signal });
-      var innerSniff = await _sniffMagic(source);
-      format = innerSniff.format;
-    }
     var reader;
     if (format === "zip") {
       reader = archiveRead().zip(source, {
@@ -388,7 +447,7 @@ async function inspect(opts) {
       });
     } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
-        "inspect: format=" + JSON.stringify(format) + " — v0.12.19 ships ZIP + tar + tar.gz; auto-unwraps wrap envelopes");
+        "inspect: format=" + JSON.stringify(format) + " — supported formats are zip, tar, tar.gz; wrap envelopes are auto-unwrapped first");
     }
     var entries = await reader.inspect();
     var totalCompressed = 0;
@@ -412,6 +471,7 @@ async function inspect(opts) {
 
 module.exports = {
   extract:           extract,
+  extractToMemory:   extractToMemory,
   inspect:           inspect,
   SafeArchiveError:  SafeArchiveError,
   // Exposed for tests + sibling modules.

package/lib/validate-opts.js

@@ -190,6 +190,29 @@ function requireObject(opts, callerLabel, errorClass, code) {
   return opts;
 }
 
+// requireMethods — validate an injected dependency exposes the named
+// methods. Collapses the repeated `if (!obj || typeof obj.fn !==
+// "function" || ...) throw` injected-store / exporter / backend guards
+// (b.agent.*.reseal stores, b.dsr / b.outbox create() backends, etc.)
+// into one definition. Throws on null / non-object / any missing-or-
+// non-function method; returns obj on success.
+function requireMethods(obj, methods, callerLabel, errorClass, code) {
+  var label = callerLabel || "dependency";
+  if (!obj || typeof obj !== "object") {
+    _throw(errorClass, code, label + " must be an object exposing { " +
+           methods.join(", ") + " }, got " + (obj === null ? "null" : typeof obj),
+           "validate-opts/bad-methods-object");
+  }
+  for (var i = 0; i < methods.length; i += 1) {
+    if (typeof obj[methods[i]] !== "function") {
+      _throw(errorClass, code, label + " must expose a " + methods[i] +
+             "() method (requires { " + methods.join(", ") + " })",
+             "validate-opts/missing-method");
+    }
+  }
+  return obj;
+}
+
 function optionalNonEmptyString(value, label, errorClass, code) {
   if (value === undefined || value === null) return value;
   if (typeof value !== "string" || value.length === 0) {
@@ -376,6 +399,7 @@ module.exports.optionalPlainObject = optionalPlainObject;
 module.exports.requireNonEmptyString = requireNonEmptyString;
 module.exports.observabilityShape = observabilityShape;
 module.exports.requireObject = requireObject;
+module.exports.requireMethods = requireMethods;
 module.exports.applyDefaults = applyDefaults;
 module.exports.makeAuditEmitter = makeAuditEmitter;
 module.exports.makeNamespacedEmitters = makeNamespacedEmitters;