@blamejs/core 0.8.43 → 0.8.50

package/lib/backup/index.js

@@ -1,62 +1,51 @@
 "use strict";
 /**
- * backup — operator-facing backup orchestration.
+ * @module b.backup
+ * @featured true
+ * @nav    Production
+ * @title  Backup
  *
- * 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.
+ * @intro
+ *   PQC-encrypted backup bundles — sealed columns + audit chain +
+ *   keyring. SLH-DSA signature on every bundle, kid pinning, restore
+ *   validates signature against operator-pinned public key.
  *
- *   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()
- *   });
+ *   The namespace wires `b.backupBundle.create` (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.
  *
- *   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
- *   }
+ *   Storage backend contract:
+ *
+ *     {
+ *       async writeBundle(bundleId, sourceDir),
+ *       async readBundle(bundleId, destDir),
+ *       async listBundles(),     // → [{ bundleId, createdAt, size }]
+ *       async deleteBundle(bundleId),
+ *       async hasBundle(bundleId),
+ *     }
+ *
+ *   `vaultKeyJson` can be a string (the operator has the JSON in hand)
+ *   or a function returning a string (or async returning a string) — the
+ *   framework calls it each backup so a long-running app doesn't pin
+ *   the vault key in memory between runs.
  *
- * 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.
+ *   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.
+ *
+ *   Posture-enforced encryption: HIPAA / PCI-DSS postures refuse a
+ *   pipeline created with `encrypt: false`. Posture-enforced residency:
+ *   gdpr / uk-gdpr / dpdp / pipl-cn / lgpd-br / appi-jp / pdpa-sg refuse
+ *   a destination tag that doesn't match the live DB residency unless
+ *   the operator passes `allowCrossBorder: true` with a documented
+ *   `legalBasis`.
+ *
+ * @card
+ *   PQC-encrypted backup bundles — sealed columns + audit chain + keyring.
  */
 
 var fs = require("fs");
@@ -65,10 +54,12 @@ var path = require("path");
 var crypto = require("../crypto");
 var atomicFile = require("../atomic-file");
 var backupBundle = require("./bundle");
+var backupManifest = require("./manifest");
 var lazyRequire = require("../lazy-require");
 var validateOpts = require("../validate-opts");
 var numericBounds = require("../numeric-bounds");
 var audit = lazyRequire(function () { return require("../audit"); });
+var compliance = lazyRequire(function () { return require("../compliance"); });
 // lazyRequire ../db so backup stays a leaf module operators can use
 // without the rest of the framework's DB chain loaded in the same
 // module graph (CLI tools, stand-alone backup runners). The db()
@@ -78,6 +69,15 @@ var { defineClass } = require("../framework-error");
 
 var BackupError = defineClass("BackupError");
 
+// Postures whose published controls require backup encryption. PCI
+// DSS 4.0.1 Req 9.4.1.b ("backups are protected with strong cryptography
+// and encrypted") and HIPAA §164.310(d)(2)(iv) ("create a retrievable,
+// exact copy of ePHI" — encryption strongly implied by §164.312(a)(2)
+// (iv) addressable encryption standard).
+var BACKUP_ENCRYPTION_REQUIRED_POSTURES = Object.freeze([
+  "hipaa", "pci-dss",
+]);
+
 // "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}$/;
