@blamejs/blamejs-shop 0.3.39 → 0.3.41

package/lib/vendor/blamejs/lib/agent-orchestrator.js

@@ -58,6 +58,8 @@ var { defineClass }   = require("./framework-error");
 var guardAgentRegistry = require("./guard-agent-registry");
 var bCrypto           = require("./crypto");
 var agentAudit        = require("./agent-audit");
+var vaultAad          = require("./vault-aad");
+var validateOpts      = require("./validate-opts");
 
 var audit             = lazyRequire(function () { return require("./audit"); });
 var cluster           = lazyRequire(function () { return require("./cluster"); });
@@ -796,13 +798,119 @@ function _safeAudit(ctx, action, actor, metadata) {
   agentAudit.safeAudit(ctx.audit, action, actor, metadata);
 }
 
+// ---- Vault-key rotation: out-of-band reseal hook -------------------------
+//
+// Registry rows are AAD-sealed on an OPERATOR-SUPPLIED backend (opts.backend /
+// the in-memory default), NOT in the framework's db.enc. The vault-key
+// rotation pipeline (b.vaultRotate.rotate) only walks tables inside db.enc,
+// so it cannot reach this backend — sealed tenantId + metadata cells would be
+// ORPHANED under the old vault root after a rotation (CWE-320 cryptographic-
+// key-management failure: ciphertext stranded under a retired key, then
+// unreadable once the old keypair is destroyed). This reseal hook rotates the
+// backend out-of-band, composing the SAME explicit-root primitive the in-tree
+// pipeline uses (vaultAad.resealRoot) and the SAME AAD builder the seal path
+// used (cryptoField._aadParts) so the re-sealed AAD tuple is byte-identical —
+// one source of truth, no drift.
+//
+// Reseal store contract: the durable backend the operator wired for
+// opts.backend already exposes list() (enumerate every row) + set(name, row)
+// (write by name). The row identity column `name` is the AAD anchor and is
+// never sealed, so it is always present in plaintext for the write-back.
+// `tenantId` is a plain sealed string; `metadata` is a sealed JSON string —
+// both are AAD-sealed cells, so each is re-sealed in place under the same AAD
+// without unwrapping the metadata JSON.
+/**
+ * @primitive b.agent.orchestrator.reseal
+ * @signature b.agent.orchestrator.reseal(opts)
+ * @since      0.14.12
+ * @status     stable
+ * @compliance gdpr, soc2
+ * @related    b.vault.getKeysJson, b.cryptoField.sealRow
+ *
+ * Re-seals every AAD-bound registry cell (tenantId / metadata) on an
+ * operator-supplied backend from the OLD vault keypair to the NEW one,
+ * out-of-band. The in-tree vault-key rotation pipeline only walks tables
+ * inside `db.enc`, so an operator-supplied orchestrator backend is
+ * unreachable to it — after a keypair rotation its cells would otherwise be
+ * orphaned under the retired root (CWE-320). Rebuilds each cell's AAD from
+ * the registered schema (one source of truth); only AAD-sealed cells are
+ * touched. The `name` row-identity column is the AAD anchor and is never
+ * sealed, so it is always present for the write-back.
+ *
+ * @opts
+ *   store:       Object,   // { list(): rows[], set(name, row) } (the create() backend contract)
+ *   oldRootJson: string,   // b.vault.getKeysJson() of the retired keypair
+ *   newRootJson: string,   // b.vault.getKeysJson() of the new keypair
+ *
+ * @example
+ *   await b.agent.orchestrator.reseal({ store: backend, oldRootJson: oldKeys, newRootJson: newKeys });
+ *   // → { table: "agent_orchestrator_registry", resealed: 4 }
+ */
+function reseal(args) {
+  args = args || {};
+  validateOpts.requireNonEmptyString(args.oldRootJson,
+    "reseal: oldRootJson (b.vault.getKeysJson() of the OLD keypair)",
+    AgentOrchestratorError, "agent-orchestrator/bad-root");
+  validateOpts.requireNonEmptyString(args.newRootJson,
+    "reseal: newRootJson (b.vault.getKeysJson() of the NEW keypair)",
+    AgentOrchestratorError, "agent-orchestrator/bad-root");
+  var store = args.store;
+  validateOpts.requireMethods(store, ["list", "set"],
+    "reseal: operator store (same backend contract as create({ backend }))",
+    AgentOrchestratorError, "agent-orchestrator/bad-reseal-store");
+  _ensureSealTable();
+  var schema = cryptoField().getSchema(SEAL_TABLE);
+  return Promise.resolve(store.list()).then(function (rows) {
+    if (!Array.isArray(rows)) {
+      throw new AgentOrchestratorError("agent-orchestrator/bad-reseal-store",
+        "reseal: store.list() must resolve to an array of rows");
+    }
+    var chain = Promise.resolve();
+    var resealed = 0;
+    rows.forEach(function (row) {
+      if (!row || typeof row !== "object") return;
+      var changed = false;
+      for (var f = 0; f < schema.sealedFields.length; f += 1) {
+        var column = schema.sealedFields[f];
+        var value = row[column];
+        // Only AAD-sealed cells need rotating. Vault-less / pre-sealing rows
+        // carry plain values (sealRow leaves them untouched when vault-less);
+        // resealRoot would throw not-sealed on a plain value, so skip.
+        if (typeof value !== "string" || !vaultAad.isAadSealed(value)) continue;
+        var aadParts = cryptoField()._aadParts(schema, SEAL_TABLE, column, row);
+        row[column] = vaultAad.resealRoot(value, aadParts, args.oldRootJson, args.newRootJson);
+        changed = true;
+      }
+      if (changed) {
+        resealed += 1;
+        chain = chain.then(function () { return store.set(row.name, row); });
+      }
+    });
+    return chain.then(function () { return { table: SEAL_TABLE, resealed: resealed }; });
+  });
+}
+
 module.exports = {
   create:                   create,
   shardFor:                 shardFor,
+  reseal:                   reseal,
   AgentOrchestratorError:   AgentOrchestratorError,
   guards: {
     registry: guardAgentRegistry,
   },
+  // AAD_ROTATION — the vault-key rotation descriptor every framework module
+  // that seals an {aad:true} table on an OPERATOR-SUPPLIED backend (outside
+  // db.enc) exports, so an operator can register it with a rotation eager-
+  // sweep and the codebase-patterns detect-and-refuse gate can confirm no
+  // such external-store table is silently orphaned. `backend: "external"`
+  // flags that the in-tree b.vaultRotate.rotate pipeline cannot reach it.
+  AAD_ROTATION: {
+    table:         SEAL_TABLE,
+    rowIdField:    "name",
+    schemaVersion: "1",
+    backend:       "external",
+    reseal:        reseal,
+  },
   // Test-only — flush the salted FNV basis cache so a vault reset
   // between tests forces re-derivation.
   _resetForTest: function () { _saltedFnvBasisCache = null; },

package/lib/vendor/blamejs/lib/agent-snapshot.js

@@ -53,6 +53,8 @@ var bCrypto               = require("./crypto");
 var guardSnapshotEnvelope = require("./guard-snapshot-envelope");
 var agentAudit            = require("./agent-audit");
 var safeJson              = require("./safe-json");
+var vaultAad              = require("./vault-aad");
+var validateOpts          = require("./validate-opts");
 
 var audit                 = lazyRequire(function () { return require("./audit"); });
 var auditSign             = lazyRequire(function () { return require("./audit-sign"); });
@@ -163,6 +165,117 @@ function create(opts) {
   };
 }
 
