@blamejs/core 0.12.19 → 0.12.21

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.21 (2026-05-24) — **`bundleAdapterStorage.rewrapBundle(bundleId, opts)` — key rotation without restore + rewrite of inner archive bytes.** `storage.rewrapBundle(bundleId, opts?)` rotates a bundle's wrap envelope under a new recipient keypair or passphrase WITHOUT touching the inner tar / tar.gz bytes. Operators rotating a compromised keypair, migrating to a new HSM, or refreshing passphrases on a HIPAA-posture repository previously had to `readBundle` → write to a stage dir → `writeBundle` under the new key — three byte-walks of the bundle payload, two filesystem touches, transient plaintext on disk. rewrapBundle does it as unwrap + rewrap in memory: zero disk plaintext, one round-trip through the wrap layer, the gzipped tar archive bytes inside the envelope are never inflated. Cross-kind rotation (recipient ↔ passphrase) is refused — that's a separate migration the operator configures with explicit cryptoStrategy switch. **Added:** *`storage.rewrapBundle(bundleId, opts?)` — in-place envelope rotation* — Unwraps the bundle under the old key (storage's configured recipient/passphrase OR `opts.oldRecipient` / `opts.oldPassphrase`), re-wraps under the new key (`opts.newRecipient` / `opts.newPassphrase`), writes the rewrapped bytes back to the same storage key. Returns `{ bundleId, oldEnvelopeKind, newEnvelopeKind, bytesRewritten }`. Plaintext bundles refused with `backup/no-envelope-to-rewrap`; cross-kind rotation refused with `backup/no-new-recipient` / `backup/no-new-passphrase`. The inner archive bytes (the gz-compressed tar payload) are never decompressed or re-encoded — rewrap is a wrap-layer-only operation. **Security:** *Zero plaintext on disk during rotation* — The inner tar bytes flow only through memory — old-envelope unwrap → new-envelope wrap → adapter writeFile. Operators previously rotating via readBundle + writeBundle wrote plaintext archive bytes to a temporary stage directory; rewrapBundle removes that exposure window entirely. Matches the operator-side discipline that backup payloads should never land on disk in plaintext form during steady-state operations.
+
+- v0.12.20 (2026-05-24) — **`bundleAdapterStorage.verifyAllBundles(opts)` — bounded-parallel batch integrity walk with stopOnFirstFailure short-circuit.** Batch wrapper over the v0.12.19 verifyBundle primitive. `storage.verifyAllBundles(opts?)` iterates `listBundles()` + walks each bundle with a bounded-parallel pool. Returns `{ total, ok, failed, results }` where `results` carries every per-bundle verifyBundle output (including bundleId, format, envelopeKind, entryCount, errors). `opts.concurrency` defaults to 4 (gentle on the storage backend); `opts.stopOnFirstFailure` short-circuits the walk when an unhealthy bundle is found (default off — operators want the full health report). `opts.recipient` / `opts.passphrase` forwarded to every per-bundle verify call. Operators wiring a periodic cron job over a backup repository now have a single primitive to call instead of hand-rolling the listBundles loop. **Added:** *`storage.verifyAllBundles(opts?)` — batch integrity walk* — Iterates `listBundles()` + calls `verifyBundle(bundleId, opts)` on each. Bounded-parallel fan-out (default 4 workers; `opts.concurrency` raises or lowers); each worker pulls from a shared queue + the warm-up keeps `concurrency` workers in flight until the queue drains. Returns the aggregate `{ total, ok, failed, results }` with `results` sorted by bundleId so the report is stable across runs regardless of completion order. `opts.stopOnFirstFailure` short-circuits the walk when the first unhealthy bundle is found — useful for fast-fail CI gates that don't need to enumerate every failure.
+
 - 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.

package/lib/backup/index.js

@@ -1532,6 +1532,200 @@ function bundleAdapterStorage(opts) {
         };
       }
     },
