@blamejs/core 0.12.20 → 0.12.22

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.22 (2026-05-24) — **`bundleAdapterStorage.rewrapAllBundles(opts)` — bounded-parallel batch envelope rotation with mixed-storage skip semantics.** Batch wrapper over the v0.12.21 rewrapBundle primitive. `storage.rewrapAllBundles(opts?)` iterates `listBundles()` + rotates each bundle's wrap envelope through a bounded-parallel pool (default 4 workers). Plaintext bundles + directory-format bundles get skipped cleanly (recorded as `status: "skipped"` with a `reason` field); rewrap failures get bucketed into `status: "failed"`. Operators completing a key-rotation event across an entire backup repository now have a single call that handles mixed-strategy storage correctly. `opts.newRecipient` / `opts.newPassphrase` / `opts.oldRecipient` / `opts.oldPassphrase` / `opts.concurrency` / `opts.stopOnFirstFailure` mirror the verifyAllBundles + rewrapBundle surface. **Added:** *`storage.rewrapAllBundles(opts?)` — batch envelope rotation* — Iterates listBundles() + dispatches each bundle through rewrapBundle with the operator-supplied new key. Returns `{ total, rotated, skipped, failed, results }` where the per-bundle results carry `{ status: "rotated" | "skipped" | "failed", oldEnvelopeKind, newEnvelopeKind, reason }`. Bounded-parallel fan-out (default 4) keeps the storage backend under control; opts.stopOnFirstFailure short-circuits on the first rotation that throws an unexpected error (skips don't trip the short-circuit — they're expected for mixed-strategy storage). Plaintext + directory bundles skipped with `reason: "format-not-wrappable"` / `reason: "no-envelope"` rather than reported as failures.
+
+- 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.

package/lib/backup/index.js

@@ -1532,6 +1532,105 @@ 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
@@ -1541,6 +1640,113 @@ function bundleAdapterStorage(opts) {
     // unhealthy bundle is found (default false — operators want
     // the full report). opts.recipient / opts.passphrase forwarded
     // to verifyBundle for each bundle.
+    // rewrapAllBundles(opts) — v0.12.22 batch wrapper over the
+    // v0.12.21 rewrapBundle primitive. Iterates listBundles() +
+    // rewraps each through a bounded-parallel pool, skipping
+    // plaintext / directory bundles cleanly. Returns
+    // `{ total, rotated, skipped, failed, results }` where the
+    // results array carries per-bundle `{ status: "rotated" |
+    // "skipped" | "failed", ... }`. opts.concurrency /
+    // opts.stopOnFirstFailure mirror verifyAllBundles.
+    // opts.newRecipient / opts.newPassphrase /
+    // opts.oldRecipient / opts.oldPassphrase forwarded to each
+    // per-bundle rewrap.
+    async rewrapAllBundles(opts) {
+      opts = opts || {};
+      var concurrency = 4;                                                            // allow:raw-byte-literal — default fan-out, not byte count
+      if (typeof opts.concurrency === "number" && Number.isFinite(opts.concurrency) &&
+          opts.concurrency > 0) {
+        concurrency = Math.max(1, Math.floor(opts.concurrency));
+      }
+      var stopOnFirst = opts.stopOnFirstFailure === true;
+      var list = await this.listBundles();
+      var self = this;
+      var results = [];
+      var rotated = 0;
+      var skipped = 0;
+      var failed = 0;
+      var pending = list.slice();
+      var inflight = [];
+      var aborted = false;
+      function _spawn() {
+        // Codex P1 on v0.12.22 PR #173 — synchronously drain
+        // non-wrappable entries inside _spawn until we hit one
+        // that actually needs an async rewrap (or the pending
+        // queue empties). The prior implementation returned
+        // Promise.resolve() for skipped entries without adding
+        // to inflight; if the first `concurrency` items were
+        // all directory bundles, the warm-up drained pending
+        // into the skipped bucket without spawning any inflight
+        // workers + the drain loop exited immediately, leaving
+        // the rest of the queue unprocessed.
+        while (!aborted && pending.length > 0) {
+          var entry = pending.shift();
+          if (entry.format !== "tar" && entry.format !== "tar.gz") {
+            results.push({
+              bundleId:        entry.bundleId,
+              status:          "skipped",
+              reason:          "format-not-wrappable",
+              oldEnvelopeKind: null,
+              newEnvelopeKind: null,
+            });
+            skipped += 1;
+            continue;                                                                 // try the next pending entry
+          }
+          return _spawnRewrap(entry);
+        }
+        return null;
+      }
+      function _spawnRewrap(entry) {
+        var p = self.rewrapBundle(entry.bundleId, opts).then(function (r) {
+          results.push(Object.assign({ status: "rotated" }, r));
+          rotated += 1;
+        }, function (err) {
+          var code = (err && err.code) || (err && err.message) || String(err);
+          if (/no-envelope-to-rewrap/.test(code)) {
+            results.push({
+              bundleId:        entry.bundleId,
+              status:          "skipped",
+              reason:          "no-envelope",
+              oldEnvelopeKind: null,
+              newEnvelopeKind: null,
+            });
+            skipped += 1;
+          } else {
+            results.push({
+              bundleId:        entry.bundleId,
+              status:          "failed",
+              reason:          code,
+              oldEnvelopeKind: null,
+              newEnvelopeKind: null,
+            });
+            failed += 1;
+            if (stopOnFirst) aborted = true;
+          }
+        });
+        inflight.push(p);
+        p.finally(function () {
+          var idx = inflight.indexOf(p);
+          if (idx !== -1) inflight.splice(idx, 1);
+        });
+        return p;
+      }
+      var ri;
+      for (ri = 0; ri < concurrency; ri += 1) _spawn();
+      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();
+        }
+      }
+      results.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
+      return {
+        total:    list.length,
+        rotated:  rotated,
+        skipped:  skipped,
+        failed:   failed,
+        results:  results,
+      };
+    },
     async verifyAllBundles(vOpts) {
       vOpts = vOpts || {};
       // Codex P1 on v0.12.20 PR #171 — clamp fractional + zero

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.20",
+  "version": "0.12.22",
   "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:d7fb9c32-9b4a-4de6-a37c-b0a5326a3078",
+  "serialNumber": "urn:uuid:aa0703c8-0954-482c-af7e-d813018096cf",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T06:29:55.574Z",
+    "timestamp": "2026-05-24T08:01:37.093Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.20",
+      "bom-ref": "@blamejs/core@0.12.22",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.20",
+      "version": "0.12.22",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.20",
+      "purl": "pkg:npm/%40blamejs/core@0.12.22",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.20",
+      "ref": "@blamejs/core@0.12.22",
       "dependsOn": []
     }
   ]