@blamejs/core 0.4.1

package/lib/backup/crypto.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * backup-crypto — passphrase-based symmetric crypto for backup files.
+ *
+ * The primitive layer used by lib/backup.js and the backup/restore
+ * workers. Argon2id key derivation + XChaCha20-Poly1305 AEAD. Salt is
+ * managed alongside the ciphertext so backups carry their KDF input
+ * with them — restoring a backup needs the bundle's salt + the
+ * operator passphrase, nothing else.
+ *
+ *   var bc = b.backupCrypto;
+ *
+ *   bc.ARGON2_OPTS                      // baseline KDF parameters
+ *
+ *   await bc.deriveKey(passphrase, saltHex)
+ *     → Buffer(32)                      // raw key bytes for AEAD
+ *
+ *   await bc.encryptWithPassphrase(plain, passphrase, saltHex)
+ *     → Buffer (24-byte nonce + ciphertext+tag)
+ *   await bc.decryptWithPassphrase(buf, passphrase, saltHex)
+ *     → Buffer (plaintext)
+ *
+ *   await bc.encryptWithFreshSalt(plain, passphrase)
+ *     → { encrypted: Buffer, salt: hexString }
+ *
+ *   bc.checksum(buf)                    // sha3-512 hex; bundle integrity
+ *
+ * Argon2id parameters match lib/vault-wrap defaults — backup integrity
+ * tracks the framework's at-rest discipline. Operators with stricter
+ * requirements (longer passphrases, higher memoryCost) bypass these
+ * defaults by passing a full Argon2 opts object to deriveKey.
+ *
+ * Algorithm choices are deliberate and locked:
+ *   - KDF:  Argon2id (RFC 9106) — memory-hard, the only KDF the
+ *           framework uses for password-derived keys
+ *   - AEAD: XChaCha20-Poly1305 — 24-byte random nonce per message
+ *           means we never need to track per-passphrase nonce counters
+ *
+ * Operators with non-standard cipher needs build their own primitive;
+ * this one's whole point is "do the framework's PQC-aligned crypto
+ * correctly without per-call decisions".
+ */
+
+var nodeCrypto = require("node:crypto");
+var { xchacha20poly1305 } = require("../vendor/noble-ciphers.cjs");
+var argon2 = require("../vendor/argon2");
+var { FrameworkError } = require("../framework-error");
+
+class BackupCryptoError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "BackupCryptoError";
+    this.permanent = true;
+    this.isBackupCryptoError = true;
+  }
+}
+
+// Baseline Argon2id parameters. Identical to vault-wrap's defaults so
+// operators see one set of numbers across the framework's password-
+// derivation surfaces. Tuned for: ~64 MiB memory, 3 passes, 4 lanes,
+// 32-byte raw output (matches XChaCha20-Poly1305 key length).
+var ARGON2_OPTS = Object.freeze({
+  type:        2,        // 2 = argon2id
+  memoryCost:  65536,    // 64 MiB
+  timeCost:    3,
+  parallelism: 4,
+  hashLength:  32,
+  raw:         true,
+});
+
+var SALT_BYTES  = 32;    // 256 bits — comfortable margin for global uniqueness
+var NONCE_BYTES = 24;    // XChaCha20 nonce length
+
+function checksum(buf) {
+  if (!Buffer.isBuffer(buf) && typeof buf !== "string") {
+    throw new BackupCryptoError("backup-crypto/bad-input",
+      "checksum: argument must be a Buffer or string");
+  }
+  return nodeCrypto.createHash("sha3-512").update(buf).digest("hex");
+}
+
+function _validateSaltHex(saltHex) {
+  if (typeof saltHex !== "string" || !/^[0-9a-fA-F]+$/.test(saltHex) || saltHex.length % 2 !== 0) {
+    throw new BackupCryptoError("backup-crypto/bad-salt",
+      "saltHex must be a non-empty hex string with even length");
+  }
+}
+
+function _validatePassphrase(p) {
+  if (!Buffer.isBuffer(p) && typeof p !== "string") {
+    throw new BackupCryptoError("backup-crypto/bad-passphrase",
+      "passphrase must be a Buffer or string");
+  }
+  if (Buffer.isBuffer(p) ? p.length === 0 : p.length === 0) {
+    throw new BackupCryptoError("backup-crypto/bad-passphrase",
+      "passphrase must be non-empty");
+  }
+}
+
+async function deriveKey(passphrase, saltHex, opts) {
+  _validatePassphrase(passphrase);
+  _validateSaltHex(saltHex);
+  var argonOpts = Object.assign({}, ARGON2_OPTS, opts || {}, {
+    salt: Buffer.from(saltHex, "hex"),
+  });
+  var hash = await argon2.hash(passphrase, argonOpts);
+  // Argon2 raw mode returns a Buffer of hashLength bytes. Defensive
+  // length check — better to fail loudly than ship a short key into
+  // XChaCha20 and trip a later cryptic error.
+  if (!Buffer.isBuffer(hash) || hash.length !== ARGON2_OPTS.hashLength) {
+    throw new BackupCryptoError("backup-crypto/derive-failed",
+      "argon2 hash returned unexpected output (expected " + ARGON2_OPTS.hashLength +
+      "-byte Buffer, got " + (hash && hash.length) + ")");
+  }
+  return hash;
+}
+
+async function encryptWithPassphrase(plaintext, passphrase, saltHex) {
+  if (!Buffer.isBuffer(plaintext) && typeof plaintext !== "string") {
+    throw new BackupCryptoError("backup-crypto/bad-plaintext",
+      "encryptWithPassphrase: plaintext must be a Buffer or string");
+  }
+  var plainBuf = Buffer.isBuffer(plaintext) ? plaintext : Buffer.from(plaintext, "utf8");
+  var key = await deriveKey(passphrase, saltHex);
+  var nonce = nodeCrypto.randomBytes(NONCE_BYTES);
+  var ct = xchacha20poly1305(new Uint8Array(key), nonce).encrypt(new Uint8Array(plainBuf));
+  return Buffer.concat([nonce, Buffer.from(ct)]);
+}
+
+async function decryptWithPassphrase(encrypted, passphrase, saltHex) {
+  if (!Buffer.isBuffer(encrypted)) {
+    throw new BackupCryptoError("backup-crypto/bad-input",
+      "decryptWithPassphrase: encrypted must be a Buffer");
+  }
+  if (encrypted.length <= NONCE_BYTES) {
+    throw new BackupCryptoError("backup-crypto/bad-input",
+      "decryptWithPassphrase: encrypted buffer is too short to contain nonce + tag");
+  }
+  var key = await deriveKey(passphrase, saltHex);
+  var nonce = encrypted.subarray(0, NONCE_BYTES);
+  var ct    = encrypted.subarray(NONCE_BYTES);
+  var plain;
+  try {
+    plain = xchacha20poly1305(new Uint8Array(key), new Uint8Array(nonce))
+      .decrypt(new Uint8Array(ct));
+  } catch (e) {
+    throw new BackupCryptoError("backup-crypto/decrypt-failed",
+      "XChaCha20-Poly1305 decryption failed (wrong passphrase or tampered ciphertext): " +
+      ((e && e.message) || String(e)));
+  }
+  return Buffer.from(plain);
+}
+
+// Convenience for the common "encrypt this with a fresh salt" pattern.
+// Returns the salt as hex so callers can store it alongside the
+// ciphertext in the bundle manifest.
+async function encryptWithFreshSalt(plaintext, passphrase) {
+  var salt = nodeCrypto.randomBytes(SALT_BYTES);
+  var saltHex = salt.toString("hex");
+  var encrypted = await encryptWithPassphrase(plaintext, passphrase, saltHex);
+  return { encrypted: encrypted, salt: saltHex };
+}
+
+module.exports = {
+  deriveKey:             deriveKey,
+  encryptWithPassphrase: encryptWithPassphrase,
+  decryptWithPassphrase: decryptWithPassphrase,
+  encryptWithFreshSalt:  encryptWithFreshSalt,
+  checksum:              checksum,
+  ARGON2_OPTS:           ARGON2_OPTS,
+  SALT_BYTES:            SALT_BYTES,
+  NONCE_BYTES:           NONCE_BYTES,
+  BackupCryptoError:     BackupCryptoError,
+};

