@blamejs/core 0.12.14 → 0.12.15

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.15 (2026-05-23) — **`b.safeArchive.extract` auto-unwraps v0.12.10 recipient and v0.12.11 passphrase envelopes inline.** The safeArchive orchestrator's `format: "auto"` sniffer recognises `BAWRP` (v0.12.10 recipient) and `BAWPP` (v0.12.11 passphrase) envelope magics and routes through `b.archive.unwrap` / `b.archive.unwrapWithPassphrase` inline before re-sniffing the inner format. Operators pass `opts.recipient` (or `opts.passphrase`) alongside `source` + `destination` and get a single extract() call regardless of envelope shape. Missing the matching key opt surfaces a structured `safe-archive/no-recipient-for-wrap` / `safe-archive/no-passphrase-for-wrap` refusal upfront rather than a downstream crypto error. **Added:** *`b.safeArchive.extract` auto-unwraps wrap envelopes* — The sniffer at byte 0-4 recognises `BAWRP` (returns `format: "wrap-recipient"`) and `BAWPP` (returns `format: "wrap-passphrase"`). The extract path collects the sealed adapter into a Buffer, routes through `b.archive.unwrap` (recipient) or `b.archive.unwrapWithPassphrase` (passphrase), wraps the inner bytes in a buffer adapter, re-sniffs the inner format, and dispatches to the appropriate `b.archive.read.*` reader. A wrap-around-tar.gz envelope round-trips through wrap → unwrap → gunzip → untar with no operator intervention beyond passing the key opt. **Security:** *Missing-key opt refused upfront with structured error* — When the sniffer identifies a wrap envelope but the operator hasn't supplied `opts.recipient` (BAWRP) or `opts.passphrase` (BAWPP), extract refuses with `safe-archive/no-recipient-for-wrap` / `safe-archive/no-passphrase-for-wrap` BEFORE any decryption attempt. Operators wiring extract behind an HTTP boundary get a typed refusal instead of a leaked crypto-level error.
+
 - v0.12.14 (2026-05-23) — **`b.archive.sniffEnvelope(bytes)` — identify recipient vs passphrase vs raw payload without attempting decryption.** Small helper closing a gap in the archive-wrap surface. `b.archive.sniffEnvelope(bytes)` reads the first 5 bytes of a buffer and returns one of `"recipient"` (v0.12.10 BAWRP envelope), `"passphrase"` (v0.12.11 BAWPP envelope), or `"none"` (raw payload or unrelated bytes). The sniff does NO cryptographic work — no Argon2id round, no decapsulation, no allocation beyond a 5-byte ASCII compare — so it's safe to call on adversarial input. Operators dispatching between unwrap paths get a clean predicate instead of trial-decrypting under multiple key candidates. **Added:** *`b.archive.sniffEnvelope(bytes)` — magic-byte envelope identifier* — Returns `"recipient"` (BAWRP / v0.12.10 hybrid PQC envelope), `"passphrase"` (BAWPP / v0.12.11 Argon2id + XChaCha20 envelope), or `"none"` (raw archive bytes / unrelated payload). Accepts Buffer + Uint8Array; non-buffer / null / undefined / empty-buffer inputs return `"none"` upfront. Operators wire the result into a switch that dispatches to the matching unwrap primitive — no trial decryption, no per-key candidate attempts.
 
 - v0.12.13 (2026-05-23) — **`b.backup.bundleAdapterStorage.objectStoreAdapter` — wraps any `b.objectStore` backend (local / SigV4 / GCS / Azure-Blob) into the backup-adapter contract; closes the v0.11.2 "any custom backend" promise.** `b.backup.bundleAdapterStorage.objectStoreAdapter(client, opts)` adapts a `b.objectStore`-shaped client into the `{ writeFile, readFile, listKeys, deleteKey, hasKey }` adapter contract that `bundleAdapterStorage` consumes. Operators wire any of the four shipped object-store backends (`protocol: "local"` / `"sigv4"` for S3+MinIO / `"gcs"` / `"azure-blob"`) through the same recipient / passphrase wrap layers shipped in v0.12.10 and v0.12.11 — the bundle bytes hit the object-store `put` as an opaque envelope. `opts.prefix` namespaces every key under a fixed root inside the bucket so operators sharing a bucket across deployments keep listings scoped. Closes the deferral surfaced in v0.11.2 JSDoc and the v0.12.10 release-notes follow-up list: "S3 or any custom backend" is now wired with no operator-supplied adapter glue. **Added:** *`b.backup.bundleAdapterStorage.objectStoreAdapter(client, opts?)` — object-store-backed bundle storage* — Adapts any `b.objectStore.buildBackend({ protocol })` client (local / sigv4 / gcs / azure-blob) into the `{ writeFile, readFile, listKeys, deleteKey, hasKey }` adapter contract. NOT_FOUND errors from the underlying client translate to `backup/no-key` for the readFile path and to idempotent return-without-throw for deleteKey (matching the fsAdapter contract). hasKey routes through `client.head(key)` — NOT_FOUND → false; any other error propagates so operators can distinguish network failure from missing-key. Composes transparently with v0.12.10 `cryptoStrategy: "recipient"` and v0.12.11 `cryptoStrategy: "passphrase"` — the wrap envelope is the bytes hitting the object-store put. · *`opts.prefix` — per-deployment key namespacing inside the bucket* — Operators sharing one bucket across multiple deployments (per-environment / per-tenant / per-region) pass distinct prefixes so listings stay scoped. The prefix gets a trailing slash inserted automatically; traversal segments (`..`) and NUL bytes refused upfront with `backup/bad-arg` so a misconfigured prefix can't escape the operator's intended scope. listKeys strips the prefix on return so the adapter surface looks identical to the fsAdapter — operators switching backends don't see key-shape drift. **Security:** *Key path validation — traversal + NUL byte refusal at every adapter call* — Every `_scopedKey(key)` invocation refuses keys containing `..` traversal segments or NUL bytes upfront with `backup/bad-key` so a misconfigured bundleId or an attacker-controlled value never reaches the underlying `client.put(...)` / `client.get(...)`. Matches the same defensive posture the fsAdapter carries against operator-supplied key shapes.