@@ -109,6 +109,37 @@ function _dirSize(p) {
 
 // ---- Local filesystem storage backend (the default) ----
 
+/**
+ * @primitive b.backup.localStorage
+ * @signature b.backup.localStorage(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.backup.create
+ *
+ * Local-filesystem storage backend implementing the
+ * `{ writeBundle, readBundle, listBundles, deleteBundle, hasBundle }`
+ * contract. Bundles land as directories named by bundle id under
+ * `opts.root`. Newest-first ordering is enforced by reverse
+ * lexicographic sort on the timestamp-prefixed bundle id.
+ *
+ * Operators pointing at S3 / GCS / Azure Blob / a tape gateway pass a
+ * custom backend matching the same shape; the engine never touches the
+ * filesystem directly.
+ *
+ * @opts
+ *   root: string,   // required; directory under which bundle dirs land
+ *
+ * @example
+ *   var fs   = require("node:fs");
+ *   var path = require("node:path");
+ *   var os   = require("node:os");
+ *   var root = fs.mkdtempSync(path.join(os.tmpdir(), "backup-root-"));
+ *
+ *   var storage = b.backup.localStorage({ root: root });
+ *   storage.name;                                      // → "local"
+ *   typeof storage.writeBundle;                        // → "function"
+ *   typeof storage.listBundles;                        // → "function"
+ */
 function localStorage(opts) {
   opts = opts || {};
   validateOpts.requireNonEmptyString(opts.root, "localStorage: opts.root", BackupError, "backup/no-storage-root");
@@ -210,6 +241,71 @@ async function _resolveVaultKeyJson(vaultKeyJsonOpt) {
     "opts.vaultKeyJson is required (string or function returning a string)");
 }
 
+/**
+ * @primitive b.backup.create
+ * @signature b.backup.create(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2, dora
+ * @related   b.backup.localStorage, b.backup.recommendedFiles, b.backup.verifyManifestSignature, b.backupBundle.create
+ *
+ * Build a backup engine bound to a data directory, a storage backend,
+ * the operator's passphrase, and an include list. Returns an object
+ * with `run` / `list` / `delete` / `read` / `purgeOlder` / `schedule` /
+ * `scheduleTest` plus the wired `storage` reference.
+ *
+ * Each `run()` produces a fresh bundle id (`<iso-timestamp>-<8 hex>`),
+ * stages encryption to a process-private tmpdir, writes through
+ * `storage.writeBundle`, sweeps tmpdir, then applies retention. Audit
+ * events `backup.success` / `backup.failure` / `backup.retention.swept`
+ * land on `b.audit` when `opts.audit !== false`.
+ *
+ * Posture gates fire at `create()` time, not `run()` time — so a
+ * misconfigured pipeline refuses to construct rather than producing
+ * one good bundle and then failing the next.
+ *
+ * @opts
+ *   dataDir:           string,                       // required; must exist on disk
+ *   storage:           StorageBackend,               // required; localStorage() or custom
+ *   passphrase:        Buffer | string,              // required; KEK for per-file Argon2id wrap
+ *   files:             Array<{ relativePath, kind, required }>,
+ *   vaultKeyJson:      string | () => string | Promise<string>,
+ *   retention:         { keep: number },             // optional; sweep older bundles after run()
+ *   audit:             boolean,                      // default true
+ *   scheduler:         b.scheduler,                  // required for schedule() / scheduleTest()
+ *   flushBeforeBackup: false | () => void | Promise<void>,
+ *   requireFlush:      boolean,                      // default false
+ *   encrypt:           boolean,                      // default true; refused under hipaa / pci-dss
+ *   residencyTag:      string | null,                // e.g. "EU"; checked against b.db.getDataResidency()
+ *   allowCrossBorder:  boolean,                      // explicit override for residency mismatch
+ *   legalBasis:        string,                       // recorded in audit chain when allowCrossBorder
+ *
+ * @example
+ *   var fs     = require("node:fs");
+ *   var path   = require("node:path");
+ *   var os     = require("node:os");
+ *
+ *   var dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "backup-data-"));
+ *   var root    = fs.mkdtempSync(path.join(os.tmpdir(), "backup-root-"));
+ *   fs.writeFileSync(path.join(dataDir, "db.enc"),     Buffer.from([1, 2, 3]));
+ *   fs.writeFileSync(path.join(dataDir, "db.key.enc"), Buffer.from([4, 5, 6]));
+ *
+ *   var engine = b.backup.create({
+ *     dataDir:      dataDir,
+ *     storage:      b.backup.localStorage({ root: root }),
+ *     passphrase:   Buffer.from("operator backup passphrase"),
+ *     files: [
+ *       { relativePath: "db.enc",     kind: "raw", required: true },
+ *       { relativePath: "db.key.enc", kind: "raw", required: true },
+ *     ],
+ *     vaultKeyJson: '{"version":1,"kid":"k1"}',
+ *     retention:    { keep: 7 },
+ *   });
+ *
+ *   typeof engine.run;          // → "function"
+ *   typeof engine.list;         // → "function"
+ *   typeof engine.purgeOlder;   // → "function"
+ */
 function create(opts) {
   opts = opts || {};
   if (typeof opts.dataDir !== "string" || !fs.existsSync(opts.dataDir)) {
@@ -230,6 +326,85 @@ function create(opts) {
       "create: opts.vaultKeyJson is required (string or function returning string)");
   }
 
+  // Posture-enforced backup encryption (F-BUDR-4). HIPAA / PCI-DSS
+  // operators MUST keep encryption on. The framework's backup pipeline
+  // is encrypted-by-default — passphrase + per-file XChaCha20-Poly1305
+  // — but operators in third-party storage backends sometimes pass
+  // `encrypt: false` on bespoke backends. Refuse boot under regulated
+  // postures. Permits explicit `opts.allowUnencrypted: true` only when
+  // a documented compensating control is present (offline tape vault
+  // with physical custody, separate KMS-encrypted bucket, etc.) — and
+  // even then the framework refuses unless paired with the operator's
+  // posture explicitly acknowledging the deviation.
+  var posture = null;
+  try { posture = compliance().current(); }
+  catch (_e) { /* compliance optional at backup-create time */ }
+  if (posture && BACKUP_ENCRYPTION_REQUIRED_POSTURES.indexOf(posture) !== -1) {
+    if (opts.encrypt === false) {
+      throw new BackupError("backup/encryption-required",
+        "backup.create: posture='" + posture + "' requires backup encryption " +
+        "(HIPAA §164.310(d)(2)(iv) / PCI DSS 4.0.1 Req 9.4.1.b). " +
+        "Refusing to create an unencrypted backup pipeline.");
+    }
+  }
+
+  // F-CBT-3 — backup destination residency posture. EU-tagged primary
+  // backing up to a US-region destination is a GDPR Article 46
+  // cross-border transfer; without an explicit operator opt-in the
+  // framework refuses to create the pipeline under gdpr / dpdp /
+  // pipl-cn / uk-gdpr / lgpd-br / appi-jp / pdpa-sg postures.
+  //
+  //   b.backup.create({
+  //     ...,
+  //     residencyTag: "EU",                  // matches your DB residency
+  //     allowCrossBorder: true,              // explicit override
+  //     legalBasis: "EU SCCs 2021/914",      // recorded in audit chain
+  //   });
+  var BACKUP_RESIDENCY_REGULATED_POSTURES = ["gdpr", "uk-gdpr", "dpdp", "pipl-cn",
+    "lgpd-br", "appi-jp", "pdpa-sg"];
+  var backupResidencyTag = opts.residencyTag || null;
+  if (opts.residencyTag !== undefined && opts.residencyTag !== null &&
+      (typeof opts.residencyTag !== "string" || opts.residencyTag.length === 0)) {
+    throw new BackupError("backup/bad-residency-tag",
+      "backup.create: opts.residencyTag must be a non-empty string or null");
+  }
+  if (posture && BACKUP_RESIDENCY_REGULATED_POSTURES.indexOf(posture) !== -1) {
+    var dbResidency = null;
+    try {
+      var dbModuleR = dbModuleLazy();
+      dbResidency = (dbModuleR && typeof dbModuleR.getDataResidency === "function")
+        ? dbModuleR.getDataResidency() : null;
+    } catch (_e) { dbResidency = null; }
+    var dbTag = (dbResidency && dbResidency.region) || null;
+    if (dbTag && backupResidencyTag &&
+        dbTag !== backupResidencyTag &&
+        backupResidencyTag !== "unrestricted" &&
+        dbTag !== "unrestricted") {
+      if (!opts.allowCrossBorder) {
+        throw new BackupError("backup/residency-mismatch",
+          "backup.create: db residency '" + dbTag +
+          "' but backup destination residencyTag '" + backupResidencyTag +
+          "' under '" + posture + "' posture. This is a cross-border data " +
+          "transfer (GDPR Art 46 / DPDP / PIPL category). Pass " +
+          "allowCrossBorder: true with a documented legalBasis to suppress.");
+      }
+    }
+    if (!backupResidencyTag) {
+      // Under regulated posture an undeclared backup residency is a
+      // smell — emit warning, don't refuse (operators with single-
+      // region S3 buckets that match the DB region are the common
+      // case and shouldn't be blocked).
+      try {
+        audit().safeEmit({
+          action:   "backup.residency_undeclared",
+          outcome:  "success",
+          metadata: { severity: "warning", posture: posture, dbResidency: dbTag,
+            recommendation: "declare opts.residencyTag matching the DB residency tag" },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+  }
+
   var dataDir = opts.dataDir;
   var storage = opts.storage;
   var passphrase = opts.passphrase;
@@ -440,6 +615,140 @@ function create(opts) {
     return { name: name, instance: schedInstance };
   }
 
+  // scheduleTest — periodic restore-and-verify drill required by HIPAA
+  // §164.308(a)(7)(ii)(D) ("testing and revision procedures"). The
+  // framework picks the latest backup, restores it to the operator-
+  // supplied directory, runs the operator's verify callback, and emits
+  // backup.test.passed / backup.test.failed in the audit chain.
+  //
+  //   await b.backup.scheduleTest({
+  //     cron:      "0 3 * * 0",                  // weekly at 03:00 Sunday
+  //     restoreTo: "/var/backup-test/staging",
+  //     verify:    async function ({ outDir, manifest }) {
+  //       // operator confirms key files restored, returns truthy on
+  //       // success or throws on failure.
+  //     },
+  //     notify:    async function ({ outcome, reason, manifest }) { /* page operator */ },
+  //     posture:   "hipaa",
+  //   });
+  function scheduleTest(testOpts) {
+    if (!scheduler || typeof scheduler.create !== "function") {
+      throw new BackupError("backup/no-scheduler",
+        "scheduleTest: opts.scheduler must be wired at create() to use scheduleTest()");
+    }
+    testOpts = testOpts || {};
+    if (typeof testOpts.cron !== "string" || testOpts.cron.length === 0) {
+      throw new BackupError("backup/bad-test-schedule",
+        "scheduleTest: opts.cron is required");
+    }
+    if (typeof testOpts.restoreTo !== "string" || testOpts.restoreTo.length === 0) {
+      throw new BackupError("backup/bad-test-restore-to",
+        "scheduleTest: opts.restoreTo is required (operator-controlled staging dir)");
+    }
+    if (typeof testOpts.verify !== "function") {
+      throw new BackupError("backup/bad-test-verify",
+        "scheduleTest: opts.verify must be an async function — operator " +
+        "supplies the per-deployment verification (file exists, schema " +
+        "matches, audit chain verifies, etc.)");
+    }
+    var name = testOpts.name || "blamejs.backup.test";
+    var schedInstance = scheduler.create({ audit: auditOn });
+    schedInstance.schedule({
+      name:     name,
+      cron:     testOpts.cron,
+      timezone: testOpts.timezone,
+      run:      async function () {
+        var startedAt = Date.now();
+        var bundles = [];
+        try { bundles = await storage.listBundles(); }
+        catch (e) {
+          _emitAudit("backup.test.failed",
+            { reason: "listBundles failed: " + ((e && e.message) || String(e)) },
+            "failure");
+          return;
+        }
+        if (!bundles || bundles.length === 0) {
+          _emitAudit("backup.test.failed",
+            { reason: "no bundles in storage to test against" },
+            "failure");
+          return;
+        }
+        // Newest bundle (storage.listBundles returns newest first).
+        var bundleId = bundles[0].bundleId;
+        var stagingDir = path.join(testOpts.restoreTo,
+          "test-" + bundleId.replace(/[:.]/g, "-"));
+        // Refuse to overwrite an existing dir — operators get a fresh
+        // restore every drill.
+        if (fs.existsSync(stagingDir)) {
+          _emitAudit("backup.test.failed",
+            { bundleId: bundleId, reason: "stagingDir already exists: " + stagingDir },
+            "failure");
+          return;
+        }
+        var manifestPath, manifest, sigVerification;
+        try {
+          await storage.readBundle(bundleId, stagingDir);
+          manifestPath = path.join(stagingDir, "manifest.json");
+          if (!fs.existsSync(manifestPath)) {
+            throw new BackupError("backup/test-no-manifest",
+              "manifest.json missing under restored bundle " + bundleId);
+          }
+          manifest = backupManifest.parse(fs.readFileSync(manifestPath, "utf8"));
+          // Verify the manifest signature so a tampered backup test
+          // surfaces here, not as a regulator finding later.
+          sigVerification = backupManifest.verifySignature(manifest, {
+            expectedFingerprint: testOpts.expectedFingerprint || undefined,
+          });
+          if (!sigVerification.ok) {
+            throw new BackupError("backup/test-bad-signature",
+              "manifest signature invalid: " + sigVerification.reason);
+          }
+          // Hand off to operator verify hook
+          await testOpts.verify({
+            outDir:       stagingDir,
+            manifest:     manifest,
+            bundleId:     bundleId,
+            sigFingerprint: sigVerification.fingerprint,
+          });
+          _emitAudit("backup.test.passed", {
+            bundleId:        bundleId,
+            posture:         testOpts.posture || posture || null,
+            fingerprint:     sigVerification.fingerprint,
+            durationMs:      Date.now() - startedAt,
+          }, "success");
+          if (typeof testOpts.notify === "function") {
+            try { await testOpts.notify({ outcome: "success", bundleId: bundleId, manifest: manifest }); }
+            catch (_e) { /* notify hook is best-effort */ }
+          }
+        } catch (e) {
+          _emitAudit("backup.test.failed", {
+            bundleId:    bundleId,
+            posture:     testOpts.posture || posture || null,
+            reason:      (e && e.message) || String(e),
+            durationMs:  Date.now() - startedAt,
+          }, "failure");
+          if (typeof testOpts.notify === "function") {
+            try {
+              await testOpts.notify({
+                outcome: "failure",
+                bundleId: bundleId,
+                reason: (e && e.message) || String(e),
+              });
+            } catch (_e) { /* notify hook is best-effort */ }
+          }
+        } finally {
+          // Best-effort cleanup so the staging dir doesn't accumulate
+          // across drills.
+          if (testOpts.cleanup !== false) {
+            try { fs.rmSync(stagingDir, { recursive: true, force: true }); }
+            catch (_e) { /* tmpdir cleanup best-effort */ }
+          }
+        }
+      },
+    });
+    return { name: name, instance: schedInstance };
+  }
+
   return {
     run:           run,
     list:          list,
@@ -447,26 +756,116 @@ function create(opts) {
     read:          read,
     purgeOlder:    purgeOlder,
     schedule:      schedule,
+    scheduleTest:  scheduleTest,
     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
+/**
+ * @primitive b.backup.verifyManifestSignature
+ * @signature b.backup.verifyManifestSignature(target, opts)
+ * @since     0.7.30
+ * @status    stable
+ * @compliance hipaa, pci-dss, soc2
+ * @related   b.backup.create, b.backupManifest.verifySignature
+ *
+ * Read the manifest from a restored bundle directory (or accept a
+ * pre-parsed manifest object) and verify its SLH-DSA audit-sign
+ * signature. Operator-facing wrapper around
+ * `b.backupManifest.verifySignature` that handles the on-disk fetch
+ * + JCS parse, so a regulator-facing restore drill is a single call.
+ *
+ * Returns `{ ok, fingerprint?, reason? }`. Throws `BackupError` only
+ * for missing / unreadable / unparseable manifests — a bad signature
+ * returns `{ ok: false, reason }` so the caller can branch on the
+ * verdict without a try/catch.
+ *
+ * Pass `opts.expectedFingerprint` to pin the signing key; the
+ * verification rejects any signature that validates against a
+ * different key, even if the math checks out. That's the kid-pinning
+ * the restore drill leans on.
+ *
+ * @opts
+ *   expectedFingerprint: string,   // optional; SHA3-512 fingerprint to pin
+ *
+ * @example
+ *   var fs   = require("node:fs");
+ *   var path = require("node:path");
+ *   var os   = require("node:os");
+ *
+ *   var bundleDir = fs.mkdtempSync(path.join(os.tmpdir(), "verify-bundle-"));
+ *   try {
+ *     b.backup.verifyManifestSignature(bundleDir);
+ *   } catch (e) {
+ *     e.code;           // → "backup/no-manifest"
+ *   }
+ */
+function verifyManifestSignature(target, opts) {
+  opts = opts || {};
+  var manifest;
+  if (typeof target === "string") {
+    var manifestPath = path.join(target, "manifest.json");
+    if (!fs.existsSync(manifestPath)) {
+      throw new BackupError("backup/no-manifest",
+        "verifyManifestSignature: manifest.json missing at " + manifestPath);
+    }
+    try { manifest = backupManifest.parse(fs.readFileSync(manifestPath, "utf8")); }
+    catch (e) {
+      throw new BackupError("backup/bad-manifest",
+        "verifyManifestSignature: parse failed: " + ((e && e.message) || String(e)));
+    }
+  } else if (target && typeof target === "object" && target.manifest) {
+    manifest = target.manifest;
+  } else if (target && typeof target === "object" &&
+             typeof target.version === "number") {
+    manifest = target;
+  } else {
+    throw new BackupError("backup/bad-target",
+      "verifyManifestSignature: target must be a bundle dir path, " +
+      "{ manifest } object, or a parsed manifest object");
+  }
+  return backupManifest.verifySignature(manifest, opts);
+}
+
+/**
+ * @primitive b.backup.recommendedFiles
+ * @signature b.backup.recommendedFiles(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.backup.create, b.db.getMode, b.vault.getMode
+ *
+ * Return the framework-default include list for a given DB at-rest
+ * mode + vault wrap mode. Operators with the standard layout pass the
+ * result straight to `b.backup.create({ files })`; operators with
+ * custom data files (additional sealed keys, OIDC provider material,
+ * application-specific keystores) append their own entries.
+ *
+ * The list adapts to mode:
+ * - plain DB        → the live SQLite file (default name `blamejs.db`)
+ * - encrypted DB    → `db.enc` + `db.key.enc` (envelope + sealed DEK)
+ * - plaintext vault → `vault.key`
+ * - wrapped vault   → `vault.key.sealed`
+ *
+ * The audit-signing key is always included (sealed in `wrapped` mode)
+ * so a restored deployment can verify its own audit chain.
+ *
+ * @opts
+ *   atRest:           "plain" | "encrypted",       // default "encrypted"
+ *   vaultMode:        "plaintext" | "wrapped",     // default "wrapped"
+ *   dbName:           string,                      // default "blamejs.db"
+ *   additionalSealed: Array<string>,               // operator-supplied sealed-file paths
+ *
+ * @example
+ *   var files = b.backup.recommendedFiles({
+ *     atRest:           "encrypted",
+ *     vaultMode:        "wrapped",
+ *     additionalSealed: ["ca.key.sealed", "tls/privkey.pem.sealed"],
+ *   });
+ *
+ *   files[0].relativePath;   // → "db.enc"
+ *   files[1].relativePath;   // → "db.key.enc"
+ *   files[2].relativePath;   // → "vault.key.sealed"
+ */
 function recommendedFiles(opts) {
   opts = opts || {};
   var atRest = opts.atRest || "encrypted";
@@ -507,20 +906,42 @@ function recommendedFiles(opts) {
   return files;
 }
 
-// runInWorker — execute the backup/restore against a worker_thread so
-// the heavy-CPU encryption + checksum walk doesn't block the request
-// loop. Returns a Promise that resolves with the worker's result, or
-// rejects with the worker's error. The worker module is supplied by
-// the operator (responsibility for thread-safe storage adapters
-// stays with the operator); this helper is the dispatch glue. Falls
-// back to in-process execution when worker_threads is unavailable
-// (older Node, sandboxed runtime).
-//
-//   var result = await b.backup.runInWorker({
-//     workerScript: path.join(__dirname, "backup-worker.js"),
-//     args:         { mode: "full", out: "/data/backups", passphrase: ... },
-//     timeoutMs:    C.TIME.minutes(30),
-//   });
+/**
+ * @primitive b.backup.runInWorker
+ * @signature b.backup.runInWorker(opts)
+ * @since     0.8.41
+ * @status    stable
+ * @related   b.backup.create
+ *
+ * Execute a backup or restore inside a `node:worker_threads` worker
+ * so the heavy-CPU Argon2id + XChaCha20-Poly1305 + SHA3-512 walk
+ * doesn't block the request loop. Returns a Promise resolving with
+ * the worker's posted message, or rejecting with the worker's error,
+ * a non-zero exit, or the operator's `timeoutMs`.
+ *
+ * The worker script is supplied by the operator — responsibility for
+ * thread-safe storage adapters stays with the operator; this helper
+ * is the dispatch + lifecycle glue. The framework rejects with
+ * `backup/no-worker-threads` when `node:worker_threads` is
+ * unavailable (sandboxed runtimes, stripped Node builds).
+ *
+ * @opts
+ *   workerScript: string,   // required; absolute path to the worker module
+ *   args:         object,   // optional; passed as workerData to the worker
+ *   timeoutMs:    number,   // optional; positive finite int, terminates worker on miss
+ *
+ * @example
+ *   var path = require("node:path");
+ *
+ *   b.backup.runInWorker({
+ *     workerScript: path.resolve("/does/not/exist/worker.js"),
+ *     args:         { mode: "full" },
+ *     timeoutMs:    60000,
+ *   }).catch(function (err) {
+ *     // worker failed to load — error surfaces as a rejected promise
+ *     typeof err.message;   // → "string"
+ *   });
+ */
 function runInWorker(opts) {
   opts = opts || {};
   try {
@@ -569,10 +990,12 @@ function runInWorker(opts) {
 }
 
 module.exports = {
-  create:           create,
-  localStorage:     localStorage,
-  recommendedFiles: recommendedFiles,
-  runInWorker:      runInWorker,
-  BackupError:      BackupError,
-  BUNDLE_ID_RE:     BUNDLE_ID_RE,
+  create:                    create,
+  localStorage:              localStorage,
+  recommendedFiles:          recommendedFiles,
+  runInWorker:               runInWorker,
+  verifyManifestSignature:   verifyManifestSignature,
+  BACKUP_ENCRYPTION_REQUIRED_POSTURES: BACKUP_ENCRYPTION_REQUIRED_POSTURES,
+  BackupError:               BackupError,
+  BUNDLE_ID_RE:              BUNDLE_ID_RE,
 };