@blamejs/core 0.14.24 → 0.14.25

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.14.x
 
+- v0.14.25 (2026-06-06) — **Per-row crypto-shred is real and AAD-bound, and the idempotency fingerprint key is sealed at rest.** The per-row encryption-key feature that backs `b.subject.eraseHard` crypto-shred was both non-functional and, as documented, unsound: the per-row key (`K_row`) was derived deterministically from a salt that is stored in plaintext in the data directory, so an actor with disk access could re-derive it and decrypt 'shredded' residual ciphertext (WAL / replica / backup) — and the key was never actually materialized on insert, so no table ever used it. Per-row keys are now derived from a fresh 32-byte CSPRNG secret stored only in `_blamejs_per_row_keys`, wrapped under the vault with AEAD additional-data binding `(table, rowId)`, and materialized on insert for tables that declare them; destroying the wrapped secret now genuinely renders the row's residual ciphertext undecryptable. The same plaintext-salt class is fixed for the idempotency request-fingerprint HMAC, which now seeds off the sealed-at-rest `vault.getDerivedHashMacKey()`. There is no migration: the per-row-key table was empty in every deployment, so keyed tables are correct from their first write. **Security:** *Per-row crypto-shred: random secret, AAD-bound wrap, materialized on insert* — `b.cryptoField.declarePerRowKey` tables now get a per-row key derived from a fresh `b.crypto.generateBytes(32)` secret — never from the plaintext per-deployment salt — so the key has no input recomputable from disk. The secret is stored in `_blamejs_per_row_keys` wrapped via `b.vault.aad.seal` with additional-data bound to `(table, rowId)`, so a wrapped key copied onto another row fails its Poly1305 tag. Sealed columns are encrypted under the per-row key and tagged with a `vault.row:` envelope (`b.cryptoField.isRowSealed`); the residency-tag column is never key-sealed so the write-boundary residency gate can still read it. The key is materialized on insert (it previously never was) and re-derived once per read; `b.subject.eraseHard` and the retention sweep destroy the wrapped secret, after which the row's residual ciphertext reads as absent and cannot be recovered even if the vault root is later compromised. Wrapped keys are re-sealed under the new root on vault keypair rotation, so rotation does not strand keyed rows. · *Idempotency request-fingerprint HMAC seeds off the sealed MAC key* — The `fingerprintSeal` HMAC over the request fingerprint was keyed from the plaintext per-deployment salt, so a disk-access actor could recompute the key and brute-force the low-entropy preimage (method + URL + body) offline. It now seeds off `b.vault.getDerivedHashMacKey()`, which is sealed at rest. Fingerprints cached before the upgrade no longer match, so a replayed request re-executes once (the safe direction). **Detectors:** *kdf-key-from-plaintext-derived-hash-salt* — The pattern catalog refuses a key-derivation (`kdf(... getDerivedHashSalt() ...)`) that seeds a per-row shred key or a vault-secret-promising keyed-MAC off the plaintext-on-disk derived-hash salt. Such a key is re-derivable by anyone with the data directory, defeating the shred / secrecy it advertises; the correct sources are a CSPRNG secret or the sealed `getDerivedHashMacKey()`. The deterministic salted-SHA3 equality index is a distinct shape and is unaffected. **Migration:** *No action required* — No data migration: the per-row-key table was empty in every deployment, so tables that declare per-row keys are correct from their first write going forward. The only observable change is that the first request after upgrade matching a pre-upgrade idempotency fingerprint re-executes once.
+
 - v0.14.24 (2026-06-05) — **Per-row data residency enforced at the write boundary, and the long-advertised column-residency gate is wired.** Rows can now carry their own residency tag, and the database write paths enforce it: under a cross-border regulated posture (GDPR / UK-GDPR / DPDP / PIPL / LGPD / APPI / PDPA) a row tagged for one region is refused before it lands on a backend in another. `b.cryptoField.declarePerRowResidency` declares which column carries the tag; local SQLite writes check it against the deployment's `dataResidency` region set, and `b.externalDb.query` / `transaction` DML to a residency-tagged backend takes the tag per call via `rowResidencyTag`. The column-scoped gate (`assertColumnResidency`) — exported and documented since v0.7.27 but never composed into any write path — is now enforced on the same boundary. Unregulated deployments are unaffected: every gate passes with an advisory audit instead of a refusal, so operators can observe before adopting a posture. Note: v0.14.23 was tagged but not published to npm (its publish run timed out in validation); its changes — the MX DATA-phase SPF/DKIM/DMARC gate and the inbound mail authentication pipeline — are included in this package, and the publish-validation timeout is fixed here. **Added:** *`b.cryptoField.declarePerRowResidency` / `getPerRowResidency` — row-scoped residency tags* — Declares the plaintext column carrying each row's residency tag plus the whitelist of valid tag values (`{ residencyColumn, allowedTags }`). On INSERT to a declared table the tag is required and must be in `allowedTags`; rows tagged `global` or `unrestricted` pass any backend. The declaration registry mirrors `declareColumnResidency`, and `clearResidencyForTest` now clears both. The tag comes from application logic (the user's declared region) — the framework never infers it from request metadata. · *Local write gate on `b.db.from(...).insertOne` / `update`* — Runs on the plaintext row before sealing, so the tag column stays inspectable when sibling columns seal. Under a cross-border regulated posture, a row whose tag falls outside the deployment's region set (`dataResidency.region` plus `allowedStorageRegions`) is refused with `db-query/row-residency-local-mismatch`; a missing or out-of-whitelist tag refuses with `db-query/row-residency-tag-missing` / `-tag-invalid` regardless of posture. UPDATEs gate when the change set touches the residency column — an update that doesn't move residency is not a transfer. Refusals are typed `DbQueryError`s (new error class) and land in the audit chain (`db.residency.gate.rejected`); unregulated postures emit `db.residency.gate.advisory` and pass. · *External write gate — `rowResidencyTag` on `b.externalDb.query` / `transaction`* — External-db takes raw SQL, not row objects, so the row's tag travels as `opts.rowResidencyTag` (validated at transaction entry too). Under a regulated posture, a write to a residency-tagged backend requires the tag (`RESIDENCY_GATE_REQUIRED`) and refuses a mismatch (`RESIDENCY_TAG_MISMATCH`) before the statement reaches the wire. The gate classifies by what a statement does, not its leading keyword: it resolves the effective verb behind a `WITH` (CTE) or `EXPLAIN ANALYZE` prefix and treats `INSERT`/`UPDATE`/`DELETE`/`MERGE`/`REPLACE`, `CALL`/`EXECUTE`/`DO`, and `COPY ... FROM` as writes — only recognized pure reads (`SELECT`, `SHOW`/`DESCRIBE`/`PRAGMA`, a `COPY ... TO` export, plan-only `EXPLAIN`, and session/transaction statements) pass untagged. A statement whose class can't be resolved, or a multi-statement string that hides a trailing write behind a harmless prefix, is refused (`STATEMENT_UNRESOLVED_REFUSED` / `MULTI_STATEMENT_REFUSED`). Inside `transaction()`, the transaction-level tag applies to every statement and a per-call override on `tx.query(sql, params, opts)` wins for that statement; a refusal rolls the transaction back. Replica reads that carry a tag refuse routing to an incompatible replica (`REPLICA_RESIDENCY_INCOMPATIBLE`) unless the replica is configured `allowCrossBorder: true`, which is audited (`db.residency.replica.cross_border` at read time, `db.residency.replica.cross_border_allowed` at config time). Unrestricted backends are not gated, and the migration runner's own tracking writes are region-neutral so migrations run unaffected on a residency-tagged backend. · *`b.compliance.isCrossBorderRegulated` — shared posture vocabulary* — The cross-border regulated posture set (gdpr, uk-gdpr, dpdp, pipl-cn, lgpd-br, appi-jp, pdpa-sg) now lives on `b.compliance` (`CROSS_BORDER_REGULATED_POSTURES` + the membership helper), one source of truth shared by the local gate, the external gate, and the existing replica-topology boot check. **Fixed:** *`assertColumnResidency` is now actually enforced* — `b.cryptoField.declareColumnResidency` / `assertColumnResidency` shipped in v0.7.27 documenting a write-time gate, but no write path ever called the assertion — column tags were recorded and never checked. The local write paths now run it against the deployment region: a mismatch refuses with `db-query/column-residency-mismatch` under a regulated posture and emits an advisory otherwise. Operators tag columns with the region value their `dataResidency` declares. · *Cross-border-allowed replica audit event is now recorded* — The config-time audit event for a consciously-permitted cross-border replica used a malformed action name that the audit validator silently dropped, so a compliance reviewer saw no record of the `allowCrossBorder` decision in the audit chain. It now emits as `db.residency.replica.cross_border_allowed` and lands like every other audit row. · *Publish-validation timeout that blocked the v0.14.23 npm release* — The v0.14.23 publish run timed out in release validation — the pattern-catalog self-test crossed a per-file watchdog budget as the codebase grew, and the same self-test, which scans the whole library and runs far longer on the slower macOS CI runner, hit the same wall on this package's first CI run. The validation budgets are corrected so a genuinely stuck file still fails fast while the catalog completes. v0.14.23 exists as a signed tag; npm goes 0.14.22 → 0.14.24 carrying both releases' changes. **Detectors:** *db-query-write-without-residency-gate* — Every local write method that seals a row must run the residency gates on the plaintext first — a future write path (upsert, bulk) inherits the requirement automatically. · *Residency-gates-wired catalog check* — The pattern catalog now pins the wiring itself: the local write methods call the gate, the external query/transaction paths call theirs, and `assertColumnResidency` has a real caller — the declared-but-never-enforced class cannot silently reappear. **Migration:** *No action required unless you adopt the gates* — Tables without a residency declaration, deployments without a `dataResidency` region, and unregulated postures behave exactly as before (advisory audit events at most). Adopting: declare per-row residency on mixed-region tables, pass `rowResidencyTag` on external DML, and set a cross-border posture (`b.compliance.set("gdpr")`) to turn refusals on.
 
 - v0.14.23 (2026-06-05) — **Inbound mail authentication: a DATA-phase SPF/DKIM/DMARC gate on the MX listener and the one-call receiver pipeline.** The MX listener can now refuse policy-failing mail at the wire instead of asking operators to verify after delivery. `b.mail.inbound.verify` is the receiver pipeline — SPF on the envelope identity, DKIM on the message bytes, DMARC policy + alignment on the From-header domain, and the RFC 8601 Authentication-Results header — and the listener's new `guardEnvelope` opt runs it at DATA completion: when the sender's published DMARC policy says reject, the message is refused with 550 before it reaches the agent handoff; accepted mail carries the verdict to the agent and gains the receiver's Authentication-Results header, with any sender-forged header carrying the receiver's name stripped first. Monitor mode annotates without refusing, so operators can observe verdicts on live traffic before enforcing. **Added:** *`b.mail.inbound.verify` — one-call receiver authentication pipeline* — Runs the inbound authentication set on a full RFC 5322 message (string or Buffer): SPF (RFC 7208) on the MAIL FROM identity with HELO fallback for the null reverse-path, DKIM (RFC 6376) on every signature, From-header extraction, DMARC (RFC 7489 / DMARCbis) policy discovery + alignment, and — when an `authservId` is supplied — the RFC 8601 Authentication-Results header. Returns `{ spf, dkim, from, dmarc, authResults }` with `dmarc.recommendedAction` carrying the policy disposition. From-header discipline per RFC 7489 §6.6.1: a message with zero From fields, several From fields, or several author addresses in one field returns `permerror` with a reject recommendation instead of picking one of the authors — the header-duplication shape behind the CVE-2024-7208 / CVE-2024-7209 hosted-relay spoofing class. The author parser is quote-aware: a literal `<` or comma inside a quoted display-name (`"Doe, John" <j@example.com>`) is one author, not two. A fail verdict computed while SPF or DKIM returned temperror surfaces as temperror (RFC 7489 §6.6.2) — the transiently-failed lookup could have produced the aligned pass, so the caller defers and the sender retries instead of being permanently refused during a DNS blip. · *MX listener `guardEnvelope` — the DATA-phase authentication gate* — `b.mail.server.mx.create({ guardEnvelope: true })` (or a config object: `mode`, `onTemperror`, `authservId`, `dnsLookup`, `maxSignatures`, `clockSkewMs`, `minRsaBits`, `timeoutMs`) runs the pipeline after the SIZE check and before the agent handoff. Enforce mode refuses with 550 5.7.26 (RFC 7372 — multiple authentication checks failed) when DMARC evaluates to fail under a reject policy, 550 5.7.1 on the multi-From shape, and 451 4.7.0 on DNS temperror or pipeline timeout — `onTemperror: "accept"` admits unauthenticated mail instead when availability wins. The whole pipeline runs under a wall-clock ceiling (`timeoutMs`, default 20s) so a message stuffed with signatures pointing at slow resolvers cannot pin the connection slot. Accepted messages reach the agent handoff with the verdict as `auth` (including `quarantine: true` when the sender's policy says quarantine — the agent owns foldering) and gain the receiver's Authentication-Results header; any sender-attached header forging the receiver's authserv-id is stripped first (RFC 8601 §5). Monitor mode (the default under the permissive profile) annotates and audits without refusing. New audit events: `mail.server.mx.envelope_verdict` and `mail.server.mx.envelope_error`. **Detectors:** *ar-header-prepend-without-forged-strip* — Any code path that prepends an emitted Authentication-Results header must first strip sender-attached instances claiming the same authserv-id (RFC 8601 §5) — a forged pre-attached verdict would otherwise shadow the computed one for downstream consumers. **Migration:** *No action required; the gate is opt-in* — `guardEnvelope` is off unless wired — an unwired gate is skipped like the sibling HELO / RBL / greylist gates, and existing listeners behave exactly as before. The agent handoff context gains an `auth` field (null when the gate is off). Start with `guardEnvelope: { mode: "monitor" }` to observe verdicts on live traffic before switching to enforce.

package/lib/constants.js

@@ -179,6 +179,16 @@ var TLS_GROUP_CURVE_STR = TLS_GROUP_PREFERENCE.join(":");
 // ---- Vault sealed-value prefix ----
 var VAULT_PREFIX = "vault:";
 
+// ---- Per-row-key sealed-column prefix ----
+// Columns encrypted under a row-scoped key (K_row) — distinct from the
+// vault-root `vault:` / AAD-bound `vault.aad:` prefixes so the read path
+// can route a cell to its decrypt: K_row-sealed cells unwrap the row's
+// secret from `_blamejs_per_row_keys`, derive K_row, then decrypt under
+// it (XChaCha20-Poly1305, AEAD-bound to (table, rowId, column,
+// schemaVersion)). Destroying the row's wrapped secret leaves these
+// cells mathematically undecryptable — the crypto-shred substrate.
+var ROW_PREFIX = "vault.row:";
+
 // ---- Default hash namespaces for derived-hash indexed lookups ----
 // Apps add their own via app-config registries. The 'bj-' namespace
 // prevents collision between framework-derived and app-derived hashes.
@@ -205,5 +215,6 @@ module.exports = {
   TLS_GROUP_PREFERENCE:   TLS_GROUP_PREFERENCE,
   TLS_GROUP_CURVE_STR:    TLS_GROUP_CURVE_STR,
   VAULT_PREFIX:           VAULT_PREFIX,
+  ROW_PREFIX:             ROW_PREFIX,
   HASH_PREFIX:            HASH_PREFIX,
 };

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 —
@@ -139,13 +148,77 @@ var columnResidency = Object.create(null);
 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)
@@ -641,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
@@ -654,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"],
@@ -665,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
@@ -709,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]));
     }
   }
 
