@blamejs/core 0.14.22 → 0.14.25

package/lib/crypto-field.js

@@ -15,14 +15,23 @@
  *   random nonce, so two seals of the same plaintext never collide.
  *
  *   Per-row key (K_row) derivation is opt-in via `declarePerRowKey`.
- *   Tables that opt in get a fresh K_row per INSERT, stored sealed in
- *   `_blamejs_per_row_keys`. AAD on the K_row binds (table, rowId,
- *   info-label) — copying a wrapped K_row from one row to another
- *   fails Poly1305 verification, so a DB-write attacker cannot move
- *   ciphertext between rows to bypass row-scoped erasure. This is the
- *   crypto-shred substrate for `b.subject.eraseHard`: deleting the
- *   K_row entry leaves WAL / replica residual ciphertext mathematically
- *   undecryptable.
+ *   Tables that opt in get a fresh K_row per INSERT: the framework
+ *   generates a 32-byte CSPRNG row-secret, derives
+ *   `K_row = SHAKE256(rowSecret || ":" || table || ":" || rowId || ":"
+ *   || info)`, and stores the SECRET (never K_row) AAD-sealed in
+ *   `_blamejs_per_row_keys.wrappedKey`. Because the secret is random —
+ *   not a function of any on-disk salt — an attacker with full disk
+ *   access cannot re-derive K_row once the wrapped secret is gone. The
+ *   AAD on the wrap binds (table, rowId, column, schemaVersion):
+ *   copying a wrapped secret from one row to another fails Poly1305
+ *   verification, so a DB-write attacker cannot move it between rows to
+ *   bypass row-scoped erasure. Sealed columns on a keyed row carry the
+ *   `vault.row:` prefix and are XChaCha20-Poly1305 ciphertext under
+ *   K_row, AEAD-bound to the same (table, rowId, column) tuple. This is
+ *   the crypto-shred substrate for `b.subject.eraseHard` /
+ *   `b.retention`: destroying the wrapped secret leaves WAL / replica
+ *   residual ciphertext mathematically undecryptable — even with the
+ *   vault root key — because K_row is gone everywhere it ever lived.
  *
  *   Derived hashes (`derivedHashes`) provide indexed lookup for sealed
  *   columns: a normalized SHA3 of the plaintext, salted by the vault's
@@ -48,8 +57,8 @@ var vaultAad = require("./vault-aad");
 var validateOpts = require("./validate-opts");
 var numericBounds = require("./numeric-bounds");
 var { defineClass } = require("./framework-error");
-var { sha3Hash, kdf } = require("./crypto");
-var { HASH_PREFIX, VAULT_PREFIX, TIME } = require("./constants");
+var { sha3Hash, kdf, generateBytes, encryptPacked, decryptPacked, generateToken } = require("./crypto");
+var { HASH_PREFIX, VAULT_PREFIX, ROW_PREFIX, TIME } = require("./constants");
 
 // Typed refusal raised when a (actor, table, column) tuple exceeds the
 // opt-in unseal-failure rate cap and is in cooldown. alwaysPermanent —
@@ -132,15 +141,84 @@ var schemas = Object.create(null);
 //
 //   { tableName: { columnName: "eu" | "us" | "global" | <tag> } }
 var columnResidency = Object.create(null);
+// Per-ROW residency registry — table → { residencyColumn, allowedTags }.
+// The row-level sibling of columnResidency: one plaintext column on each
+// row carries that row's residency tag; write gates refuse a tagged row
+// landing on an incompatible backend.
+var perRowResidency = Object.create(null);
 
 // Per-row key declaration registry. For tables that opt
-// into per-row keying, b.subject.eraseHard deletes the wrapped K_row
-// from _blamejs_per_row_keys, leaving WAL/replica residual ciphertext
-// undecryptable.
+// into per-row keying, b.subject.eraseHard / b.retention destroy the
+// wrapped row-secret from _blamejs_per_row_keys, leaving WAL/replica
+// residual ciphertext undecryptable.
 //
-//   { tableName: { keySize, info, residencyTag } }
+//   { tableName: { keySize, info } }
 var perRowKeyTables = Object.create(null);
 
