@blamejs/core 0.12.15 → 0.12.17

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.17 (2026-05-23) — **`bundleAdapterStorage.bundleInfo` + `listBundles.format` — per-bundle introspection for envelope kind + format without restore.** Two introspection additions on `b.backup.bundleAdapterStorage`. `listBundles()` now returns the inferred `format` (`"tar"` / `"tar.gz"` / `"directory"`) per bundle from the storage key suffix — no byte read. `storage.bundleInfo(bundleId)` returns `{ bundleId, format, envelopeKind, sizeBytes }` where `envelopeKind` is the result of a 5-byte magic probe (`"recipient"` / `"passphrase"` / `"none"`). Operators administering a multi-strategy backup repository can now filter bundles by encryption posture or by format without a full restore cycle. **Added:** *`listBundles()` carries inferred format per bundle* — Each entry now includes `format` alongside `bundleId` / `createdAt` / `size`. Inference is from the storage key suffix the writeBundle path produced — `<bid>/bundle.tar` → tar, `<bid>/bundle.tar.gz` → tar.gz, anything else → directory. Cheap: no byte read, no per-key stat call. Operators rendering a bundle picker UI now sort + filter by format from a single list call. · *`storage.bundleInfo(bundleId)` — per-bundle introspection* — Returns `{ bundleId, format, envelopeKind, sizeBytes }`. `format` from the storage layout (no byte read). `envelopeKind` from `b.archive.sniffEnvelope` over the bundle payload — `"recipient"` (BAWRP / v0.12.10 hybrid PQC), `"passphrase"` (BAWPP / v0.12.11 Argon2id), `"none"` (plaintext or directory format). `sizeBytes` is the payload byte count for tar / tar.gz; null for directory format (operator's per-file walk applies if exact size matters). Nonexistent bundles refused with `backup/bundle-not-found`.
+
+- v0.12.16 (2026-05-23) — **`b.safeArchive.inspect` auto-unwraps wrap envelopes (parallel to the v0.12.15 extract path).** Mirrors the v0.12.15 auto-unwrap support into `b.safeArchive.inspect`. Operators enumerating entries of a sealed archive get a single inspect() call regardless of envelope shape — pass `opts.recipient` or `opts.passphrase` alongside `source` and the orchestrator unwraps inline before walking the inner format. Missing-key opt surfaces a structured `safe-archive/no-recipient-for-wrap` / `safe-archive/no-passphrase-for-wrap` refusal upfront. Carries the v0.12.15 P1 + P2 fixes (close original source before replacing + forward opts.signal to inner buffer adapter) into the inspect path so the same descriptor-leak + abort-propagation contracts hold. **Added:** *`b.safeArchive.inspect` auto-unwraps `BAWRP` + `BAWPP` envelopes* — The orchestrator's `format: "auto"` sniffer recognises the wrap magics and routes through `b.archive.unwrap` / `b.archive.unwrapWithPassphrase` inline. After unwrap, the inner bytes are wrapped in a buffer adapter + re-sniffed; the resulting summary carries the INNER `format` (`"tar"` / `"zip"` / etc.) — operators querying `summary.format` see the carrier format, not `"wrap-recipient"`. Entry enumeration walks the inner archive after a single key-derivation pass; no temporary file lands on disk.
+
 - 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.

package/lib/backup/index.js

@@ -1367,6 +1367,19 @@ function bundleAdapterStorage(opts) {
     },
     async listBundles() {
       // Get every key, partition by bundleId prefix, return sorted.
+      // v0.12.17 — each bundle now carries the inferred format
+      // (tar / tar.gz / directory) so operators picking which
+      // bundle to restore can filter by format without touching
+      // bytes. Format is inferred from the key suffix the
+      // writeBundle path produced (rule §2 — the format is part
+      // of the storage layout, not behind a probe).
+      //
+      // Codex P2 on v0.12.17 PR #168 — track WHICH suffixes a
+      // bundle carries (set of booleans) then apply explicit
+      // precedence at the end: tar.gz > tar > directory. Matches
+      // readBundle's preference (which checks hasTarGz first)
+      // so listBundles' reported format aligns with restore
+      // behavior regardless of adapter.listKeys() order.
       var allKeys = await adapter.listKeys("");
       var byBundle = new Map();
       for (var i = 0; i < allKeys.length; i += 1) {
@@ -1377,28 +1390,103 @@ function bundleAdapterStorage(opts) {
         if (!_isValidBundleId(bid)) continue;
         var stats = byBundle.get(bid);
         if (!stats) {
-          stats = { count: 0, size: 0 };
+          stats = { count: 0, hasTar: false, hasTarGz: false, hasOther: false };
           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 rest = key.slice(slash + 1);
+        if (rest === "bundle.tar")         stats.hasTar = true;
+        else if (rest === "bundle.tar.gz") stats.hasTarGz = true;
+        else                                stats.hasOther = true;
       }
       var out = [];
       var entries = Array.from(byBundle.entries());
       for (var j = 0; j < entries.length; j += 1) {
         var bidJ = entries[j][0];
+        var statsJ = entries[j][1];
+        var fmtJ;
+        if (statsJ.hasTarGz)    fmtJ = "tar.gz";        // matches readBundle precedence
+        else if (statsJ.hasTar) fmtJ = "tar";
+        else                    fmtJ = "directory";
         out.push({
           bundleId:  bidJ,
-          createdAt: null,    // adapter may not expose mtime
-          size:      null,    // best-effort
+          format:    fmtJ,
+          createdAt: null,                    // adapter may not expose mtime
+          size:      null,                    // best-effort; operators with stat-fast adapters call bundleInfo
         });
       }
       out.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
       return out;
     },
+    // bundleInfo(bundleId) — v0.12.17 per-bundle introspection.
+    // Returns `{ bundleId, format, envelopeKind, sizeBytes }`.
+    // `format` is one of `"tar"` / `"tar.gz"` / `"directory"`
+    // inferred from the storage layout (no byte read).
+    // `envelopeKind` is the result of a 5-byte magic probe on the
+    // bundle payload — `"recipient"` (BAWRP) / `"passphrase"`
+    // (BAWPP) / `"none"` (plaintext). `sizeBytes` is the payload
+    // byte count for tar / tar.gz; null for directory format
+    // (operator's per-file walk if exact size matters).
+    //
+    // Instance method — wiki page documents this under the
+    // bundleAdapterStorage primitive rather than as a top-level
+    // b.X primitive.
+    async bundleInfo(bundleId) {
+      _ensureBundleId(bundleId);
+      var tarKey = bundleId + TAR_KEY_SUFFIX;
+      var tarGzKey = bundleId + TAR_GZ_KEY_SUFFIX;
+      var manifestKey = bundleId + "/manifest.json";
+      var fmt = null;
+      var payloadKey = null;
+      if (await adapter.hasKey(tarGzKey)) {
+        fmt = "tar.gz"; payloadKey = tarGzKey;
+      } else if (await adapter.hasKey(tarKey)) {
+        fmt = "tar"; payloadKey = tarKey;
+      } else if (await adapter.hasKey(manifestKey)) {
+        fmt = "directory";
+      } else {
+        throw new BackupError("backup/bundle-not-found",
+          "bundleInfo: '" + bundleId + "' not in storage");
+      }
+      var envelopeKind = "none";
+      var sizeBytes = null;
+      if (payloadKey !== null) {
+        // Codex P1 on v0.12.17 PR #168 — claim was a 5-byte magic
+        // probe; the implementation was reading the entire bundle
+        // into memory. For multi-GB bundles, an administrative
+        // metadata call would allocate the whole payload and put
+        // memory pressure on the host. Prefer the adapter's
+        // optional `readPartial(key, length)` capability for the
+        // probe. fsAdapter + objectStoreAdapter both expose it as
+        // of v0.12.17; legacy adapters without it fall back to a
+        // capped 16-byte readFile via the fallback path (still
+        // bounded; better than full payload).
+        if (typeof adapter.readPartial === "function") {
+          var probe = await adapter.readPartial(payloadKey, 16);                      // allow:raw-byte-literal — 16-byte probe head, magic comparison
+          envelopeKind = archiveLazy().sniffEnvelope(probe);
+        } else {
+          // Legacy adapter — readPartial missing. Operators using
+          // a custom adapter without the capability get
+          // envelopeKind: "unknown" rather than an OOM risk. They
+          // can probe themselves by reading the first N bytes via
+          // their own client.
+          envelopeKind = "unknown";
+        }
+        // sizeBytes is reported via a stat-like path when the
+        // adapter exposes one; otherwise stays null. fsAdapter +
+        // objectStoreAdapter expose `statKey`.
+        if (typeof adapter.statKey === "function") {
+          var st = await adapter.statKey(payloadKey);
+          if (st && typeof st.size === "number") sizeBytes = st.size;
+        }
+      }
+      return {
+        bundleId:     bundleId,
+        format:       fmt,
+        envelopeKind: envelopeKind,
+        sizeBytes:    sizeBytes,
+      };
+    },
     async deleteBundle(bundleId) {
       _ensureBundleId(bundleId);
       var keys = await adapter.listKeys(bundleId + "/");
@@ -1494,6 +1582,42 @@ bundleAdapterStorage.fsAdapter = function (fsOpts) {
       try { return nodeFs.existsSync(_keyPath(key)); }
       catch (_e) { return false; }
     },
+    // v0.12.17 — optional capabilities consumed by bundleInfo.
+    // readPartial: open + read up to `length` bytes from the start
+    // of the file without materializing the whole payload.
+    // Bundle-info's envelope probe needs at most 16 bytes — the
+    // partial read keeps multi-GB bundle metadata cheap.
+    async readPartial(key, length) {
+      // CodeQL js/file-system-race + js/insecure-temporary-file —
+      // drop the existsSync probe (TOCTOU) and the default mode on
+      // open. Use openSync with explicit owner-only mode + handle
+      // ENOENT atomically; the system call is itself the existence
+      // check.
+      var p = _keyPath(key);
+      var fd;
+      try {
+        fd = nodeFs.openSync(p, "r", 0o600);
+      } catch (e) {
+        if (e && e.code === "ENOENT") {
+          throw new BackupError("backup/no-key",
+            "fsAdapter.readPartial: key not found: " + JSON.stringify(key));
+        }
+        throw e;
+      }
+      try {
+        var buf = Buffer.alloc(length);
+        var bytesRead = nodeFs.readSync(fd, buf, 0, length, 0);
+        return buf.slice(0, bytesRead);
+      } finally {
+        try { nodeFs.closeSync(fd); } catch (_e) { /* drop-silent */ }
+      }
+    },
+    async statKey(key) {
+      var p = _keyPath(key);
+      if (!nodeFs.existsSync(p)) return null;
+      var st = nodeFs.statSync(p);
+      return { size: st.size, mtimeMs: st.mtimeMs };
+    },
   };
 };
 
@@ -1682,6 +1806,36 @@ bundleAdapterStorage.objectStoreAdapter = function (client, osOpts) {
         throw e;
       }
     },
+    // v0.12.17 — readPartial uses the b.objectStore client's range
+    // capability (every shipped backend honours `{ range: [start,
+    // end] }` per the client contract). bundleInfo's envelope probe
+    // reads 16 bytes regardless of bundle size.
+    async readPartial(key, length) {
+      var scoped = _scopedKey(key);
+      try {
+        var body = await client.get(scoped, { range: [0, Math.max(0, length - 1)] });
+        var buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
+        return buf.slice(0, length);
+      } catch (e) {
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          throw new BackupError("backup/no-key",
+            "objectStoreAdapter.readPartial: key not found: " + JSON.stringify(key));
+        }
+        throw e;
+      }
+    },
+    async statKey(key) {
+      try {
+        var meta = await client.head(_scopedKey(key));
+        if (!meta || typeof meta.size !== "number") return null;
+        return { size: meta.size, mtimeMs: meta.lastModified || null };
+      } catch (e) {
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          return null;
+        }
+        throw e;
+      }
+    },
   };
 };
 

package/lib/safe-archive.js

@@ -330,6 +330,38 @@ async function inspect(opts) {
       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, {
@@ -343,7 +375,7 @@ async function inspect(opts) {
       });
     } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
-        "inspect: format=" + JSON.stringify(format) + " — v0.12.8 ships ZIP + tar");
+        "inspect: format=" + JSON.stringify(format) + " — v0.12.8 ships ZIP + tar; v0.12.16 auto-unwraps wrap envelopes");
     }
     var entries = await reader.inspect();
     var totalCompressed = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.15",
+  "version": "0.12.17",
   "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:73e48489-0fa1-477f-b6f3-eec74e9ba65f",
+  "serialNumber": "urn:uuid:5b052d03-601b-4eb1-93d8-60aaaf81b2f7",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T03:18:46.285Z",
+    "timestamp": "2026-05-24T04:43:58.102Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.15",
+      "bom-ref": "@blamejs/core@0.12.17",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.15",
+      "version": "0.12.17",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.15",
+      "purl": "pkg:npm/%40blamejs/core@0.12.17",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.15",
+      "ref": "@blamejs/core@0.12.17",
       "dependsOn": []
     }
   ]