package/lib/safe-archive.js

@@ -47,6 +47,7 @@ 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"); });
 var archiveGz = lazyRequire(function () { return require("./archive-gz"); });
+var archiveWrap = lazyRequire(function () { return require("./archive-wrap"); });
 
 // ---- Format sniffing ----------------------------------------------------
 
@@ -93,6 +94,10 @@ async function _sniffMagic(adapter) {
   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.
   if (head.length >= 263) {
@@ -102,6 +107,22 @@ async function _sniffMagic(adapter) {
   return { format: "unknown" };
 }
 
+// Collect a random-access adapter's bytes into a Buffer. Used by
+// the v0.12.15 auto-unwrap path so the envelope can be decrypted
+// inline + the inner bytes re-fed to a buffer adapter for format
+// re-sniffing. Adapters expose `size` + `range(offset, length)`.
+async function _collectSourceBytes(source) {
+  var size = source.size;
+  if (size == null && typeof source.resolveSize === "function") {
+    size = await source.resolveSize();
+  }
+  if (typeof size !== "number" || size < 0) {
+    throw new SafeArchiveError("safe-archive/bad-source",
+      "_collectSourceBytes: source adapter did not report a numeric size");
+  }
+  return source.range(0, size);
+}
+
 // ---- Public extract orchestrator ----------------------------------------
 
 /**
@@ -180,6 +201,50 @@ async function extract(opts) {
       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 });
+      }
+      // Codex P1 on v0.12.15 PR #166 — 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 */ }
+      }
+      // Codex P2 on v0.12.15 PR #166 — 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, {
@@ -210,8 +275,8 @@ async function extract(opts) {
       });
     } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
-        "extract: format=" + JSON.stringify(format) + " — v0.12.9 ships ZIP + tar + tar.gz " +
-        "(encryptPacked-wrap lands v0.12.10)");
+        "extract: format=" + JSON.stringify(format) + " — v0.12.9 ships ZIP + tar + tar.gz; " +
+        "v0.12.10/v0.12.11 added wrap-recipient + wrap-passphrase envelopes (auto-unwrap as of v0.12.15)");
     }
     var result = await reader.extract({
       destination:    opts.destination,

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:e3025640-8314-45f6-9dc8-7e1f45fb1063",
+  "serialNumber": "urn:uuid:73e48489-0fa1-477f-b6f3-eec74e9ba65f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T02:31:34.805Z",
+    "timestamp": "2026-05-24T03:18:46.285Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.14",
+      "bom-ref": "@blamejs/core@0.12.15",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.14",
+      "version": "0.12.15",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.14",
+      "purl": "pkg:npm/%40blamejs/core@0.12.15",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.14",
+      "ref": "@blamejs/core@0.12.15",
       "dependsOn": []
     }
   ]