+    // rewrapBundle(bundleId, opts) — v0.12.21 key rotation
+    // without restore + rewrite. Unwraps the bundle under the old
+    // key + re-wraps under the new key. Inner tar / tar.gz bytes
+    // are never decompressed or rewritten. Operators rotating
+    // recipient keypairs avoid the full restore-to-disk → rewrite
+    // cycle. Returns `{ bundleId, oldEnvelopeKind, newEnvelopeKind,
+    // bytesRewritten }`. Refuses cross-kind rotation (recipient ↔
+    // passphrase) — that's a separate migration the operator
+    // configures explicitly.
+    async rewrapBundle(bundleId, rwOpts) {
+      rwOpts = rwOpts || {};
+      _ensureBundleId(bundleId);
+      var info = await this.bundleInfo(bundleId);
+      if (info.format !== "tar" && info.format !== "tar.gz") {
+        throw new BackupError("backup/format-not-wrappable",
+          "rewrapBundle: '" + bundleId + "' has format=" + JSON.stringify(info.format) +
+          " — only tar / tar.gz bundles carry wrap envelopes");
+      }
+      var rwKeySuffix = info.format === "tar.gz" ? TAR_GZ_KEY_SUFFIX : TAR_KEY_SUFFIX;
+      var sealed = await adapter.readFile(bundleId + rwKeySuffix);
+      var envelopeKind = info.envelopeKind;
+      // Codex P2 on v0.12.21 PR #172 — when the adapter has no
+      // readPartial capability, bundleInfo returns envelopeKind:
+      // "unknown" rather than risk a full payload load. For
+      // rewrap, we already have to load the payload (to unwrap),
+      // so fall back to a sniffEnvelope on the loaded sealed
+      // bytes — fixes the regression where adapters satisfying
+      // the minimum contract couldn't use rewrapBundle.
+      if (envelopeKind === "unknown") {
+        envelopeKind = archiveLazy().sniffEnvelope(sealed);
+      }
+      if (envelopeKind !== "recipient" && envelopeKind !== "passphrase") {
+        throw new BackupError("backup/no-envelope-to-rewrap",
+          "rewrapBundle: '" + bundleId + "' carries envelopeKind=" +
+          JSON.stringify(envelopeKind) + " — nothing to rewrap");
+      }
+      // Override the info.envelopeKind we use below so the
+      // dispatch + return shape reflect the actual envelope we
+      // detected (matters when bundleInfo returned "unknown").
+      info = Object.assign({}, info, { envelopeKind: envelopeKind });
+      var inner;
+      if (info.envelopeKind === "recipient") {
+        var oldRcp = rwOpts.oldRecipient !== undefined ? rwOpts.oldRecipient : recipient;
+        if (!oldRcp) {
+          throw new BackupError("backup/no-old-recipient",
+            "rewrapBundle: opts.oldRecipient (or the storage's configured recipient) is required to unwrap");
+        }
+        if (!rwOpts.newRecipient || typeof rwOpts.newRecipient !== "object") {
+          throw new BackupError("backup/no-new-recipient",
+            "rewrapBundle: opts.newRecipient is required to re-seal under the rotated key");
+        }
+        inner = archiveLazy().unwrap(sealed, { recipient: oldRcp });
+        var resealed = archiveLazy().wrap(inner, { recipient: rwOpts.newRecipient });
+        await adapter.writeFile(bundleId + rwKeySuffix, resealed);
+        return {
+          bundleId:         bundleId,
+          oldEnvelopeKind:  "recipient",
+          newEnvelopeKind:  "recipient",
+          bytesRewritten:   resealed.length,
+        };
+      }
+      // passphrase
+      var oldPass = rwOpts.oldPassphrase !== undefined ? rwOpts.oldPassphrase : passphrase;
+      if (typeof oldPass !== "string" && !Buffer.isBuffer(oldPass)) {
+        throw new BackupError("backup/no-old-passphrase",
+          "rewrapBundle: opts.oldPassphrase (or the storage's configured passphrase) is required to unwrap");
+      }
+      if (typeof rwOpts.newPassphrase !== "string" && !Buffer.isBuffer(rwOpts.newPassphrase)) {
+        throw new BackupError("backup/no-new-passphrase",
+          "rewrapBundle: opts.newPassphrase is required (string or Buffer) to re-seal");
+      }
+      inner = await archiveLazy().unwrapWithPassphrase(sealed, { passphrase: oldPass });
+      // Codex P1 on v0.12.21 PR #172 — preserve the storage's
+      // configured entropy floor across rewrap. The
+      // writeBundle path raises the floor to 128 bits under
+      // HIPAA / PCI-DSS postures (per
+      // BACKUP_ENCRYPTION_REQUIRED_POSTURES); rewrapBundle MUST
+      // apply the same floor so a rotated passphrase that
+      // writeBundle would refuse can't slip through. The
+      // operator's explicit rwOpts.passphraseMinEntropyBits
+      // can raise the floor further but cannot lower it.
+      var effectiveFloor = passphraseMinEntropyBits;                                  // storage's posture-effective floor
+      if (typeof rwOpts.passphraseMinEntropyBits === "number" &&
+          Number.isFinite(rwOpts.passphraseMinEntropyBits) &&
+          rwOpts.passphraseMinEntropyBits > effectiveFloor) {
+        effectiveFloor = Math.floor(rwOpts.passphraseMinEntropyBits);
+      }
+      var resealedP = await archiveLazy().wrapWithPassphrase(inner, {
+        passphrase:     rwOpts.newPassphrase,
+        minEntropyBits: effectiveFloor,
+      });
+      await adapter.writeFile(bundleId + rwKeySuffix, resealedP);
+      return {
+        bundleId:         bundleId,
+        oldEnvelopeKind:  "passphrase",
+        newEnvelopeKind:  "passphrase",
+        bytesRewritten:   resealedP.length,
+      };
+    },
+    // verifyAllBundles(opts?) — v0.12.20 batch integrity check.
+    // Iterates listBundles() + calls verifyBundle on each. Returns
+    // `{ total, ok, failed, results }` where `results` is an array
+    // of per-bundle verifyBundle outputs. opts.concurrency caps the
+    // parallelism (default 4 — gentle on the storage backend);
+    // opts.stopOnFirstFailure short-circuits the walk when an
+    // unhealthy bundle is found (default false — operators want
+    // the full report). opts.recipient / opts.passphrase forwarded
+    // to verifyBundle for each bundle.
+    async verifyAllBundles(vOpts) {
+      vOpts = vOpts || {};
+      // Codex P1 on v0.12.20 PR #171 — clamp fractional + zero
+      // floors so a stray `0.5` doesn't spawn zero workers + return
+      // a silent ok=0/failed=0 report on non-empty storage. Default
+      // 4; minimum 1; non-finite / non-positive falls back to
+      // default.
+      var concurrency = 4;                                                            // allow:raw-byte-literal — default fan-out, not byte count
+      if (typeof vOpts.concurrency === "number" && Number.isFinite(vOpts.concurrency) &&
+          vOpts.concurrency > 0) {
+        concurrency = Math.max(1, Math.floor(vOpts.concurrency));
+      }
+      var stopOnFirst = vOpts.stopOnFirstFailure === true;
+      var list = await this.listBundles();
+      var self = this;
+      var results = [];
+      var failed = 0;
+      var ok = 0;
+      var pending = list.slice();
+      var inflight = [];
+      var aborted = false;
+      // Sequential bounded-parallel walk. Bring up `concurrency`
+      // workers; each pulls the next bundleId until the queue is
+      // empty or stopOnFirstFailure trips.
+      function _spawn() {
+        if (aborted) return null;
+        if (pending.length === 0) return null;
+        var entry = pending.shift();
+        // Codex P2 on v0.12.20 PR #171 — wrap each worker so any
+        // verifyBundle rejection becomes a failed-result entry
+        // rather than rejecting the whole batch. Without this, a
+        // mid-walk failure (payload disappeared between listBundles
+        // + readFile, network blip on object-store, etc.) would
+        // throw out of Promise.race and abort verifyAllBundles
+        // without returning the promised aggregate report.
+        var promise = self.verifyBundle(entry.bundleId, {
+          recipient:  vOpts.recipient,
+          passphrase: vOpts.passphrase,
+        }).then(function (r) {
+          results.push(Object.assign({ bundleId: entry.bundleId }, r));
+          if (r.ok) ok += 1;
+          else {
+            failed += 1;
+            if (stopOnFirst) aborted = true;
+          }
+        }, function (err) {
+          // Rejection path — convert to a failed-result entry so
+          // the aggregate stays consistent.
+          results.push({
+            bundleId:     entry.bundleId,
+            ok:           false,
+            format:       null,
+            envelopeKind: null,
+            entryCount:   0,
+            errors:       [err && err.code ? err.code : ((err && err.message) || String(err))],
+          });
+          failed += 1;
+          if (stopOnFirst) aborted = true;
+        });
+        inflight.push(promise);
+        promise.finally(function () {
+          var idx = inflight.indexOf(promise);
+          if (idx !== -1) inflight.splice(idx, 1);
+        });
+        return promise;
+      }
+      // Warm-up: spawn up to concurrency workers.
+      var i;
+      for (i = 0; i < concurrency; i += 1) _spawn();
+      // Drain: as each worker resolves, spawn its replacement.
+      while (inflight.length > 0) {
+        await Promise.race(inflight.slice());
+        if (!aborted && pending.length > 0 && inflight.length < concurrency) {
+          while (inflight.length < concurrency && pending.length > 0) _spawn();
+        }
+      }
+      // Sort results back to listBundles order for operator-
+      // friendly output (concurrency reorders inflight completion).
+      results.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
+      return {
+        total:   list.length,
+        ok:      ok,
+        failed:  failed,
+        results: results,
+      };
+    },
     // bundleInfo(bundleId) — v0.12.17 per-bundle introspection.
     // Returns `{ bundleId, format, envelopeKind, sizeBytes }`.
     // `format` is one of `"tar"` / `"tar.gz"` / `"directory"`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.19",
+  "version": "0.12.21",
   "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:4b94a721-bd76-436d-8d96-e205956b6d90",
+  "serialNumber": "urn:uuid:2525a280-77a5-4844-bb70-d0fe3edb44f8",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T05:39:53.422Z",
+    "timestamp": "2026-05-24T07:09:48.128Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.19",
+      "bom-ref": "@blamejs/core@0.12.21",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.19",
+      "version": "0.12.21",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.19",
+      "purl": "pkg:npm/%40blamejs/core@0.12.21",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.19",
+      "ref": "@blamejs/core@0.12.21",
       "dependsOn": []
     }
   ]