@blamejs/core 0.12.17 → 0.12.19

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.19 (2026-05-24) — **`bundleAdapterStorage.verifyBundle(bundleId)` — bundle integrity check without restore + `b.safeArchive.inspect` tar.gz support.** `storage.verifyBundle(bundleId, opts?)` walks a bundle without restoring it: confirms the payload exists, the envelope (if any) decrypts under the supplied key, and the inner tar / tar.gz walker enumerates every entry without writing to disk. Returns `{ ok, format, envelopeKind, entryCount, errors }` — operators wanting periodic health-check of a backup repository call verifyBundle across `listBundles()` and aggregate `ok === false` results. Composes the bundle's known format directly through the unwrap → gunzip → tar pipeline (skips safeArchive's auto-sniff because the bundle's format is already known from bundleInfo). `b.safeArchive.inspect` separately gains `format: "tar.gz"` dispatch — operators with a known tar.gz payload now get entry enumeration without extracting. **Added:** *`storage.verifyBundle(bundleId, opts?)` — integrity check without restore* — Composes bundleInfo for format/envelope detection + the unwrap → gunzip → tar walker chain directly. opts.recipient / opts.passphrase override the storage's configured keys (useful for verifying a bundle under a different key set than the storage was opened with — e.g. verifying that a key rotation candidate can still read a bundle). Wrong key / corrupted payload returns `ok: false` with a typed error code in the errors array rather than throwing. Directory format reports ok=true based on manifest existence + readability (the inspect walker doesn't apply). · *`b.safeArchive.inspect` accepts `format: "tar.gz"`* — Mirrors the v0.12.9 extract surface: operators handed a `.tar.gz` payload can now enumerate entries without extracting. Composes `b.archive.read.gz` + `.asTar()` internally so the same bomb caps apply (1 GiB output / 100× ratio default) to inspect calls.
+
+- v0.12.18 (2026-05-24) — **`bundleAdapterStorage.listBundles({ withStats })` + `bundleInfo.createdAt` — opt-in mtime + size from `statKey`.** Two additions on `b.backup.bundleAdapterStorage`. `listBundles({ withStats: true })` fans out `statKey` per bundle and populates `createdAt` (ISO string from mtimeMs) + `size` (bytes) on every entry. Without the opt the default fast path stays a single listKeys call — operators rendering a bundle picker UI choose between O(1) listings and O(N) stat-enriched listings explicitly. `bundleInfo(bundleId)` gains the same `createdAt` field for parity. fsAdapter + objectStoreAdapter both expose `statKey`; legacy adapters without the capability leave the fields null. **Added:** *`storage.listBundles({ withStats: true })` — opt-in per-bundle stat fan-out* — When the adapter exposes `statKey`, populates `createdAt` (ISO string from mtimeMs) + `size` (bytes) per entry. Stat fan-out is O(N) round-trips so the opt is OFF by default — operators wanting cheap one-shot listings stay on `listBundles()`. Format precedence (tar.gz > tar > directory) carries through to which payload key gets stat'd. · *`storage.bundleInfo(bundleId)` returns `createdAt`* — The bundle introspection primitive now returns `{ bundleId, format, envelopeKind, sizeBytes, createdAt }`. `createdAt` is the ISO string derived from `statKey.mtimeMs` (when the adapter exposes it) — null otherwise. Matches the listBundles+withStats shape so operators can use bundleInfo for single-bundle drill-downs without re-mapping field names.
+
 - 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.

package/lib/backup/index.js

@@ -1365,8 +1365,10 @@ function bundleAdapterStorage(opts) {
         nodeFs.writeFileSync(destPath, bytes, { flag: "wx", mode: 0o600 });
       }
     },