+// The framework registry table that holds each row's AAD-sealed
+// row-secret. Named once so the seal-side AAD (materializePerRowKey),
+// the read-side AAD (unsealRow's K_row fetch), and rotate's reseal all
+// quote the byte-identical (table, rowId, column, schemaVersion) tuple.
+var PER_ROW_KEYS_TABLE = "_blamejs_per_row_keys";
+var PER_ROW_KEYS_COLUMN = "wrappedKey";
+var PER_ROW_KEYS_SCHEMA_VERSION = "1";
+
+// Build the canonical AAD parts for a row-secret wrap in
+// _blamejs_per_row_keys. One source of truth so seal / unseal / rotate
+// never drift. `rowId` is the app row's _id (the same value
+// destroyPerRowKey + subject.eraseHard delete on).
+function _wrappedKeyAad(rowId) {
+  return vaultAad.buildColumnAad({
+    table:         PER_ROW_KEYS_TABLE,
+    rowId:         rowId,
+    column:        PER_ROW_KEYS_COLUMN,
+    schemaVersion: PER_ROW_KEYS_SCHEMA_VERSION,
+  });
+}
+
+// Build the canonical AAD parts for a K_row-sealed data cell. Binds the
+// ciphertext to (table, rowId, column, schemaVersion) under K_row so a
+// cell pasted into a different row / column fails Poly1305 — the same
+// copy-protection the AAD-bound vault.aad: path gives, but keyed by the
+// row-scoped K_row rather than the vault root.
+function _rowCellAad(schema, table, column, rowId) {
+  return vaultAad.buildColumnAad({
+    table:         table,
+    rowId:         rowId,
+    column:        column,
+    schemaVersion: (schema && schema.schemaVersion) || "1",
+  });
+}
+
+// Encode a buildColumnAad parts object into the byte form
+// encryptPacked / decryptPacked thread into the AEAD tag. The vault.aad
+// canonicalizer (length-prefixed, sorted-keys) is the one encoder so a
+// K_row cell sealed here and a wrapped-secret sealed via vaultAad.seal
+// agree byte-for-byte on the same logical AAD.
+function _aadBytes(parts) {
+  return vaultAad.canonicalizeAad(parts);
+}
+
+/**
+ * @primitive b.cryptoField.isRowSealed
+ * @signature b.cryptoField.isRowSealed(value)
+ * @since     0.14.25
+ * @related   b.cryptoField.sealRow, b.cryptoField.unsealRow
+ *
+ * Returns `true` when `value` is a string carrying the per-row-key
+ * sealed-cell prefix (`vault.row:`), `false` otherwise. The row-keyed
+ * sibling of `b.vault.aad.isAadSealed` — the read path uses it to route
+ * a cell to its K_row decrypt instead of the vault-root unseal.
+ *
+ * @example
+ *   b.cryptoField.isRowSealed("vault.row:AAAA");   // → true
+ *   b.cryptoField.isRowSealed("vault:AAAA");        // → false
+ *   b.cryptoField.isRowSealed(null);                // → false
+ */
+function isRowSealed(value) {
+  return typeof value === "string" && value.indexOf(ROW_PREFIX) === 0;
+}
+
 /**
  * @primitive b.cryptoField.registerTable
  * @signature b.cryptoField.registerTable(name, opts)
@@ -636,7 +714,7 @@ function clearRateCapForTest() {
 
 /**
  * @primitive b.cryptoField.sealRow
- * @signature b.cryptoField.sealRow(table, row)
+ * @signature b.cryptoField.sealRow(table, row, opts?)
  * @since     0.4.0
  * @compliance hipaa, gdpr, pci-dss
  * @related   b.cryptoField.unsealRow, b.cryptoField.eraseRow, b.vault.seal
@@ -649,6 +727,20 @@ function clearRateCapForTest() {
  * computed BEFORE sealing the source so the indexed lookup column
  * captures the plaintext digest.
  *
+ * When `opts.kRow` (a row-scoped key Buffer from
+ * `materializePerRowKey`) is supplied — wired automatically by the
+ * db-query write boundary for `declarePerRowKey` tables — sealed
+ * columns are instead XChaCha20-Poly1305-encrypted under K_row and
+ * emitted with the `vault.row:` prefix, AEAD-bound to (table, rowId,
+ * column, schemaVersion). The residency-tag column (when the table
+ * declares per-row residency) is NEVER K_row-sealed: the write gate
+ * and reads must see it in plaintext.
+ *
+ * @opts
+ *   kRow:  Buffer,   // row-scoped key from materializePerRowKey; when present,
+ *                    // sealed columns emit vault.row: cells under K_row
+ *   rowId: string,   // the row's _id; required when kRow is present (AAD term)
+ *
  * @example
  *   b.cryptoField.registerTable("patients", {
  *     sealedFields: ["ssn"],
@@ -660,11 +752,29 @@ function clearRateCapForTest() {
  *   typeof sealed.ssnHash;                     // → "string"
  *   row.ssn;                                   // → "123-45-6789" (input untouched)
  */
