@blamejs/core 0.12.21 → 0.12.23

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.23 (2026-05-24) — **`bundleAdapterStorage.cloneBundle(src, dst, opts?)` — same-storage byte-verbatim bundle clone for pre-rotation snapshots.** `storage.cloneBundle(srcBundleId, dstBundleId, opts?)` copies a bundle's adapter payload (bundle.tar / bundle.tar.gz / every directory key) from src to dst WITHOUT touching the envelope or inner archive. Encrypted bundles are cloned byte-verbatim — the new bundleId carries the same envelope under the same recipient/passphrase. Operators preserving a known-good snapshot before a destructive operation (rewrap, key rotation, schema migration, manual operator-side editing) get a single-call atomic clone instead of a manual readBundle → writeBundle cycle (which would re-encode through the envelope and adapter contracts, breaking byte-identity). **Added:** *`storage.cloneBundle(src, dst, opts?)` — byte-verbatim payload clone* — Reads the source bundle's storage keys + writes them under the destination bundleId without invoking the wrap layer, gunzip path, or tar walker. Encrypted bundles produce byte-identical clones (a tar.gz wrap-recipient envelope cloned via cloneBundle has bit-for-bit equal bytes to the source). Returns `{ srcBundleId, dstBundleId, format, keysCopied, bytesCopied }`. `opts.overwrite` (default false) gates whether to refuse if dstBundleId already exists. Same-id clones refused upfront with `backup/clone-same-id`.
+
+- 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.

package/lib/backup/index.js

@@ -1541,6 +1541,80 @@ function bundleAdapterStorage(opts) {
     // bytesRewritten }`. Refuses cross-kind rotation (recipient ↔
     // passphrase) — that's a separate migration the operator
     // configures explicitly.
+    // cloneBundle(srcBundleId, dstBundleId, opts?) — v0.12.23
+    // same-storage bundle clone. Copies the bundle's adapter
+    // payload (bundle.tar / bundle.tar.gz / every directory key)
+    // from src to dst WITHOUT touching the envelope or inner
+    // archive. Useful before destructive operations (rewrap, key
+    // rotation, schema migration) to preserve a known-good
+    // snapshot under a distinct bundleId. opts.overwrite (default
+    // false) gates whether to refuse if dstBundleId already
+    // exists in storage.
+    //
+    // Returns `{ srcBundleId, dstBundleId, format, keysCopied,
+    // bytesCopied }`.
+    async cloneBundle(srcBundleId, dstBundleId, cloneOpts) {
+      cloneOpts = cloneOpts || {};
+      _ensureBundleId(srcBundleId);
+      _ensureBundleId(dstBundleId);
+      if (srcBundleId === dstBundleId) {
+        throw new BackupError("backup/clone-same-id",
+          "cloneBundle: srcBundleId === dstBundleId — refusing same-id clone");
+      }
+      var info = await this.bundleInfo(srcBundleId);
+      var dstAlreadyExists = await this.hasBundle(dstBundleId);
+      if (cloneOpts.overwrite !== true && dstAlreadyExists) {
+        throw new BackupError("backup/clone-dst-exists",
+          "cloneBundle: dstBundleId '" + dstBundleId + "' already exists; " +
+          "pass opts.overwrite=true to replace");
+      }
+      // Codex P1 on v0.12.23 PR #174 — when overwrite=true, the
+      // existence guard was the only protection but it didn't
+      // delete the destination's existing keys before writing
+      // the source keys. Stale-format bundles (dst=tar, src=
+      // directory) ended up with BOTH the old tar key and the
+      // new directory keys present — bundleInfo / readBundle
+      // would resolve to the (still-existing) tar payload,
+      // disagreeing with the reported clone result. Same applies
+      // for directory→directory clones where the destination
+      // had extra files not in source.
+      //
+      // Fix: when overwrite is enabled + the destination
+      // already exists, call deleteBundle(dst) first to purge
+      // every key under the destination's prefix so clone
+      // semantics are actually replace-bytes.
+      if (dstAlreadyExists && cloneOpts.overwrite === true) {
+        await this.deleteBundle(dstBundleId);
+      }
+      var keysCopied = 0;
+      var bytesCopied = 0;
+      if (info.format === "tar" || info.format === "tar.gz") {
+        var suffix = info.format === "tar.gz" ? TAR_GZ_KEY_SUFFIX : TAR_KEY_SUFFIX;
+        var payload = await adapter.readFile(srcBundleId + suffix);
+        await adapter.writeFile(dstBundleId + suffix, payload);
+        keysCopied += 1;
+        bytesCopied += payload.length;
+      } else {
+        // Directory format — walk every key under the source
+        // bundleId + replicate under the destination prefix.
+        var srcKeys = await adapter.listKeys(srcBundleId + "/");
+        for (var ki = 0; ki < srcKeys.length; ki += 1) {
+          var srcKey = srcKeys[ki];
+          var rel = srcKey.slice((srcBundleId + "/").length);
+          var keyBytes = await adapter.readFile(srcKey);
+          await adapter.writeFile(dstBundleId + "/" + rel, keyBytes);
+          keysCopied += 1;
+          bytesCopied += keyBytes.length;
+        }
+      }
+      return {
+        srcBundleId:  srcBundleId,
+        dstBundleId:  dstBundleId,
+        format:       info.format,
+        keysCopied:   keysCopied,
+        bytesCopied:  bytesCopied,
+      };
+    },
     async rewrapBundle(bundleId, rwOpts) {
       rwOpts = rwOpts || {};
       _ensureBundleId(bundleId);
@@ -1640,6 +1714,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.21",
+  "version": "0.12.23",
   "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:2525a280-77a5-4844-bb70-d0fe3edb44f8",
+  "serialNumber": "urn:uuid:913ec1d4-c11d-49fe-922b-3738c93f2aad",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-24T07:09:48.128Z",
+    "timestamp": "2026-05-24T08:56:20.519Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.21",
+      "bom-ref": "@blamejs/core@0.12.23",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.21",
+      "version": "0.12.23",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.21",
+      "purl": "pkg:npm/%40blamejs/core@0.12.23",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.21",
+      "ref": "@blamejs/core@0.12.23",
       "dependsOn": []
     }
   ]