@blamejs/core 0.4.1

package/lib/restore-rollback.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * restore-rollback — atomic dataDir swap with a versioned rollback path.
+ *
+ * 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.
+ *
+ *   var rb = b.restoreRollback;
+ *
+ *   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:
+ *
+ *   ./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
+ *
+ * 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.
+ */
+
+var fs = require("fs");
+var path = require("path");
+var atomicFile = require("./atomic-file");
+var { defineClass } = require("./framework-error");
+
+var RestoreRollbackError = defineClass("RestoreRollbackError", { alwaysPermanent: true });
+
+function _resolveRollbackRoot(opts) {
+  if (typeof opts.rollbackRoot === "string" && opts.rollbackRoot.length > 0) {
+    return opts.rollbackRoot;
+  }
+  // Default: sibling of dataDir named <dataDir>.rollbacks
+  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw new RestoreRollbackError("restore-rollback/no-rollback-root",
+      "rollbackRoot must be supplied or derivable from opts.dataDir");
+  }
+  return opts.dataDir + ".rollbacks";
+}
+
+
+function swap(opts) {
+  opts = opts || {};
+  if (typeof opts.stagingDir !== "string" || !fs.existsSync(opts.stagingDir)) {
+    throw new RestoreRollbackError("restore-rollback/no-staging",
+      "swap: opts.stagingDir is required and must exist");
+  }
+  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw new RestoreRollbackError("restore-rollback/no-datadir",
+      "swap: opts.dataDir is required");
+  }
+  var rollbackRoot = _resolveRollbackRoot(opts);
+  atomicFile.ensureDir(rollbackRoot);
+
+  var swappedAt = atomicFile.pathTimestamp();
+  var rollbackPath = path.join(rollbackRoot, swappedAt);
+  var markerPath = path.join(rollbackRoot, swappedAt + ".marker.json");
+
+  if (fs.existsSync(rollbackPath) || fs.existsSync(markerPath)) {
+    throw new RestoreRollbackError("restore-rollback/collision",
+      "swap: a rollback at " + rollbackPath + " already exists — refusing to overwrite");
+  }
+
+  var hadDataDir = fs.existsSync(opts.dataDir);
+
+  // Step 1: rename current dataDir → rollback path. Skipped on first
+  // restore (no existing dataDir).
+  if (hadDataDir) {
+    try { fs.renameSync(opts.dataDir, rollbackPath); }
+    catch (e) {
+      throw new RestoreRollbackError("restore-rollback/rename-existing-failed",
+        "swap: could not move existing dataDir to rollback: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  // Step 2: rename staging → dataDir
+  try { fs.renameSync(opts.stagingDir, opts.dataDir); }
+  catch (e) {
+    // Step 2 failed — try to undo step 1 so the operator's dataDir is back
+    if (hadDataDir) {
+      try { fs.renameSync(rollbackPath, opts.dataDir); }
+      catch (_e) { /* dataDir is now in rollbackPath; operator must recover manually */ }
+    }
+    throw new RestoreRollbackError("restore-rollback/rename-staging-failed",
+      "swap: could not move staging to dataDir: " + ((e && e.message) || String(e)) +
+      (hadDataDir ? " (attempted to undo previous rename — verify dataDir state)" : ""));
+  }
+
+  // Step 3: write the marker (best-effort; missing marker is recoverable
+  // from the rollback dir's mtime, but operators want it for audit)
+  var marker = {
+    swappedAt:    new Date().toISOString(),
+    rollbackPath: rollbackPath,
+    dataDir:      opts.dataDir,
+    operator:     opts.marker || null,
+  };
+  try {
+    fs.writeFileSync(markerPath, JSON.stringify(marker, null, 2) + "\n", { mode: 0o600 });
+  } catch (_e) { /* marker write is best-effort */ }
+
+  return {
+    rollbackPath: hadDataDir ? rollbackPath : null,
+    markerPath:   markerPath,
+    swappedAt:    swappedAt,
+    marker:       marker,
+  };
+}
+
+async function rollback(opts) {
+  opts = opts || {};
+  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw new RestoreRollbackError("restore-rollback/no-datadir",
+      "rollback: opts.dataDir is required");
+  }
+  if (typeof opts.rollbackPath !== "string" || !fs.existsSync(opts.rollbackPath)) {
+    throw new RestoreRollbackError("restore-rollback/no-rollback",
+      "rollback: opts.rollbackPath is required and must exist");
+  }
+
+  // Move the current dataDir aside (so the rollback's rename target is empty)
+  var discardedAt = null;
+  if (fs.existsSync(opts.dataDir)) {
+    var rollbackRoot = _resolveRollbackRoot(opts);
+    atomicFile.ensureDir(rollbackRoot);
+    discardedAt = atomicFile.pathTimestamp();
+    var discardedPath = path.join(rollbackRoot, "discarded-" + discardedAt);
+    try { fs.renameSync(opts.dataDir, discardedPath); }
+    catch (e) {
+      throw new RestoreRollbackError("restore-rollback/rename-existing-failed",
+        "rollback: could not move current dataDir aside: " + ((e && e.message) || String(e)));
+    }
+    discardedAt = discardedPath;
+  }
+
+  // Rename the rollback dir back into dataDir's place
+  try { fs.renameSync(opts.rollbackPath, opts.dataDir); }
+  catch (e) {
+    throw new RestoreRollbackError("restore-rollback/rollback-rename-failed",
+      "rollback: could not move rollback into dataDir: " + ((e && e.message) || String(e)) +
+      " (current dataDir, if any, was moved to " + discardedAt + ")");
+  }
+
+  // Best-effort: clean up the marker file alongside the rollback path
+  var markerPath = opts.rollbackPath + ".marker.json";
+  try { if (fs.existsSync(markerPath)) fs.unlinkSync(markerPath); }
+  catch (_e) { /* marker cleanup is best-effort */ }
+
+  return {
+    restoredFrom: opts.rollbackPath,
+    discardedAt:  discardedAt,
+  };
+}
+
+function list(opts) {
+  opts = opts || {};
+  var rollbackRoot = _resolveRollbackRoot(opts);
+  if (!fs.existsSync(rollbackRoot)) return [];
+  var entries = fs.readdirSync(rollbackRoot, { withFileTypes: true });
+  var out = [];
+  for (var i = 0; i < entries.length; i++) {
+    if (!entries[i].isDirectory()) continue;
+    var name = entries[i].name;
+    if (name.indexOf("discarded-") === 0) continue; // discarded dirs aren't restore points
+    var p = path.join(rollbackRoot, name);
+    var markerPath = p + ".marker.json";
+    var marker = null;
+    if (fs.existsSync(markerPath)) {
+      try { marker = JSON.parse(fs.readFileSync(markerPath, "utf8")); }
+      catch (_e) { marker = null; }
+    }
+    var stat;
+    try { stat = fs.statSync(p); } catch (_e) { continue; }
+    out.push({
+      rollbackPath: p,
+      swappedAt:    (marker && marker.swappedAt) || stat.mtime.toISOString(),
+      marker:       marker,
+    });
+  }
+  // Newest first
+  out.sort(function (a, b) { return a.swappedAt < b.swappedAt ? 1 : -1; });
+  return out;
+}
+
+function purge(opts) {
+  opts = opts || {};
+  var keep = typeof opts.keep === "number" && opts.keep >= 0 ? Math.floor(opts.keep) : 0;
+  var rollbackRoot = _resolveRollbackRoot(opts);
+  if (!fs.existsSync(rollbackRoot)) return { kept: keep, deleted: [] };
+  // Always sweep "discarded-*" dirs — they're never restore points
+  var entries = fs.readdirSync(rollbackRoot, { withFileTypes: true });
+  var deleted = [];
+  for (var i = 0; i < entries.length; i++) {
+    if (entries[i].isDirectory() && entries[i].name.indexOf("discarded-") === 0) {
+      var p = path.join(rollbackRoot, entries[i].name);
+      try { fs.rmSync(p, { recursive: true, force: true }); deleted.push(p); }
+      catch (_e) { /* best-effort */ }
+    }
+  }
+
+  // Keep newest `keep`, delete the rest (and their marker files)
+  var rb = list(opts);
+  var toDelete = rb.slice(keep);
+  for (var j = 0; j < toDelete.length; j++) {
+    var rbPath = toDelete[j].rollbackPath;
+    var mkPath = rbPath + ".marker.json";
+    try { fs.rmSync(rbPath, { recursive: true, force: true }); deleted.push(rbPath); }
+    catch (_e) { /* best-effort */ }
+    try { if (fs.existsSync(mkPath)) fs.unlinkSync(mkPath); }
+    catch (_e) { /* best-effort */ }
+  }
+  return { kept: keep, deleted: deleted };
+}
+
+module.exports = {
+  swap:                  swap,
+  rollback:              rollback,
+  list:                  list,
+  purge:                  purge,
+  RestoreRollbackError:  RestoreRollbackError,
+};

package/lib/restore.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * restore — operator-facing restore from a backup bundle in storage.
+ *
+ * Mirror of lib/backup. Pulls a bundle from a storage backend,
+ * decrypts it via lib/restore-bundle into a staging directory, then
+ * swaps that staging into place as the new dataDir via
+ * lib/restore-rollback (saving the previous dataDir as a versioned
+ * rollback point). Operators stop the framework first, run restore,
+ * then start the framework — same workflow as a database restore.
+ *
+ *   var restore = b.restore.create({
+ *     dataDir:      "./data",
+ *     storage:      b.backup.localStorage({ root: "./backups" }),
+ *     passphrase:   Buffer.from("operator backup passphrase"),
+ *     rollbackRoot: "./data.rollbacks",   // optional; default <dataDir>.rollbacks
+ *     audit:        true,
+ *   });
+ *
+ *   await restore.list();                 // → [{ bundleId, createdAt, size }]
+ *   await restore.inspect(bundleId);      // → manifest (no decrypt; no passphrase
+ *                                            //  needed for inspect)
+ *
+ *   await restore.run({
+ *     bundleId,
+ *     filter,                              // optional file filter
+ *     marker: { reason: "incident-2026-04-27" },
+ *   });
+ *   // → { bundleId, fileCount, totalBytes, rollbackPath, vaultKeyJson,
+ *   //     durationMs }
+ *
+ *   await restore.rollback();              // → reverts the most recent restore
+ *   await restore.listRollbacks();         // → [{ rollbackPath, swappedAt, marker }]
+ *   await restore.purgeRollbacks({ keep });
+ *
+ * vaultKeyJson: the manifest's vaultKeyEnc decrypted via the passphrase,
+ * returned to the caller as a string. Returned but NOT auto-installed —
+ * the caller decides what to do with it (the swap may have already put
+ * the bundle's vault.key file into place if the bundle included one;
+ * operators with vault-passphrase-wrapped setups handle the placement
+ * themselves before re-starting the framework).
+ *
+ * Failure modes (each cleans up the tmp pull dir + staging dir):
+ *   - bundle not in storage → restore/bundle-not-found
+ *   - manifest absent / bad → restore/missing-manifest
+ *   - wrong passphrase → restore/decrypt-failed
+ *   - tampered blob → restore/decrypt-failed (AEAD tag check)
+ *   - checksum mismatch → restore/checksum-mismatch
+ *   - swap fails after extract → restore/swap-failed (staging is
+ *     preserved at the path returned in error.stagingDir for operator
+ *     manual recovery)
+ */
+
+var fs = require("fs");
+var nodeCrypto = require("node:crypto");
+var os = require("os");
+var path = require("path");
+var restoreBundle = require("./restore-bundle");
+var restoreRollback = require("./restore-rollback");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var audit = lazyRequire(function () { return require("./audit"); });
+var { FrameworkError } = require("./framework-error");
+
+class RestoreError extends FrameworkError {
+  constructor(code, message, permanent) {
+    super(message, code);
+    this.name = "RestoreError";
+    this.permanent = !!permanent;
+    this.isRestoreError = true;
+  }
+}
+
+function _validateStorage(storage) {
+  if (!storage || typeof storage !== "object") {
+    throw new RestoreError("restore/bad-storage",
+      "storage backend is required (use b.backup.localStorage or pass a custom one)");
+  }
+  var required = ["readBundle", "listBundles", "hasBundle"];
+  for (var i = 0; i < required.length; i++) {
+    if (typeof storage[required[i]] !== "function") {
+      throw new RestoreError("restore/bad-storage",
+        "storage backend missing method '" + required[i] + "'");
+    }
+  }
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "dataDir", "storage", "passphrase", "rollbackRoot", "audit",
+  ], "restore");
+  if (typeof opts.dataDir !== "string" || opts.dataDir.length === 0) {
+    throw new RestoreError("restore/no-datadir",
+      "create: opts.dataDir is required");
+  }
+  _validateStorage(opts.storage);
+  if (!Buffer.isBuffer(opts.passphrase) && typeof opts.passphrase !== "string") {
+    throw new RestoreError("restore/no-passphrase",
+      "create: opts.passphrase is required (Buffer or string)");
+  }
+
+  var dataDir = opts.dataDir;
+  var storage = opts.storage;
+  var passphrase = opts.passphrase;
+  var rollbackRoot = opts.rollbackRoot || (dataDir + ".rollbacks");
+  var auditOn = opts.audit !== false;
+
+  function _emitAudit(action, info, outcome) {
+    if (!auditOn) return;
+    audit().safeEmit({
+      action:   action,
+      outcome:  outcome,
+      metadata: info || {},
+      reason:   info && info.reason ? info.reason : null,
+    });
+  }
+
+  async function list() { return await storage.listBundles(); }
+
+  async function inspect(bundleId) {
+    if (typeof bundleId !== "string" || bundleId.length === 0) {
+      throw new RestoreError("restore/bad-bundle-id", "inspect: bundleId is required");
+    }
+    var has = await storage.hasBundle(bundleId);
+    if (!has) {
+      throw new RestoreError("restore/bundle-not-found",
+        "inspect: bundle '" + bundleId + "' not in storage");
+    }
+    var pullDir = path.join(os.tmpdir(),
+      "blamejs-restore-inspect-" + nodeCrypto.randomBytes(4).toString("hex"));
+    try {
+      await storage.readBundle(bundleId, pullDir);
+      return restoreBundle.inspect({ bundleDir: pullDir });
+    } finally {
+      try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) {}
+    }
+  }
+
+  async function run(runOpts) {
+    runOpts = runOpts || {};
+    var t0 = Date.now();
+    var bundleId = runOpts.bundleId;
+    if (typeof bundleId !== "string" || bundleId.length === 0) {
+      throw new RestoreError("restore/bad-bundle-id", "run: opts.bundleId is required");
+    }
+    var has = await storage.hasBundle(bundleId);
+    if (!has) {
+      throw new RestoreError("restore/bundle-not-found",
+        "run: bundle '" + bundleId + "' not in storage");
+    }
+
+    var pullId = nodeCrypto.randomBytes(4).toString("hex");
+    var pullDir    = path.join(os.tmpdir(), "blamejs-restore-pull-"    + pullId);
+    var stagingDir = path.join(os.tmpdir(), "blamejs-restore-staging-" + pullId);
+
+    function _cleanupTmp() {
+      try { fs.rmSync(pullDir,    { recursive: true, force: true }); } catch (_e) {}
+      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) {}
+    }
+
+    // 1. Pull bundle out of storage
+    try {
+      await storage.readBundle(bundleId, pullDir);
+    } catch (e) {
+      _cleanupTmp();
+      _emitAudit("restore.failure",
+        { bundleId: bundleId, reason: "storage.readBundle: " + ((e && e.message) || String(e)) },
+        "failure");
+      throw new RestoreError("restore/storage-read-failed",
+        "pulling bundle from storage failed: " + ((e && e.message) || String(e)));
+    }
+
+    // 2. Decrypt + verify into stagingDir
+    var extracted;
+    try {
+      extracted = await restoreBundle.extract({
+        bundleDir:        pullDir,
+        stagingDir:       stagingDir,
+        passphrase:       passphrase,
+        filter:           runOpts.filter,
+        progressCallback: runOpts.progressCallback,
+      });
+    } catch (e) {
+      _cleanupTmp();
+      // Map restore-bundle error codes to restore/* domain so consumer
+      // code sees a single error namespace
+      var code = e && e.code;
+      var mappedCode = "restore/extract-failed";
+      if (code === "restore-bundle/decrypt-failed")     mappedCode = "restore/decrypt-failed";
+      else if (code === "restore-bundle/checksum-mismatch") mappedCode = "restore/checksum-mismatch";
+      else if (code === "restore-bundle/missing-manifest")  mappedCode = "restore/missing-manifest";
+      else if (code === "restore-bundle/missing-blob")      mappedCode = "restore/missing-blob";
+      else if (code === "restore-bundle/size-mismatch")     mappedCode = "restore/size-mismatch";
+      _emitAudit("restore.failure",
+        { bundleId: bundleId, reason: (e && e.message) || String(e) }, "failure");
+      throw new RestoreError(mappedCode,
+        "extract failed: " + ((e && e.message) || String(e)));
+    }
+
+    // 3. Atomic swap. On swap failure, the stagingDir is preserved so
+    // an operator can recover manually — we do NOT delete it here.
+    var swapResult;
+    try {
+      swapResult = restoreRollback.swap({
+        stagingDir:    stagingDir,
+        dataDir:       dataDir,
+        rollbackRoot:  rollbackRoot,
+        marker:        Object.assign({ bundleId: bundleId }, runOpts.marker || {}),
+      });
+    } catch (e) {
+      // Pull dir is safe to clean (the source bundle is in storage);
+      // staging stays for manual recovery.
+      try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) {}
+      _emitAudit("restore.failure",
+        { bundleId: bundleId, reason: "swap: " + ((e && e.message) || String(e)) },
+        "failure");
+      var err = new RestoreError("restore/swap-failed",
+        "atomic swap failed after successful extract — staging preserved at " +
+        stagingDir + ": " + ((e && e.message) || String(e)));
+      err.stagingDir = stagingDir;
+      throw err;
+    }
+
+    // 4. Clean up the pull dir (source bundle still in storage)
+    try { fs.rmSync(pullDir, { recursive: true, force: true }); } catch (_e) {}
+
+    var summary = {
+      bundleId:     bundleId,
+      fileCount:    extracted.fileCount,
+      totalBytes:   extracted.totalBytes,
+      rollbackPath: swapResult.rollbackPath,
+      vaultKeyJson: extracted.vaultKeyJson,
+      durationMs:   Date.now() - t0,
+    };
+    _emitAudit("restore.success", {
+      bundleId:     bundleId,
+      fileCount:    extracted.fileCount,
+      totalBytes:   extracted.totalBytes,
+      rollbackPath: swapResult.rollbackPath,
+      durationMs:   summary.durationMs,
+    });
+    return summary;
+  }
+
+  async function rollback(rollbackOpts) {
+    rollbackOpts = rollbackOpts || {};
+    // Either an explicit rollbackPath OR pull the most-recent one
+    var target = rollbackOpts.rollbackPath;
+    if (!target) {
+      var bundles = restoreRollback.list({ rollbackRoot: rollbackRoot });
+      if (bundles.length === 0) {
+        throw new RestoreError("restore/no-rollbacks",
+          "rollback: no rollback points found at " + rollbackRoot);
+      }
+      target = bundles[0].rollbackPath;
+    }
+    var r;
+    try {
+      r = await restoreRollback.rollback({
+        dataDir:      dataDir,
+        rollbackPath: target,
+        rollbackRoot: rollbackRoot,
+      });
+    } catch (e) {
+      _emitAudit("restore.rollback.failure",
+        { rollbackPath: target, reason: (e && e.message) || String(e) }, "failure");
+      throw new RestoreError("restore/rollback-failed",
+        "rollback failed: " + ((e && e.message) || String(e)));
+    }
+    _emitAudit("restore.rollback.success",
+      { rollbackPath: target, discardedAt: r.discardedAt });
+    return r;
+  }
+
+  function listRollbacks() {
+    return restoreRollback.list({ rollbackRoot: rollbackRoot });
+  }
+  function purgeRollbacks(purgeOpts) {
+    return restoreRollback.purge({
+      rollbackRoot: rollbackRoot,
+      keep:         (purgeOpts && purgeOpts.keep) || 0,
+    });
+  }
+
+  return {
+    list:           list,
+    inspect:        inspect,
+    run:            run,
+    rollback:       rollback,
+    listRollbacks:  listRollbacks,
+    purgeRollbacks: purgeRollbacks,
+    storage:        storage,
+    rollbackRoot:   rollbackRoot,
+  };
+}
+
+module.exports = {
+  create:        create,
+  RestoreError:  RestoreError,
+};