@blamejs/core 0.8.43 → 0.8.50

package/lib/restore-bundle.js

@@ -1,47 +1,48 @@
 "use strict";
 /**
- * restore-bundle — extract an encrypted backup bundle to a staging dir.
+ * @module b.restoreBundle
+ * @nav    Production
+ * @title  Restore Bundle
  *
- * The mirror of backup-bundle. Reads manifest.json from a bundle
- * directory, decrypts each per-file blob via backup-crypto, verifies
- * each plaintext's sha3-512 checksum matches the manifest, and writes
- * the recovered files to a staging directory the caller then atomically
- * swaps into place. The bundle directory itself is read-only throughout.
+ * @intro
+ *   Backup-bundle reader — verify the manifest signature, list bundle
+ *   contents without decrypting, and cherry-pick a restore subset to a
+ *   staging directory the caller atomically swaps into place.
  *
- *   var r = await b.restoreBundle.extract({
- *     bundleDir:    "./backups/2026-04-27.bundle",
- *     stagingDir:   "./data.staging",       // must NOT exist
- *     passphrase:   Buffer.from("operator passphrase"),
- *     filter:       function (entry) { return true; },  // optional
- *     progressCallback: function (event) { ... },
- *   });
- *   // → { manifest, vaultKeyJson, fileCount, totalBytes,
- *   //     stagingDir, durationMs }
+ *   The mirror of `b.backupBundle`. `b.restoreBundle.inspect` reads
+ *   `manifest.json` and returns the parsed object — useful for
+ *   dashboards and pre-flight UI that want to list files, sizes,
+ *   timestamps, and kinds before prompting the operator for the
+ *   passphrase. `b.restoreBundle.extract` decrypts each per-file blob
+ *   via `b.backup/crypto`, verifies the SHA3-512 plaintext checksum
+ *   against the manifest, and writes the recovered files into a
+ *   fresh `stagingDir`. The bundle directory itself stays read-only
+ *   throughout.
  *
- * vaultKeyJson is the decrypted vault keypair JSON the bundle carried
- * in manifest.vaultKeyEnc. The caller decides what to do with it:
- * write to stagingDir/vault.key for a fresh framework boot, hand to
- * vault.init for an in-process load, etc. — restore-bundle's job ends
- * at recovery; vault-key placement is operator policy.
+ *   `extract` always recovers the wrapped vault key (decrypted JSON
+ *   returned on `vaultKeyJson`) so the operator can unseal columns
+ *   from a partial restore. The `filter` predicate lets the caller
+ *   pull a subset — only the DB, only TLS keys, only the consent
+ *   log — without producing every blob.
  *
- * filter: optional predicate that lets a caller pull a subset (only
- * the DB, only the TLS keys, etc.). The vault key is always recovered
- * regardless of filter so the operator can read sealed values from a
- * partial restore.
+ *   Defense surface:
  *
- * Defense:
- *   - Wrong passphrase → AEAD tag check fails on first blob →
- *     restore-bundle/decrypt-failed (no plaintext leaked, no staging
+ *   - Wrong passphrase / tampered blob → AEAD tag failure →
+ *     `restore-bundle/decrypt-failed` (no plaintext leak, no staging
  *     left behind)
- *   - Tampered blob (single byte flip in ciphertext) → same path
- *   - encryptedSize mismatch → restore-bundle/size-mismatch (cheap
- *     pre-decrypt check)
- *   - Plaintext sha3-512 != manifest.checksum → restore-bundle/
- *     checksum-mismatch (post-decrypt integrity guard)
- *   - Missing blob file → restore-bundle/missing-blob (manifest
- *     references a path the bundle dir doesn't have)
- *   - On any failure, the partially-built stagingDir is removed so a
- *     subsequent retry isn't blocked by a stale dir
+ *   - Pre-decrypt `encryptedSize` mismatch → `restore-bundle/
+ *     size-mismatch`
+ *   - Post-decrypt SHA3-512 ≠ manifest checksum →
+ *     `restore-bundle/checksum-mismatch`
+ *   - Missing blob file → `restore-bundle/missing-blob`
+ *   - Bad manifest signature → `restore-bundle/bad-signature`;
+ *     `requireSignature: true` upgrades a missing signature to
+ *     `restore-bundle/missing-signature`
+ *   - On any failure the partially-built `stagingDir` is removed so a
+ *     subsequent retry is not blocked by a stale directory
+ *
+ * @card
+ *   Backup-bundle reader — verify the manifest signature, list bundle contents without decrypting, and cherry-pick a restore subset to a staging directory the caller atomically swaps into place.
  */
 
 var fs = require("fs");
