@blamejs/core 0.14.11 → 0.14.12

package/lib/cluster.js

@@ -52,6 +52,7 @@ var safeAsync = require("./safe-async");
 var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
 var safeUrl = require("./safe-url");
+var validateOpts = require("./validate-opts");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
 // Lazy: vault → db → cluster forms a load-time chain, and external-db is
@@ -99,6 +100,15 @@ var configuredDialect            = null;
 // (or external observer) can resolve "where is the current leader?"
 // via cluster.currentLeader() / cluster.discoveryHandler().
 var configuredEndpoint          = null;
+// Operator declaration that this node's vault keypair legitimately
+// changed via a key rotation (b.vault.rotate). When set, a fingerprint
+// that differs from the canonical cluster-state row is ADOPTED (the row
+// advances to the new fingerprint + bumps the rotation epoch) instead
+// of FATAL-refusing boot. Unset (the default) keeps the strict
+// drift-refusal posture for the UNexpected mismatch. See
+// _checkVaultKeyConsistency for the consistency model.
+var configuredAcceptRotation     = false;
+var configuredExpectedVaultKeyFp = null;
 
 var log = boot("cluster");
 
@@ -142,6 +152,16 @@ function _emitTransition(kind, detail) {
  * outside `leader` / `follower`, and on a chain or vault-key mismatch
  * that would let this node corrupt cluster state.
  *
+ * After a vault-key rotation (`b.vault.rotate`) the public-key
+ * fingerprint changes, so the canonical cluster-state row no longer
+ * matches and every node would otherwise refuse boot with
+ * `VAULT_KEY_DRIFT`. Pass `acceptVaultKeyRotation: true` to declare the
+ * change legitimate: the node advances the canonical fingerprint and
+ * bumps a rotation epoch instead of refusing. `expectedVaultKeyFp`
+ * narrows the acceptance to a single blessed fingerprint so a typo'd /
+ * stale key file is still caught. The strict cross-node drift refusal
+ * stays in force whenever the rotation is NOT declared.
+ *
  * @opts
  *   nodeId:             string,            // required; stable identity
  *   role:               "leader"|"follower",
@@ -152,6 +172,11 @@ function _emitTransition(kind, detail) {
  *   provider:           object,            // custom election provider
  *   externalDbBackend:  object,            // required when no custom provider
  *   dialect:            "postgres"|"sqlite"|"mysql",
+ *   acceptVaultKeyRotation: boolean,        // adopt a rotated vault-key
+ *                                          // fingerprint instead of
+ *                                          // refusing boot on mismatch
+ *   expectedVaultKeyFp: string,            // optional; bless ONLY this
+ *                                          // post-rotation fingerprint
  *   onTransition:       function (event),
  *
  * @example
@@ -227,6 +252,31 @@ async function init(opts) {
     configuredEndpoint = null;
   }
 
+  // Vault-key rotation acceptance (config-time tier: THROW on bad
+  // input). acceptVaultKeyRotation is a boolean declaration; an
+  // expectedVaultKeyFp without it is a misconfiguration (the operator
+  // blessed a fingerprint but never enabled adoption).
+  validateOpts.optionalBoolean(opts.acceptVaultKeyRotation,
+    "cluster.init({ acceptVaultKeyRotation })", ClusterError, "INVALID_CONFIG");
+  configuredAcceptRotation = opts.acceptVaultKeyRotation === true;
+  if (opts.expectedVaultKeyFp !== undefined) {
+    if (typeof opts.expectedVaultKeyFp !== "string" ||
+        !/^[0-9a-f]{128}$/.test(opts.expectedVaultKeyFp)) {
+      throw _err("INVALID_CONFIG",
+        "cluster.init({ expectedVaultKeyFp }) must be a 128-char " +
+        "lowercase-hex SHA3-512 fingerprint (b.vault rotation output)", true);
+    }
+    if (!configuredAcceptRotation) {
+      throw _err("INVALID_CONFIG",
+        "cluster.init({ expectedVaultKeyFp }) requires " +
+        "acceptVaultKeyRotation: true — blessing a fingerprint without " +
+        "enabling adoption has no effect", true);
+    }
+    configuredExpectedVaultKeyFp = opts.expectedVaultKeyFp;
+  } else {
+    configuredExpectedVaultKeyFp = null;
+  }
+
   if (typeof opts.onTransition === "function") {
     transitionHandlers.push(opts.onTransition);
   }
@@ -433,6 +483,49 @@ function _vaultKeyFingerprint() {
                          keys.ecPublicKey);
 }
 
+// Idempotent migration for the rotationEpoch column. cluster-provider-db
+// ensureSchema creates _blamejs_cluster_state without it (the column was
+// added when rotation-epoch acceptance landed); ADD COLUMN here keeps the
+// path version-agnostic the same way the provider migrates the leader
+// row's `endpoint` column. The only expected failure is "column already
+// exists," which is swallowed. SQLite / MySQL don't take a DEFAULT on a
+// non-constant, so the column is nullable and treated as epoch 0 when
+// absent on legacy rows.
+async function _ensureRotationEpochColumn() {
+  try {
+    await externalDb().query(
+      "ALTER TABLE _blamejs_cluster_state ADD COLUMN rotationEpoch BIGINT",
+      [],
+      { backend: configuredExternalDbBackend }
+    );
+  } catch (_e) { /* column already exists (or table absent — caught upstream) */ }
+}
+
+// Consistency model (CWE-345 binding-integrity for sealed columns):
+//
+//   Every node fingerprints its vault PUBLIC keys (SHA3-512, one-way) and
+//   the cluster agrees on ONE canonical fingerprint stored in
+//   _blamejs_cluster_state. A node holding a different key seals new
+//   writes the rest of the cluster can't unseal — silent corruption — so
+//   an UNDECLARED mismatch fails closed (FATAL: VAULT_KEY_DRIFT).
+//
+//   A vault-key rotation (b.vault.rotate, lib/vault/rotate.js) legitimately
+//   changes the public-key fingerprint on EVERY node. The rotation only
+//   re-seals the local dataDir; it does not touch the external coordination
+//   row, so the canonical fingerprint goes stale and every node would
+//   refuse boot. acceptVaultKeyRotation: true is the operator's signed-off
+//   declaration "this change is a rotation, not drift": the booting node
+//   ADVANCES the canonical row to its own fingerprint and bumps a
+//   monotonic rotationEpoch. expectedVaultKeyFp narrows the adoption to a
+//   single blessed fingerprint so a stale / wrong key file is still
+//   refused. The strict refusal is unchanged when no rotation is declared,
+//   which is exactly the cross-node drift case the check defends.
+//
+//   The epoch is observability + a future-replay guard, not an auth
+//   boundary — the auth boundary is the operator's deliberate opt
+//   (acceptVaultKeyRotation) plus the optional fingerprint allowlist. A
+//   forged row can only ever cost a single declared boot, and a genuinely
+//   different key would still fail every sealed read.
 async function _checkVaultKeyConsistency() {
   var localFp = _vaultKeyFingerprint();
   if (localFp === null) {
@@ -469,10 +562,15 @@ async function _checkVaultKeyConsistency() {
     throw e;
   }
 
+  // Bring the rotationEpoch column into existence (idempotent). The INSERT
+  // above already proved the table is present, so a real ALTER failure
+  // here is "column exists" and is swallowed.
+  await _ensureRotationEpochColumn();
+
   // Read whatever fingerprint is canonical (ours if first boot,
   // someone else's if we lost the race or are joining an existing cluster).
   var rows = await externalDb().query(
-    "SELECT vaultKeyFp, recordedByNode, recordedAt FROM _blamejs_cluster_state " +
+    "SELECT vaultKeyFp, recordedByNode, recordedAt, rotationEpoch FROM _blamejs_cluster_state " +
     "WHERE scope = 'state'",
     [],
     { backend: configuredExternalDbBackend }
@@ -486,22 +584,92 @@ async function _checkVaultKeyConsistency() {
       true);
   }
   var canonical = rows.rows[0];
+  var fpPrefix = C.BYTES.bytes(16);
   if (canonical.vaultKeyFp !== localFp) {
-    var fpPrefix = C.BYTES.bytes(16);
-    throw _err("VAULT_KEY_DRIFT",
-      "FATAL: vault-key drift detected. " +
-      "local node: " + nodeId +
-      "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
-      "; canonical recorded by: " + canonical.recordedByNode +
-      "; canonical fingerprint: " + canonical.vaultKeyFp.slice(0, fpPrefix) + "…" +
-      ". This node holds a DIFFERENT vault key than the rest of the " +
-      "cluster. Sealed-column writes from this node would be unreadable " +
-      "by the others (and vice versa). Restore the same vault key file " +
-      "before booting this node into the cluster.",
-      true);
+    // Mismatch. Two readings: a legitimate vault-key rotation the
+    // operator has declared, or genuine cross-node drift. Without the
+    // declaration, always fail closed — sealed-column corruption is the
+    // worse outcome.
+    if (!configuredAcceptRotation) {
+      throw _err("VAULT_KEY_DRIFT",
+        "FATAL: vault-key drift detected. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; canonical recorded by: " + canonical.recordedByNode +
+        "; canonical fingerprint: " + canonical.vaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". This node holds a DIFFERENT vault key than the rest of the " +
+        "cluster. Sealed-column writes from this node would be unreadable " +
+        "by the others (and vice versa). If the key changed via " +
+        "b.vault.rotate, re-init with acceptVaultKeyRotation: true to " +
+        "advance the cluster's recorded fingerprint; otherwise restore the " +
+        "same vault key file before booting this node into the cluster.",
+        true);
+    }
+    // Rotation declared. If the operator blessed a specific fingerprint,
+    // the LOCAL key must match it — this rejects a stale / wrong key file
+    // that happens to differ from canonical for the wrong reason.
+    if (configuredExpectedVaultKeyFp && configuredExpectedVaultKeyFp !== localFp) {
+      throw _err("VAULT_KEY_ROTATION_MISMATCH",
+        "FATAL: acceptVaultKeyRotation is set but this node's vault-key " +
+        "fingerprint does not match the blessed expectedVaultKeyFp. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; expected fingerprint: " + configuredExpectedVaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". This node is NOT holding the rotated key the operator approved. " +
+        "Restore the post-rotation vault key file (or correct " +
+        "expectedVaultKeyFp) before booting this node into the cluster.",
+        true);
+    }
+    // Adopt: advance the canonical row to the new fingerprint and bump
+    // the monotonic rotation epoch. The UPDATE is gated on the OLD
+    // fingerprint so two nodes adopting concurrently converge on a single
+    // advance (the loser's WHERE matches nothing and it re-reads the
+    // already-advanced row below).
+    var priorEpoch = (canonical.rotationEpoch != null) ? Number(canonical.rotationEpoch) : 0;
+    if (!isFinite(priorEpoch) || priorEpoch < 0) priorEpoch = 0;
+    var nextEpoch = priorEpoch + 1;
+    await externalDb().query(
+      "UPDATE _blamejs_cluster_state SET " +
+      "  vaultKeyFp = " + (ph ? "$1" : "?") + ", " +
+      "  recordedAt = " + (ph ? "$2" : "?") + ", " +
+      "  recordedByNode = " + (ph ? "$3" : "?") + ", " +
+      "  rotationEpoch = " + (ph ? "$4" : "?") + " " +
+      "WHERE scope = 'state' AND vaultKeyFp = " + (ph ? "$5" : "?"),
+      [localFp, nowMs, nodeId, nextEpoch, canonical.vaultKeyFp],
+      { backend: configuredExternalDbBackend }
+    );
+    // Re-read so the post-adopt state reflects whoever actually won the
+    // advance (this node, or a peer that adopted the SAME rotated key a
+    // beat earlier). A surviving mismatch here means the row now carries a
+    // fingerprint that is neither the old one nor ours — a real drift that
+    // the rotation declaration does not cover, so fail closed.
+    var after = await externalDb().query(
+      "SELECT vaultKeyFp, recordedByNode, rotationEpoch FROM _blamejs_cluster_state " +
+      "WHERE scope = 'state'",
+      [],
+      { backend: configuredExternalDbBackend }
+    );
+    var post = (after.rows && after.rows[0]) || canonical;
+    if (post.vaultKeyFp !== localFp) {
+      throw _err("VAULT_KEY_DRIFT",
+        "FATAL: vault-key drift detected after rotation-accept. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; canonical fingerprint: " + post.vaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". A concurrent node advanced the cluster to a DIFFERENT key than " +
+        "this node holds — the declared rotation does not cover this " +
+        "fingerprint. Restore the agreed post-rotation vault key file.",
+        true);
+    }
+    log("cluster vault-key rotation accepted (fingerprint " +
+      localFp.slice(0, fpPrefix) + "… epoch " +
+      (post.rotationEpoch != null ? Number(post.rotationEpoch) : nextEpoch) +
+      ", recorded by " + post.recordedByNode + ")");
+    return;
   }
   log("cluster vault-key consistency ok (fingerprint " +
-    localFp.slice(0, C.BYTES.bytes(16)) + "… recorded by " + canonical.recordedByNode + ")");
+    localFp.slice(0, fpPrefix) + "… recorded by " + canonical.recordedByNode +
+    (canonical.rotationEpoch != null ? ", epoch " + Number(canonical.rotationEpoch) : "") + ")");
 }
 
 async function _tryAcquire() {
@@ -967,6 +1135,8 @@ async function shutdown() {
   configuredExternalDbBackend = null;
   configuredDialect = null;
   configuredEndpoint = null;
+  configuredAcceptRotation = false;
+  configuredExpectedVaultKeyFp = null;
   transitionHandlers = [];
   // nodeId is preserved post-shutdown so audit metadata still reflects
   // who this process was; cleared only by _resetForTest.
@@ -988,6 +1158,8 @@ function _resetForTest() {
   configuredExternalDbBackend = null;
   configuredDialect = null;
   configuredEndpoint = null;
+  configuredAcceptRotation = false;
+  configuredExpectedVaultKeyFp = null;
   transitionHandlers = [];
 }
 

package/lib/crypto-field.js

@@ -1105,6 +1105,11 @@ module.exports = {
   getSealedFields:  getSealedFields,
   sealRow:          sealRow,
   unsealRow:        unsealRow,
+  // _aadParts — the column-AAD builder the seal/unseal path uses. Exported
+  // (internal) so the vault-key rotation pipeline reconstructs the IDENTICAL
+  // AAD tuple a cell was sealed under — one source of truth, no drift
+  // between the seal side and the rotate side.
+  _aadParts:        _aadParts,
   // Doc-shaped aliases — operators / tests preparing a JS document
   // object (vs. a SQL row) reach for sealDoc / unsealDoc naming. Same
   // function, identical shape, returns a new object (input untouched).

package/lib/db.js

@@ -1318,6 +1318,15 @@ async function init(opts) {
       derivedHashes:   t.derivedHashes,
       hashNamespaces:  t.hashNamespaces,
       derivedHashMode: t.derivedHashMode,
+      // AAD-binding metadata MUST pass through — without it a schema that
+      // declares { aad: true } registers as a plain table, so its cells
+      // seal under vault: (not vault.aad:) and the vault-key rotation
+      // pipeline cannot reconstruct their AAD. registerTable defaults these
+      // (aad:false / rowIdField:"id" / schemaVersion:"1") so non-AAD tables
+      // are unaffected.
+      aad:             t.aad,
+      rowIdField:      t.rowIdField,
+      schemaVersion:   t.schemaVersion,
     });
     tableMetadata[t.name] = {
       primaryKey:             _normalizePk(t),
@@ -3161,6 +3170,12 @@ module.exports = {
   // (plain mode) or when the plaintext DB doesn't exist.
   flushToDisk:         encryptToDisk,
   snapshot:            snapshot,
+  // Internal AAD constructors, exported so the vault-key rotation
+  // pipeline (lib/vault/rotate.js) re-seals db.enc / db.key.enc under the
+  // SAME deployment-bound AAD this module writes them with — single source
+  // of truth for the wire-format literals (no duplicated constants).
+  _dbEncAad:           _dbEncAad,
+  _dbKeyAad:           _dbKeyAad,
   // integrityCheck — runs PRAGMA integrity_check against the live db
   // and returns "ok" on success, an array of corruption lines
   // otherwise. Operators wire this into a periodic monitor or a

package/lib/validate-opts.js

@@ -190,6 +190,29 @@ function requireObject(opts, callerLabel, errorClass, code) {
   return opts;
 }
 
+// requireMethods — validate an injected dependency exposes the named
+// methods. Collapses the repeated `if (!obj || typeof obj.fn !==
+// "function" || ...) throw` injected-store / exporter / backend guards
+// (b.agent.*.reseal stores, b.dsr / b.outbox create() backends, etc.)
+// into one definition. Throws on null / non-object / any missing-or-
+// non-function method; returns obj on success.
+function requireMethods(obj, methods, callerLabel, errorClass, code) {
+  var label = callerLabel || "dependency";
+  if (!obj || typeof obj !== "object") {
+    _throw(errorClass, code, label + " must be an object exposing { " +
+           methods.join(", ") + " }, got " + (obj === null ? "null" : typeof obj),
+           "validate-opts/bad-methods-object");
+  }
+  for (var i = 0; i < methods.length; i += 1) {
+    if (typeof obj[methods[i]] !== "function") {
+      _throw(errorClass, code, label + " must expose a " + methods[i] +
+             "() method (requires { " + methods.join(", ") + " })",
+             "validate-opts/missing-method");
+    }
+  }
+  return obj;
+}
+
 function optionalNonEmptyString(value, label, errorClass, code) {
   if (value === undefined || value === null) return value;
   if (typeof value !== "string" || value.length === 0) {
@@ -376,6 +399,7 @@ module.exports.optionalPlainObject = optionalPlainObject;
 module.exports.requireNonEmptyString = requireNonEmptyString;
 module.exports.observabilityShape = observabilityShape;
 module.exports.requireObject = requireObject;
+module.exports.requireMethods = requireMethods;
 module.exports.applyDefaults = applyDefaults;
 module.exports.makeAuditEmitter = makeAuditEmitter;
 module.exports.makeNamespacedEmitters = makeNamespacedEmitters;

package/lib/vault/rotate.js

@@ -56,6 +56,7 @@ var safeSql = require("../safe-sql");
 var C = require("../constants");
 var cryptoField = require("../crypto-field");
 var bCrypto = require("../crypto");
+var vaultAad = require("../vault-aad");
 var dbSchema = require("../db-schema");
 var lazyRequire = require("../lazy-require");
 var { boot } = require("../log");
@@ -63,6 +64,23 @@ var numericBounds = require("../numeric-bounds");
 var safeJson = require("../safe-json");
 var validateOpts = require("../validate-opts");
 var vaultWrap = lazyRequire(function () { return require("./wrap"); });
+// lazyRequire (named dbModuleLazy to match the canonical binding in
+// lib/backup/index.js and to avoid shadowing the local SQLite handle `db`
+// inside rotate()): the db at-rest AAD constructors live in lib/db.js.
+var dbModuleLazy = lazyRequire(function () { return require("../db"); });
+// Framework AAD modules whose stores live outside db.enc — lazyRequire'd
+// at top-of-file (deferred, never inline in a function body) so rotate's
+// detect-and-refuse can read each module's AAD_ROTATION descriptor without
+// eagerly loading them at require time.
+var agentIdempotencyLazy = lazyRequire(function () { return require("../agent-idempotency"); });
+var agentOrchestratorLazy = lazyRequire(function () { return require("../agent-orchestrator"); });
+var agentTenantLazy = lazyRequire(function () { return require("../agent-tenant"); });
+var agentSnapshotLazy = lazyRequire(function () { return require("../agent-snapshot"); });
+// Tenant archive blobs (recipient: "tenant") are keyed off the vault root but
+// live in operator-placed storage (files / object stores / backups) the
+// rotation pipeline never walks, so archive-wrap exports the same external
+// AAD_ROTATION descriptor and must be gated here too.
+var archiveWrapLazy = lazyRequire(function () { return require("../archive-wrap"); });
 var { defineClass } = require("../framework-error");
 
 var rotateLog = boot("vault-rotate");
@@ -254,6 +272,10 @@ function verify(opts) {
   var keys       = opts.keys;
   var db         = opts.db;
   var oldKeys    = opts.oldKeys || null;
+  // Serialized roots for AAD-cell verification — match getKeysJson() so an
+  // AAD cell sealed under the new root opens here.
+  var keysJson    = JSON.stringify(keys, null, 2);
+  var oldKeysJson = oldKeys ? JSON.stringify(oldKeys, null, 2) : null;
   numericBounds.requirePositiveFiniteIntIfPresent(opts.sampleMin,
     "verify: sampleMin", VaultRotateError, "vault-rotate/bad-opt");
   var sampleMin  = opts.sampleMin !== undefined
@@ -308,7 +330,29 @@ function verify(opts) {
       for (var sf = 0; sf < schema.sealedFields.length; sf++) {
         var col = schema.sealedFields[sf];
         var v = row[col];
-        if (typeof v !== "string" || v.indexOf(VAULT_PREFIX) !== 0) continue;
+        if (typeof v !== "string") continue;
+
+        if (vaultAad.isAadSealed(v)) {
+          // AAD cell: reconstruct the seal-side AAD (cryptoField._aadParts)
+          // and verify under the new root; flag a regression if it still
+          // opens under the old root (rotation didn't take effect).
+          var aad = cryptoField._aadParts(schema, table, col, row);
+          try { vaultAad.unsealRoot(v, aad, keysJson); }
+          catch (e) {
+            rowFailed = true;
+            failures.push({ table: table, column: col, _id: row._id, error: (e && e.message) || String(e) });
+          }
+          if (oldKeysJson && !foundOldFail) {
+            try {
+              vaultAad.unsealRoot(v, aad, oldKeysJson);
+              regressions.push({ table: table, column: col, _id: row._id,
+                error: "old keys still decrypt this AAD value — rotation did not take effect" });
+            } catch (_e) { foundOldFail = true; }
+          }
+          continue;
+        }
+
+        if (v.indexOf(VAULT_PREFIX) !== 0) continue;
         var payload = v.substring(VAULT_PREFIX.length);
 
         try { bCrypto.decrypt(payload, keys); }
@@ -379,6 +423,41 @@ function verify(opts) {
 var ROW_BATCH_SIZE_DEFAULT = 0x3E8;
 var VAULT_PREFIX_LEN = C.VAULT_PREFIX.length;
 
+// db.enc / db.key.enc AAD constructors come from the module that OWNS the
+// db at-rest format (lib/db.js _dbEncAad / _dbKeyAad), not re-declared
+// here — one source of truth for the wire-format literals so a rotation
+// re-seal binds the SAME deployment AAD db.init expects on next open.
+
+// Framework modules that seal AAD cells on operator-supplied (external)
+// stores this pipeline never reaches (it only walks db.enc). Each exports
+// an AAD_ROTATION descriptor + a reseal hook to rotate its store
+// out-of-band. rotate() REFUSES a keypair rotation unless the operator
+// acknowledges (opts.externalAadResealed) each has been re-sealed —
+// otherwise those cells silently orphan under the retired root (CWE-320).
+// Only the module PATHS live here; the table / backend metadata lives in
+// each module's AAD_ROTATION export (single source of truth). lazyRequire
+// so loading rotate.js doesn't eagerly pull the agent modules.
+var EXTERNAL_AAD_MODULE_LOADERS = [
+  agentIdempotencyLazy, agentOrchestratorLazy, agentTenantLazy, agentSnapshotLazy,
+  archiveWrapLazy,
+];
+
+function _externalAadTables() {
+  var tables = [];
+  for (var i = 0; i < EXTERNAL_AAD_MODULE_LOADERS.length; i += 1) {
+    var mod;
+    try { mod = EXTERNAL_AAD_MODULE_LOADERS[i](); }
+    catch (_e) { continue; }   // module unavailable in this process — skip
+    var desc = mod && mod.AAD_ROTATION;
+    if (!desc) continue;
+    var list = Array.isArray(desc) ? desc : [desc];
+    for (var j = 0; j < list.length; j += 1) {
+      if (list[j] && list[j].backend === "external" && list[j].table) tables.push(list[j].table);
+    }
+  }
+  return tables;
+}
+
 function _emit(cb, ev) {
   if (typeof cb === "function") {
     try { cb(ev); } catch (_e) { /* progress-callback errors are non-fatal */ }
@@ -444,7 +523,7 @@ function _walkAndReSeal(node, oldKeys, newKeys) {
 
 function _runStmt(db, sql) { db.prepare(sql).run(); }
 
-function _rotateColumn(db, table, column, oldKeys, newKeys, batchSize, progress) {
+function _rotateColumn(db, table, column, schema, roots, batchSize, progress) {
   // Identifiers reach SQL through safeSql.quoteIdentifier — runs
   // validateIdentifier (rejects bad shape / reserved words /
   // sqlite_-prefix) + emits the dialect-correct quoted form.
@@ -453,8 +532,18 @@ function _rotateColumn(db, table, column, oldKeys, newKeys, batchSize, progress)
   var total = db.prepare("SELECT COUNT(*) AS n FROM " + qt + " WHERE " + qc + " IS NOT NULL").get().n;
   if (total === 0) return 0;
 
+  // AAD-bound tables (registerTable({aad:true})) seal each cell under a
+  // (table, rowId, column, schemaVersion) tuple. Rotation reads the
+  // rowIdField value and reconstructs the IDENTICAL AAD via the seal-side
+  // builder cryptoField._aadParts (one source of truth), then re-seals
+  // old-root -> new-root. Plain (non-AAD) cells use the plain-vault reseal.
+  var aadMode = !!(schema && schema.aad);
+  var rowIdField = aadMode ? schema.rowIdField : null;
+  var needRid = aadMode && rowIdField && rowIdField !== "_id";
+  var qrid = needRid ? safeSql.quoteIdentifier(rowIdField, "sqlite") : null;
+
   var sel = db.prepare(
-    "SELECT _id, " + qc + " AS v FROM " + qt +
+    "SELECT _id, " + qc + " AS v" + (qrid ? ", " + qrid + " AS rid" : "") + " FROM " + qt +
     " WHERE " + qc + " IS NOT NULL AND _id > ? ORDER BY _id LIMIT ?"
   );
   var upd = db.prepare("UPDATE " + qt + " SET " + qc + " = ? WHERE _id = ?");
@@ -468,8 +557,19 @@ function _rotateColumn(db, table, column, oldKeys, newKeys, batchSize, progress)
     dbSchema.runInTransaction(db, function () {
       for (var i = 0; i < rows.length; i++) {
         var row = rows[i];
-        if (typeof row.v === "string" && row.v.indexOf(C.VAULT_PREFIX) === 0) {
-          upd.run(_reSealValue(row.v, oldKeys, newKeys), row._id);
+        if (typeof row.v !== "string") continue;
+        if (aadMode && vaultAad.isAadSealed(row.v)) {
+          // Rebuild the exact AAD the seal side used. cryptoField._aadParts
+          // reads row[schema.rowIdField]; feed it the rowIdField value we
+          // selected (rid, or _id when rowIdField IS _id).
+          var rowForAad = {};
+          rowForAad[rowIdField] = needRid ? row.rid : row._id;
+          var aad = cryptoField._aadParts(schema, table, column, rowForAad);
+          upd.run(vaultAad.resealRoot(row.v, aad, roots.oldRootJson, roots.newRootJson), row._id);
+        } else if (row.v.indexOf(C.VAULT_PREFIX) === 0) {
+          // Plain vault: cell (non-AAD table, or a legacy pre-AAD cell in
+          // an AAD table that the next sealRow upgrades).
+          upd.run(_reSealValue(row.v, roots.oldKeys, roots.newKeys), row._id);
         }
       }
     });
@@ -555,6 +655,27 @@ async function rotate(opts) {
     throw new VaultRotateError("vault-rotate/no-passphrase",
       "rotate: wrapped mode requires opts.newPassphrase (Buffer)");
   }
+  // Detect-and-refuse: AAD-bound state on operator-supplied stores is NOT
+  // reached by this pipeline (it walks only db.enc). Refuse unless the
+  // operator acknowledges each such store has been re-sealed via its
+  // module hook — otherwise a keypair rotation silently orphans them.
+  var externalAad = _externalAadTables();
+  if (externalAad.length > 0) {
+    var ack = opts.externalAadResealed;
+    var acknowledged = ack === true ||
+      (Array.isArray(ack) && externalAad.every(function (t) { return ack.indexOf(t) !== -1; }));
+    if (!acknowledged) {
+      throw new VaultRotateError("vault-rotate/external-aad-unresealed",
+        "rotate: AAD-bound state on operator-supplied stores is not reached by this " +
+        "pipeline and would be orphaned under the retired keypair: " + externalAad.join(", ") +
+        ". Re-seal each via its module hook (b.agent.idempotency.reseal / " +
+        "b.agent.orchestrator.reseal / b.agent.tenant AAD_ROTATION reseal / " +
+        "b.agent.snapshot.reseal / b.archive.rewrapTenant for archive-wrap:tenant-blobs) " +
+        "BEFORE retiring the old keypair, then pass " +
+        "opts.externalAadResealed: [" + externalAad.map(function (t) { return JSON.stringify(t); }).join(", ") +
+        "] to acknowledge. If you do not use these features, pass opts.externalAadResealed: true.");
+    }
+  }
   var rowBatchSize = opts.rowBatchSize || ROW_BATCH_SIZE_DEFAULT;
   var progress = opts.progressCallback;
   var warnings = [];
@@ -608,6 +729,12 @@ async function rotate(opts) {
   // 2. write new vault key
   _emit(progress, { phase: "write_vault_key" });
   var keysJson = JSON.stringify(newKeys, null, 2);
+  // Serialized roots for the explicit-root AAD reseal path. These match
+  // b.vault.getKeysJson() EXACTLY (JSON.stringify(keys, null, 2)) so an
+  // AAD cell re-sealed under newRootJson here unseals once the new keypair
+  // is live after the atomic swap.
+  var oldRootJson = JSON.stringify(oldKeys, null, 2);
+  var newRootJson = keysJson;
   if (mode === "wrapped") {
     var sealed = await vaultWrap().wrap(keysJson, opts.newPassphrase);
     nodeFs.writeFileSync(nodePath.join(stagingDir, paths.vaultKeySealed), sealed, { mode: 0o600 });
@@ -621,14 +748,29 @@ async function rotate(opts) {
   var dbKey = null;
   if (nodeFs.existsSync(dbKeySealedPath)) {
     var sealedKey = nodeFs.readFileSync(dbKeySealedPath, "utf8").trim();
-    if (sealedKey.indexOf(C.VAULT_PREFIX) !== 0) {
+    if (vaultAad.isAadSealed(sealedKey)) {
+      // AAD-bound db.key.enc (db.js since v0.14.7): unseal under the OLD
+      // root with the deployment-context AAD, then re-emit under the NEW
+      // root with the SAME context (an in-place swap keeps dataDir +
+      // keyPath, so source and target AAD match). The vault.aad: shape is
+      // preserved — a plain-vault re-emit would strip the deployment-
+      // substitution binding (CWE-345 / CWE-441).
+      var dbKeyAad = dbModuleLazy()._dbKeyAad(dataDir, dbKeySealedPath);
+      var dbKeyB64Aad = vaultAad.unsealRoot(sealedKey, dbKeyAad, oldRootJson);
+      dbKey = Buffer.from(dbKeyB64Aad, "base64");
+      var resealedAad = vaultAad.sealRoot(dbKeyB64Aad, dbKeyAad, newRootJson);
+      nodeFs.writeFileSync(nodePath.join(stagingDir, paths.dbKeySealed), resealedAad, { mode: 0o600 });
+    } else if (sealedKey.indexOf(C.VAULT_PREFIX) === 0) {
+      // Legacy plain-sealed db.key.enc (pre-AAD). Re-key in place; db.init
+      // read-migrates plain -> AAD on the next boot.
+      var dbKeyB64 = bCrypto.decrypt(sealedKey.substring(VAULT_PREFIX_LEN), oldKeys);
+      dbKey = Buffer.from(dbKeyB64, "base64");
+      var resealedKey = C.VAULT_PREFIX + bCrypto.encrypt(dbKeyB64, newKeys);
+      nodeFs.writeFileSync(nodePath.join(stagingDir, paths.dbKeySealed), resealedKey, { mode: 0o600 });
+    } else {
       throw new VaultRotateError("vault-rotate/bad-dbkey",
-        "rotate: db.key.enc does not start with the vault prefix");
+        "rotate: db.key.enc does not start with a vault prefix (vault: or vault.aad:)");
     }
-    var dbKeyB64 = bCrypto.decrypt(sealedKey.substring(VAULT_PREFIX_LEN), oldKeys);
-    dbKey = Buffer.from(dbKeyB64, "base64");
-    var resealedKey = C.VAULT_PREFIX + bCrypto.encrypt(dbKeyB64, newKeys);
-    nodeFs.writeFileSync(nodePath.join(stagingDir, paths.dbKeySealed), resealedKey, { mode: 0o600 });
   }
   for (var as = 0; as < paths.additionalSealed.length; as++) {
     var ase = paths.additionalSealed[as];
@@ -679,7 +821,14 @@ async function rotate(opts) {
 
   if (nodeFs.existsSync(encDbPath) && dbKey) {
     var packed = nodeFs.readFileSync(encDbPath);
-    var plainBytes = bCrypto.decryptPacked(packed, dbKey);
+    // db.enc is XChaCha20-Poly1305-sealed AAD-bound to its dataDir
+    // (db.js _dbEncAad). Read with the dataDir AAD; retry without AAD for
+    // pre-AAD envelopes (mirrors db.js:765-768). The in-place swap keeps
+    // the same dataDir, so this AAD is reused on the re-encrypt below.
+    var dbEncAad = dbModuleLazy()._dbEncAad(dataDir);
+    var plainBytes;
+    try { plainBytes = bCrypto.decryptPacked(packed, dbKey, dbEncAad); }
+    catch (_eAad) { plainBytes = bCrypto.decryptPacked(packed, dbKey); }
     var tmpDbPath = nodePath.join(stagingDir, "_blamejs_rotate.tmp.db");
     nodeFs.writeFileSync(tmpDbPath, plainBytes, { mode: 0o600 });
 
@@ -698,6 +847,11 @@ async function rotate(opts) {
             "WHERE type='table' AND name NOT LIKE 'sqlite_%'"
           ).all().map(function (r) { return r.name; });
 
+      // Serialized roots threaded to the AAD reseal path; oldRootJson /
+      // newRootJson match b.vault.getKeysJson() so rotated AAD cells unseal
+      // once the new keypair is live after the swap.
+      var roots = { oldKeys: oldKeys, newKeys: newKeys, oldRootJson: oldRootJson, newRootJson: newRootJson };
+
       for (var ti = 0; ti < tablesToRotate.length; ti++) {
         var table = tablesToRotate[ti];
         var tableExists = db.prepare(
@@ -717,7 +871,7 @@ async function rotate(opts) {
           for (var sc = 0; sc < schema.sealedFields.length; sc++) {
             var col = schema.sealedFields[sc];
             if (!liveColSet[col]) continue;
-            tableRows += _rotateColumn(db, table, col, oldKeys, newKeys, rowBatchSize, progress);
+            tableRows += _rotateColumn(db, table, col, schema, roots, rowBatchSize, progress);
           }
         }
         tableRows += _rotateOverflow(db, table, oldKeys, newKeys, rowBatchSize, progress, warnings);
@@ -748,15 +902,17 @@ async function rotate(opts) {
     // inside it. Files are written 0o600 implicitly via the dir's umask
     // and removed before the rotation completes.
     var rotatedBytes = nodeFs.readFileSync(tmpDbPath);
+    // Re-encrypt under the SAME dataDir AAD so db.init's AAD-first open
+    // succeeds after the staged dir is swapped over dataDir in place.
     nodeFs.writeFileSync(nodePath.join(stagingDir, paths.encryptedDb),
-      bCrypto.encryptPacked(rotatedBytes, dbKey));
+      bCrypto.encryptPacked(rotatedBytes, dbKey, dbEncAad));
     nodeFs.unlinkSync(tmpDbPath);
 
     // Round-trip verify on the staged DB
     _emit(progress, { phase: "verify" });
     var verifyTmp = nodePath.join(stagingDir, "_blamejs_verify.tmp.db");
     nodeFs.writeFileSync(verifyTmp,
-      bCrypto.decryptPacked(nodeFs.readFileSync(nodePath.join(stagingDir, paths.encryptedDb)), dbKey));
+      bCrypto.decryptPacked(nodeFs.readFileSync(nodePath.join(stagingDir, paths.encryptedDb)), dbKey, dbEncAad));
     var vdb = new DatabaseSync(verifyTmp);
     try {
       verifyResult = verify({ keys: newKeys, db: vdb, oldKeys: oldKeys });
@@ -819,4 +975,8 @@ module.exports = {
   DEFAULT_VERIFY_SAMPLE_MIN:  DEFAULT_VERIFY_SAMPLE_MIN,
   DEFAULT_VERIFY_SAMPLE_FRAC: DEFAULT_VERIFY_SAMPLE_FRAC,
   ROW_BATCH_SIZE_DEFAULT:     ROW_BATCH_SIZE_DEFAULT,
+  // Exposed for the rotation-gate coverage test: every lib module that exports
+  // an external AAD_ROTATION descriptor must be reachable here, or a keypair
+  // rotation silently orphans its store.
+  _externalAadTables:         _externalAadTables,
 };