@blamejs/core 0.14.10 → 0.14.12

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/framework-error.js

@@ -412,6 +412,20 @@ var McpError              = defineClass("McpError",              { alwaysPermane
 // input shape, classifier-result-shape errors, oversized input bypass.
 // Permanent — caller-shape errors.
 var AiInputError          = defineClass("AiInputError",          { alwaysPermanent: true });
+// AiOutputError covers LLM output-handling violations raised by
+// b.ai.output.sanitize / b.ai.output.redact: malformed input shape
+// (non-string), oversized output bypass (exceeds maxBytes cap), bad
+// maxBytes opt, unknown redaction entity. Permanent — caller-shape
+// errors that retry will not recover. OWASP LLM05:2025 (Improper
+// Output Handling) + LLM02:2025 (Sensitive Information Disclosure).
+var AiOutputError         = defineClass("AiOutputError",         { alwaysPermanent: true });
+// AiPromptError covers LLM prompt-assembly violations raised by
+// b.ai.prompt.template: malformed segment shape (non-string system /
+// context / user), bad maxBytes / nonceBytes opt, oversized assembled
+// prompt. Permanent — caller-shape errors that retry will not recover.
+// OWASP LLM01:2025 (Prompt Injection — indirect / data-plane injection
+// from untrusted context).
+var AiPromptError         = defineClass("AiPromptError",         { alwaysPermanent: true });
 // A2aError covers A2A (Agent-to-Agent) protocol violations: signed-
 // agent-card signature mismatch, expired card, unknown card id,
 // malformed card shape, signature-algorithm allowlist drift.
@@ -691,6 +705,8 @@ module.exports = {
   SseError:               SseError,
   McpError:               McpError,
   AiInputError:           AiInputError,
+  AiOutputError:          AiOutputError,
+  AiPromptError:          AiPromptError,
   A2aError:               A2aError,
   GraphqlFederationError: GraphqlFederationError,
   Fda21Cfr11Error:        Fda21Cfr11Error,

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,
 };

package/lib/vault-aad.js

@@ -147,13 +147,17 @@ function buildContextAad(parts) {
 // 32 bytes). Constant-domain prefix prevents key collision with other
 // uses of the vault root.
 
-function _deriveKey(aadBytes) {
-  var keysJson = vault().getKeysJson();
-  // The vault keys JSON includes the active keypair PEMs. We hash the
-  // whole serialized form to get a stable per-vault root secret —
-  // this is a deterministic derivation; rotating vault keys produces
-  // a different root and breaks all prior AAD-sealed values (operator
-  // intent: rotation = re-seal).
+function _deriveKey(aadBytes, rootKeysJson) {
+  // rootKeysJson lets the vault-key rotation pipeline derive the per-row
+  // key under a SPECIFIC vault root (old or new keypair) within one
+  // process; when omitted it uses the live singleton. The keys JSON
+  // includes the active keypair PEMs — hashing the whole serialized form
+  // gives a stable per-vault root secret. Rotating vault keys produces a
+  // different root, so prior AAD-sealed values must be re-sealed (the
+  // rotation pipeline walks them via sealRoot/unsealRoot/resealRoot).
+  var keysJson = (typeof rootKeysJson === "string" && rootKeysJson.length > 0)
+    ? rootKeysJson
+    : vault().getKeysJson();
   var rootHash = bCrypto().sha3Hash(keysJson);
   var prefix   = Buffer.from("vault.aad/v1/", "utf8");
   var rootBuf  = Buffer.from(rootHash, "hex");
@@ -161,7 +165,7 @@ function _deriveKey(aadBytes) {
   return bCrypto().kdf(input, C.BYTES.bytes(32));
 }
 
-function seal(plaintext, aadParts) {
+function _seal(plaintext, aadParts, rootKeysJson, suppressAudit) {
   if (plaintext == null) {
     throw new VaultAadError("vault-aad/bad-input",
       "seal: plaintext is required (use null/undefined-stripping at the call site)");
@@ -176,26 +180,32 @@ function seal(plaintext, aadParts) {
       "seal: value is already AAD-sealed (refuses to double-seal)");
   }
   var aadBytes = _canonicalize(aadParts);
-  var key = _deriveKey(aadBytes);
+  var key = _deriveKey(aadBytes, rootKeysJson);
   var ptBuf = Buffer.from(plaintext, "utf8");
   var packed = bCrypto().encryptPacked(ptBuf, key, aadBytes);
 
-  try {
-    audit().safeEmit({
-      action:   "vault.aad.sealed",
-      outcome:  "success",
-      actor:    null,
-      metadata: {
-        aadKeys: Object.keys(aadParts).sort(),    // allow:bare-canonicalize-walk — audit-emit metadata, not for signing
-        bytes:   ptBuf.length,
-      },
-    });
-  } catch (_e) { /* drop-silent */ }
+  if (!suppressAudit) {
+    try {
+      audit().safeEmit({
+        action:   "vault.aad.sealed",
+        outcome:  "success",
+        actor:    null,
+        metadata: {
+          aadKeys: Object.keys(aadParts).sort(),    // allow:bare-canonicalize-walk — audit-emit metadata, not for signing
+          bytes:   ptBuf.length,
+        },
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
 
   return AAD_PREFIX + packed.toString("base64");
 }
 
-function unseal(value, aadParts) {
+function seal(plaintext, aadParts) {
+  return _seal(plaintext, aadParts, undefined, false);
+}
+
+function _unseal(value, aadParts, rootKeysJson, suppressAudit) {
   if (value == null || typeof value !== "string") {
     throw new VaultAadError("vault-aad/bad-input",
       "unseal: value must be a non-empty string");
@@ -205,7 +215,7 @@ function unseal(value, aadParts) {
       "unseal: value is not AAD-sealed (missing " + JSON.stringify(AAD_PREFIX) + " prefix)");
   }
   var aadBytes = _canonicalize(aadParts);
-  var key = _deriveKey(aadBytes);
+  var key = _deriveKey(aadBytes, rootKeysJson);
   var packed;
   try { packed = Buffer.from(value.slice(AAD_PREFIX.length), "base64"); }
   catch (e) {
@@ -215,17 +225,19 @@ function unseal(value, aadParts) {
   var pt;
   try { pt = bCrypto().decryptPacked(packed, key, aadBytes); }
   catch (e) {
-    try {
-      audit().safeEmit({
-        action:   "vault.aad.unseal_failed",
-        outcome:  "denied",
-        actor:    null,
-        metadata: {
-          aadKeys: Object.keys(aadParts).sort(),  // allow:bare-canonicalize-walk — audit-emit metadata, not for signing
-          reason:  e.message,
-        },
-      });
-    } catch (_e) { /* drop-silent */ }
+    if (!suppressAudit) {
+      try {
+        audit().safeEmit({
+          action:   "vault.aad.unseal_failed",
+          outcome:  "denied",
+          actor:    null,
+          metadata: {
+            aadKeys: Object.keys(aadParts).sort(),  // allow:bare-canonicalize-walk — audit-emit metadata, not for signing
+            reason:  e.message,
+          },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
     throw new VaultAadError("vault-aad/aead-mismatch",
       "unseal: AEAD authentication failed — value may have been tampered, " +
       "copied from a different row, or sealed under different AAD");
@@ -233,6 +245,10 @@ function unseal(value, aadParts) {
   return pt.toString("utf8");
 }
 
+function unseal(value, aadParts) {
+  return _unseal(value, aadParts, undefined, false);
+}
+
 function isAadSealed(value) {
   return typeof value === "string" && value.indexOf(AAD_PREFIX) === 0;
 }
@@ -246,10 +262,45 @@ function reseal(value, fromAad, toAad) {
   return seal(plaintext, toAad);
 }
 
+// ---- explicit-root variants (vault-key rotation pipeline) ----
+//
+// The rotation pipeline must decrypt a cell under the OLD vault root and
+// re-encrypt it under the NEW root within one process — the live-singleton
+// _deriveKey cannot straddle two keypairs. These take the serialized vault
+// keys JSON (b.vault.getKeysJson() output) for a specific root; the AAD
+// tuple is unchanged, only the root differs. Per-cell audit is suppressed
+// (the rotation pipeline has its own progress + verify reporting).
+
+function sealRoot(plaintext, aadParts, rootKeysJson) {
+  if (typeof rootKeysJson !== "string" || rootKeysJson.length === 0) {
+    throw new VaultAadError("vault-aad/bad-root", "sealRoot: rootKeysJson (vault keys JSON) is required");
+  }
+  return _seal(plaintext, aadParts, rootKeysJson, true);
+}
+
+function unsealRoot(value, aadParts, rootKeysJson) {
+  if (typeof rootKeysJson !== "string" || rootKeysJson.length === 0) {
+    throw new VaultAadError("vault-aad/bad-root", "unsealRoot: rootKeysJson (vault keys JSON) is required");
+  }
+  return _unseal(value, aadParts, rootKeysJson, true);
+}
+
+// Re-seal a value from the old root to the new root under the SAME AAD
+// tuple: authenticate under the old root (throws aead-mismatch if the
+// value was not sealed under oldRootJson + aadParts), then re-encrypt
+// under the new root. The rotation pipeline composes this per cell.
+function resealRoot(value, aadParts, oldRootJson, newRootJson) {
+  var plaintext = unsealRoot(value, aadParts, oldRootJson);
+  return sealRoot(plaintext, aadParts, newRootJson);
+}
+
 module.exports = {
   seal:               seal,
   unseal:             unseal,
   reseal:             reseal,
+  sealRoot:           sealRoot,
+  unsealRoot:         unsealRoot,
+  resealRoot:         resealRoot,
   isAadSealed:        isAadSealed,
   buildColumnAad:     buildColumnAad,
   buildContextAad:    buildContextAad,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.14.10",
+  "version": "0.14.12",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:a284c3a3-4413-4bda-9a99-ef60b057cc3a",
+  "serialNumber": "urn:uuid:f81dd931-ce62-498a-ac6f-d9ac5b0be399",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-31T11:30:02.144Z",
+    "timestamp": "2026-05-31T18:05:40.945Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.14.10",
+      "bom-ref": "@blamejs/core@0.14.12",
       "type": "application",
       "name": "blamejs",
-      "version": "0.14.10",
+      "version": "0.14.12",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.14.10",
+      "purl": "pkg:npm/%40blamejs/core@0.14.12",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.14.10",
+      "ref": "@blamejs/core@0.14.12",
       "dependsOn": []
     }
   ]