@@ -68,6 +69,57 @@ function _cleanupStaging(stagingDir) {
   catch (_e) { /* best-effort */ }
 }
 
+/**
+ * @primitive b.restoreBundle.extract
+ * @signature b.restoreBundle.extract(opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.restoreBundle.inspect, b.backupBundle.create, b.vault.init
+ *
+ * Decrypt every blob the manifest references (or the subset
+ * `opts.filter` accepts), verify each plaintext's checksum, and write
+ * the recovered files into `opts.stagingDir`. Returns
+ * `{ manifest, vaultKeyJson, fileCount, totalBytes, stagingDir,
+ * durationMs }`.
+ *
+ * `stagingDir` MUST NOT exist — extract refuses to merge into an
+ * existing directory so a half-finished prior restore can never get
+ * silently overlaid. On any failure the partial `stagingDir` is
+ * removed.
+ *
+ * Signature handling: when the manifest carries a signature it is
+ * verified with `b.backup/manifest`'s public-key check. Pass
+ * `verifySignature: false` for cold restores from an org whose
+ * audit-sign keypair the framework cannot reach; pass
+ * `requireSignature: true` to fail-closed on bundles missing a
+ * signature; pass `expectedFingerprint` to pin a specific signing
+ * key.
+ *
+ * @opts
+ *   bundleDir:           string,                   // read-only bundle dir (required)
+ *   stagingDir:          string,                   // fresh output dir (required, must not exist)
+ *   passphrase:          Buffer | string,          // unwrap key (required)
+ *   filter:              function (entry): boolean,// subset predicate
+ *   progressCallback:    function (ev): void,      // phase events: read_manifest / decrypt / done
+ *   verifySignature:     boolean,                  // default: true
+ *   requireSignature:    boolean,                  // fail-closed on missing signature
+ *   expectedFingerprint: string,                   // pin specific signing key
+ *
+ * @example
+ *   try {
+ *     var report = await b.restoreBundle.extract({
+ *       bundleDir:        "/srv/backups/2026-04-27.bundle",
+ *       stagingDir:       "/srv/restore/data.staging",
+ *       passphrase:       Buffer.from("operator-passphrase"),
+ *       requireSignature: true,
+ *       filter:           function (entry) { return entry.kind === "db"; },
+ *     });
+ *     report.fileCount;            // → 1
+ *     typeof report.vaultKeyJson;  // → "string"
+ *   } catch (e) {
+ *     e.code; // → "restore-bundle/decrypt-failed"
+ *   }
+ */
 async function extract(opts) {
   var t0 = Date.now();
   opts = opts || {};
@@ -107,6 +159,27 @@ async function extract(opts) {
       "extract: manifest could not be parsed: " + ((e && e.message) || String(e)));
   }
 
+  // Verify the manifest signature when present. Operators can pass
+  // `requireSignature: true` to fail-closed on missing signatures
+  // (HIPAA/PCI-DSS), `expectedFingerprint` to pin a specific signing
+  // key, or pass `verifySignature: false` to skip verification when
+  // the signing key is genuinely unavailable (cold-restore from a
+  // separate org with their own audit-sign keypair the framework
+  // can't reach).
+  var verifySig = opts.verifySignature !== false;
+  if (verifySig && manifest.signature) {
+    var sigResult = backupManifest.verifySignature(manifest, {
+      expectedFingerprint: opts.expectedFingerprint || undefined,
+    });
+    if (!sigResult.ok) {
+      throw new RestoreBundleError("restore-bundle/bad-signature",
+        "extract: manifest signature invalid: " + sigResult.reason);
+    }
+  } else if (opts.requireSignature === true && !manifest.signature) {
+    throw new RestoreBundleError("restore-bundle/missing-signature",
+      "extract: manifest has no signature but opts.requireSignature=true");
+  }
+
   // 2. Recover the vault key (always, regardless of filter — the
   // operator may need it to unseal post-restore even on partial
   // restores)
