@blamejs/core 0.14.27 → 0.15.0

package/lib/crypto-field.js

@@ -34,11 +34,15 @@
  *   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
- *   per-deployment salt + a per-field namespace, so dictionary /
- *   rainbow attacks across fields and across deployments fail. Sealed
- *   columns without a derived hash are unindexable — queries on them
- *   silently return zero rows.
+ *   columns. The default digest is a keyed MAC
+ *   (`hmac-shake256`: SHAKE256 under the vault's per-deployment MAC key) +
+ *   a per-field namespace, so an attacker who recovers the salt alone
+ *   cannot correlate low-entropy plaintexts across fields or across
+ *   deployments. Operators keeping byte-compatibility with an existing
+ *   salted index opt out per-table (`derivedHashMode: "salted-sha3"`) or
+ *   per-column (`derivedHashes.<col>.mode`). Sealed columns without a
+ *   derived hash are unindexable — queries on them silently return zero
+ *   rows.
  *
  *   Per-column residency (`declareColumnResidency`) declares EU / US /
  *   global tags; the storage-write gate (`assertColumnResidency`)
@@ -56,6 +60,9 @@ var vault = require("./vault");
 var vaultAad = require("./vault-aad");
 var validateOpts = require("./validate-opts");
 var numericBounds = require("./numeric-bounds");
+var safeJson = require("./safe-json");
+var frameworkSchema = require("./framework-schema");
+var sql = require("./sql");
 var { defineClass } = require("./framework-error");
 var { sha3Hash, kdf, generateBytes, encryptPacked, decryptPacked, generateToken } = require("./crypto");
 var { HASH_PREFIX, VAULT_PREFIX, ROW_PREFIX, TIME } = require("./constants");
@@ -67,6 +74,38 @@ var { HASH_PREFIX, VAULT_PREFIX, ROW_PREFIX, TIME } = require("./constants");
 var CryptoFieldRateError = defineClass("CryptoFieldRateError", { alwaysPermanent: true });
 var CryptoFieldError     = defineClass("CryptoFieldError", { alwaysPermanent: true });
 
+// Typed-value codec for sealed columns. Sealing previously String()-coerced
+// every value before encryption, which silently corrupts a Buffer (lossy
+// UTF-8 round-trip) or an object ("[object Object]"). This codec preserves
+// byte/type fidelity through a sealed column so unseal restores the original
+// type. Backward-compatible: a plain string is stored VERBATIM (pre-codec
+// cells decode unchanged) - only a non-string value, or the rare string that
+// itself begins with the sentinel, is wrapped. The NUL-led sentinel never
+// occurs at the start of a normal stored string. number / boolean / bigint
+// keep the existing String() contract (they round-trip as strings as before).
+var TYPED_SENTINEL = String.fromCharCode(0) + "bjsv1:";
+
+function _encodeTyped(value) {
+  if (typeof value === "string") {
+    return value.indexOf(TYPED_SENTINEL) === 0 ? TYPED_SENTINEL + "S:" + value : value;
+  }
+  if (Buffer.isBuffer(value)) return TYPED_SENTINEL + "B:" + value.toString("base64");
+  if (value instanceof Uint8Array) return TYPED_SENTINEL + "B:" + Buffer.from(value).toString("base64");
+  if (typeof value === "object" && value !== null) return TYPED_SENTINEL + "J:" + JSON.stringify(value);
+  return String(value);
+}
+
+function _decodeTyped(str) {
+  if (typeof str !== "string" || str.indexOf(TYPED_SENTINEL) !== 0) return str;
+  var body = str.slice(TYPED_SENTINEL.length);
+  var tag = body.slice(0, 2);
+  var payload = body.slice(2);
+  if (tag === "B:") return Buffer.from(payload, "base64");
+  if (tag === "J:") return safeJson.parse(payload);   // plaintext is AEAD-verified; safeJson blocks proto-pollution defensively
+  if (tag === "S:") return payload;
+  return str;   // unknown tag - return the raw decrypted string defensively
+}
+
 var compliance    = lazyRequire(function () { return require("./compliance"); });
 var db            = lazyRequire(function () { return require("./db"); });
 var audit         = lazyRequire(function () { return require("./audit"); });
@@ -178,10 +217,24 @@ var SEAL_ENVELOPE_RANK = Object.freeze({
 // 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";
+// Canonical LOGICAL name for the per-row-key registry. It is the AAD-tuple
+// table component (so seal / unseal / rotate quote a byte-identical tuple)
+// and the frameworkSchema.tableName key the local-handle SQL resolves
+// through. allow:hand-rolled-sql — canonical logical-name declaration.
+var PER_ROW_KEYS_TABLE = "_blamejs_per_row_keys";   // allow:hand-rolled-sql
 var PER_ROW_KEYS_COLUMN = "wrappedKey";
 var PER_ROW_KEYS_SCHEMA_VERSION = "1";
 
+// The per-row-key registry is read/written against the LOCAL db() / dbHandle
+// handle directly (not clusterStorage), so SQL composed for it uses the
+// RESOLVED name (prefix-aware via frameworkSchema.tableName) and quoteName so
+// b.sql emits the quoted identifier the single-node path expects — the same
+// shape db-query.js's _sqlOpts and db.js's own local-handle b.sql calls use.
+var _PER_ROW_SQL_OPTS = { dialect: "sqlite", quoteName: true };
+function _perRowKeysTableName() {
+  return frameworkSchema.tableName(PER_ROW_KEYS_TABLE);
+}
+
 // 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
@@ -300,11 +353,20 @@ function registerTable(name, opts) {
   var rowIdField = typeof opts.rowIdField === "string" && opts.rowIdField.length > 0
     ? opts.rowIdField : "id";
   var schemaVersion = opts.schemaVersion != null ? String(opts.schemaVersion) : "1";
-  var derivedHashMode = opts.derivedHashMode || "salted-sha3";
+  // Derived-hash mode default-on flip (v0.15.0): the per-table default is
+  // the keyed MAC "hmac-shake256" (SHAKE256 under vault.getDerivedHashMacKey),
+  // so an attacker who recovers the per-deployment salt alone cannot
+  // correlate two low-entropy plaintexts across the indexed-lookup column.
+  // Operators who need the deterministic-per-deployment salted digest (e.g.
+  // to keep byte-compatibility with an existing salted-sha3 index) opt out
+  // explicitly with registerTable({ derivedHashMode: "salted-sha3" }), or
+  // per-column via derivedHashes.<col>.mode. GDPR Art. 4(5) pseudonymisation;
+  // HIPAA 45 CFR 164.514(b); FIPS 202; NIST SP 800-185.
+  var derivedHashMode = opts.derivedHashMode || "hmac-shake256";
   if (derivedHashMode !== "salted-sha3" && derivedHashMode !== "hmac-shake256") {
     throw new CryptoFieldError("crypto-field/bad-derived-hash-mode",
-      "registerTable: derivedHashMode must be 'salted-sha3' (default) or " +
-      "'hmac-shake256', got " + JSON.stringify(derivedHashMode));
+      "registerTable: derivedHashMode must be 'hmac-shake256' (default) or " +
+      "'salted-sha3', got " + JSON.stringify(derivedHashMode));
   }
   var derivedHashes = Object.assign({}, opts.derivedHashes || {});
   for (var col in derivedHashes) {
@@ -391,23 +453,47 @@ function _assertSealEnvelopeFloor(table, aadOn) {
 var DERIVED_HASH_BYTES = 32;
 
 // Compute the indexed-lookup digest for a derived-hash column.
-//   - "salted-sha3" (default): SHA3-512 over <per-deployment salt> + ns
-//     + value (128 hex). Deterministic per deployment.
-//   - "hmac-shake256": SHAKE256(<vault-sealed MAC key> || ns + value)
-//     truncated to 32 bytes (64 hex). The key is a vault-derived secret,
-//     NOT a static salt, so an attacker who recovers the salt alone
-//     can't correlate two low-entropy plaintexts; the sponge has no
-//     length-extension weakness. (b.crypto.hmacSha3 (HMAC-SHA3-512) was
-//     considered; SHAKE256(key||msg) is chosen for the fixed-width keyed
-//     digest with the same MAC-grade guarantee.) FIPS 202; NIST SP
-//     800-185; GDPR Art. 4(5) pseudonymisation; HIPAA 45 CFR 164.514(b).
+//   - "hmac-shake256" (registerTable default since v0.15.0):
+//     SHAKE256(<vault-sealed MAC key> || ns + value) truncated to 32 bytes
+//     (64 hex). The key is a vault-derived secret, NOT a static salt, so an
+//     attacker who recovers the salt alone can't correlate two low-entropy
+//     plaintexts; the sponge has no length-extension weakness.
+//     (b.crypto.hmacSha3 (HMAC-SHA3-512) was considered; SHAKE256(key||msg)
+//     is chosen for the fixed-width keyed digest with the same MAC-grade
+//     guarantee.) FIPS 202; NIST SP 800-185; GDPR Art. 4(5)
+//     pseudonymisation; HIPAA 45 CFR 164.514(b).
+//   - "salted-sha3" (opt-out / pre-v0.15.0 legacy index): SHA3-512 over
+//     <per-deployment salt> + ns + value (128 hex). Deterministic per
+//     deployment, byte-compatible with the legacy index.
+// The bare-fallback (`|| "salted-sha3"`) applies only when NEITHER the
+// per-column spec.mode NOR a table mode is supplied — an ad-hoc caller that
+// named no mode; registerTable always records a derivedHashMode, so a
+// registered table is never bare-fallthrough.
 function _computeDerivedHash(spec, tableMode, ns, normalized) {
-  var mode = (spec && spec.mode) || tableMode || "salted-sha3";
+  var mode = _resolveDerivedHashMode(spec, tableMode);
   if (mode === "hmac-shake256") {
     var macKey = vault.getDerivedHashMacKey();
     return kdf(Buffer.concat([macKey, Buffer.from(ns + normalized, "utf8")]),
       DERIVED_HASH_BYTES).toString("hex");
   }
+  return _legacyDerivedHash(ns, normalized);
+}
+
+// Resolve the effective derived-hash mode for a (spec, tableMode) pair —
+// per-column override beats the table mode beats the bare salted-sha3
+// fallback (the ad-hoc-no-mode case; see _computeDerivedHash).
+function _resolveDerivedHashMode(spec, tableMode) {
+  return (spec && spec.mode) || tableMode || "salted-sha3";
+}
+
+// The legacy (pre-v0.15.0 default) salted-sha3 digest — SHA3-512 over the
+// per-deployment salt + namespace + normalized value (128 hex). Factored out
+// so the dual-read LOOKUP path and the upgrade-on-read auto-migrate can
+// recompute the OLD-default hash for a (ns, value) regardless of the table's
+// current keyed-MAC mode: a row written before the default flipped still
+// carries this digest in its derived-hash column, and a lookup that only
+// computed the keyed-MAC would miss it.
+function _legacyDerivedHash(ns, normalized) {
   return sha3Hash(vault.getDerivedHashSalt().toString("hex") + ns + normalized);
 }
 
@@ -584,6 +670,33 @@ function namespaceFor(table, field, registered) {
  *
  *   b.cryptoField.computeDerived("users", "email", null);   // → null
  */
+// Build the derived-hash result for a (schema, derivedField, spec,
+// sourceField, value) tuple — the single source of truth for both
+// computeDerived and lookupHash. Returns `{ field, value, legacyValue? }`.
+//
+//   value       — the digest under the column's ACTIVE mode (keyed-MAC for a
+//                 v0.15.0-default table; salted-sha3 when opted out). New
+//                 writes index under this, so it stays the primary equality
+//                 value every existing caller already reads.
+//   legacyValue — present ONLY when the active mode is the keyed MAC: the
+//                 byte-form a row written under the PRE-v0.15.0 salted-sha3
+//                 default would carry. A dual-read lookup matches EITHER
+//                 value so the keyed-default flip doesn't silently lose
+//                 pre-flip rows; the upgrade-on-read auto-migrate in
+//                 unsealRow re-hashes a row found via the legacy digest.
+function _derivedHashResult(s, table, derivedField, spec, sourceField, value) {
+  var ns = namespaceFor(table, sourceField, s.hashNamespaces);
+  var normalized = spec.normalize ? spec.normalize(value) : String(value);
+  var mode = _resolveDerivedHashMode(spec, s.derivedHashMode);
+  var primary = _computeDerivedHash(spec, s.derivedHashMode, ns, normalized);
+  var out = { field: derivedField, value: primary };
+  if (mode === "hmac-shake256") {
+    var legacy = _legacyDerivedHash(ns, normalized);
+    if (legacy !== primary) out.legacyValue = legacy;
+  }
+  return out;
+}
+
 function computeDerived(table, sourceField, sourceValue) {
   if (sourceValue === undefined || sourceValue === null) return null;
   var s = schemas[table];
@@ -592,9 +705,7 @@ function computeDerived(table, sourceField, sourceValue) {
   for (var derivedField in s.derivedHashes) {
     var spec = s.derivedHashes[derivedField];
     if (spec.from === sourceField) {
-      var ns = namespaceFor(table, sourceField, s.hashNamespaces);
-      var normalized = spec.normalize ? spec.normalize(sourceValue) : String(sourceValue);
-      return { field: derivedField, value: _computeDerivedHash(spec, s.derivedHashMode, ns, normalized) };
+      return _derivedHashResult(s, table, derivedField, spec, sourceField, sourceValue);
     }
   }
   return null;
@@ -614,18 +725,50 @@ function computeDerived(table, sourceField, sourceValue) {
 // tuple are refused for `cooldownMs` with a typed CryptoFieldRateError and
 // a distinct system.crypto.unseal_rate_exceeded audit row.
 //
-// Default OFF — when no cap is configured, unsealRow behaves exactly as
-// before (null-the-field + audit-only). Composes the same timestamp-array
-// sliding-window shape used by b.mail.server.rateLimit (_pruneWindow):
-// count-based, lazily pruned on read, no background timer.
+// Default-ON (v0.15.0) — the cap is armed at module load with the
+// DEFAULT_RATE_CAP below, so a forged-ciphertext unseal-oracle is bounded
+// out of the box. Operators who want the prior audit-only behaviour opt
+// out explicitly with configureUnsealRateCap(null) / { disabled: true }.
+// Composes the same timestamp-array sliding-window shape used by
+// b.mail.server.rateLimit (_pruneWindow): count-based, lazily pruned on
+// read, no background timer.
 //
 // CWE-307 (Improper Restriction of Excessive Authentication Attempts —
 // generalized here to excessive decryption-oracle attempts); OWASP ASVS
 // v5 §2.2.1 (anti-automation); NIST SP 800-63B §5.2.2 (rate limiting).
-var _rateCap = null;                          // null = disabled
+//
+// DEFAULT_RATE_CAP — the secure baseline the cap arms with at module load.
+// 10 forged-ciphertext failures for one (actor, table, column) inside a
+// 1-minute window trip a 5-minute cooldown. Generous enough that no
+// legitimate read pattern hits it (a real ciphertext never fails the
+// AEAD), tight enough that an oracle-hammering attacker is shut off fast.
+var DEFAULT_RATE_CAP_THRESHOLD  = 10;
+var DEFAULT_RATE_CAP_WINDOW_MS  = TIME.minutes(1);
+var DEFAULT_RATE_CAP_COOLDOWN_MS = TIME.minutes(5);
+var _rateCap = null;                          // installed by _installDefaultRateCap() below
 var _rateFailWindows = new Map();             // "actor\x00table\x00column" → [tsMs, ...]
 var _rateCooldowns = new Map();               // same key → cooldownUntilMs
 
+// Build the default cap record (Date.now clock, framework-audit sink).
+// Separated so module-load and clearRateCapForTest install the identical
+// secure baseline.
+function _defaultRateCapRecord() {
+  return {
+    threshold:  DEFAULT_RATE_CAP_THRESHOLD,
+    windowMs:   DEFAULT_RATE_CAP_WINDOW_MS,
+    cooldownMs: DEFAULT_RATE_CAP_COOLDOWN_MS,
+    now:        function () { return Date.now(); },
+    onAudit:    null,
+  };
+}
+function _installDefaultRateCap() {
+  _rateCap = _defaultRateCapRecord();
+  _rateFailWindows.clear();
+  _rateCooldowns.clear();
+}
+// Arm the secure default at module load (security-on, not opt-in).
+_installDefaultRateCap();
+
 // Tuple key. \x00 is not a legal column / table identifier byte and is
 // vanishingly unlikely in an actor id, so the join is unambiguous; the
 // composite is only ever a Map key (never an object property), so no
@@ -641,23 +784,25 @@ function _rateKey(actor, table, column) {
  * @compliance hipaa, gdpr, pci-dss
  * @related   b.cryptoField.unsealRow, b.cryptoField.clearRateCapForTest
  *
- * Opt into a per-(actor, table, column) cap on sealed-column unseal
- * FAILURES. By default (unconfigured) `unsealRow` only nulls the field
- * and emits `system.crypto.unseal_failed` on a forged-ciphertext read —
- * an attacker who can write `vault:<crafted>` payloads can hammer the
- * KEM-decapsulation / AEAD-verify oracle indefinitely, and only an
- * off-band operator alert rule catches the burst. With a cap configured,
- * once a single tuple accrues `threshold` failures inside `windowMs`,
- * every subsequent `unsealRow` touching that tuple is REFUSED for
- * `cooldownMs` with a `CryptoFieldRateError` and a distinct
+ * Tune the per-(actor, table, column) cap on sealed-column unseal
+ * FAILURES. The cap is ON BY DEFAULT (default-on, v0.15.0): the framework
+ * arms it at module load (threshold 10 / 1-minute window / 5-minute
+ * cooldown) so a forged-ciphertext oracle is bounded with no operator
+ * action. Once a single tuple accrues `threshold` failures inside
+ * `windowMs`, every subsequent `unsealRow` touching that tuple is REFUSED
+ * for `cooldownMs` with a `CryptoFieldRateError` and a distinct
  * `system.crypto.unseal_rate_exceeded` audit row, bounding the oracle.
- *
- * Pass `null` (or `{ disabled: true }`) to turn the cap back off. This is
- * a behaviour-changing refusal gate, so it is opt-in: unconfigured
- * deployments keep today's audit-only behaviour with full back-compat.
- * Validation is config-time / entry-point tier — bad `threshold` /
- * `windowMs` / `cooldownMs` THROW so an operator catches the typo at
- * boot rather than silently disabling the cap.
+ * Without the cap, an attacker who can write `vault:<crafted>` payloads
+ * can hammer the KEM-decapsulation / AEAD-verify oracle indefinitely and
+ * only an off-band operator alert rule catches the burst.
+ *
+ * Pass an opts object to RAISE/lower the thresholds. Pass `null` (or
+ * `{ disabled: true }`) to turn the cap off entirely and fall back to
+ * audit-only (the pre-v0.15.0 behaviour) — the documented opt-out for the
+ * rare deployment that needs an unbounded read path. Validation is
+ * config-time / entry-point tier — bad `threshold` / `windowMs` /
+ * `cooldownMs` THROW so an operator catches the typo at boot rather than
+ * silently mis-configuring the cap.
  *
  * CWE-307 (excessive-attempt restriction); OWASP ASVS v5 §2.2.1;
  * NIST SP 800-63B §5.2.2.
@@ -780,20 +925,19 @@ function _rateNoteFailure(actor, table, column) {
  * @status    experimental
  * @related   b.cryptoField.configureUnsealRateCap
  *
- * Test-only helper. Disables the unseal-failure rate cap and drops every
- * in-flight sliding-window + cooldown entry so a fixture can re-configure
- * the cap between cases. Operator code never calls this — production
- * deployments configure the cap once at boot.
+ * Test-only helper. Restores the secure DEFAULT cap (default-on baseline)
+ * and drops every in-flight sliding-window + cooldown entry so a fixture
+ * can re-configure the cap between cases from a known-good starting point.
+ * Operator code never calls this — production deployments inherit the
+ * default cap at boot and tune or disable it via configureUnsealRateCap.
  *
  * @example
  *   b.cryptoField.configureUnsealRateCap({ threshold: 3 });
  *   b.cryptoField.clearRateCapForTest();
- *   // cap is off again; windows + cooldowns cleared
+ *   // cap is back at the secure default; windows + cooldowns cleared
  */
 function clearRateCapForTest() {
-  _rateCap = null;
-  _rateFailWindows.clear();
-  _rateCooldowns.clear();
+  _installDefaultRateCap();
 }
 
 // ---- Row sealing / unsealing ----
@@ -896,7 +1040,7 @@ function sealRow(table, row, opts) {
         "' is AAD-bound (registerTable({aad:true})); the row's identity " +
         "column '" + s.rowIdField + "' must be populated BEFORE sealRow. " +
         "Generate the primary key first (e.g. uuid / sequence INSERT … RETURNING), " +
-        "set row." + s.rowIdField + ", then sealRow.");
+        "set row." + s.rowIdField + ", then sealRow.");   // allow:hand-rolled-sql — error-message prose, not SQL
     }
   }
 
@@ -916,10 +1060,11 @@ function sealRow(table, row, opts) {
       // 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]);
+      // Encode the value type-faithfully (Buffer / object preserved, not
+      // String()-mangled), then UTF-8 to bytes for the AEAD. The typed
+      // encoding of a string / base64 / JSON is pure ASCII-or-UTF8, so the
+      // Buffer.from(str, "utf8") round-trips losslessly.
+      var plainStr = _encodeTyped(out[field]);
       out[field] = ROW_PREFIX +
         encryptPacked(Buffer.from(plainStr, "utf8"), kRow, cellAad).toString("base64");
     } else if (s.aad) {
@@ -927,12 +1072,12 @@ function sealRow(table, row, opts) {
       if (typeof out[field] === "string" && vaultAad.isAadSealed(out[field])) {
         continue;
       }
-      out[field] = vaultAad.seal(String(out[field]),
+      out[field] = vaultAad.seal(_encodeTyped(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]));
+      out[field] = vault.seal(_encodeTyped(out[field]));
     }
   }
 
@@ -980,15 +1125,17 @@ function _aadParts(schema, table, column, row) {
  * 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:
- * once tripped, this call THROWS `CryptoFieldRateError` and emits a
- * distinct `system.crypto.unseal_rate_exceeded` audit instead of
- * exercising the decryption oracle again (CWE-307). `actor` identifies
- * the caller for that tuple (e.g. session subject / API key id); it
- * defaults to an anonymous bucket when omitted, and is ignored entirely
- * when no cap is configured (full back-compat for the 2-arg call).
+ * The unseal-failure rate cap is ON BY DEFAULT (default-on, v0.15.0):
+ * repeated forged-ciphertext failures for a single `(actor, table,
+ * column)` tuple trip a cooldown (threshold 10 / 1-minute window /
+ * 5-minute cooldown out of the box; tune or disable via
+ * `configureUnsealRateCap`). Once tripped, this call THROWS
+ * `CryptoFieldRateError` and emits a distinct
+ * `system.crypto.unseal_rate_exceeded` audit instead of exercising the
+ * decryption oracle again (CWE-307). `actor` identifies the caller for
+ * that tuple (e.g. session subject / API key id); it defaults to an
+ * anonymous bucket when omitted, and is ignored entirely when the cap is
+ * disabled (full back-compat for the 2-arg call).
  *
  * @example
  *   b.cryptoField.registerTable("patients", { sealedFields: ["ssn"] });
@@ -1035,9 +1182,13 @@ function unsealRow(table, row, actor, dbHandle) {
       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);
+      var wrapSelBuilt = sql.select(_perRowKeysTableName(), _PER_ROW_SQL_OPTS)
+        .columns(["wrappedKey"])
+        .where("tableName", table)
+        .where("rowId", kRowId)
+        .toSql();
+      var wrapStmt = prep(wrapSelBuilt.sql);
+      wrap = wrapStmt.get.apply(wrapStmt, wrapSelBuilt.params);
     } catch (_e) {
       return null;
     }
@@ -1053,7 +1204,7 @@ function unsealRow(table, row, actor, dbHandle) {
       // 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
+      // Default-on 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)) {
@@ -1082,14 +1233,14 @@ function unsealRow(table, row, actor, dbHandle) {
               "' is unavailable (shredded or never materialized)");
           }
           var cellAad = _aadBytes(_rowCellAad(s, table, field, kRowId));
-          unsealed = decryptPacked(
+          unsealed = _decodeTyped(decryptPacked(
             Buffer.from(out[field].slice(ROW_PREFIX.length), "base64"), kRow, cellAad
-          ).toString("utf8");
+          ).toString("utf8"));
         } else if (typeof out[field] === "string" && vaultAad.isAadSealed(out[field])) {
-          unsealed = vaultAad.unseal(out[field],
-            _aadParts(s, table, field, out));
+          unsealed = _decodeTyped(vaultAad.unseal(out[field],
+            _aadParts(s, table, field, out)));
         } else if (typeof out[field] === "string" && out[field].startsWith(VAULT_PREFIX)) {
-          unsealed = vault.unseal(out[field]);
+          unsealed = _decodeTyped(vault.unseal(out[field]));
         } else {
           // Not a sealed value — pass through.
           unsealed = out[field];
@@ -1117,7 +1268,7 @@ function unsealRow(table, row, actor, dbHandle) {
             },
           });
         } catch (_e) { /* drop-silent */ }
-        // Opt-in rate cap: account this failure against the (actor,
+        // Default-on rate cap: account this failure against the (actor,
         // table, column) tuple. When it trips the threshold, arm the
         // cooldown + emit the distinct rate-exceeded audit once on the
         // transition. No-op when the cap is disabled.
@@ -1140,9 +1291,91 @@ function unsealRow(table, row, actor, dbHandle) {
     }
   }
 
+  // Upgrade-on-read auto-migrate for the keyed-MAC derived-hash default
+  // flip (v0.15.0). A row written BEFORE the default moved from salted-sha3
+  // to hmac-shake256 carries the legacy salted digest in its derived-hash
+  // column; a keyed-only lookup would miss it (the dual-read in
+  // lookupHashCandidates is what FINDS it). When such a row is unsealed and
+  // we now hold the source plaintext, recompute the keyed-MAC digest and, if
+  // the stored column still holds the legacy salted-sha3 value, re-write that
+  // column to the keyed form so the row is keyed-indexed from now on and the
+  // candidate set collapses back to a single value over time. Best-effort:
+  // the returned row always carries the upgraded hash; the durable rewrite
+  // happens only when a writable dbHandle is available + the row has an _id.
+  _upgradeDerivedHashesOnRead(s, table, out, dbHandle);
+
   return out;
 }
 
+// Re-hash any legacy-salted derived-hash columns on a just-unsealed row to
+// the active keyed-MAC form. Pure-detect + in-place upgrade on the returned
+// `out` object; when `dbHandle` exposes a writable .prepare(), the upgrade is
+// also persisted with one UPDATE per row keyed on `_id`. Never throws — a
+// failed durable rewrite leaves the row matchable via the legacy digest (the
+// dual-read still finds it next time).
+function _upgradeDerivedHashesOnRead(s, table, out, dbHandle) {
+  if (!s.derivedHashes) return;
+  var rowId = out._id != null ? String(out._id) : "";
+  var upgrades = null;   // { derivedField: keyedValue } to persist
+  for (var derivedField in s.derivedHashes) {
+    if (!Object.prototype.hasOwnProperty.call(s.derivedHashes, derivedField)) continue;
+    var spec = s.derivedHashes[derivedField];
+    // Only the keyed-MAC mode has a distinct legacy form to migrate from.
+    if (_resolveDerivedHashMode(spec, s.derivedHashMode) !== "hmac-shake256") continue;
+    var stored = out[derivedField];
+    if (typeof stored !== "string" || stored.length === 0) continue;
+    var plain = out[spec.from];
+    if (plain === undefined || plain === null) continue;   // source erased / absent — nothing to re-hash
+    var ns = namespaceFor(table, spec.from, s.hashNamespaces);
+    var normalized = spec.normalize ? spec.normalize(plain) : String(plain);
+    var keyed  = _computeDerivedHash(spec, s.derivedHashMode, ns, normalized);
+    if (stored === keyed) continue;                         // already keyed-indexed
+    var legacy = _legacyDerivedHash(ns, normalized);
+    if (stored !== legacy) continue;                        // not the legacy digest — leave untouched
+    // Found a legacy-indexed row: surface the keyed hash on the returned row
+    // and queue the durable rewrite.
+    out[derivedField] = keyed;
+    if (!upgrades) upgrades = {};
+    upgrades[derivedField] = keyed;
+  }
+  if (!upgrades) return;
+  // Persist when we can resolve a writable local handle + have a row identity.
+  // The derived-hash columns + the app table live on the LOCAL db (the same
+  // handle the per-row-key registry uses); the rewrite is a plain UPDATE.
+  if (rowId.length === 0) return;
+  var handle = (dbHandle && typeof dbHandle.prepare === "function")
+    ? dbHandle
+    : _resolveLocalDbHandle();
+  if (!handle) return;
+  try {
+    var updBuilt = sql.update(table, { dialect: "sqlite", quoteName: true })
+      .set(upgrades)
+      .where("_id", rowId)
+      .toSql();
+    var stmt = handle.prepare(updBuilt.sql);
+    stmt.run.apply(stmt, updBuilt.params);
+  } catch (_e) {
+    // Best-effort — DB not initialized, read-only handle, or the app table
+    // isn't on this handle (cluster mode where the row came from the external
+    // backend). The returned row still carries the upgraded hash; the legacy
+    // digest stays matchable via lookupHashCandidates until a writable read
+    // path re-hashes it.
+  }
+}
+
+// Resolve the framework's local db handle for the upgrade-on-read rewrite.
+// Mirrors the K_row read path's fallback: prefer an explicit dbHandle, else
+// the framework's own db(). Returns null when no .prepare()-capable handle
+// is reachable (db not initialized yet) so the caller skips the durable write.
+function _resolveLocalDbHandle() {
+  try {
+    var inst = db();
+    return (inst && typeof inst.prepare === "function") ? inst : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
 // ---- Erasure (GDPR Art. 17 / "right to be forgotten") ----
 //
 // eraseRow(table, row) returns a tombstoned copy of the row: every
@@ -1277,6 +1510,16 @@ function eraseRow(table, row) {
  * every encryption uses a fresh random nonce, so the ciphertext alone
  * cannot anchor a query.
  *
+ * `value` is the digest under the column's ACTIVE mode (keyed-MAC by
+ * default since v0.15.0; salted-sha3 when opted out), so existing callers
+ * that emit `where(result.field, result.value)` are unchanged. When the
+ * active mode is the keyed MAC, the result ALSO carries `legacyValue` — the
+ * byte-form a row written under the pre-v0.15.0 salted-sha3 default would
+ * hold. Callers that can issue a match-EITHER query (or that prefer the
+ * ready-made candidate list) use `b.cryptoField.lookupHashCandidates`; the
+ * upgrade-on-read auto-migrate in `unsealRow` re-hashes any row found via
+ * the legacy digest to the keyed-MAC form.
+ *
  * @example
  *   b.cryptoField.registerTable("users", {
  *     sealedFields: ["email"],
@@ -1294,14 +1537,52 @@ function lookupHash(table, field, value) {
   for (var derivedField in s.derivedHashes) {
     var spec = s.derivedHashes[derivedField];
     if (spec.from === field) {
-      var ns = namespaceFor(table, field, s.hashNamespaces);
-      var normalized = spec.normalize ? spec.normalize(value) : String(value);
-      return { field: derivedField, value: _computeDerivedHash(spec, s.derivedHashMode, ns, normalized) };
+      return _derivedHashResult(s, table, derivedField, spec, field, value);
     }
   }
   return null;
 }
 
+/**
+ * @primitive b.cryptoField.lookupHashCandidates
+ * @signature b.cryptoField.lookupHashCandidates(table, field, value)
+ * @since     0.15.0
+ * @compliance gdpr, hipaa
+ * @related   b.cryptoField.lookupHash, b.cryptoField.unsealRow
+ *
+ * Dual-read sibling of `lookupHash`. Returns `{ field, values }` where
+ * `values` is the list of derived-hash digests that should ALL be treated
+ * as a match for `value` — the digest under the column's active mode FIRST,
+ * plus (when the active mode is the keyed MAC) the pre-v0.15.0 salted-sha3
+ * digest a row written under the old default would carry. A caller that can
+ * issue an `IN (…)` / `OR` equality over `field` finds both the new
+ * keyed-indexed rows and the legacy salted-indexed rows in one query, so the
+ * keyed-MAC default flip never silently drops pre-flip rows. Returns null
+ * when no derived hash is declared for `field`.
+ *
+ * Pair it with the upgrade-on-read auto-migrate: `unsealRow` re-hashes any
+ * row whose stored derived-hash matches the legacy digest to the keyed-MAC
+ * form, so the candidate list shrinks back to a single value as rows are
+ * read over time.
+ *
+ * @example
+ *   b.cryptoField.registerTable("users", {
+ *     sealedFields:  ["email"],
+ *     derivedHashes: { emailHash: { from: "email" } },
+ *   });
+ *   var c = b.cryptoField.lookupHashCandidates("users", "email", "alice@example.com");
+ *   c.field;            // → "emailHash"
+ *   c.values.length;    // → 2  (keyed-MAC + legacy salted-sha3)
+ *   // → b.db.from("users").where(c.field, "IN", c.values)
+ */
+function lookupHashCandidates(table, field, value) {
+  var r = lookupHash(table, field, value);
+  if (!r) return null;
+  var values = [r.value];
+  if (r.legacyValue && r.legacyValue !== r.value) values.push(r.legacyValue);
+  return { field: r.field, values: values };
+}
+
 /**
  * @primitive b.cryptoField.declareColumnResidency
  * @signature b.cryptoField.declareColumnResidency(table, opts)
@@ -1658,9 +1939,13 @@ function materializePerRowKey(table, rowId, dbHandle) {
   }
   var ridStr = String(rowId);
   // Existing secret? Unwrap + re-derive to support idempotent UPSERTs.
-  var existing = dbHandle.prepare(
-    'SELECT wrappedKey FROM "' + PER_ROW_KEYS_TABLE + '" WHERE tableName = ? AND rowId = ?'
-  ).get(table, ridStr);
+  var existingSelBuilt = sql.select(_perRowKeysTableName(), _PER_ROW_SQL_OPTS)
+    .columns(["wrappedKey"])
+    .where("tableName", table)
+    .where("rowId", ridStr)
+    .toSql();
+  var existingStmt = dbHandle.prepare(existingSelBuilt.sql);
+  var existing = existingStmt.get.apply(existingStmt, existingSelBuilt.params);
   if (existing) {
     return _deriveKRow(_unwrapRowSecret(existing.wrappedKey, ridStr), table, ridStr, spec);
   }
@@ -1677,10 +1962,17 @@ function materializePerRowKey(table, rowId, dbHandle) {
   // _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 "' + PER_ROW_KEYS_TABLE + '" (_id, tableName, rowId, wrappedKey, createdAt) ' +
-    'VALUES (?, ?, ?, ?, ?)'
-  ).run(generateToken(16), table, ridStr, sealed, Date.now());
+  var insBuilt = sql.insert(_perRowKeysTableName(), _PER_ROW_SQL_OPTS)
+    .values({
+      _id:        generateToken(16),
+      tableName:  table,
+      rowId:      ridStr,
+      wrappedKey: sealed,
+      createdAt:  Date.now(),
+    })
+    .toSql();
+  var insStmt = dbHandle.prepare(insBuilt.sql);
+  insStmt.run.apply(insStmt, insBuilt.params);
   return kRow;
 }
 
@@ -1739,9 +2031,12 @@ function destroyPerRowKey(table, rowId, dbHandle) {
     throw new CryptoFieldError("crypto-field/destroy-per-row-key-no-db",
       "destroyPerRowKey: dbHandle (b.db) is required");
   }
-  var result = dbHandle.prepare(
-    'DELETE FROM "' + PER_ROW_KEYS_TABLE + '" WHERE tableName = ? AND rowId = ?'
-  ).run(table, String(rowId));
+  var delBuilt = sql.delete(_perRowKeysTableName(), _PER_ROW_SQL_OPTS)
+    .where("tableName", table)
+    .where("rowId", String(rowId))
+    .toSql();
+  var delStmt = dbHandle.prepare(delBuilt.sql);
+  var result = delStmt.run.apply(delStmt, delBuilt.params);
   return { destroyed: (result && result.changes) || 0 };
 }
 
@@ -1797,6 +2092,7 @@ module.exports = {
   computeDerived:   computeDerived,
   computeNamespacedHash: computeNamespacedHash,
   lookupHash:       lookupHash,
+  lookupHashCandidates: lookupHashCandidates,
   clearForTest:     clearForTest,
   declareColumnResidency: declareColumnResidency,
   getColumnResidency:     getColumnResidency,