@@ -749,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
@@ -763,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:
@@ -779,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;
@@ -787,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",
@@ -807,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)) {
@@ -834,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),
             },
           });
@@ -845,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,
           });
         }
@@ -1272,13 +1464,16 @@ function getPerRowResidency(table) {
  * @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
@@ -1340,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 });
@@ -1368,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)
@@ -1399,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
@@ -1426,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 };
 }
 
@@ -1463,6 +1691,7 @@ module.exports = {
   getSealedFields:  getSealedFields,
   sealRow:          sealRow,
   unsealRow:        unsealRow,
+  isRowSealed:      isRowSealed,
   configureUnsealRateCap: configureUnsealRateCap,
   clearRateCapForTest:    clearRateCapForTest,
   CryptoFieldRateError:   CryptoFieldRateError,

package/lib/db-query.js

@@ -509,7 +509,9 @@ class Query {
               this._whereClause() + this._orderLimitOffset() + " LIMIT 1";
     var stmt = this._db.prepare(sql);
     var row = stmt.get.apply(stmt, this._whereParams);
-    return row ? cryptoField.unsealRow(this._cryptoFieldKey(), row) : null;
+    // 4th arg (dbHandle) lets unsealRow fetch + unwrap the row-scoped
+    // K_row for vault.row: cells (declarePerRowKey tables).
+    return row ? cryptoField.unsealRow(this._cryptoFieldKey(), row, undefined, this._db) : null;
   }
 
   all() {
@@ -519,8 +521,9 @@ class Query {
     var rows = stmt.all.apply(stmt, this._whereParams);
     var out = new Array(rows.length);
     var key = this._cryptoFieldKey();
+    var dbHandle = this._db;
     for (var i = 0; i < rows.length; i++) {
-      out[i] = cryptoField.unsealRow(key, rows[i]);
+      out[i] = cryptoField.unsealRow(key, rows[i], undefined, dbHandle);
     }
     return out;
   }
@@ -549,6 +552,7 @@ class Query {
     }
     var stmt = this._db.prepare(sql);
     var key = this._cryptoFieldKey();
+    var dbHandle = this._db;
     var iter;
     try { iter = stmt.iterate.apply(stmt, this._whereParams); }
     catch (e) {
@@ -570,7 +574,7 @@ class Query {
           var step = iter.next();
           if (step.done) { this.push(null); return; }
           emitted += 1;
-          this.push(cryptoField.unsealRow(key, step.value));
+          this.push(cryptoField.unsealRow(key, step.value, undefined, dbHandle));
         } catch (e) {
           this.destroy(e);
         }
@@ -596,7 +600,19 @@ class Query {
     // Residency gates read the PLAINTEXT row (the tag column must be
     // inspectable even when sibling columns seal below).
     _assertLocalResidency(this._cryptoFieldKey(), withId, "insert");
-    var sealed = cryptoField.sealRow(this._cryptoFieldKey(), withId);
+    // Per-row-key tables (declarePerRowKey): materialize a fresh K_row
+    // BEFORE sealRow so sealed columns encrypt under the row-scoped key
+    // (vault.row: cells). rowId MUST be withId._id — the same value
+    // b.subject.eraseHard / b.retention destroy on, so a later shred
+    // makes these cells undecryptable. Materialize stores the random
+    // row-secret AAD-sealed in _blamejs_per_row_keys.
+    var sealOpts;
+    var cfKey = this._cryptoFieldKey();
+    if (cryptoField.hasPerRowKey(cfKey)) {
+      var kRow = cryptoField.materializePerRowKey(cfKey, withId._id, this._db);
+      sealOpts = { kRow: kRow, rowId: withId._id };
+    }
+    var sealed = cryptoField.sealRow(cfKey, withId, sealOpts);
     var cols = Object.keys(sealed);
     var placeholders = cols.map(function () { return "?"; }).join(", ");
     var quotedCols = cols.map(function (c) { return '"' + c + '"'; }).join(", ");
@@ -637,7 +653,16 @@ class Query {
     // touches the residency tag (or a region-bound column) is a
     // transfer and goes through the same refusal matrix as INSERT.
     _assertLocalResidency(this._cryptoFieldKey(), changes, "update");
-    var sealed = cryptoField.sealRow(this._cryptoFieldKey(), changes);
+    var cfKey = this._cryptoFieldKey();
+    // Per-row-key tables: sealed columns must re-encrypt under EACH
+    // affected row's own K_row, so a single set-based UPDATE can't seal
+    // one value across rows. Resolve the affected _id set, then seal +
+    // write each row under its row-scoped key. Idempotent materialize
+    // re-derives the existing K_row (created on INSERT).
+    if (cryptoField.hasPerRowKey(cfKey)) {
+      return this._updatePerRowKey(cfKey, changes, single);
+    }
+    var sealed = cryptoField.sealRow(cfKey, changes);
     var setKeys = Object.keys(sealed);
     if (setKeys.length === 0) {
       throw new Error("update changes object is empty");
@@ -666,6 +691,41 @@ class Query {
     return info.changes;
   }
 
+  // Per-row-key UPDATE. Sealed columns on a declarePerRowKey table are
+  // K_row cells (vault.row:), so each affected row must be re-sealed
+  // under its OWN K_row — a single set-based UPDATE can't carry per-row
+  // ciphertext. Resolve the affected _id set via the WHERE, then for
+  // each row: materialize (idempotent) its K_row, seal the change set
+  // under it (derived hashes computed from plaintext as usual), and
+  // UPDATE that single row by _id. `single` stops after the first row.
+  _updatePerRowKey(cfKey, changes, single) {
+    var whereSql = this._where.join(" AND ");
+    var qt = this._quotedTable();
+    var idStmt = this._db.prepare(
+      "SELECT _id FROM " + qt + " WHERE " + whereSql + (single ? " LIMIT 1" : ""));
+    var idRows = idStmt.all.apply(idStmt, this._whereParams);
+    var changed = 0;
+    for (var r = 0; r < idRows.length; r++) {
+      var rowId = idRows[r]._id;
+      if (rowId === undefined || rowId === null) continue;
+      var kRow = cryptoField.materializePerRowKey(cfKey, rowId, this._db);
+      var sealed = cryptoField.sealRow(cfKey, changes, { kRow: kRow, rowId: rowId });
+      var setKeys = Object.keys(sealed);
+      if (setKeys.length === 0) {
+        throw new Error("update changes object is empty");
+      }
+      setKeys.forEach(_validateField);
+      var selfUpd = this;
+      setKeys.forEach(function (k) { selfUpd._assertColumnMember(k, "update"); });
+      var setClause = setKeys.map(function (k) { return '"' + k + '" = ?'; }).join(", ");
+      var setValues = setKeys.map(function (k) { return sealed[k]; });
+      var updStmt = this._db.prepare("UPDATE " + qt + " SET " + setClause + " WHERE _id = ?");
+      var info = updStmt.run.apply(updStmt, setValues.concat([rowId]));
+      changed += (info && info.changes) || 0;
+    }
+    return changed;
+  }
+
   deleteOne() {
     return this._delete(true) > 0;
   }

package/lib/db.js

@@ -295,11 +295,21 @@ var FRAMEWORK_SCHEMA = [
   },
   {
     // Per-row crypto-erasure key registry — per-row keys.
-    // Each entry holds a sealed wrapped K_row keyed by (table,
-    // rowId). b.subject.eraseHard deletes the entry, leaving WAL /
-    // replica residuals undecryptable.
+    // Each entry holds the AAD-sealed random row-secret keyed by
+    // (tableName, rowId); the row-scoped K_row is derived from it.
+    // b.subject.eraseHard / b.retention destroy the entry, leaving WAL /
+    // replica residuals undecryptable. wrappedKey is registered as an
+    // AAD-bound sealed field (aad:true, rowIdField:"rowId") so a vault
+    // keypair rotation auto-reseals it old-root -> new-root via
+    // rotate._rotateColumn — without this a rotation would orphan every
+    // wrapped secret and brick every keyed row.
     name: "_blamejs_per_row_keys",
     columns: {
+      // _id is the rotation pipeline's keyset-pagination + UPDATE key
+      // (rotate._rotateColumn SELECTs _id and orders by it); the natural
+      // identity stays the composite (tableName, rowId). materialize
+      // populates _id with a fresh token.
+      _id:        "TEXT",
       tableName:  "TEXT NOT NULL",
       rowId:      "TEXT NOT NULL",
       wrappedKey: "BLOB NOT NULL",
@@ -307,6 +317,10 @@ var FRAMEWORK_SCHEMA = [
     },
     primaryKey: ["tableName", "rowId"],
     indexes: [],
+    sealedFields:  ["wrappedKey"],
+    aad:           true,
+    rowIdField:    "rowId",
+    schemaVersion: "1",
   },
   {
     // Operator-declared WORM (write-once-read-many) registry. Each

package/lib/middleware/idempotency-key.js

@@ -309,25 +309,33 @@ function dbStore(opts) {
     });
   }
 
-  // Derive a per-vault HMAC secret for fingerprint sealing.
-  // The vault root key is the trust root; without it the secret is
-  // unrecoverable. Lazy: only derived when fpSealOn is enabled AND the
-  // vault is ready, so test fixtures that haven't initialized the
-  // vault still construct a dbStore (the fingerprint then falls back
-  // to bare sha3-256 with a single audit warning).
+  // Derive a per-vault HMAC secret for fingerprint sealing. Seed off the
+  // SEALED per-deployment MAC key (vault.getDerivedHashMacKey, sealed at
+  // rest under the vault root) — NOT getDerivedHashSalt, which sits in
+  // PLAINTEXT on disk. With the salt-derived seed an attacker who read
+  // the disk could recompute the HMAC key and forge / correlate request
+  // fingerprints; the sealed MAC key closes that (the vault root is the
+  // trust root, so the secret is unrecoverable without it). Lazy: only
+  // derived when fpSealOn is enabled AND the vault is ready, so test
+  // fixtures that haven't initialized the vault still construct a
+  // dbStore (the fingerprint then falls back to bare sha3-256 with a
+  // single audit warning).
   var fpHmacSecret = null;
   if (fpSealOn) {
     try {
-      // Use vault.aad.buildContextAad as a stable derivation input;
-      // the derivedHashSalt is per-deployment so the same dbStore
-      // instance across hosts converges on the same HMAC key.
-      var fpDeriveInput = "idempotency.fingerprint:" + tableNameRaw + ":" +
-        vault.getDerivedHashSalt().toString("hex");
-      fpHmacSecret = bCrypto.kdf(Buffer.from(fpDeriveInput, "utf8"), C.BYTES.bytes(32));
+      // The MAC key is per-deployment + sealed, so the same dbStore
+      // instance across hosts converges on the same HMAC key while disk
+      // access alone cannot recover it. The table name domain-separates
+      // the fingerprint secret from other consumers of the MAC key.
+      var fpDeriveInput = Buffer.concat([
+        vault.getDerivedHashMacKey(),
+        Buffer.from("idempotency.fingerprint:" + tableNameRaw, "utf8"),
+      ]);
+      fpHmacSecret = bCrypto.kdf(fpDeriveInput, C.BYTES.bytes(32));
     } catch (_fpErr) {
       _emitAudit("idempotency.fingerprint_seal_skipped_no_vault",
         { tableName: tableNameRaw,
-          reason: "vault.getDerivedHashSalt() unavailable; fingerprint falls back to plain sha3-256" },
+          reason: "vault.getDerivedHashMacKey() unavailable; fingerprint falls back to plain sha3-256" },
         "warning");
       fpHmacSecret = null;
     }

package/lib/retention.js

@@ -274,8 +274,18 @@ function create(opts) {
     values.push(row._id);
     var upd2 = db.prepare("UPDATE \"" + table + "\" SET " + setClauses.join(", ") + " WHERE _id = ?");
     upd2.run.apply(upd2, values);
+    // Per-row-key tables (declarePerRowKey): NULLing the sealed columns
+    // is not enough — WAL / replica residuals keep the old K_row cells.
+    // Destroy the row's wrapped secret so K_row is unrecoverable and the
+    // residual ciphertext reads as absent (crypto-shred, GDPR Art. 17).
+    // rowId is row._id, the same identity materialize / eraseHard use.
+    var perRowKeysDestroyed = 0;
+    if (cryptoField.hasPerRowKey(table)) {
+      var dr = cryptoField.destroyPerRowKey(table, row._id, db);
+      perRowKeysDestroyed = (dr && dr.destroyed) || 0;
+    }
     void erased;
-    return { erased: 1, sealedFieldCount: sealedFields.length };
+    return { erased: 1, sealedFieldCount: sealedFields.length, perRowKeysDestroyed: perRowKeysDestroyed };
   }
 
   function _cascade(rule, rowId, dryRun) {

package/lib/vault-aad.js

@@ -304,6 +304,12 @@ module.exports = {
   isAadSealed:        isAadSealed,
   buildColumnAad:     buildColumnAad,
   buildContextAad:    buildContextAad,
+  // canonicalizeAad — the length-prefixed, sorted-keys AAD-bytes
+  // encoder. Exported (internal) so a sibling primitive that runs its
+  // own AEAD (crypto-field's per-row K_row cells) threads byte-identical
+  // AAD into encryptPacked/decryptPacked as this module does for its
+  // own seal/unseal — one canonical encoder, no drift.
+  canonicalizeAad:    _canonicalize,
   AAD_PREFIX:         AAD_PREFIX,
   AAD_VERSION:        AAD_VERSION,
   VaultAadError:      VaultAadError,

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:0697fb13-faa3-47c7-8ac0-7a29c980f002",
+  "serialNumber": "urn:uuid:a667e112-0ef6-4c72-b5b8-839233b6e4a6",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-06T15:36:19.660Z",
+    "timestamp": "2026-06-06T17:19:53.413Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.14.24",
+      "bom-ref": "@blamejs/core@0.14.25",
       "type": "application",
       "name": "blamejs",
-      "version": "0.14.24",
+      "version": "0.14.25",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.14.24",
+      "purl": "pkg:npm/%40blamejs/core@0.14.25",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.14.24",
+      "ref": "@blamejs/core@0.14.25",
       "dependsOn": []
     }
   ]