@@ -213,9 +286,39 @@ async function extract(opts) {
   };
 }
 
-// Inspect a bundle without decrypting — read the manifest and return
-// it. Useful for dashboards and pre-flight UI: list files, sizes,
-// timestamps, kinds without prompting for the passphrase.
+/**
+ * @primitive b.restoreBundle.inspect
+ * @signature b.restoreBundle.inspect(opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.restoreBundle.extract, b.backupBundle.create
+ *
+ * Read `manifest.json` from `opts.bundleDir` and return the parsed
+ * object — files, sizes, timestamps, kinds, signature presence —
+ * without prompting for the passphrase or decrypting anything. Useful
+ * for dashboards, pre-flight UI, and "what's in this bundle?" checks
+ * before kicking off a long extract.
+ *
+ * Throws `RestoreBundleError("restore-bundle/no-bundle")` when
+ * `bundleDir` is missing, and
+ * `RestoreBundleError("restore-bundle/missing-manifest")` when the
+ * directory exists but has no `manifest.json` (the bundle is
+ * incomplete or not a blamejs bundle).
+ *
+ * @opts
+ *   bundleDir: string,   // bundle directory (required, must exist)
+ *
+ * @example
+ *   try {
+ *     var manifest = b.restoreBundle.inspect({
+ *       bundleDir: "/srv/backups/2026-04-27.bundle",
+ *     });
+ *     manifest.files.length;    // → 12
+ *     typeof manifest.signature; // → "string"
+ *   } catch (e) {
+ *     e.code; // → "restore-bundle/missing-manifest"
+ *   }
+ */
 function inspect(opts) {
   opts = opts || {};
   if (typeof opts.bundleDir !== "string" || !fs.existsSync(opts.bundleDir)) {

package/lib/restore-rollback.js

@@ -1,56 +1,45 @@
 "use strict";
 /**
- * restore-rollback — atomic dataDir swap with a versioned rollback path.
+ * @module b.restoreRollback
+ * @nav    Other
+ * @title  Restore Rollback
  *
- * The primitive used by lib/restore to put a freshly-decrypted bundle
- * into place. Filesystem-level directory rename is atomic on POSIX
- * (and on Windows when nothing has the dir open) — the swap either
- * fully completes or the previous dataDir is recoverable.
+ * @intro
+ *   Backup-restore safety net — atomic dataDir swap with a versioned
+ *   rollback path. The primitive `b.restore` calls to put a
+ *   freshly-decrypted bundle into place: filesystem rename is atomic
+ *   on POSIX (and on Windows when nothing has the dir open), so the
+ *   swap either fully completes or the previous `dataDir` is
+ *   recoverable through `rollback`.
  *
- *   var rb = b.restoreRollback;
+ *   Three steps frame every restore: pre-restore snapshot (the
+ *   existing `dataDir` is renamed into `<root>/<timestamp>/` before
+ *   the new bundle moves in), post-restore verify (operator runs
+ *   integrity / audit-chain checks against the live framework), and
+ *   rollback on failure (a single `rollback({ rollbackPath })` call
+ *   reverses the swap). A marker JSON file carries operator-supplied
+ *   metadata (`bundleId`, `reason`, timestamps) so `list` and `purge`
+ *   are informative without rifling through directory contents.
  *
- *   var r = rb.swap({
- *     stagingDir:    "./data.staging",
- *     dataDir:       "./data",
- *     rollbackRoot:  "./data.rollbacks",      // optional; defaults to <dataDir>.rollbacks
- *     marker:        { bundleId: "...", reason: "scheduled-restore" },
- *   });
- *   // → { rollbackPath, markerPath, swappedAt }
- *
- *   // Reverse the most recent swap (or a specific one by path)
- *   await rb.rollback({ dataDir: "./data", rollbackPath: r.rollbackPath });
- *   // → { restoredFrom, discardedAt }
- *
- *   rb.list({ rollbackRoot: "./data.rollbacks" });
- *   // → [{ rollbackPath, swappedAt, marker }] (newest first)
- *
- *   rb.purge({ rollbackRoot: "./data.rollbacks", keep: 3 });
- *   // → { kept, deleted: [paths] }
+ *   Layout after a successful swap:
  *
- * Layout after a successful swap:
+ *       ./data                         <- freshly-restored bundle
+ *       ./data.rollbacks/
+ *         2026-04-27T17-46-36-075Z/    <- previous dataDir
+ *         2026-04-27T17-46-36-075Z.marker.json
  *
- *   ./data                         ← the freshly-restored bundle
- *   ./data.rollbacks/
- *     2026-04-27T17-46-36-075Z/    ← previous dataDir, renamed atomically
- *       (whatever was in dataDir at the time of swap)
- *     2026-04-27T17-46-36-075Z.marker.json
+ *   Stop-framework-first contract: this primitive does NOT close the
+ *   framework's open file handles. On Linux a directory rename
+ *   succeeds with handles open, but the running process keeps reading
+ *   stale data. Operators run restore as `stop framework -> swap ->
+ *   start framework`, same shape as a database restore. Concurrency
+ *   guard: `swap` refuses if another rollback for the same
+ *   millisecond timestamp already exists — collisions are
+ *   vanishingly rare but the check keeps a double-fire from
+ *   corrupting state.
  *
- * The marker file carries operator-supplied metadata (which bundle
- * triggered the swap, what reason was given, when) so a list / audit
- * over rollback dirs is informative without rifling through their
- * contents.
- *
- * Concurrency: swap() refuses to operate if another rollback dir for
- * the same timestamp already exists — collisions are vanishingly rare
- * because the timestamp has millisecond precision plus the framework
- * never runs two restores in parallel on the same dataDir, but the
- * check makes a corrupted state impossible if an operator fires twice.
- *
- * Operator stop-framework-first contract: this primitive does NOT
- * close the framework's open file handles. On Linux a directory
- * rename succeeds even with handles open, but the running framework
- * process will see stale data. Operators run restore as: stop
- * framework → swap → start framework. Same as a database restore.
+ * @card
+ *   Backup-restore safety net — atomic dataDir swap with a versioned rollback path.
  */
 
 var fs = require("fs");
@@ -76,6 +65,33 @@ function _resolveRollbackRoot(opts) {
 }
 
 
+/**
+ * @primitive  b.restoreRollback.swap
+ * @signature  b.restoreRollback.swap(opts)
+ * @since      0.1.89
+ * @status     stable
+ * @related    b.restoreRollback.rollback, b.restoreRollback.list, b.restore.applyBundle
+ *
+ * Pre-restore snapshot + atomic swap. Renames the existing `dataDir`
+ * into `<rollbackRoot>/<timestamp>/`, then renames `stagingDir` into
+ * `dataDir`. If step two fails, step one is undone so the operator's
+ * dataDir is intact. Writes a `<timestamp>.marker.json` carrying
+ * operator metadata for later `list` / `rollback` discovery.
+ *
+ * @opts
+ *   stagingDir:   string,                         // pre-decrypted bundle, must exist
+ *   dataDir:      string,                         // live data dir to replace
+ *   rollbackRoot: string,                         // optional; defaults to "<dataDir>.rollbacks"
+ *   marker:       object,                         // operator metadata for the marker file
+ *
+ * @example
+ *   var r = b.restoreRollback.swap({
+ *     stagingDir: "./data.staging",
+ *     dataDir:    "./data",
+ *     marker:     { bundleId: "bk-2026-05-09", reason: "scheduled-restore" },
+ *   });
+ *   // → { rollbackPath: "./data.rollbacks/2026-05-09T...", markerPath, swappedAt, marker }
+ */
 function swap(opts) {
   opts = opts || {};
   if (typeof opts.stagingDir !== "string" || !fs.existsSync(opts.stagingDir)) {
@@ -143,6 +159,34 @@ function swap(opts) {
   };
 }
 
+/**
+ * @primitive  b.restoreRollback.rollback
+ * @signature  b.restoreRollback.rollback(opts)
+ * @since      0.1.89
+ * @status     stable
+ * @related    b.restoreRollback.swap, b.restoreRollback.list
+ *
+ * Reverse a prior swap. Moves the current `dataDir` aside as
+ * `discarded-<timestamp>/` (so the rename target is empty), then
+ * renames the named `rollbackPath` back into `dataDir`. The marker
+ * JSON is removed best-effort. Operator must have stopped the
+ * framework first — open file handles on the live dataDir on Windows
+ * cause the rename to fail.
+ *
+ * @opts
+ *   dataDir:      string,                         // live dataDir to replace
+ *   rollbackPath: string,                         // must exist; from swap() return
+ *   rollbackRoot: string,                         // optional; defaults to "<dataDir>.rollbacks"
+ *
+ * @example
+ *   var r = b.restoreRollback.swap({
+ *     stagingDir: "./data.staging", dataDir: "./data",
+ *     marker: { reason: "test" },
+ *   });
+ *   // post-restore verify failed:
+ *   await b.restoreRollback.rollback({ dataDir: "./data", rollbackPath: r.rollbackPath });
+ *   // → { restoredFrom: "./data.rollbacks/2026-05-09T...", discardedAt: "..." }
+ */
 async function rollback(opts) {
   opts = opts || {};
   if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
@@ -188,6 +232,29 @@ async function rollback(opts) {
   };
 }
 
+/**
+ * @primitive  b.restoreRollback.list
+ * @signature  b.restoreRollback.list(opts)
+ * @since      0.1.89
+ * @status     stable
+ * @related    b.restoreRollback.swap, b.restoreRollback.purge
+ *
+ * Enumerate available rollback points, newest first. Reads each
+ * marker file (capped at 64 KiB via `b.safeJson` to bound a
+ * tampered-marker DoS). Skips `discarded-*` directories — those are
+ * sweep-only and never restore points.
+ *
+ * @opts
+ *   dataDir:      string,                         // optional, used to derive rollbackRoot
+ *   rollbackRoot: string,                         // optional; defaults to "<dataDir>.rollbacks"
+ *
+ * @example
+ *   var points = b.restoreRollback.list({ dataDir: "./data" });
+ *   points.forEach(function (p) {
+ *     console.log(p.swappedAt, p.marker && p.marker.operator);
+ *   });
+ *   // → [{ rollbackPath, swappedAt, marker }, ...]
+ */
 function list(opts) {
   opts = opts || {};
   var rollbackRoot = _resolveRollbackRoot(opts);
@@ -218,6 +285,30 @@ function list(opts) {
   return out;
 }
 
+/**
+ * @primitive  b.restoreRollback.purge
+ * @signature  b.restoreRollback.purge(opts)
+ * @since      0.1.89
+ * @status     stable
+ * @related    b.restoreRollback.list, b.restoreRollback.swap
+ *
+ * Sweep stale rollback directories. Always removes every directory
+ * named `discarded-<timestamp>` (those are never restore points),
+ * then keeps the newest `keep` rollback points and removes the rest
+ * along with their marker files. `opts.keep` defaults to 0; pass a
+ * positive integer to retain a sliding window. Best-effort: a
+ * per-path unlink failure is logged via the deleted-list omission
+ * rather than thrown.
+ *
+ * @opts
+ *   dataDir:      string,
+ *   rollbackRoot: string,
+ *   keep:         number,                         // non-negative integer, default 0
+ *
+ * @example
+ *   var r = b.restoreRollback.purge({ dataDir: "./data", keep: 3 });
+ *   // → { kept: 3, deleted: ["./data.rollbacks/2026-04-...", ...] }
+ */
 function purge(opts) {
   opts = opts || {};
   nb.requireNonNegativeFiniteIntIfPresent(opts.keep,