-function sealRow(table, row) {
+function sealRow(table, row, opts) {
   if (!row) return row;
   var s = schemas[table];
   if (!s) return row;
   var out = Object.assign({}, row);
+  opts = opts || {};
+  var kRow = Buffer.isBuffer(opts.kRow) ? opts.kRow : null;
+  // The per-row-key path needs the row identity for the cell AAD. Prefer
+  // the explicit opts.rowId; fall back to the row's _id. A K_row with no
+  // rowId can't build a stable AAD, so refuse rather than seal under a
+  // placeholder that no later unseal could open.
+  var kRowId = kRow
+    ? String(opts.rowId != null ? opts.rowId : (out._id != null ? out._id : ""))
+    : null;
+  if (kRow && kRowId.length === 0) {
+    throw new CryptoFieldError("crypto-field/seal-row-krow-rowid-missing",
+      "cryptoField.sealRow: opts.kRow supplied but no rowId (set opts.rowId " +
+      "or row._id) — the K_row cell AAD binds (table, rowId, column)");
+  }
+  // Residency tag column must stay plaintext even under a K_row seal —
+  // the write gate reads it before sealRow and reads surface it verbatim.
+  var residencySpec = perRowResidency[table];
+  var residencyCol = residencySpec ? residencySpec.residencyColumn : null;
 
   // Compute derived hashes from plaintext source values BEFORE sealing those
   // sources. If a source value arrives already sealed (e.g. from an internal
@@ -704,25 +814,39 @@ function sealRow(table, row) {
     }
   }
 
-  // Seal fields. Plain mode: vault.seal (idempotent — already-sealed
-  // values pass through). AAD mode: vault.aad.seal binds the AEAD tag
-  // to (table, rowId, column, schemaVersion) — cross-row copy of a
-  // ciphertext fails Poly1305 on read.
+  // Seal fields. Three shapes:
+  //   - K_row (opts.kRow present): XChaCha20-Poly1305 under the row-
+  //     scoped key, vault.row: prefix, AEAD-bound (table, rowId, column,
+  //     schemaVersion). Crypto-shred: destroying the wrapped row-secret
+  //     leaves these cells undecryptable.
+  //   - AAD mode (registerTable({aad:true})): vault.aad.seal binds the
+  //     tag to (table, rowId, column, schemaVersion) under the vault root.
+  //   - plain mode: vault.seal (idempotent — already-sealed pass through).
   for (var i = 0; i < s.sealedFields.length; i++) {
     var field = s.sealedFields[i];
-    if (out[field] !== undefined && out[field] !== null) {
-      if (s.aad) {
-        // Idempotent: already-AAD-sealed values pass through unchanged.
-        if (typeof out[field] === "string" && vaultAad.isAadSealed(out[field])) {
-          continue;
-        }
-        out[field] = vaultAad.seal(String(out[field]),
-          _aadParts(s, table, field, out));
-      } else {
-        // allow:seal-without-aad — plain-mode legacy table; operator
-        // opts into AAD via registerTable({aad:true})
-        out[field] = vault.seal(String(out[field]));
+    if (out[field] === undefined || out[field] === null) continue;
+    if (kRow && field === residencyCol) continue;   // residency tag stays plaintext
+    if (kRow) {
+      // Idempotent: an already-K_row-sealed value passes through.
+      if (isRowSealed(out[field])) continue;
+      var cellAad = _aadBytes(_rowCellAad(s, table, field, kRowId));
+      // Coerce to a string the same way the vault.aad path does, then
+      // encode as UTF-8 bytes for the AEAD (split out so the byte
+      // coercion is Buffer.from(str, "utf8"), not Buffer.from(String(...))).
+      var plainStr = String(out[field]);
+      out[field] = ROW_PREFIX +
+        encryptPacked(Buffer.from(plainStr, "utf8"), kRow, cellAad).toString("base64");
+    } else if (s.aad) {
+      // Idempotent: already-AAD-sealed values pass through unchanged.
+      if (typeof out[field] === "string" && vaultAad.isAadSealed(out[field])) {
+        continue;
       }
+      out[field] = vaultAad.seal(String(out[field]),
+        _aadParts(s, table, field, out));
+    } else {
+      // allow:seal-without-aad — plain-mode legacy table; operator
+      // opts into AAD via registerTable({aad:true})
+      out[field] = vault.seal(String(out[field]));
     }
   }
 
@@ -744,7 +868,7 @@ function _aadParts(schema, table, column, row) {
 
 /**
  * @primitive b.cryptoField.unsealRow
- * @signature b.cryptoField.unsealRow(table, row, actor?)
+ * @signature b.cryptoField.unsealRow(table, row, actor?, dbHandle?)
  * @since     0.4.0
  * @compliance hipaa, gdpr, pci-dss
  * @related   b.cryptoField.sealRow, b.vault.unseal, b.cryptoField.configureUnsealRateCap
@@ -758,6 +882,18 @@ function _aadParts(schema, table, column, row) {
  * so downstream code sees "no value" instead of crashing the request.
  * The input row is never mutated.
  *
+ * `vault.row:`-prefixed cells (per-row-key tables, `declarePerRowKey`)
+ * are decrypted under the row's K_row: a `dbHandle` (the db-query layer
+ * passes `this._db`) is used to fetch the row's wrapped secret from
+ * `_blamejs_per_row_keys`, unwrap it, and derive K_row once per call.
+ * When a caller passes no `dbHandle` (e.g. `b.breakGlass.unsealRow`,
+ * which reads the row via clusterStorage), the framework's local db is
+ * resolved automatically — the wrapped secret always lives in the local
+ * `_blamejs_per_row_keys`, so keyed reads work on every path.
+ * A missing wrapped row (crypto-shredded by `eraseHard` / `retention`)
+ * makes the unwrap throw → the field nulls + `system.crypto.unseal_failed`
+ * fires, which is correct: shredded data reads as absent.
+ *
  * When an unseal-failure rate cap is configured via
  * `configureUnsealRateCap` (default off), repeated forged-ciphertext
  * failures for a single `(actor, table, column)` tuple trip a cooldown:
@@ -774,7 +910,7 @@ function _aadParts(schema, table, column, row) {
  *   var clear  = b.cryptoField.unsealRow("patients", sealed);
  *   clear.ssn;   // → "123-45-6789"
  */
-function unsealRow(table, row, actor) {
+function unsealRow(table, row, actor, dbHandle) {
   if (!row) return row;
   var s = schemas[table];
   if (!s || s.sealedFields.length === 0) return row;
@@ -782,15 +918,61 @@ function unsealRow(table, row, actor) {
   var capActor = (actor === undefined || actor === null || String(actor).length === 0)
     ? "_anon" : String(actor);
 
+  // Lazy K_row: derive at most once per unsealRow call, only if a cell
+  // actually carries the vault.row: prefix. Cached across fields (and
+  // the failure case is cached too, so a shredded row doesn't re-query
+  // _blamejs_per_row_keys for every sealed column). The row identity for
+  // both the cell AAD and the wrapped-secret lookup is the row's _id —
+  // the same value the seal side (write boundary) passed as rowId and
+  // that destroyPerRowKey / eraseHard delete on.
+  var kRowId = out._id != null ? String(out._id) : "";
+  var keyedTable = hasPerRowKey(table);
+  var _kRowCache;            // undefined = not yet derived; null = derive failed
+  function _kRowOnce() {
+    if (_kRowCache !== undefined) return _kRowCache;
+    _kRowCache = null;
+    if (!keyedTable || kRowId.length === 0) return null;
+    // Resolve a prepared-statement source for the wrapped-secret lookup.
+    // Prefer the caller's dbHandle (the db-query read layer threads it on
+    // first()/all()/stream()); otherwise resolve the framework's local
+    // db ourselves. A DIRECT caller — e.g. b.breakGlass.unsealRow, which
+    // fetches the target row via clusterStorage and calls unsealRow with
+    // no handle — would otherwise null every K_row cell on a keyed table
+    // even though the wrapped secret still exists. The secret always
+    // lives in the local _blamejs_per_row_keys, so keyed reads must work
+    // on every path, not only db-query's. Any failure (db not yet
+    // initialized, unusable handle) → null, and the field reads as absent
+    // exactly as a shredded row would (the caller audits it).
+    var spec = perRowKeyTables[table];
+    var wrap;
+    try {
+      var prep = (dbHandle && typeof dbHandle.prepare === "function")
+        ? dbHandle.prepare.bind(dbHandle)
+        : db().prepare;
+      wrap = prep(
+        'SELECT wrappedKey FROM "' + PER_ROW_KEYS_TABLE + '" WHERE tableName = ? AND rowId = ?'
+      ).get(table, kRowId);
+    } catch (_e) {
+      return null;
+    }
+    if (!wrap || wrap.wrappedKey == null) return null;   // shredded / never materialized
+    _kRowCache = _deriveKRow(_unwrapRowSecret(wrap.wrappedKey, kRowId), table, kRowId, spec);
+    return _kRowCache;
+  }
+
   for (var i = 0; i < s.sealedFields.length; i++) {
     var field = s.sealedFields[i];
     if (out[field]) {
+      // Per-cell envelope shape for audit metadata (operators write alert
+      // rules off it): "row" = K_row cell, "aad" = vault.aad: cell on an
+      // AAD table, "plain" otherwise.
+      var shape = isRowSealed(out[field]) ? "row" : (s.aad ? "aad" : "plain");
       // Opt-in cap: if this (actor, table, column) tuple is in cooldown
       // from prior forged-ciphertext failures, refuse before touching the
       // decryption oracle again (CWE-307). No-op when the cap is disabled.
       if (_rateInCooldown(capActor, table, field)) {
         _emitRateAudit({
-          table: table, field: field, actor: capActor, shape: s.aad ? "aad" : "plain",
+          table: table, field: field, actor: capActor, shape: shape,
           threshold: _rateCap.threshold, windowMs: _rateCap.windowMs, cooldownMs: _rateCap.cooldownMs,
         });
         throw new CryptoFieldRateError("crypto-field/unseal-rate-exceeded",
@@ -802,7 +984,22 @@ function unsealRow(table, row, actor) {
         // Auto-detect the envelope shape so an AAD-bound table that
         // contains pre-migration plain-vault rows still reads. Read-
         // side migration is lazy; the next sealRow re-emits AAD-bound.
-        if (typeof out[field] === "string" && vaultAad.isAadSealed(out[field])) {
+        if (typeof out[field] === "string" && isRowSealed(out[field])) {
+          // Per-row-key cell: derive K_row (lazy, once), then decrypt
+          // under it with the (table, rowId, column, schemaVersion) AAD.
+          // A null K_row means the wrapped secret is gone (shredded) or
+          // unreadable — throw so the catch nulls the field + audits.
+          var kRow = _kRowOnce();
+          if (!kRow) {
+            throw new CryptoFieldError("crypto-field/row-key-unavailable",
+              "unsealRow: per-row key for '" + table + "' row '" + kRowId +
+              "' is unavailable (shredded or never materialized)");
+          }
+          var cellAad = _aadBytes(_rowCellAad(s, table, field, kRowId));
+          unsealed = decryptPacked(
+            Buffer.from(out[field].slice(ROW_PREFIX.length), "base64"), kRow, cellAad
+          ).toString("utf8");
+        } else if (typeof out[field] === "string" && vaultAad.isAadSealed(out[field])) {
           unsealed = vaultAad.unseal(out[field],
             _aadParts(s, table, field, out));
         } else if (typeof out[field] === "string" && out[field].startsWith(VAULT_PREFIX)) {
@@ -829,7 +1026,7 @@ function unsealRow(table, row, actor) {
               table:   table,
               field:   field,
               rowId:   out[s.rowIdField] || out._id || null,
-              shape:   s.aad ? "aad" : "plain",
+              shape:   shape,
               reason:  (e && e.message) || String(e),
             },
           });
@@ -840,7 +1037,7 @@ function unsealRow(table, row, actor) {
         // transition. No-op when the cap is disabled.
         if (_rateNoteFailure(capActor, table, field)) {
           _emitRateAudit({
-            table: table, field: field, actor: capActor, shape: s.aad ? "aad" : "plain",
+            table: table, field: field, actor: capActor, shape: shape,
             threshold: _rateCap.threshold, windowMs: _rateCap.windowMs, cooldownMs: _rateCap.cooldownMs,
           });
         }
@@ -1105,7 +1302,7 @@ function getColumnResidency(table) {
  * @signature b.cryptoField.assertColumnResidency(table, row, args)
  * @since     0.7.27
  * @compliance gdpr
- * @related   b.cryptoField.declareColumnResidency
+ * @related   b.cryptoField.declareColumnResidency, b.cryptoField.declarePerRowResidency
  *
  * Storage-write gate. Storage backends call this with the proposed
  * row before the SQL hits the wire; refusal under regulated postures
@@ -1161,6 +1358,104 @@ function assertColumnResidency(table, row, args) {
   return null;
 }
 
+/**
+ * @primitive b.cryptoField.declarePerRowResidency
+ * @signature b.cryptoField.declarePerRowResidency(table, opts)
+ * @since     0.14.24
+ * @compliance gdpr
+ * @related   b.cryptoField.getPerRowResidency, b.cryptoField.declareColumnResidency
+ *
+ * Declares per-ROW data residency for `table`: one plaintext column on
+ * each row carries that row's residency tag, and the write gates
+ * refuse a tagged row landing on an incompatible backend. The sibling
+ * of `declareColumnResidency` — columns answer "which fields are
+ * region-bound", rows answer "which region does THIS record belong
+ * to" (an EU user's row next to a US user's row in the same table).
+ * Local writes (`b.db.from(...).insertOne` / `.update`) enforce the
+ * tag against the deployment's `dataResidency` region set under
+ * cross-border regulated postures; external writes
+ * (`b.externalDb.query`) take the tag per call via
+ * `opts.rowResidencyTag` because raw SQL carries no row object. Rows
+ * tagged "global" or "unrestricted" pass any backend. Throws on bad
+ * input (config-time fail-loud).
+ *
+ * @opts
+ *   residencyColumn: string,    // plaintext column carrying the row's tag
+ *   allowedTags:     string[],  // whitelist of valid tag values ("eu", "us", "global", region names)
+ *
+ * @example
+ *   b.cryptoField.declarePerRowResidency("users", {
+ *     residencyColumn: "dataRegion",
+ *     allowedTags:     ["eu-west-1", "us-east-1", "global"],
+ *   });
+ *   var spec = b.cryptoField.getPerRowResidency("users");
+ *   spec.residencyColumn;   // → "dataRegion"
+ */
+function declarePerRowResidency(table, opts) {
+  validateOpts.requireNonEmptyString(table, "declarePerRowResidency: table",
+    CryptoFieldError, "crypto-field/per-row-residency-table-empty");
+  validateOpts.requireObject(opts, "declarePerRowResidency",
+    CryptoFieldError, "crypto-field/per-row-residency-opts-not-object");
+  validateOpts(opts, ["residencyColumn", "allowedTags"], "cryptoField.declarePerRowResidency");
+  validateOpts.requireNonEmptyString(opts.residencyColumn,
+    "declarePerRowResidency: opts.residencyColumn",
+    CryptoFieldError, "crypto-field/per-row-residency-column-invalid");
+  if (!Array.isArray(opts.allowedTags) || opts.allowedTags.length === 0) {
+    throw new CryptoFieldError("crypto-field/per-row-residency-tags-invalid",
+      "declarePerRowResidency: opts.allowedTags must be a non-empty array of tag strings");
+  }
+  validateOpts.optionalNonEmptyStringArray(opts.allowedTags,
+    "declarePerRowResidency: opts.allowedTags",
+    CryptoFieldError, "crypto-field/per-row-residency-tag-empty");
+  // The residency tag column MUST stay plaintext — the write gate reads
+  // it on every INSERT / UPDATE before sealRow, and reads return it
+  // verbatim. A sealed residency column would be ciphertext the gate
+  // can't compare and reads can't surface. Refuse the misconfiguration
+  // at declaration time when the table's sealed-field set is already
+  // known (registration order permitting).
+  var sealed = getSealedFields(table);
+  if (Array.isArray(sealed) && sealed.indexOf(opts.residencyColumn) !== -1) {
+    throw new CryptoFieldError("crypto-field/per-row-residency-sealed-conflict",
+      "declarePerRowResidency: residencyColumn '" + opts.residencyColumn +
+      "' is a sealed field on table '" + table + "' — the residency tag must " +
+      "stay plaintext so the write gate can read it. Choose a non-sealed column");
+  }
+  perRowResidency[table] = {
+    residencyColumn: opts.residencyColumn,
+    allowedTags:     opts.allowedTags.slice(),
+  };
+  return {
+    table:           table,
+    residencyColumn: opts.residencyColumn,
+    allowedTags:     opts.allowedTags.slice(),
+  };
+}
+
+/**
+ * @primitive b.cryptoField.getPerRowResidency
+ * @signature b.cryptoField.getPerRowResidency(table)
+ * @since     0.14.24
+ * @related   b.cryptoField.declarePerRowResidency
+ *
+ * Returns the per-row residency spec declared for `table`
+ * (`{ residencyColumn, allowedTags }`), or null when the table has no
+ * declaration. Read-only — storage backends call this at the write
+ * boundary to decide whether the row-residency gate applies.
+ *
+ * @example
+ *   b.cryptoField.declarePerRowResidency("users", {
+ *     residencyColumn: "dataRegion",
+ *     allowedTags:     ["eu-west-1", "global"],
+ *   });
+ *   b.cryptoField.getPerRowResidency("users").allowedTags;   // → ["eu-west-1", "global"]
+ *   b.cryptoField.getPerRowResidency("unknown");             // → null
+ */
+function getPerRowResidency(table) {
+  var spec = perRowResidency[table];
+  if (!spec) return null;
+  return { residencyColumn: spec.residencyColumn, allowedTags: spec.allowedTags.slice() };
+}
+
 /**
  * @primitive b.cryptoField.declarePerRowKey
  * @signature b.cryptoField.declarePerRowKey(table, opts)
@@ -1169,13 +1464,16 @@ function assertColumnResidency(table, row, args) {
  * @related   b.cryptoField.materializePerRowKey, b.cryptoField.destroyPerRowKey, b.subject.eraseHard
  *
  * Opts a table into per-row keying (K_row crypto-shred substrate).
- * After registration, every INSERT generates a fresh K_row and stores
- * it sealed in `_blamejs_per_row_keys (table, rowId, wrapped)`. AAD on
- * the K_row binds (table, rowId, info-label) — copy-row attacks fail
- * Poly1305 verification. `b.subject.eraseHard(subjectId)` deletes the
- * per-row key entries for the subject's rows; WAL / replica residual
- * ciphertext becomes mathematically undecryptable because K_row is
- * gone everywhere it ever lived. Throws on bad input (config-time
+ * After registration, every INSERT generates a fresh 32-byte CSPRNG
+ * row-secret, derives K_row from it, and stores the SECRET (never
+ * K_row) AAD-sealed in `_blamejs_per_row_keys (tableName, rowId,
+ * wrappedKey)`. AAD on the wrap binds (table, rowId, column,
+ * schemaVersion) — a wrapped secret copied to a different row fails
+ * Poly1305 verification. `b.subject.eraseHard(subjectId)` /
+ * `b.retention` destroy the per-row entries for the subject's rows; WAL
+ * / replica residual ciphertext becomes mathematically undecryptable
+ * because the random row-secret — the only seed for K_row — is gone
+ * everywhere it ever lived. Throws on bad input (config-time
  * fail-loud).
  *
  * @opts
@@ -1237,15 +1535,22 @@ function hasPerRowKey(table) {
  * @compliance gdpr, hipaa
  * @related   b.cryptoField.declarePerRowKey, b.cryptoField.destroyPerRowKey
  *
- * Derive-and-store: called by the storage backend on INSERT. Generates
- * `K_row = SHAKE256(vaultSalt + table + rowId + info, keySize)`, seals
- * it via `vault.seal`, and inserts into `_blamejs_per_row_keys`.
- * Returns the unwrapped K_row Buffer for the caller to use to encrypt
- * sealed columns under the row-scoped key. Idempotent on UPSERT — if
- * a K_row already exists for (table, rowId), returns the unwrapped
- * existing key. The AAD-bound envelope rejects copy-row attacks: a
- * wrapped K_row pasted under a different rowId fails Poly1305
- * verification at unseal time.
+ * Derive-and-store: called by the storage backend on INSERT (the
+ * db-query write boundary, gated on `hasPerRowKey`). Generates a fresh
+ * 32-byte CSPRNG row-secret, derives
+ * `K_row = SHAKE256(rowSecret || ":" || table || ":" || rowId || ":"
+ * || info, keySize)`, AAD-seals the SECRET (base64) into
+ * `_blamejs_per_row_keys.wrappedKey` via `b.vault.aad.seal`, and
+ * returns the unwrapped K_row Buffer for the caller to encrypt sealed
+ * columns under the row-scoped key. The secret is random — never a
+ * function of any on-disk salt — so destroying the wrapped secret
+ * makes K_row unrecoverable even with full disk + vault-root access.
+ * Idempotent on UPSERT — if a secret already exists for (table,
+ * rowId), unwraps it and re-derives the same K_row. The AAD-bound wrap
+ * rejects copy-row attacks: a wrapped secret pasted under a different
+ * rowId fails Poly1305 verification at unseal time. `dbHandle` is a
+ * b.db handle (`.prepare`); rowId MUST be the row's `_id` (the value
+ * `destroyPerRowKey` / `b.subject.eraseHard` delete on).
  *
  * @example
  *   b.cryptoField.declarePerRowKey("orders", { keySize: 32 });
@@ -1265,30 +1570,55 @@ function materializePerRowKey(table, rowId, dbHandle) {
     throw new CryptoFieldError("crypto-field/materialize-per-row-key-no-db",
       "materializePerRowKey: dbHandle (b.db) is required");
   }
-  // Existing key? Re-use to support idempotent UPSERTs.
+  var ridStr = String(rowId);
+  // Existing secret? Unwrap + re-derive to support idempotent UPSERTs.
   var existing = dbHandle.prepare(
-    'SELECT wrappedKey FROM "_blamejs_per_row_keys" WHERE tableName = ? AND rowId = ?'
-  ).get(table, rowId);
+    'SELECT wrappedKey FROM "' + PER_ROW_KEYS_TABLE + '" WHERE tableName = ? AND rowId = ?'
+  ).get(table, ridStr);
   if (existing) {
-    return vault.unseal(existing.wrappedKey);
+    return _deriveKRow(_unwrapRowSecret(existing.wrappedKey, ridStr), table, ridStr, spec);
   }
-  // Derive K_row from the table-level vault key salt + rowId via
-  // SHAKE256 expand. This is a one-shot derivation (HKDF-shaped) that
-  // matches the framework's PQC-first kdf — no HMAC-SHA3 dependency.
-  var saltHex = vault.getDerivedHashSalt().toString("hex");
-  var ikm = Buffer.from(saltHex + ":" + table + ":" + rowId + ":" + spec.info, "utf8");
-  var kRow = kdf(ikm, spec.keySize);
-  // allow:seal-without-aad — per-row K_row wrap; row identity is the
-  // K_row KDF input, not the AEAD AAD on the wrap. Copy-attacks fail
-  // because the wrapped K_row only decrypts data sealed under it.
-  var sealed = vault.seal(kRow.toString("base64"));
+  // Fresh random row-secret. CRITICAL: this is CSPRNG, not a function
+  // of any on-disk value (the pre-v0.14.25 design derived K_row from
+  // the plaintext-on-disk derivedHash salt, so an attacker with disk
+  // access re-derived it and deleting the wrap shred nothing). With a
+  // random secret, K_row is unrecoverable once the wrap is destroyed.
+  var rowSecret = generateBytes(32);
+  var kRow = _deriveKRow(rowSecret, table, ridStr, spec);
+  // Store the SECRET (never K_row), AAD-sealed under the vault root so a
+  // wrapped secret copied to a different (table, rowId) fails Poly1305.
+  var sealed = vaultAad.seal(rowSecret.toString("base64"), _wrappedKeyAad(ridStr));
+  // _id is the rotation pipeline's pagination/UPDATE key (the natural
+  // identity is the composite (tableName, rowId)). A fresh token keeps
+  // it unique per registry row.
   dbHandle.prepare(
-    'INSERT INTO "_blamejs_per_row_keys" (tableName, rowId, wrappedKey, createdAt) ' +
-    'VALUES (?, ?, ?, ?)'
-  ).run(table, rowId, sealed, Date.now());
+    'INSERT INTO "' + PER_ROW_KEYS_TABLE + '" (_id, tableName, rowId, wrappedKey, createdAt) ' +
+    'VALUES (?, ?, ?, ?, ?)'
+  ).run(generateToken(16), table, ridStr, sealed, Date.now());
   return kRow;
 }
 
+// Derive the row-scoped key from the random row-secret. SHAKE256 expand
+// (HKDF-shaped, matches the framework's PQC-first kdf) over
+// rowSecret || ":" || table || ":" || rowId || ":" || info — the
+// non-secret context terms domain-separate two rows that (astronomically
+// improbably) drew the same secret; the secret is the entropy source.
+function _deriveKRow(rowSecret, table, rowId, spec) {
+  var ikm = Buffer.concat([
+    rowSecret,
+    Buffer.from(":" + table + ":" + rowId + ":" + spec.info, "utf8"),
+  ]);
+  return kdf(ikm, spec.keySize);
+}
+
+// Unwrap a stored row-secret back to its 32 raw bytes. The wrap is
+// AAD-bound to (PER_ROW_KEYS_TABLE, rowId, wrappedKey, schemaVersion);
+// a tampered / copied wrap throws here, which the read path surfaces as
+// system.crypto.unseal_failed (shredded data reads as absent).
+function _unwrapRowSecret(wrapped, rowId) {
+  return Buffer.from(vaultAad.unseal(wrapped, _wrappedKeyAad(rowId)), "base64");
+}
+
 /**
  * @primitive b.cryptoField.destroyPerRowKey
  * @signature b.cryptoField.destroyPerRowKey(table, rowId, dbHandle)
@@ -1296,13 +1626,14 @@ function materializePerRowKey(table, rowId, dbHandle) {
  * @compliance gdpr, hipaa
  * @related   b.cryptoField.materializePerRowKey, b.subject.eraseHard
  *
- * Crypto-shred: drops the per-row K_row entry from
- * `_blamejs_per_row_keys`. Called by `b.subject.eraseHard` for each
- * row mapped to the erased subject. Returns
+ * Crypto-shred: drops the row's wrapped row-secret from
+ * `_blamejs_per_row_keys`. Called by `b.subject.eraseHard` and
+ * `b.retention` for each row mapped to the erased subject. Returns
  * `{ destroyed: <rowsAffected> }`. After destruction, any WAL /
  * replica residual ciphertext for the row is mathematically
- * undecryptable — even with the vault root key — because K_row is
- * gone everywhere it ever lived. No-op when the table is not
+ * undecryptable — even with the vault root key — because the random
+ * row-secret (the only seed for K_row) is gone everywhere it ever
+ * lived. `rowId` MUST be the row's `_id`. No-op when the table is not
  * registered for per-row keying.
  *
  * @example
@@ -1323,8 +1654,8 @@ function destroyPerRowKey(table, rowId, dbHandle) {
       "destroyPerRowKey: dbHandle (b.db) is required");
   }
   var result = dbHandle.prepare(
-    'DELETE FROM "_blamejs_per_row_keys" WHERE tableName = ? AND rowId = ?'
-  ).run(table, rowId);
+    'DELETE FROM "' + PER_ROW_KEYS_TABLE + '" WHERE tableName = ? AND rowId = ?'
+  ).run(table, String(rowId));
   return { destroyed: (result && result.changes) || 0 };
 }
 
@@ -1336,10 +1667,10 @@ function destroyPerRowKey(table, rowId, dbHandle) {
  * @related   b.cryptoField.declareColumnResidency, b.cryptoField.declarePerRowKey
  *
  * Test-only helper. Drops every entry from the per-column residency
- * registry AND the per-row-key registry so a test fixture can
- * re-declare both between cases. Operator code never calls this —
- * production declarations come from `b.db.init({ schema })` once at
- * boot.
+ * registry, the per-row residency registry, and the per-row-key
+ * registry so a test fixture can re-declare them between cases.
+ * Operator code never calls this — production declarations come from
+ * `b.db.init({ schema })` once at boot.
  *
  * @example
  *   b.cryptoField.declareColumnResidency("users", {
@@ -1351,6 +1682,7 @@ function destroyPerRowKey(table, rowId, dbHandle) {
 function clearResidencyForTest() {
   for (var t in columnResidency) delete columnResidency[t];
   for (var u in perRowKeyTables) delete perRowKeyTables[u];
+  for (var v in perRowResidency) delete perRowResidency[v];
 }
 
 module.exports = {
@@ -1359,6 +1691,7 @@ module.exports = {
   getSealedFields:  getSealedFields,
   sealRow:          sealRow,
   unsealRow:        unsealRow,
+  isRowSealed:      isRowSealed,
   configureUnsealRateCap: configureUnsealRateCap,
   clearRateCapForTest:    clearRateCapForTest,
   CryptoFieldRateError:   CryptoFieldRateError,
@@ -1382,6 +1715,8 @@ module.exports = {
   declareColumnResidency: declareColumnResidency,
   getColumnResidency:     getColumnResidency,
   assertColumnResidency:  assertColumnResidency,
+  declarePerRowResidency: declarePerRowResidency,
+  getPerRowResidency:     getPerRowResidency,
   declarePerRowKey:       declarePerRowKey,
   hasPerRowKey:           hasPerRowKey,
   materializePerRowKey:   materializePerRowKey,