@blamejs/core 0.14.11 → 0.14.13

package/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,
   },

package/lib/archive-wrap.js

@@ -20,11 +20,32 @@
  * seal keyed by the vault root (no key-pair to manage; unwrap
  * re-derives from the tenant id). b.backup's `cryptoStrategy:
  * "recipient"` consumes the same substrate.
+ *
+ * Vault rotation and the tenant strategy: a `recipient: "tenant"`
+ * envelope is keyed by the vault root (`b.agent.tenant.derivedKey`),
+ * which changes whenever the vault keypair / passphrase rotates
+ * (`b.vaultRotate.rotate`). The rotation pipeline re-seals values it
+ * can WALK — sealed DB columns + the framework's sealed key files. It
+ * CANNOT walk tenant archive blobs: they are opaque bytes the operator
+ * placed in files / object-storage / backups outside any store the
+ * pipeline indexes. After a rotation, an old tenant envelope no longer
+ * opens (its key was derived from the OLD root) — a data-loss class
+ * (CWE-325 missing cryptographic step / CWE-665 improper
+ * initialization of the new-root key) if the operator assumed rotation
+ * re-sealed them. The operator must enumerate every tenant blob
+ * location and re-wrap each one old-root -> new-root with
+ * `b.archive.rewrapTenant` BEFORE retiring the old vault keypair (keep
+ * the old keypair JSON until the migration completes — it is the only
+ * material that can open the old envelopes). Re-open this gap to a
+ * framework-side index only if operators surface demand for the
+ * framework to track blob locations; today the operator owns the
+ * inventory because blob placement is operator-controlled.
  */
 
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var { defineClass } = require("./framework-error");
+var validateOpts = require("./validate-opts");
 
 var ArchiveWrapError = defineClass("ArchiveWrapError", { alwaysPermanent: true });
 
@@ -84,7 +105,11 @@ var ARCH_PASSPHRASE_HEADER_BYTES = C.BYTES.bytes(7);
  *                   AAD so one tenant's envelope cannot open under
  *                   another's key. No recipient key-pair to manage;
  *                   `unwrap` re-derives from the same `tenantId`. Requires
- *                   an initialized vault.
+ *                   an initialized vault. The derived key tracks the vault
+ *                   root: after a vault rotation the operator must re-wrap
+ *                   each stored tenant blob old-root -> new-root via
+ *                   `b.archive.rewrapTenant` (the rotation pipeline does
+ *                   not walk operator-placed blobs).
  *
  * @opts
  *   recipient:  object | string,   // see strategies above; required
@@ -239,10 +264,207 @@ function _tenantKey(tenantId) {
 // AAD context-binds the symmetric envelope to the tenant: the Poly1305
 // tag covers this, so a tenant-A envelope cannot be decrypted under
 // tenant-B's key even if an attacker swaps headers between envelopes.
+// Independent of the vault root, so rotation re-wrap reuses the SAME
+// AAD — only the derived key changes old-root -> new-root.
 function _tenantAad(tenantId) {
   return Buffer.from("archive-wrap|tenant|" + tenantId, "utf8");
 }
 
+// Domain-separation constants for the explicit-root fallback derivation.
+// MUST stay byte-identical to b.agent.tenant's _deriveTenantKeyBytes
+// (TENANT_KDF_LABEL / TENANT_KEY_BYTES) so a key derived here under the
+// LIVE root equals agentTenant().derivedKey(tenantId, "archive-wrap").
+// The fallback only runs when the agent-tenant build predates the
+// explicit-root export; the live-root path (_tenantKey) always uses
+// agent-tenant directly.
+var TENANT_KDF_LABEL = "blamejs.agent.tenant/v1";
+var TENANT_KEY_BYTES = C.BYTES.bytes(32);
+
+// Resolve a tenant's archive-wrap key under an EXPLICIT vault root
+// (the serialized keys JSON of the old OR new keypair) rather than the
+// live singleton — the rotation re-wrap path must straddle two roots in
+// one process. Prefers b.agent.tenant's explicit-root export so the
+// derivation stays single-sourced; falls back to a byte-identical local
+// derivation when running against an agent-tenant build that predates
+// that export (coordination escape hatch, removed once the floor moves).
+function _tenantKeyWithRoot(tenantId, rootKeysJson) {
+  if (typeof tenantId !== "string" || tenantId.length === 0) {
+    throw new ArchiveWrapError("archive-wrap/no-tenant-id",
+      "rewrapTenant: tenantId is required (a non-empty string)");
+  }
+  if (typeof rootKeysJson !== "string" || rootKeysJson.length === 0) {
+    throw new ArchiveWrapError("archive-wrap/bad-root",
+      "rewrapTenant: root keys JSON is required (b.vault.getKeysJson() output for the old/new keypair)");
+  }
+  var at = agentTenant();
+  if (typeof at.derivedKeyWithRoot === "function") {
+    return Buffer.from(at.derivedKeyWithRoot(tenantId, TENANT_KEY_PURPOSE, rootKeysJson), "hex");
+  }
+  // Byte-identical fallback: SHAKE256(label || 0x00 || SHA3-512(rootKeysJson)
+  // || 0x00 || tenantId || 0x00 || purpose, 32). Matches the agent-tenant
+  // KDF construction exactly so the live-root and explicit-root keys agree.
+  var rootBytes = Buffer.from(bCrypto().sha3Hash(rootKeysJson), "hex");
+  var input = Buffer.concat([
+    Buffer.from(TENANT_KDF_LABEL, "utf8"),
+    Buffer.from([0x00]),
+    rootBytes,
+    Buffer.from([0x00]),
+    Buffer.from(tenantId, "utf8"),
+    Buffer.from([0x00]),
+    Buffer.from(TENANT_KEY_PURPOSE, "utf8"),
+  ]);
+  return bCrypto().kdf(input, TENANT_KEY_BYTES);
+}
+
+/**
+ * @primitive b.archive.rewrapTenant
+ * @signature b.archive.rewrapTenant(opts)
+ * @since     0.14.12
+ * @status    stable
+ * @related   b.archive.wrap, b.archive.unwrap, b.agent.tenant.derivedKey, b.vaultRotate.rotate
+ *
+ * Re-wrap a single `recipient: "tenant"` archive blob from the old
+ * vault root to the new one after a vault rotation. The tenant
+ * strategy keys each envelope off the vault root
+ * (`b.agent.tenant.derivedKey`); rotating the vault keypair changes
+ * that root, so envelopes sealed under the old root no longer open.
+ *
+ * The vault rotation pipeline (`b.vaultRotate.rotate`) re-seals every
+ * value it can WALK — sealed DB columns and the framework's sealed key
+ * files. It cannot reach tenant archive blobs: those are opaque bytes
+ * the operator placed in files / object-storage / backups outside any
+ * store the framework indexes. The framework does not track blob
+ * locations, so the operator enumerates them and calls this primitive
+ * once per blob, supplying both the old and new keypair JSON.
+ *
+ * The re-wrap unwraps under the old-root tenant key, then re-wraps
+ * under the new-root tenant key with the SAME tenant-bound AAD — the
+ * plaintext archive bytes are recovered in memory and immediately
+ * re-sealed; the AEAD tag on the new envelope binds the same
+ * `tenantId`, so cross-tenant replay is refused exactly as on a fresh
+ * `b.archive.wrap`.
+ *
+ * Run this BEFORE retiring the old vault keypair: the old keypair JSON
+ * is the only material that can open the old envelopes (CWE-325 —
+ * skipping it strands the blobs; CWE-665 — re-keying under the wrong
+ * root yields an unopenable envelope). Refuses any non-tenant envelope
+ * (recipient / passphrase magic) so a key-pair or passphrase blob is
+ * never silently mis-routed through the tenant key path.
+ *
+ * @opts
+ *   blob:         Buffer | Uint8Array,   // a tenant (BAWRP v2) envelope; required
+ *   oldRootJson:  string,                // b.vault.getKeysJson() of the OLD keypair; required
+ *   newRootJson:  string,                // b.vault.getKeysJson() of the NEW keypair; required
+ *   tenantId:     string,                // the tenant the blob was sealed for; required
+ *
+ * @example
+ *   var oldRoot = oldKeys;  // captured before rotation
+ *   var newKeys = b.vault.getKeysJson();
+ *   // operator enumerates blob locations (framework does not index them):
+ *   for (var loc of operatorBlobInventory) {
+ *     var rewrapped = b.archive.rewrapTenant({
+ *       blob:        fs.readFileSync(loc),
+ *       oldRootJson: oldRoot,
+ *       newRootJson: newKeys,
+ *       tenantId:    "alpha",
+ *     });
+ *     fs.writeFileSync(loc, rewrapped);
+ *   }
+ */
+function rewrapTenant(opts) {
+  opts = opts || {};
+  var blob = opts.blob;
+  if (!Buffer.isBuffer(blob) && !(blob instanceof Uint8Array)) {
+    throw new ArchiveWrapError("archive-wrap/bad-input",
+      "rewrapTenant: opts.blob must be a Buffer or Uint8Array");
+  }
+  var buf = Buffer.isBuffer(blob) ? blob : Buffer.from(blob);
+  if (buf.length < ARCH_WRAP_HEADER_BYTES) {
+    throw new ArchiveWrapError("archive-wrap/bad-magic",
+      "rewrapTenant: blob shorter than 6-byte archive-wrap header");
+  }
+  var magic = buf.slice(0, 5).toString("ascii");
+  if (magic !== ARCH_WRAP_MAGIC) {
+    throw new ArchiveWrapError("archive-wrap/bad-magic",
+      "rewrapTenant: blob does not start with archive-wrap magic " +
+      JSON.stringify(ARCH_WRAP_MAGIC) + "; got " + JSON.stringify(magic) +
+      " (only recipient: \"tenant\" envelopes are root-keyed; key-pair / passphrase " +
+      "envelopes are re-keyed by re-encrypting to a new recipient, not by rewrapTenant)");
+  }
+  if (buf[5] !== ARCH_WRAP_VERSION_TENANT) {
+    throw new ArchiveWrapError("archive-wrap/not-tenant-envelope",
+      "rewrapTenant: blob is not a recipient: \"tenant\" envelope (version byte " + buf[5] +
+      ", expected " + ARCH_WRAP_VERSION_TENANT + "). Key-pair / peer-cert envelopes are not " +
+      "root-keyed — re-encrypt them to a fresh recipient instead.");
+  }
+  var aad = _tenantAad(opts.tenantId);
+  var oldKey = _tenantKeyWithRoot(opts.tenantId, opts.oldRootJson);
+  var packedBody = buf.slice(ARCH_WRAP_HEADER_BYTES);
+  var plaintext;
+  try {
+    plaintext = bCrypto().decryptPacked(packedBody, oldKey, aad);
+  } catch (e) {
+    var derr = new ArchiveWrapError("archive-wrap/decrypt-failed",
+      "rewrapTenant: blob did not open under the OLD root + tenantId (wrong tenantId, " +
+      "wrong old keypair, or already re-wrapped?): " + ((e && e.message) || String(e)));
+    derr.cause = e;
+    throw derr;
+  }
+  var newKey = _tenantKeyWithRoot(opts.tenantId, opts.newRootJson);
+  var rePacked = bCrypto().encryptPacked(Buffer.from(plaintext), newKey, aad);
+  var header = Buffer.alloc(ARCH_WRAP_HEADER_BYTES);
+  header.write(ARCH_WRAP_MAGIC, 0, 5, "ascii");
+  header[5] = ARCH_WRAP_VERSION_TENANT;
+  return Buffer.concat([header, rePacked]);
+}
+
+// AAD_ROTATION descriptor — lets the vault-key rotation pipeline
+// discover this module's re-seal hook (eager-register / detect-and-
+// refuse). Unlike DB-column AAD modules, tenant archive blobs live
+// OUTSIDE any store the pipeline walks (operator-placed files / object-
+// storage / backups), so `backend: "external"`: the framework cannot
+// enumerate them. `reseal` iterates an OPERATOR-supplied backing store
+// — an object exposing `list()` (returns `[{ id, blob, tenantId }]`)
+// and `put(id, blob)` — re-wrapping every entry old-root -> new-root
+// via rewrapTenant and writing the result back. The operator owns the
+// inventory; the framework owns the per-blob crypto.
+function _resealExternal(args) {
+  args = args || {};
+  var store = args.store;
+  validateOpts.requireMethods(store, ["list", "put"],
+    "AAD_ROTATION.reseal: opts.store (tenant archive blobs are operator-placed; the framework cannot enumerate them)",
+    ArchiveWrapError, "archive-wrap/bad-store");
+  validateOpts.requireNonEmptyString(args.oldRootJson,
+    "AAD_ROTATION.reseal: oldRootJson (b.vault.getKeysJson() output)", ArchiveWrapError, "archive-wrap/bad-root");
+  validateOpts.requireNonEmptyString(args.newRootJson,
+    "AAD_ROTATION.reseal: newRootJson (b.vault.getKeysJson() output)", ArchiveWrapError, "archive-wrap/bad-root");
+  var entries = store.list();
+  if (!Array.isArray(entries)) {
+    throw new ArchiveWrapError("archive-wrap/bad-store",
+      "AAD_ROTATION.reseal: store.list() must return an array of { id, blob, tenantId }");
+  }
+  var resealed = 0;
+  for (var i = 0; i < entries.length; i += 1) {
+    var e = entries[i];
+    if (!e || typeof e.id === "undefined" ||
+        (!Buffer.isBuffer(e.blob) && !(e.blob instanceof Uint8Array)) ||
+        typeof e.tenantId !== "string") {
+      throw new ArchiveWrapError("archive-wrap/bad-store-entry",
+        "AAD_ROTATION.reseal: every store entry must be { id, blob: Buffer, tenantId: string }; " +
+        "entry index " + i + " is malformed");
+    }
+    var rewrapped = rewrapTenant({
+      blob:        e.blob,
+      oldRootJson: args.oldRootJson,
+      newRootJson: args.newRootJson,
+      tenantId:    e.tenantId,
+    });
+    store.put(e.id, rewrapped);
+    resealed += 1;
+  }
+  return { table: "archive-wrap:tenant-blobs", resealed: resealed };
+}
+
 // Returns { version, body } so wrap() can stamp the right version byte:
 // hybrid-KEM recipients use ARCH_WRAP_VERSION with a base64 envelope
 // body; the tenant strategy uses ARCH_WRAP_VERSION_TENANT with a
@@ -561,6 +783,7 @@ function _estimatePassphraseEntropyBits(passphrase) {
 module.exports = {
   wrap:                  wrap,
   unwrap:                unwrap,
+  rewrapTenant:          rewrapTenant,
   wrapWithPassphrase:    wrapWithPassphrase,
   unwrapWithPassphrase:  unwrapWithPassphrase,
   sniffEnvelope:         sniffEnvelope,
@@ -570,4 +793,14 @@ module.exports = {
   _isPassphraseMagic:    _isPassphraseMagic,
   ARCH_WRAP_MAGIC:       ARCH_WRAP_MAGIC,
   ARCH_PASSPHRASE_MAGIC: ARCH_PASSPHRASE_MAGIC,
+  // Vault-rotation re-seal hook. backend: "external" — tenant archive
+  // blobs live outside any store the rotation pipeline walks, so the
+  // operator supplies the backing store to reseal().
+  AAD_ROTATION: {
+    table:         "archive-wrap:tenant-blobs",
+    rowIdField:    "id",
+    schemaVersion: "1",
+    backend:       "external",
+    reseal:        _resealExternal,
+  },
 };

package/lib/archive.js

@@ -554,6 +554,7 @@ module.exports = {
   gz:                   archiveGz.gz,
   wrap:                 archiveWrap.wrap,
   unwrap:               archiveWrap.unwrap,
+  rewrapTenant:         archiveWrap.rewrapTenant,
   wrapWithPassphrase:   archiveWrap.wrapWithPassphrase,
   unwrapWithPassphrase: archiveWrap.unwrapWithPassphrase,
   sniffEnvelope:        archiveWrap.sniffEnvelope,