-    async listBundles() {
+    async listBundles(listOpts) {
       // Get every key, partition by bundleId prefix, return sorted.
+      listOpts = listOpts || {};
+      var withStats = listOpts.withStats === true;
       // 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
@@ -1408,16 +1410,128 @@ function bundleAdapterStorage(opts) {
         if (statsJ.hasTarGz)    fmtJ = "tar.gz";        // matches readBundle precedence
         else if (statsJ.hasTar) fmtJ = "tar";
         else                    fmtJ = "directory";
-        out.push({
+        var entry = {
           bundleId:  bidJ,
           format:    fmtJ,
           createdAt: null,                    // adapter may not expose mtime
           size:      null,                    // best-effort; operators with stat-fast adapters call bundleInfo
-        });
+        };
+        // v0.12.18 — when opts.withStats is true AND the adapter
+        // exposes statKey, fan-out a stat call per bundle's
+        // payload key. O(N) round-trips so this is opt-in;
+        // listBundles() with no opts stays cheap (single listKeys
+        // call). Operators wanting per-bundle stats but not the
+        // full bundleInfo envelope probe pick this middle ground.
+        if (withStats && typeof adapter.statKey === "function") {
+          var statKey;
+          if (statsJ.hasTarGz)    statKey = bidJ + TAR_GZ_KEY_SUFFIX;
+          else if (statsJ.hasTar) statKey = bidJ + TAR_KEY_SUFFIX;
+          else                    statKey = bidJ + "/manifest.json";
+          var sk = await adapter.statKey(statKey);
+          if (sk && typeof sk.size === "number") entry.size = sk.size;
+          if (sk && typeof sk.mtimeMs === "number") entry.createdAt = new Date(sk.mtimeMs).toISOString();
+        }
+        out.push(entry);
       }
       out.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
       return out;
     },
+    // verifyBundle(bundleId, opts?) — v0.12.19 integrity check.
+    // Walks the bundle without restoring: confirms the payload
+    // exists, the envelope (if any) decrypts under the supplied
+    // key, and the inner archive structure is well-formed (every
+    // entry enumerable). Returns `{ ok, format, envelopeKind,
+    // entryCount, errors }`. opts.recipient / opts.passphrase
+    // forwarded when the bundle is wrap-wrapped; omit them for
+    // plaintext bundles. Composes safeArchive.inspect which gates
+    // entries through bomb-policy + entry-type-policy walkers, so
+    // a malformed archive surfaces with a typed error rather than
+    // crashing the verify call.
+    async verifyBundle(bundleId, vOpts) {
+      vOpts = vOpts || {};
+      _ensureBundleId(bundleId);
+      var info;
+      try { info = await this.bundleInfo(bundleId); }
+      catch (e) {
+        return {
+          ok:           false,
+          format:       null,
+          envelopeKind: null,
+          entryCount:   0,
+          errors:       [e.code || e.message || String(e)],
+        };
+      }
+      if (info.format === "directory") {
+        // Directory format isn't archive-shaped — manifest.json
+        // existence + readability via bundleInfo IS the
+        // verification. No inspect walk applies.
+        return {
+          ok:           true,
+          format:       info.format,
+          envelopeKind: info.envelopeKind,
+          entryCount:   null,
+          errors:       [],
+        };
+      }
+      // Compose the reader chain directly so we don't depend on
+      // safeArchive's auto-sniff dispatch (which is conservative
+      // about inferring "tar.gz" from gzip-magic-only inner bytes).
+      // We already know the bundle's format + envelopeKind from
+      // bundleInfo — apply the layers in order: unwrap (if any)
+      // → gunzip (if tar.gz) → tar walker.
+      var keySuffix = info.format === "tar.gz" ? TAR_GZ_KEY_SUFFIX : TAR_KEY_SUFFIX;
+      var payload = await adapter.readFile(bundleId + keySuffix);
+      try {
+        // Layer 1 — unwrap envelope if present.
+        if (info.envelopeKind === "recipient") {
+          var rcp = vOpts.recipient !== undefined ? vOpts.recipient : recipient;
+          if (!rcp) {
+            return {
+              ok: false, format: info.format, envelopeKind: info.envelopeKind,
+              entryCount: 0, errors: ["backup/no-recipient-for-verify"],
+            };
+          }
+          payload = archiveLazy().unwrap(payload, { recipient: rcp });
+        } else if (info.envelopeKind === "passphrase") {
+          var pp = vOpts.passphrase !== undefined ? vOpts.passphrase : passphrase;
+          if (typeof pp !== "string" && !Buffer.isBuffer(pp)) {
+            return {
+              ok: false, format: info.format, envelopeKind: info.envelopeKind,
+              entryCount: 0, errors: ["backup/no-passphrase-for-verify"],
+            };
+          }
+          payload = await archiveLazy().unwrapWithPassphrase(payload, { passphrase: pp });
+        }
+        // Layer 2 — gunzip if tar.gz.
+        var tarReader;
+        if (info.format === "tar.gz") {
+          var gzReader = archiveLazy().read.gz(archiveAdaptersLazy().buffer(payload), {
+            maxDecompressedBytes: maxBundleBytes,
+            maxExpansionRatio:    0,
+          });
+          tarReader = gzReader.asTar();
+        } else {
+          tarReader = archiveLazy().read.tar(archiveAdaptersLazy().buffer(payload));
+        }
+        // Layer 3 — walk the tar entries (inspect doesn't extract).
+        var entries = await tarReader.inspect();
+        return {
+          ok:           true,
+          format:       info.format,
+          envelopeKind: info.envelopeKind,
+          entryCount:   entries.length,
+          errors:       [],
+        };
+      } catch (e) {
+        return {
+          ok:           false,
+          format:       info.format,
+          envelopeKind: info.envelopeKind,
+          entryCount:   0,
+          errors:       [e.code || e.message || String(e)],
+        };
+      }
+    },
     // bundleInfo(bundleId) — v0.12.17 per-bundle introspection.
     // Returns `{ bundleId, format, envelopeKind, sizeBytes }`.
     // `format` is one of `"tar"` / `"tar.gz"` / `"directory"`
@@ -1450,6 +1564,28 @@ function bundleAdapterStorage(opts) {
       }
       var envelopeKind = "none";
       var sizeBytes = null;
+      var createdAt = null;
+      // Codex P2 on v0.12.18 PR #169 — directory-format bundles
+      // leave payloadKey null but DO have a manifest.json that
+      // statKey can read. For createdAt parity with
+      // listBundles({ withStats }), stat the manifest in the
+      // directory case so the bundleInfo return shape is
+      // populated identically across formats.
+      if (payloadKey === null && fmt === "directory" &&
+          typeof adapter.statKey === "function") {
+        // Stat the manifest.json so directory-format bundles
+        // populate createdAt + sizeBytes identically to how
+        // listBundles({ withStats }) reports them. NOTE: sizeBytes
+        // is the manifest's size here, not the total file-tree
+        // payload (operators wanting the true total walk
+        // per-file keys themselves) — same convention as
+        // listBundles({ withStats }) for parity.
+        var dirSt = await adapter.statKey(manifestKey);
+        if (dirSt && typeof dirSt.size === "number") sizeBytes = dirSt.size;
+        if (dirSt && typeof dirSt.mtimeMs === "number") {
+          createdAt = new Date(dirSt.mtimeMs).toISOString();
+        }
+      }
       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
@@ -1478,6 +1614,7 @@ function bundleAdapterStorage(opts) {
         if (typeof adapter.statKey === "function") {
           var st = await adapter.statKey(payloadKey);
           if (st && typeof st.size === "number") sizeBytes = st.size;
+          if (st && typeof st.mtimeMs === "number") createdAt = new Date(st.mtimeMs).toISOString();
         }
       }
       return {
@@ -1485,6 +1622,7 @@ function bundleAdapterStorage(opts) {
         format:       fmt,
         envelopeKind: envelopeKind,
         sizeBytes:    sizeBytes,
+        createdAt:    createdAt,
       };
     },
     async deleteBundle(bundleId) {

package/lib/safe-archive.js

@@ -373,9 +373,21 @@ async function inspect(opts) {
         bombPolicy: opts.bombPolicy,
         audit:      opts.audit,
       });
+    } else if (format === "tar.gz") {
+      // v0.12.19 — inspect parity with extract for tar.gz format.
+      // gz envelope auto-decompresses + the inner tar walker
+      // enumerates entries without writing to disk.
+      reader = archiveGz().read.gz(source, {
+        maxDecompressedBytes: opts.maxDecompressedBytes,
+        maxExpansionRatio:    opts.maxExpansionRatio,
+        audit:                opts.audit,
+      }).asTar({
+        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; v0.12.16 auto-unwraps wrap envelopes");
+        "inspect: format=" + JSON.stringify(format) + " — v0.12.19 ships ZIP + tar + tar.gz; 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.17",
+  "version": "0.12.19",
   "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:5b052d03-601b-4eb1-93d8-60aaaf81b2f7",
+  "serialNumber": "urn:uuid:4b94a721-bd76-436d-8d96-e205956b6d90",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T04:43:58.102Z",
+    "timestamp": "2026-05-24T05:39:53.422Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.17",
+      "bom-ref": "@blamejs/core@0.12.19",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.17",
+      "version": "0.12.19",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.17",
+      "purl": "pkg:npm/%40blamejs/core@0.12.19",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.17",
+      "ref": "@blamejs/core@0.12.19",
       "dependsOn": []
     }
   ]