package/lib/backup/index.js

@@ -0,0 +1,490 @@
+"use strict";
+/**
+ * backup — operator-facing backup orchestration.
+ *
+ * Wires lib/backup-bundle (encrypt + emit a bundle directory) to a
+ * pluggable storage backend, plus retention policy + audit emission.
+ * Ships with a local-filesystem backend (b.backup.localStorage); S3
+ * or any custom backend drops in through the same interface.
+ *
+ *   var backup = b.backup.create({
+ *     dataDir:      "./data",
+ *     storage:      b.backup.localStorage({ root: "./backups" }),
+ *     passphrase:   Buffer.from("operator backup passphrase"),
+ *     files: [
+ *       { relativePath: "db.enc",       kind: "raw",          required: true },
+ *       { relativePath: "db.key.enc",   kind: "raw",          required: true },
+ *       { relativePath: "vault.key",    kind: "raw",          required: false },
+ *       { relativePath: "ca.key.sealed",kind: "vault-sealed", required: false },
+ *     ],
+ *     vaultKeyJson: function () { return fs.readFileSync('./data/vault.key','utf8'); },
+ *     retention:    { keep: 7 },        // keep latest 7; older purged after run
+ *     audit:        true,
+ *     scheduler:    b.scheduler,        // optional; needed for backup.schedule()
+ *   });
+ *
+ *   await backup.run({ metadata: { reason: "daily" } });
+ *     // → { bundleId, bundleSize, fileCount, durationMs }
+ *   await backup.list();
+ *     // → [{ bundleId, createdAt, size, fileCount }]
+ *   await backup.delete(bundleId);
+ *   await backup.purgeOlder({ keep: 7 });
+ *   await backup.read(bundleId, destDir);  // pull a bundle back to disk
+ *                                            // (without decrypting — that's
+ *                                            //  restore-bundle's job)
+ *
+ *   backup.schedule({ cron: "0 2 * * *", timezone: "America/New_York" });
+ *     // returns a scheduler task name; wires through b.scheduler
+ *
+ * Storage backend contract:
+ *
+ *   {
+ *     async writeBundle(bundleId, sourceDir)  copy sourceDir contents under bundleId
+ *     async readBundle(bundleId, destDir)     copy bundle out to destDir
+ *     async listBundles()                     → [{ bundleId, createdAt, size }]
+ *     async deleteBundle(bundleId)
+ *     async hasBundle(bundleId)               → boolean
+ *   }
+ *
+ * vaultKeyJson can be either:
+ *   - A string (the operator already has the JSON in hand)
+ *   - A function returning a string (or async returning a string) — the
+ *     framework calls this each backup so a long-running app doesn't pin
+ *     the vault key in memory between runs
+ *
+ * Bundle IDs are filesystem-safe timestamps with millisecond precision
+ * plus a 4-byte random suffix: "2026-04-27T14-00-00-123Z-a8f30b21".
+ * Colons + dots in standard ISO-8601 are replaced with dashes so the
+ * id works as a directory name on every platform (Windows reserves ':'
+ * for drive letters). String sort still gives chronological order.
+ */
+
+var fs = require("fs");
+var nodeCrypto = require("node:crypto");
+var os = require("os");
+var path = require("path");
+var atomicFile = require("../atomic-file");
+var backupBundle = require("./bundle");
+var lazyRequire = require("../lazy-require");
+var audit = lazyRequire(function () { return require("../audit"); });
+var { defineClass } = require("../framework-error");
+
+var BackupError = defineClass("BackupError");
+
+// "2026-04-27T14-00-00-123Z-a8f30b21" — atomicFile.pathTimestamp() form
+// (ISO with ':'+'.' replaced by '-') plus a random suffix.
+var BUNDLE_ID_RE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[0-9a-f]{8}$/;
+
+function _isValidBundleId(s) {
+  return typeof s === "string" && BUNDLE_ID_RE.test(s);
+}
+
+function _generateBundleId() {
+  return atomicFile.pathTimestamp() + "-" + nodeCrypto.randomBytes(4).toString("hex");
+}
+
+function _dirSize(p) {
+  var total = 0;
+  var entries = fs.readdirSync(p, { withFileTypes: true });
+  for (var i = 0; i < entries.length; i++) {
+    var f = path.join(p, entries[i].name);
+    if (entries[i].isDirectory()) total += _dirSize(f);
+    else if (entries[i].isFile()) total += fs.statSync(f).size;
+  }
+  return total;
+}
+
+// ---- Local filesystem storage backend (the default) ----
+
+function localStorage(opts) {
+  opts = opts || {};
+  if (typeof opts.root !== "string" || opts.root.length === 0) {
+    throw new BackupError("backup/no-storage-root",
+      "localStorage: opts.root is required");
+  }
+  var root = opts.root;
+
+  function _bundlePath(bundleId) {
+    if (!_isValidBundleId(bundleId)) {
+      throw new BackupError("backup/bad-bundle-id",
+        "bundleId must match the framework's timestamp+suffix format");
+    }
+    return path.join(root, bundleId);
+  }
+
+  return {
+    name: "local",
+    async writeBundle(bundleId, sourceDir) {
+      atomicFile.ensureDir(root);
+      var dest = _bundlePath(bundleId);
+      if (fs.existsSync(dest)) {
+        throw new BackupError("backup/bundle-exists",
+          "writeBundle: bundle '" + bundleId + "' already exists in storage");
+      }
+      atomicFile.copyDirRecursive(sourceDir, dest);
+    },
+    async readBundle(bundleId, destDir) {
+      var src = _bundlePath(bundleId);
+      if (!fs.existsSync(src)) {
+        throw new BackupError("backup/bundle-not-found",
+          "readBundle: '" + bundleId + "' not in storage at " + root);
+      }
+      if (fs.existsSync(destDir)) {
+        throw new BackupError("backup/dest-exists",
+          "readBundle: destDir already exists: " + destDir);
+      }
+      atomicFile.copyDirRecursive(src, destDir);
+    },
+    async listBundles() {
+      if (!fs.existsSync(root)) return [];
+      var entries = fs.readdirSync(root, { withFileTypes: true });
+      var out = [];
+      for (var i = 0; i < entries.length; i++) {
+        if (!entries[i].isDirectory()) continue;
+        if (!_isValidBundleId(entries[i].name)) continue;
+        var p = path.join(root, entries[i].name);
+        var stat;
+        try { stat = fs.statSync(p); } catch (_e) { continue; }
+        var size;
+        try { size = _dirSize(p); } catch (_e) { size = 0; }
+        out.push({
+          bundleId:  entries[i].name,
+          createdAt: stat.mtime.toISOString(),
+          size:      size,
+        });
+      }
+      // Newest first
+      out.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
+      return out;
+    },
+    async deleteBundle(bundleId) {
+      var p = _bundlePath(bundleId);
+      if (!fs.existsSync(p)) return;
+      fs.rmSync(p, { recursive: true, force: true });
+    },
+    async hasBundle(bundleId) {
+      try { return fs.existsSync(_bundlePath(bundleId)); }
+      catch (_e) { return false; }
+    },
+  };
+}
+
+// ---- Engine ----
+
+function _validateStorage(storage) {
+  if (!storage || typeof storage !== "object") {
+    throw new BackupError("backup/bad-storage",
+      "storage backend is required (use b.backup.localStorage or pass a custom one)");
+  }
+  var required = ["writeBundle", "readBundle", "listBundles", "deleteBundle", "hasBundle"];
+  for (var i = 0; i < required.length; i++) {
+    if (typeof storage[required[i]] !== "function") {
+      throw new BackupError("backup/bad-storage",
+        "storage backend missing method '" + required[i] + "'");
+    }
+  }
+}
+
+async function _resolveVaultKeyJson(vaultKeyJsonOpt) {
+  if (typeof vaultKeyJsonOpt === "string") return vaultKeyJsonOpt;
+  if (typeof vaultKeyJsonOpt === "function") {
+    var r = vaultKeyJsonOpt();
+    if (r && typeof r.then === "function") r = await r;
+    if (typeof r !== "string" || r.length === 0) {
+      throw new BackupError("backup/bad-vault-key",
+        "vaultKeyJson function must return a non-empty string");
+    }
+    return r;
+  }
+  throw new BackupError("backup/no-vault-key-json",
+    "opts.vaultKeyJson is required (string or function returning a string)");
+}
+
+function create(opts) {
+  opts = opts || {};
+  if (typeof opts.dataDir !== "string" || !fs.existsSync(opts.dataDir)) {
+    throw new BackupError("backup/no-datadir",
+      "create: opts.dataDir is required and must exist");
+  }
+  _validateStorage(opts.storage);
+  if (!Buffer.isBuffer(opts.passphrase) && typeof opts.passphrase !== "string") {
+    throw new BackupError("backup/no-passphrase",
+      "create: opts.passphrase is required (Buffer or string)");
+  }
+  if (!Array.isArray(opts.files) || opts.files.length === 0) {
+    throw new BackupError("backup/no-files",
+      "create: opts.files must be a non-empty array of include entries");
+  }
+  if (opts.vaultKeyJson === undefined) {
+    throw new BackupError("backup/no-vault-key-json",
+      "create: opts.vaultKeyJson is required (string or function returning string)");
+  }
+
+  var dataDir = opts.dataDir;
+  var storage = opts.storage;
+  var passphrase = opts.passphrase;
+  var files = opts.files;
+  var vaultKeyJsonOpt = opts.vaultKeyJson;
+  var retention = opts.retention || null;
+  var auditOn = opts.audit !== false;
+  var scheduler = opts.scheduler || null;
+  // flushBeforeBackup — call db.flushToDisk() (or operator-supplied
+  // flush) before snapshotting so encrypted-at-rest dbs are current.
+  // In encrypted-at-rest mode the framework re-encrypts to disk every
+  // ~5 min; without a pre-flush a backup of db.enc could be that
+  // stale relative to the live tmpfs DB. Pass false to skip when the
+  // operator's calling backup against a process that doesn't own the
+  // DB (e.g. an out-of-band backup tool reading a paused replica).
+  var flushBeforeBackup = typeof opts.flushBeforeBackup === "function"
+    ? opts.flushBeforeBackup
+    : (opts.flushBeforeBackup === false ? null : null);
+  // Default: try b.db.flushToDisk if available. Wired this way so the
+  // backup primitive doesn't take a hard dependency on b.db (operators
+  // running backup against an external db handle still work).
+  if (flushBeforeBackup === null && opts.flushBeforeBackup !== false) {
+    try {
+      var dbModule = require("../db");
+      if (typeof dbModule.flushToDisk === "function") {
+        flushBeforeBackup = function () { dbModule.flushToDisk(); };
+      }
+    } catch (_e) { /* db not available; flush is a no-op */ }
+  }
+
+  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 run(runOpts) {
+    runOpts = runOpts || {};
+    var t0 = Date.now();
+    var bundleId = _generateBundleId();
+    var stagingDir = path.join(os.tmpdir(),
+      "blamejs-backup-staging-" + bundleId.replace(/[:.]/g, "-"));
+
+    // Flush the live DB to disk so the snapshot is current. Best-effort —
+    // a flush failure logs but doesn't fail the whole backup; the bundle
+    // will just snapshot whatever's on disk.
+    if (flushBeforeBackup) {
+      try { await flushBeforeBackup(); }
+      catch (e) {
+        _emitAudit("backup.flush.failure",
+          { bundleId: bundleId, reason: (e && e.message) || String(e) },
+          "warning");
+      }
+    }
+
+    var vaultKeyJson;
+    try {
+      vaultKeyJson = await _resolveVaultKeyJson(vaultKeyJsonOpt);
+    } catch (e) {
+      _emitAudit("backup.failure", { bundleId: bundleId, reason: e.message }, "failure");
+      throw e;
+    }
+
+    var bundleResult;
+    try {
+      bundleResult = await backupBundle.create({
+        dataDir:      dataDir,
+        outDir:       stagingDir,
+        passphrase:   passphrase,
+        vaultKeyJson: vaultKeyJson,
+        files:        files,
+        metadata:     Object.assign({ bundleId: bundleId }, runOpts.metadata || {}),
+        progressCallback: runOpts.progressCallback,
+      });
+    } catch (e) {
+      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) {}
+      _emitAudit("backup.failure",
+        { bundleId: bundleId, reason: (e && e.message) || String(e) }, "failure");
+      throw e;
+    }
+
+    try {
+      await storage.writeBundle(bundleId, stagingDir);
+    } catch (e) {
+      try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) {}
+      _emitAudit("backup.failure",
+        { bundleId: bundleId, reason: "storage.writeBundle: " + ((e && e.message) || String(e)) },
+        "failure");
+      throw new BackupError("backup/storage-write-failed",
+        "writing bundle to storage failed: " + ((e && e.message) || String(e)));
+    }
+
+    try { fs.rmSync(stagingDir, { recursive: true, force: true }); } catch (_e) { /* best-effort */ }
+
+    var summary = {
+      bundleId:   bundleId,
+      bundleSize: bundleResult.bundleSize,
+      fileCount:  bundleResult.fileCount,
+      durationMs: Date.now() - t0,
+      storage:    storage.name || "custom",
+    };
+    _emitAudit("backup.success", summary);
+
+    // Retention sweep — best-effort. A failure here logs but does NOT
+    // fail the run (the bundle is already safely written; pruning
+    // can be retried).
+    if (retention && typeof retention.keep === "number" && retention.keep > 0) {
+      try {
+        var purged = await purgeOlder({ keep: retention.keep });
+        summary.retentionPurged = purged.deleted;
+      } catch (e) {
+        _emitAudit("backup.retention.failure",
+          { bundleId: bundleId, reason: (e && e.message) || String(e) },
+          "warning");
+      }
+    }
+    return summary;
+  }
+
+  async function list() {
+    return await storage.listBundles();
+  }
+
+  async function deleteBundle(bundleId) {
+    if (!_isValidBundleId(bundleId)) {
+      throw new BackupError("backup/bad-bundle-id",
+        "bundleId must match the framework's timestamp+suffix format");
+    }
+    await storage.deleteBundle(bundleId);
+    _emitAudit("backup.deleted", { bundleId: bundleId });
+  }
+
+  async function read(bundleId, destDir) {
+    if (!_isValidBundleId(bundleId)) {
+      throw new BackupError("backup/bad-bundle-id",
+        "bundleId must match the framework's timestamp+suffix format");
+    }
+    await storage.readBundle(bundleId, destDir);
+  }
+
+  async function purgeOlder(purgeOpts) {
+    purgeOpts = purgeOpts || {};
+    var keep = typeof purgeOpts.keep === "number" && purgeOpts.keep >= 0
+      ? Math.floor(purgeOpts.keep) : 0;
+    var bundles = await storage.listBundles();
+    // listBundles returns newest first; keep the first `keep`, purge rest.
+    var toDelete = bundles.slice(keep);
+    var deleted = [];
+    for (var i = 0; i < toDelete.length; i++) {
+      try {
+        await storage.deleteBundle(toDelete[i].bundleId);
+        deleted.push(toDelete[i].bundleId);
+      } catch (e) {
+        _emitAudit("backup.deleted.failure",
+          { bundleId: toDelete[i].bundleId, reason: (e && e.message) || String(e) },
+          "failure");
+      }
+    }
+    if (deleted.length > 0) {
+      _emitAudit("backup.retention.swept", { kept: keep, deleted: deleted });
+    }
+    return { kept: keep, deleted: deleted };
+  }
+
+  function schedule(scheduleOpts) {
+    if (!scheduler || typeof scheduler.create !== "function") {
+      throw new BackupError("backup/no-scheduler",
+        "schedule: opts.scheduler must be wired at create() to use schedule()");
+    }
+    scheduleOpts = scheduleOpts || {};
+    if (typeof scheduleOpts.cron !== "string" || scheduleOpts.cron.length === 0) {
+      throw new BackupError("backup/bad-schedule",
+        "schedule: opts.cron is required (POSIX 5-field cron expression)");
+    }
+    var name = scheduleOpts.name || "blamejs.backup";
+    // Operators wire scheduler instances themselves; create() returns a
+    // scheduler we can append to.
+    var schedInstance = scheduler.create({ audit: auditOn });
+    schedInstance.schedule({
+      name:     name,
+      cron:     scheduleOpts.cron,
+      timezone: scheduleOpts.timezone,
+      run:      async function () {
+        try { await run({ metadata: { reason: "scheduled" } }); }
+        catch (_e) { /* errors already audited inside run() */ }
+      },
+    });
+    return { name: name, instance: schedInstance };
+  }
+
+  return {
+    run:           run,
+    list:          list,
+    delete:        deleteBundle,
+    read:          read,
+    purgeOlder:    purgeOlder,
+    schedule:      schedule,
+    storage:       storage,
+  };
+}
+
+// recommendedFiles — return the framework-default include list for
+// a given DB at-rest mode + vault wrap mode. Operators with custom
+// data files extend the result; operators with the standard layout
+// can use it as-is.
+//
+//   var files = b.backup.recommendedFiles({
+//     atRest:    b.db.getMode(),         // 'plain' | 'encrypted'
+//     vaultMode: b.vault.getMode(),      // 'plaintext' | 'wrapped'
+//     additionalSealed: ["ca.key.sealed", "tls/privkey.pem.sealed"],
+//   });
+//
+// The list adapts to mode:
+//   plain DB       → blamejs.db (the live SQLite file)
+//   encrypted DB   → db.enc + db.key.enc (the at-rest envelope + sealed key)
+//   plaintext vault→ vault.key
+//   wrapped vault  → vault.key.sealed
+function recommendedFiles(opts) {
+  opts = opts || {};
+  var atRest = opts.atRest || "encrypted";
+  var vaultMode = opts.vaultMode || "wrapped";
+  var dbName = opts.dbName || "blamejs.db";
+  var files = [];
+
+  if (atRest === "encrypted") {
+    files.push({ relativePath: "db.enc",     kind: "raw", required: true });
+    files.push({ relativePath: "db.key.enc", kind: "raw", required: true });
+  } else {
+    files.push({ relativePath: dbName,       kind: "raw", required: true });
+  }
+
+  if (vaultMode === "wrapped") {
+    files.push({ relativePath: "vault.key.sealed", kind: "raw", required: true });
+  } else {
+    files.push({ relativePath: "vault.key", kind: "raw", required: true });
+  }
+
+  // Audit-signing key (always present; sealed in wrapped mode)
+  files.push({
+    relativePath: vaultMode === "wrapped" ? "audit-sign.key.sealed" : "audit-sign.key",
+    kind: "raw", required: false,
+  });
+
+  // Operator-supplied additional sealed files (CA, TLS, etc.)
+  if (Array.isArray(opts.additionalSealed)) {
+    for (var i = 0; i < opts.additionalSealed.length; i++) {
+      files.push({
+        relativePath: opts.additionalSealed[i],
+        kind: "vault-sealed",
+        required: false,
+      });
+    }
+  }
+
+  return files;
+}
+
+module.exports = {
+  create:           create,
+  localStorage:     localStorage,
+  recommendedFiles: recommendedFiles,
+  BackupError:      BackupError,
+  BUNDLE_ID_RE:     BUNDLE_ID_RE,
+};