+// ---- Wrapped-AAD root re-seal (vault-key rotation pipeline) ----------------
+
+/**
+ * @primitive b.agent.snapshot.reseal
+ * @signature b.agent.snapshot.reseal(opts)
+ * @since     0.14.12
+ * @status    stable
+ * @related   b.agent.snapshot.create, b.vault.getKeysJson
+ *
+ * Re-seal every persisted snapshot envelope from the OLD vault root to
+ * the NEW vault root under the SAME column-shaped AAD, for a vault-key
+ * rotation. The snapshot seal is a `vault.aad:` ciphertext hidden behind
+ * the `snap-sealed-v1:` wrapper prefix and written to an operator
+ * backend, so a `db.enc` scan for the bare `vault.aad:` prefix can
+ * neither detect nor reach it — the rotation pipeline drives the re-key
+ * through this explicit backend walk. Each row is unsealed under the old
+ * root and re-sealed under the new root in memory (composing
+ * `b.vault.aad.resealRoot`); the plaintext envelope is never written to
+ * operator-readable storage. The decorative wrapper fields the backend's
+ * `list()` filters on (`snapshotId` / `takenAt` / `tenantId`) are
+ * preserved, so the index is untouched.
+ *
+ * `allowPlaintext` envelopes (no `sealed` wrapper) carry no AAD-sealed
+ * blob to re-key and are skipped; the returned `resealed` count reflects
+ * only re-sealed rows. A row sealed by a non-default KMS sealer (the
+ * inner blob is not a `vault.aad:` value) is refused — re-key it through
+ * the operator's own KMS, not this path.
+ *
+ * @opts
+ *   backend:     { put, get, list },  // the same backend create() was wired with
+ *   oldRootJson: string,              // b.vault.getKeysJson() of the OLD keypair
+ *   newRootJson: string,              // b.vault.getKeysJson() of the NEW keypair
+ *
+ * @example
+ *   var result = await b.agent.snapshot.reseal({
+ *     backend:     operatorBackend,
+ *     oldRootJson: oldKeysJson,
+ *     newRootJson: newKeysJson,
+ *   });
+ *   result.table;      // → "agent.snapshot"
+ *   result.resealed;   // → <count of re-keyed snapshots>
+ */
+async function reseal(opts) {
+  opts = opts || {};
+  var backend = opts.backend;
+  validateOpts.requireMethods(backend, ["put", "get", "list"],
+    "reseal: opts.backend (same backend create() was wired with)",
+    AgentSnapshotError, "agent-snapshot/bad-backend");
+  validateOpts.requireNonEmptyString(opts.oldRootJson,
+    "reseal: opts.oldRootJson (b.vault.getKeysJson() of the OLD keypair)",
+    AgentSnapshotError, "agent-snapshot/bad-root");
+  validateOpts.requireNonEmptyString(opts.newRootJson,
+    "reseal: opts.newRootJson (b.vault.getKeysJson() of the NEW keypair)",
+    AgentSnapshotError, "agent-snapshot/bad-root");
+
+  var entries = await backend.list();
+  if (!Array.isArray(entries)) return { table: SNAPSHOT_TABLE, resealed: 0 };
+  var resealed = 0;
+  for (var i = 0; i < entries.length; i += 1) {
+    var snapshotId = entries[i] && entries[i].snapshotId;
+    if (typeof snapshotId !== "string" || snapshotId.length === 0) continue;
+    var raw = await backend.get(snapshotId);
+    if (!raw) continue;
+    // Only the sealed-wrapper shape carries a re-keyable blob. The
+    // allowPlaintext path stores the bare envelope (no `sealed`) — skip.
+    if (!raw.sealed || typeof raw.sealed !== "string" ||
+        raw.sealed.indexOf(SEALED_PREFIX) !== 0) {
+      continue;
+    }
+    var innerBlob = raw.sealed.slice(SEALED_PREFIX.length);
+    // The inner blob is a vault.aad: ciphertext (when sealed by the
+    // default b.vault.aad sealer — the only sealer resealRoot can
+    // re-key). A custom KMS sealer's blob isn't a vault.aad: value, so
+    // refuse rather than silently no-op: the operator must drive the
+    // re-key through their own KMS.
+    if (!vaultAad.isAadSealed(innerBlob)) {
+      throw new AgentSnapshotError("agent-snapshot/not-vault-sealed",
+        "reseal: snapshot " + snapshotId + " was sealed by a non-vault sealer " +
+        "(no " + JSON.stringify(vaultAad.AAD_PREFIX) + " prefix on the inner blob); " +
+        "re-key it through the KMS the operator wired as opts.sealer at create() time");
+    }
+    // Rebuild the EXACT AAD the envelope was sealed under via the
+    // module's own _snapshotAad builder — single source of truth with
+    // the seal (_persist) + unseal (_unwrapAndVerify) paths. The wrapper
+    // carries snapshotId; schemaVersion mirrors the unseal path's
+    // `raw.schemaVersion || SCHEMA_VERSION` fallback so an envelope
+    // written under an older SCHEMA_VERSION re-keys under its original
+    // AAD, not the current one.
+    var aad = _snapshotAad({
+      snapshotId:    snapshotId,
+      schemaVersion: raw.schemaVersion != null ? raw.schemaVersion : SCHEMA_VERSION,
+    });
+    var rekeyed;
+    try {
+      rekeyed = vaultAad.resealRoot(innerBlob, aad, opts.oldRootJson, opts.newRootJson);
+    } catch (e) {
+      throw new AgentSnapshotError("agent-snapshot/reseal-failed",
+        "reseal: snapshot " + snapshotId + " failed to re-key — the value may not have " +
+        "been sealed under oldRootJson + this AAD, or the bytes are tampered (" +
+        ((e && e.message) || String(e)) + ")");
+    }
+    // Re-apply the prefix + preserve every decorative wrapper field
+    // (snapshotId / takenAt / tenantId the backend's list() filters on)
+    // so the rotation leaves the index untouched.
+    var rewritten = Object.assign({}, raw, { sealed: SEALED_PREFIX + rekeyed });
+    await backend.put(snapshotId, rewritten);
+    resealed += 1;
+  }
+  return { table: SNAPSHOT_TABLE, resealed: resealed };
+}
+
 // ---- Signer + sealer resolution -------------------------------------------
 
 function _resolveSigner(ctx) {
@@ -666,11 +779,35 @@ function _frameworkVersion() {
   catch (_e) { return "unknown"; }
 }
 
+// AAD_ROTATION — the eager-register descriptor the vault-key rotation
+// pipeline consumes. backend "external" because snapshot envelopes live
+// in an operator-supplied backend (not the framework db.enc store), so a
+// `db.enc` scan for the bare "vault.aad:" prefix can't reach them — the
+// pipeline drives the re-key through `reseal` against the same backend.
+// The descriptor's `reseal({ store, oldRootJson, newRootJson })` maps the
+// pipeline's generic `store` term onto this module's `backend` (the
+// snapshot backing store), then defers to the module's own reseal.
 module.exports = {
   create:               create,
+  reseal:               reseal,
   SCHEMA_VERSION:       SCHEMA_VERSION,
+  SEALED_PREFIX:        SEALED_PREFIX,
   AgentSnapshotError:   AgentSnapshotError,
   guards: {
     envelope: guardSnapshotEnvelope,
   },
+  AAD_ROTATION: {
+    table:         SNAPSHOT_TABLE,
+    rowIdField:    "snapshotId",
+    schemaVersion: String(SCHEMA_VERSION),
+    backend:       "external",
+    reseal: function (rotationOpts) {
+      rotationOpts = rotationOpts || {};
+      return reseal({
+        backend:     rotationOpts.store || rotationOpts.backend,
+        oldRootJson: rotationOpts.oldRootJson,
+        newRootJson: rotationOpts.newRootJson,
+      });
+    },
+  },
 };

package/lib/vendor/blamejs/lib/agent-tenant.js

@@ -58,6 +58,8 @@ var guardTenantId    = require("./guard-tenant-id");
 var bCrypto          = require("./crypto");
 var agentAudit       = require("./agent-audit");
 var safeJson         = require("./safe-json");
+var vaultAad         = require("./vault-aad");
+var validateOpts     = require("./validate-opts");
 
 var audit            = lazyRequire(function () { return require("./audit"); });
 var cryptoField      = lazyRequire(function () { return require("./crypto-field"); });
@@ -115,8 +117,12 @@ var CROSS_TENANT_ADMIN_SCOPE = "framework-cross-tenant-admin";
 
 // Per-tenant key derivation domain separators. NIST SP 800-108 r1 §5.1
 // KDF-in-Counter shape — fixed "label" + tenantId-as-salt + purpose-as-
-// info. Operator passphrase rotation produces a fresh master, breaking
-// every prior tenant ciphertext (operator intent: rotation = re-seal).
+// info. The root secret is the vault master keypair (SHA3-512 of
+// b.vault.getKeysJson()); rotating the vault keypair changes the root,
+// so every tnt-v1: cell sealed under the old root must be re-sealed
+// under the new root. That migration is NOT automatic — it runs via the
+// AAD_ROTATION reseal hook (see `reseal` below), which the vault-key
+// rotation pipeline composes per the explicit-root primitive contract.
 var TENANT_KDF_LABEL = "blamejs.agent.tenant/v1";
 // 32 bytes — XChaCha20-Poly1305 key length. Distinct from the audit
 // truncation buffer so future key-length bumps don't have to chase a
@@ -391,20 +397,32 @@ function _check(ctx, actor, agentTenantId) {
 // rootKey is SHA3-512(vault.getKeysJson()). Same derivation `b.vault.aad`
 // uses internally — the vault's master keypair PEM is the secret KDK.
 // Rotating the vault passphrase / keypair (b.vaultRotate.rotate)
-// changes rootKey, which changes every derived tenant key — operator
-// intent for rotation IS re-seal.
+// changes rootKey, which changes every derived tenant key — so every
+// prior tnt-v1: cell must be re-sealed old-root -> new-root. The
+// `reseal` hook below (eager-registered via AAD_ROTATION) performs that
+// migration; it uses the explicit-root variant of the tenant-key
+// derivation (rootKeysJson arg) to decrypt under the old root and
+// re-encrypt under the new one within one process.
 //
 // `derivedKey` returns a hex-encoded 32-byte key (64 chars) to keep
 // the wire shape compatible with prior callers. Internal callers that
 // need the raw key use `_tenantFieldKey` directly.
 
-function _vaultRootBytes() {
-  // Vault.getKeysJson() throws when the vault hasn't been init'd. That
-  // is the right secure-by-default posture: tenant-derived keys cannot
-  // be produced before the operator has bootstrapped the vault. The
-  // error reaches the caller (sealField / register) so an operator
-  // mis-ordering boot (start agents before vault.init) sees a clear
-  // refusal rather than getting weakened-but-deterministic keys.
+function _vaultRootBytes(rootKeysJson) {
+  // rootKeysJson lets the vault-key rotation pipeline derive the per-
+  // tenant key under a SPECIFIC vault root (old or new keypair) within
+  // one process — mirrors vault-aad._deriveKey's explicit-root arg. When
+  // omitted it reads the live singleton via vault().getKeysJson().
+  //
+  // getKeysJson() throws when the vault hasn't been init'd. That is the
+  // right secure-by-default posture: tenant-derived keys cannot be
+  // produced before the operator has bootstrapped the vault. The error
+  // reaches the caller (sealField / register) so an operator mis-ordering
+  // boot (start agents before vault.init) sees a clear refusal rather
+  // than getting weakened-but-deterministic keys.
+  if (typeof rootKeysJson === "string" && rootKeysJson.length > 0) {
+    return Buffer.from(bCrypto.sha3Hash(rootKeysJson), "hex");
+  }
   var keysJson;
   try { keysJson = vault().getKeysJson(); }
   catch (e) {
@@ -415,7 +433,7 @@ function _vaultRootBytes() {
   return Buffer.from(bCrypto.sha3Hash(keysJson), "hex");
 }
 
-function _deriveTenantKeyBytes(tenantId, purpose) {
+function _deriveTenantKeyBytes(tenantId, purpose, rootKeysJson) {
   guardTenantId.validate(tenantId);
   if (typeof purpose !== "string" || purpose.length === 0) {
     throw new AgentTenantError("agent-tenant/bad-purpose",
@@ -424,8 +442,9 @@ function _deriveTenantKeyBytes(tenantId, purpose) {
   // Domain-separated KDF input. NUL separators between fields prevent
   // (label, tenantId="x\0y", purpose="z") colliding with
   // (label, tenantId="x", purpose="y\0z") — same byte concatenation,
-  // different logical context.
-  var rootBytes = _vaultRootBytes();
+  // different logical context. rootKeysJson (optional) pins the vault
+  // root for the rotation reseal path; default is the live singleton.
+  var rootBytes = _vaultRootBytes(rootKeysJson);
   var input = Buffer.concat([
     Buffer.from(TENANT_KDF_LABEL, "utf8"),
     Buffer.from([0x00]),
@@ -455,7 +474,11 @@ function _deriveTenantKeyBytes(tenantId, purpose) {
  * `derivedKey(t, "archive-wrap")` is recoverable later from the same
  * tenant + purpose with no key escrow. Rotating the vault
  * (`b.vaultRotate.rotate`) changes the root and therefore every
- * derived key — by design, rotation intent is re-seal.
+ * derived key, so every cell sealed under the old root must be
+ * re-sealed under the new one. That migration runs through the
+ * module's `reseal` hook (eager-registered via `AAD_ROTATION`), not
+ * silently on the next read — a value sealed under the old root does
+ * not decrypt under the new root until the rotation pipeline walks it.
  *
  * Throws if the vault has not been initialized (keys cannot be derived
  * before bootstrap) or if `purpose` is empty. This is the same
@@ -552,12 +575,14 @@ function _auditFor(ctx, tenantId) {
 
 var TENANT_FIELD_PREFIX = "tnt-v1:";
 
-function _tenantFieldKey(tenantId, table) {
+function _tenantFieldKey(tenantId, table, rootKeysJson) {
   // 32-byte symmetric key for XChaCha20-Poly1305. _deriveTenantKeyBytes
   // returns the raw key bound to the vault master + tenantId + purpose
   // — see the commentary above _derivedKey for the threat
   // model that drove this away from public-input-only derivation.
-  return _deriveTenantKeyBytes(tenantId, "cryptoField:" + table);
+  // rootKeysJson (optional) pins a specific vault root for the rotation
+  // reseal path; default is the live singleton.
+  return _deriveTenantKeyBytes(tenantId, "cryptoField:" + table, rootKeysJson);
 }
 
 function _tenantFieldAad(tenantId, table, field) {
@@ -602,6 +627,25 @@ function _unsealField(tenantId, table, field, ciphertext) {
   return plain.toString("utf8");
 }
 
+// Explicit-root re-seal of a single tnt-v1: cell, old root -> new root,
+// under the SAME (tenantId, table, field) AAD. Decrypts with the key
+// derived from oldRootJson and re-encrypts under newRootJson — the
+// XChaCha20-Poly1305 tag refuses any cell that wasn't sealed under the
+// old root + this AAD (CWE-345 / CWE-441). Values without the prefix
+// (plaintext columns, already-rotated cells) pass through untouched.
+function _resealTenantCell(tenantId, table, field, ciphertext, oldRootJson, newRootJson) {
+  if (typeof ciphertext !== "string" || ciphertext.indexOf(TENANT_FIELD_PREFIX) !== 0) {
+    return ciphertext;
+  }
+  var packed = Buffer.from(ciphertext.slice(TENANT_FIELD_PREFIX.length), "base64");
+  var aad    = _tenantFieldAad(tenantId, table, field);
+  var oldKey = _tenantFieldKey(tenantId, table, oldRootJson);
+  var plain  = bCrypto.decryptPacked(packed, oldKey, aad);
+  var newKey = _tenantFieldKey(tenantId, table, newRootJson);
+  var reSealed = bCrypto.encryptPacked(plain, newKey, aad);
+  return TENANT_FIELD_PREFIX + reSealed.toString("base64");
+}
+
 function _sealRowForTenant(tenantId, table, row) {
   // Adopts the existing b.cryptoField table schema (sealedFields) but
   // routes each field through the per-tenant AEAD instead of the
@@ -663,6 +707,113 @@ function _unsealRowForTenant(ctx, tenantId, table, row) {
   return out;
 }
 
+// ---- Vault-key rotation: re-seal hook -------------------------------------
+//
+// Two root-derived families live in this module, both keyed off the vault
+// master keypair (SHA3-512 of b.vault.getKeysJson()):
+//
+//   1. The registry table "agent_tenant_registry" — a b.cryptoField
+//      {aad:true} table whose `metadata` column holds vault.aad: cells.
+//      Re-sealed old-root -> new-root via vaultAad.resealRoot, with the
+//      AAD tuple rebuilt by cryptoField._aadParts (the SAME builder the
+//      seal side uses — single source of truth, no drift).
+//
+//   2. The tnt-v1: per-tenant sealed cells written by sealField /
+//      sealRowForTenant. Re-sealed via _resealTenantCell, which derives
+//      the per-tenant XChaCha20-Poly1305 key under each root explicitly
+//      and re-binds the (tenantId|table|field) AAD.
+//
+// Both descriptors export a `reseal({ store, oldRootJson, newRootJson })`
+// hook. The vault-key rotation pipeline eager-registers every module's
+// AAD_ROTATION descriptor(s) and calls each reseal with the operator-
+// supplied backing store; without this hook, a keypair rotation would
+// orphan every prior cell (decryptable under neither root). oldRootJson /
+// newRootJson are b.vault.getKeysJson() output for the two keypairs.
+
+var REGISTRY_SCHEMA_VERSION = "1";
+
+// Rebuild the registry's AAD tuple via the cryptoField seal-side builder
+// so the rotate side can never drift from the seal side. The schema
+// shape cryptoField._aadParts reads is { rowIdField, schemaVersion }.
+function _registryAadFor(row) {
+  return cryptoField()._aadParts(
+    { rowIdField: "tenantId", schemaVersion: REGISTRY_SCHEMA_VERSION },
+    SEAL_TABLE, "metadata", row);
+}
+
+// Re-seal the registry table's vault.aad: metadata cells. `store` is the
+// operator's backing store for SEAL_TABLE, exposing list() ->
+// [{ tenantId, metadata, ... }] and set(tenantId, row). Each metadata
+// cell that is vault.aad-sealed is re-sealed old-root -> new-root under
+// the SAME (table, tenantId, "metadata", schemaVersion) AAD.
+function _resealRegistry(args) {
+  var store = args && args.store;
+  validateOpts.requireMethods(store, ["list", "set"],
+    "reseal: store for the '" + SEAL_TABLE + "' table",
+    AgentTenantError, "agent-tenant/bad-reseal-store");
+  validateOpts.requireNonEmptyString(args.oldRootJson,
+    "reseal: oldRootJson (b.vault.getKeysJson output)", AgentTenantError, "agent-tenant/bad-reseal-root");
+  validateOpts.requireNonEmptyString(args.newRootJson,
+    "reseal: newRootJson (b.vault.getKeysJson output)", AgentTenantError, "agent-tenant/bad-reseal-root");
+  return Promise.resolve(store.list()).then(function (rows) {
+    rows = Array.isArray(rows) ? rows : [];
+    var resealed = 0;
+    var chain = Promise.resolve();
+    rows.forEach(function (row) {
+      if (!row || row.tenantId == null) return;
+      var cell = row.metadata;
+      if (!vaultAad.isAadSealed(cell)) return;   // plaintext / already-migrated
+      var aad = _registryAadFor(row);
+      var next = vaultAad.resealRoot(cell, aad, args.oldRootJson, args.newRootJson);
+      var updated = Object.assign({}, row, { metadata: next });
+      resealed += 1;
+      chain = chain.then(function () { return store.set(row.tenantId, updated); });
+    });
+    return chain.then(function () {
+      return { table: SEAL_TABLE, resealed: resealed };
+    });
+  });
+}
+
+// Re-seal the tnt-v1: per-tenant sealed cells. `store` is the operator's
+// backing store for every table that carries tnt-v1: columns, exposing
+// list() -> [{ tenantId, table, field, value, _id? }] (one entry per
+// sealed cell, carrying the context needed to rebuild AAD + key) and
+// write(cell, newValue) to persist the re-sealed value. Plaintext /
+// already-rotated values pass through untouched.
+function _resealTenantCells(args) {
+  var store = args && args.store;
+  validateOpts.requireMethods(store, ["list", "write"],
+    "reseal: store for tnt-v1: cells",
+    AgentTenantError, "agent-tenant/bad-reseal-store");
+  validateOpts.requireNonEmptyString(args.oldRootJson,
+    "reseal: oldRootJson (b.vault.getKeysJson output)", AgentTenantError, "agent-tenant/bad-reseal-root");
+  validateOpts.requireNonEmptyString(args.newRootJson,
+    "reseal: newRootJson (b.vault.getKeysJson output)", AgentTenantError, "agent-tenant/bad-reseal-root");
+  return Promise.resolve(store.list()).then(function (cells) {
+    cells = Array.isArray(cells) ? cells : [];
+    var resealed = 0;
+    var chain = Promise.resolve();
+    cells.forEach(function (cell) {
+      if (!cell || cell.tenantId == null ||
+          typeof cell.table !== "string" || typeof cell.field !== "string") {
+        return;
+      }
+      var value = cell.value;
+      if (typeof value !== "string" || value.indexOf(TENANT_FIELD_PREFIX) !== 0) {
+        return;   // not a tnt-v1: cell — leave untouched
+      }
+      var next = _resealTenantCell(cell.tenantId, cell.table, cell.field,
+        value, args.oldRootJson, args.newRootJson);
+      resealed += 1;
+      chain = chain.then(function () { return store.write(cell, next); });
+    });
+    return chain.then(function () {
+      return { table: TENANT_FIELD_PREFIX, resealed: resealed };
+    });
+  });
+}
+
 // ---- Destroy preconditions ------------------------------------------------
 
 function _checkDestroyPreconditions(args, tenantId) {
@@ -703,11 +854,36 @@ function _inMemoryBackend() {
   };
 }
 
+// Vault-key rotation descriptors — the rotation pipeline eager-registers
+// these and calls each reseal({ store, oldRootJson, newRootJson }) to
+// re-seal this module's two root-derived families old-root -> new-root.
+// backend: "external" — the cells live in the operator's backing store
+// (the registry backend + the operator's tenant data tables), not in the
+// framework's at-rest SQLite, so the rotation pipeline cannot walk them
+// from the data directory alone; the operator supplies the store.
+var AAD_ROTATION = [
+  {
+    table:         SEAL_TABLE,
+    rowIdField:    "tenantId",
+    schemaVersion: REGISTRY_SCHEMA_VERSION,
+    backend:       "external",
+    reseal:        _resealRegistry,
+  },
+  {
+    table:         TENANT_FIELD_PREFIX,   // prefix family, not a single SQL table
+    rowIdField:    "tenantId",
+    schemaVersion: "v1",                  // tnt-v1: ciphertext shape version
+    backend:       "external",
+    reseal:        _resealTenantCells,
+  },
+];
+
 module.exports = {
   create:                    create,
   derivedKey:                _derivedKey,
   CROSS_TENANT_ADMIN_SCOPE:  CROSS_TENANT_ADMIN_SCOPE,
   AgentTenantError:          AgentTenantError,
+  AAD_ROTATION:              AAD_ROTATION,
   guards: {
     tenantId: guardTenantId,
   },