@blamejs/core 0.14.19 → 0.14.20

package/lib/auth/sd-jwt-vc-holder.js

@@ -43,6 +43,7 @@
  * tests — production operators wire b.db / b.objectStore.
  */
 
+var nodeCrypto = require("node:crypto");
 var lazyRequire = require("../lazy-require");
 var validateOpts = require("../validate-opts");
 var { AuthError } = require("../framework-error");
@@ -51,6 +52,50 @@ var sdJwtVcCore = lazyRequire(function () { return require("./sd-jwt-vc"); });
 var audit = lazyRequire(function () { return require("../audit"); });
 var observability = lazyRequire(function () { return require("../observability"); });
 
+// EC curve → the KB-JWT alg the sd-jwt-vc core supports for it. P-521
+// has no entry — the core's SUPPORTED_ALGS stops at ES384.
+var _HOLDER_EC_CURVE_ALG = { prime256v1: "ES256", secp384r1: "ES384" };
+
+// Resolve the KB-JWT signing alg from the holder key when the operator
+// gives no explicit `algorithm`. A fixed default (the old "ES256") signed
+// a non-EC-P256 holder key under a header alg that disagreed with the key
+// — un-signable (Ed25519 / EC-P384) or a self-invalid KB-JWT a verifier
+// rejects (any key whose sign succeeds under the wrong digest). Inferring
+// from the key keeps the common EC-P256 → ES256 case unchanged while
+// producing a self-consistent KB-JWT for every other supported key, and
+// refuses a key type the core has no alg for (e.g. RSA) instead of
+// emitting a broken presentation. An explicit `algorithm` is honoured and
+// validated by the core against SUPPORTED_ALGS.
+function _resolveHolderAlg(holderKey, explicitAlg) {
+  if (explicitAlg) return explicitAlg;
+  var keyObj = null;
+  try {
+    if (holderKey instanceof nodeCrypto.KeyObject) {
+      keyObj = holderKey;
+    } else if (typeof holderKey === "string" || Buffer.isBuffer(holderKey)) {
+      keyObj = nodeCrypto.createPrivateKey({ key: holderKey, format: "pem" });
+    } else if (holderKey && typeof holderKey === "object" && holderKey.kty) {
+      keyObj = nodeCrypto.createPrivateKey({ key: holderKey, format: "jwk" });
+    }
+  } catch (_e) {
+    keyObj = null;                       // unreadable key — let the signer surface the real error
+  }
+  if (!keyObj) return "ES256";           // preserve the historical default when the type can't be read
+  var kty = keyObj.asymmetricKeyType;
+  if (kty === "ec") {
+    var curve = (keyObj.asymmetricKeyDetails && keyObj.asymmetricKeyDetails.namedCurve) || "";
+    var ecAlg = _HOLDER_EC_CURVE_ALG[curve];
+    if (ecAlg) return ecAlg;
+    throw new AuthError("auth-sd-jwt-vc/holder-key-unsupported",
+      "holder.create: EC curve '" + curve + "' has no KB-JWT algorithm (use P-256 / P-384, Ed25519, or ML-DSA-87 / ML-DSA-65)");
+  }
+  if (kty === "ed25519" || kty === "ed448") return "EdDSA";
+  if (kty === "ml-dsa-87") return "ML-DSA-87";
+  if (kty === "ml-dsa-65") return "ML-DSA-65";
+  throw new AuthError("auth-sd-jwt-vc/holder-key-unsupported",
+    "holder.create: key type '" + String(kty) + "' has no KB-JWT algorithm (use EC P-256 / P-384, Ed25519, or ML-DSA-87 / ML-DSA-65; RSA is not supported for KB-JWT)");
+}
+
 function _validateStorage(storage) {
   if (!storage || typeof storage !== "object") return false;
   return ["put", "get", "list", "delete"].every(function (m) {
@@ -96,7 +141,7 @@ function create(opts) {
     throw new AuthError("auth-sd-jwt-vc/no-key",
       "holder.create: holderKey required");
   }
-  var algorithm = opts.algorithm || "ES256";
+  var algorithm = _resolveHolderAlg(opts.holderKey, opts.algorithm);
   var auditOn = opts.auditOn !== false;
 
   function _emitAudit(action, outcome, metadata) {

package/lib/crypto-field.js

@@ -45,9 +45,19 @@
 var lazyRequire = require("./lazy-require");
 var vault = require("./vault");
 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");
 
+// Typed refusal raised when a (actor, table, column) tuple exceeds the
+// opt-in unseal-failure rate cap and is in cooldown. alwaysPermanent —
+// the caller does not retry; the cooldown is a deliberate, time-bounded
+// circuit-breaker, not a transient backend hiccup.
+var CryptoFieldRateError = defineClass("CryptoFieldRateError", { alwaysPermanent: true });
+var CryptoFieldError     = defineClass("CryptoFieldError", { alwaysPermanent: true });
+
 var compliance    = lazyRequire(function () { return require("./compliance"); });
 var db            = lazyRequire(function () { return require("./db"); });
 var audit         = lazyRequire(function () { return require("./audit"); });
@@ -187,7 +197,8 @@ function registerTable(name, opts) {
   var schemaVersion = opts.schemaVersion != null ? String(opts.schemaVersion) : "1";
   var derivedHashMode = opts.derivedHashMode || "salted-sha3";
   if (derivedHashMode !== "salted-sha3" && derivedHashMode !== "hmac-shake256") {
-    throw new Error("registerTable: derivedHashMode must be 'salted-sha3' (default) or " +
+    throw new CryptoFieldError("crypto-field/bad-derived-hash-mode",
+      "registerTable: derivedHashMode must be 'salted-sha3' (default) or " +
       "'hmac-shake256', got " + JSON.stringify(derivedHashMode));
   }
   var derivedHashes = Object.assign({}, opts.derivedHashes || {});
@@ -195,7 +206,8 @@ function registerTable(name, opts) {
     if (!Object.prototype.hasOwnProperty.call(derivedHashes, col)) continue;
     var colMode = derivedHashes[col] && derivedHashes[col].mode;
     if (colMode !== undefined && colMode !== "salted-sha3" && colMode !== "hmac-shake256") {
-      throw new Error("registerTable: derivedHashes." + col + ".mode must be " +
+      throw new CryptoFieldError("crypto-field/bad-derived-hash-col-mode",
+        "registerTable: derivedHashes." + col + ".mode must be " +
         "'salted-sha3' or 'hmac-shake256', got " + JSON.stringify(colMode));
     }
   }
@@ -285,14 +297,16 @@ function computeNamespacedHash(ns, value, opts) {
   opts = opts || {};
   var mode = opts.mode || "salted-sha3";
   if (mode !== "salted-sha3" && mode !== "hmac-shake256") {
-    throw new Error("computeNamespacedHash: opts.mode must be 'salted-sha3' " +
+    throw new CryptoFieldError("crypto-field/bad-namespaced-hash-mode",
+      "computeNamespacedHash: opts.mode must be 'salted-sha3' " +
       "(default) or 'hmac-shake256', got " + JSON.stringify(mode));
   }
   var truncateBytes = opts.truncateBytes;
   if (truncateBytes !== undefined) {
     if (typeof truncateBytes !== "number" || !isFinite(truncateBytes) ||
         truncateBytes <= 0 || Math.floor(truncateBytes) !== truncateBytes) {
-      throw new Error("computeNamespacedHash: opts.truncateBytes must be a " +
+      throw new CryptoFieldError("crypto-field/bad-truncate-bytes",
+        "computeNamespacedHash: opts.truncateBytes must be a " +
         "positive integer (bytes), got " + JSON.stringify(truncateBytes));
     }
   }
@@ -422,6 +436,202 @@ function computeDerived(table, sourceField, sourceValue) {
   return null;
 }
 
+// ---- Unseal-failure rate cap (CWE-307) ----
+//
+// Opt-in brute-force / decryption-oracle throttle for the unsealRow read
+// path. A DB-write attacker who can write `vault:<crafted>` /
+// `vault.aad:<crafted>` payloads to sealed columns can force KEM
+// decapsulation / AEAD verify on attacker-controlled bytes on every read.
+// unsealRow already nulls the field + emits system.crypto.unseal_failed,
+// but absent a cap the attacker can hammer the oracle indefinitely and
+// only an off-band operator alert rule catches the burst. This adds an
+// in-process per-(actor, table, column) sliding-window failure cap: past
+// `threshold` failures inside `windowMs`, further unseal attempts for that
+// 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.
+//
+// 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
+var _rateFailWindows = new Map();             // "actor\x00table\x00column" → [tsMs, ...]
+var _rateCooldowns = new Map();               // same key → cooldownUntilMs
+
+// 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
+// prototype-pollution surface.
+function _rateKey(actor, table, column) {
+  return String(actor) + "\x00" + table + "\x00" + column;
+}
+
+/**
+ * @primitive b.cryptoField.configureUnsealRateCap
+ * @signature b.cryptoField.configureUnsealRateCap(opts)
+ * @since     0.14.20
+ * @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
+ * `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.
+ *
+ * CWE-307 (excessive-attempt restriction); OWASP ASVS v5 §2.2.1;
+ * NIST SP 800-63B §5.2.2.
+ *
+ * @opts
+ *   threshold: number,    // failures within the window before refusal kicks in (positive int)
+ *   windowMs:  number,    // sliding-window width in ms (positive int; default 60000)
+ *   cooldownMs: number,   // refusal duration once tripped (positive int; default windowMs)
+ *   disabled:  boolean,   // pass true to turn the cap off (same as configureUnsealRateCap(null))
+ *   now:       function,  // injected clock returning epoch ms; default Date.now (test seam)
+ *   onAudit:   function,  // optional sink({ action, outcome, metadata }) for the rate audit (test seam)
+ *
+ * @example
+ *   b.cryptoField.configureUnsealRateCap({ threshold: 5, windowMs: 60000, cooldownMs: 300000 });
+ *   // ...after 5 forged-ciphertext unseal failures for one (actor, table, column):
+ *   try { b.cryptoField.unsealRow("patients", forgedRow, "actor-42"); }
+ *   catch (e) { e.code; }   // → "crypto-field/unseal-rate-exceeded"
+ *
+ *   b.cryptoField.configureUnsealRateCap(null);   // → disable again
+ */
+function configureUnsealRateCap(opts) {
+  if (opts === null || opts === undefined || opts.disabled === true) {
+    _rateCap = null;
+    _rateFailWindows.clear();
+    _rateCooldowns.clear();
+    return null;
+  }
+  validateOpts(opts, ["threshold", "windowMs", "cooldownMs", "disabled", "now", "onAudit"],
+    "cryptoField.configureUnsealRateCap");
+  // threshold is required (no default); presence-guard first, then validate
+  // the three positive-int bounds through the shared batch helper so the
+  // get-or-default and the bound checks each live in one place.
+  if (opts.threshold === undefined) {
+    throw new CryptoFieldRateError("crypto-field/bad-threshold",
+      "cryptoField.configureUnsealRateCap: opts.threshold is required and must be a positive finite integer");
+  }
+  numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
+    ["threshold", "windowMs", "cooldownMs"],
+    "cryptoField.configureUnsealRateCap", CryptoFieldRateError, "crypto-field/bad-rate-cap-opt");
+  validateOpts.optionalFunction(opts.now,
+    "cryptoField.configureUnsealRateCap: opts.now", CryptoFieldRateError,
+    "crypto-field/bad-now");
+  validateOpts.optionalFunction(opts.onAudit,
+    "cryptoField.configureUnsealRateCap: opts.onAudit", CryptoFieldRateError,
+    "crypto-field/bad-on-audit");
+
+  var windowMs = opts.windowMs === undefined ? TIME.minutes(1) : opts.windowMs;
+  _rateCap = {
+    threshold:  opts.threshold,
+    windowMs:   windowMs,
+    cooldownMs: opts.cooldownMs === undefined ? windowMs : opts.cooldownMs,
+    now:        typeof opts.now === "function" ? opts.now : function () { return Date.now(); },
+    onAudit:    typeof opts.onAudit === "function" ? opts.onAudit : null,
+  };
+  // Re-arming with a fresh config drops any in-flight windows/cooldowns
+  // so a config change can't leave a tuple stuck in an old cooldown.
+  _rateFailWindows.clear();
+  _rateCooldowns.clear();
+  return { threshold: _rateCap.threshold, windowMs: _rateCap.windowMs, cooldownMs: _rateCap.cooldownMs };
+}
+
+// Emit the distinct rate-exceeded audit. Drop-silent (hot-path sink): a
+// throwing audit on the read path must not crash the request that
+// triggered it. Honors the injected onAudit test sink when present,
+// otherwise routes through the framework audit chain.
+function _emitRateAudit(metadata) {
+  try {
+    if (_rateCap && _rateCap.onAudit) {
+      _rateCap.onAudit({ action: "system.crypto.unseal_rate_exceeded", outcome: "denied", metadata: metadata });
+      return;
+    }
+    audit().safeEmit({ action: "system.crypto.unseal_rate_exceeded", outcome: "denied", metadata: metadata });
+  } catch (_e) { /* drop-silent — audit best-effort */ }
+}
+
+// Pre-unseal gate. Returns true when the tuple is currently in cooldown
+// (caller must refuse). No-op (returns false) when the cap is disabled.
+// Prunes an expired cooldown lazily so the Map can't grow unbounded.
+function _rateInCooldown(actor, table, column) {
+  if (!_rateCap) return false;
+  var key = _rateKey(actor, table, column);
+  var until = _rateCooldowns.get(key);
+  if (until === undefined) return false;
+  if (_rateCap.now() >= until) {
+    _rateCooldowns.delete(key);
+    _rateFailWindows.delete(key);
+    return false;
+  }
+  return true;
+}
+
+// Post-failure accounting. Records one failure timestamp for the tuple,
+// prunes the sliding window, and arms a cooldown when the count reaches
+// the threshold. Returns true when this failure tripped the cap (so the
+// caller can emit the rate audit exactly once on the transition).
+function _rateNoteFailure(actor, table, column) {
+  if (!_rateCap) return false;
+  var nowMs = _rateCap.now();
+  var key = _rateKey(actor, table, column);
+  var arr = _rateFailWindows.get(key);
+  if (!arr) { arr = []; _rateFailWindows.set(key, arr); }
+  // Prune entries older than the window (sliding-window via timestamp
+  // array — same shape as b.mail.server.rateLimit._pruneWindow).
+  var cutoff = nowMs - _rateCap.windowMs;
+  var drop = 0;
+  while (drop < arr.length && arr[drop] < cutoff) drop += 1;
+  if (drop > 0) arr.splice(0, drop);
+  arr.push(nowMs);
+  if (arr.length >= _rateCap.threshold) {
+    _rateCooldowns.set(key, nowMs + _rateCap.cooldownMs);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @primitive b.cryptoField.clearRateCapForTest
+ * @signature b.cryptoField.clearRateCapForTest()
+ * @since     0.14.20
+ * @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.
+ *
+ * @example
+ *   b.cryptoField.configureUnsealRateCap({ threshold: 3 });
+ *   b.cryptoField.clearRateCapForTest();
+ *   // cap is off again; windows + cooldowns cleared
+ */
+function clearRateCapForTest() {
+  _rateCap = null;
+  _rateFailWindows.clear();
+  _rateCooldowns.clear();
+}
+
 // ---- Row sealing / unsealing ----
 
 /**
@@ -485,7 +695,8 @@ function sealRow(table, row) {
   if (s.aad) {
     var rowId = out[s.rowIdField];
     if (rowId === undefined || rowId === null || String(rowId).length === 0) {
-      throw new Error("cryptoField.sealRow: table '" + table +
+      throw new CryptoFieldError("crypto-field/seal-row-aad-rowid-missing",
+        "cryptoField.sealRow: table '" + table +
         "' 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), " +
@@ -533,10 +744,10 @@ function _aadParts(schema, table, column, row) {
 
 /**
  * @primitive b.cryptoField.unsealRow
- * @signature b.cryptoField.unsealRow(table, row)
+ * @signature b.cryptoField.unsealRow(table, row, actor?)
  * @since     0.4.0
  * @compliance hipaa, gdpr, pci-dss
- * @related   b.cryptoField.sealRow, b.vault.unseal
+ * @related   b.cryptoField.sealRow, b.vault.unseal, b.cryptoField.configureUnsealRateCap
  *
  * Returns a copy of `row` with every sealed column unwrapped via
  * `vault.unseal()`. Round-trips with `sealRow`. When `vault.unseal`
@@ -547,21 +758,45 @@ function _aadParts(schema, table, column, row) {
  * so downstream code sees "no value" instead of crashing the request.
  * The input row is never mutated.
  *
+ * 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).
+ *
  * @example
  *   b.cryptoField.registerTable("patients", { sealedFields: ["ssn"] });
  *   var sealed = b.cryptoField.sealRow("patients", { id: 1, ssn: "123-45-6789" });
  *   var clear  = b.cryptoField.unsealRow("patients", sealed);
  *   clear.ssn;   // → "123-45-6789"
  */
-function unsealRow(table, row) {
+function unsealRow(table, row, actor) {
   if (!row) return row;
   var s = schemas[table];
   if (!s || s.sealedFields.length === 0) return row;
   var out = Object.assign({}, row);
+  var capActor = (actor === undefined || actor === null || String(actor).length === 0)
+    ? "_anon" : String(actor);
 
   for (var i = 0; i < s.sealedFields.length; i++) {
     var field = s.sealedFields[i];
     if (out[field]) {
+      // 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",
+          threshold: _rateCap.threshold, windowMs: _rateCap.windowMs, cooldownMs: _rateCap.cooldownMs,
+        });
+        throw new CryptoFieldRateError("crypto-field/unseal-rate-exceeded",
+          "cryptoField.unsealRow: unseal-failure rate cap tripped for (actor, '" + table +
+          "', '" + field + "') — refusing further unseal attempts during cooldown");
+      }
       var unsealed;
       try {
         // Auto-detect the envelope shape so an AAD-bound table that
@@ -599,6 +834,16 @@ function unsealRow(table, row) {
             },
           });
         } catch (_e) { /* drop-silent */ }
+        // Opt-in 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.
+        if (_rateNoteFailure(capActor, table, field)) {
+          _emitRateAudit({
+            table: table, field: field, actor: capActor, shape: s.aad ? "aad" : "plain",
+            threshold: _rateCap.threshold, windowMs: _rateCap.windowMs, cooldownMs: _rateCap.cooldownMs,
+          });
+        }
         unsealed = null;
       }
       // Assign unconditionally. `unsealed` already carries the right value
@@ -806,21 +1051,25 @@ function lookupHash(table, field, value) {
  */
 function declareColumnResidency(table, opts) {
   if (typeof table !== "string" || table.length === 0) {
-    throw new Error("declareColumnResidency: table must be a non-empty string");
+    throw new CryptoFieldError("crypto-field/residency-table-empty",
+      "declareColumnResidency: table must be a non-empty string");
   }
   if (opts === null || opts === undefined || typeof opts !== "object" || Array.isArray(opts)) {
-    throw new Error("declareColumnResidency: opts must be a plain object");
+    throw new CryptoFieldError("crypto-field/residency-opts-not-object",
+      "declareColumnResidency: opts must be a plain object");
   }
   var map = opts.columnResidency;
   if (!map || typeof map !== "object" || Array.isArray(map)) {
-    throw new Error("declareColumnResidency: opts.columnResidency must be an object");
+    throw new CryptoFieldError("crypto-field/residency-map-not-object",
+      "declareColumnResidency: opts.columnResidency must be an object");
   }
   var entry = Object.create(null);
   for (var col in map) {
     if (!Object.prototype.hasOwnProperty.call(map, col)) continue;
     var tag = map[col];
     if (typeof tag !== "string" || tag.length === 0) {
-      throw new Error("declareColumnResidency: column '" + col +
+      throw new CryptoFieldError("crypto-field/residency-tag-empty",
+        "declareColumnResidency: column '" + col +
         "' residency tag must be a non-empty string");
     }
     entry[col] = tag;
@@ -943,17 +1192,20 @@ function assertColumnResidency(table, row, args) {
  */
 function declarePerRowKey(table, opts) {
   if (typeof table !== "string" || table.length === 0) {
-    throw new Error("declarePerRowKey: table must be a non-empty string");
+    throw new CryptoFieldError("crypto-field/per-row-key-table-empty",
+      "declarePerRowKey: table must be a non-empty string");
   }
   opts = opts || {};
   var keySize = opts.keySize === undefined ? 32 : opts.keySize; // XChaCha20-Poly1305 key length in bytes
   if (typeof keySize !== "number" || !isFinite(keySize) ||
       keySize < 16 || Math.floor(keySize) !== keySize) { // minimum AES-128 key length in bytes
-    throw new Error("declarePerRowKey: opts.keySize must be an integer >= 16 (bytes)");
+    throw new CryptoFieldError("crypto-field/per-row-key-bad-size",
+      "declarePerRowKey: opts.keySize must be an integer >= 16 (bytes)");
   }
   var info = opts.info || ("blamejs-per-row-key:" + table);
   if (typeof info !== "string" || info.length === 0) {
-    throw new Error("declarePerRowKey: opts.info must be a non-empty string");
+    throw new CryptoFieldError("crypto-field/per-row-key-info-empty",
+      "declarePerRowKey: opts.info must be a non-empty string");
   }
   perRowKeyTables[table] = { keySize: keySize, info: info };
   return { table: table, keySize: keySize, info: info };
@@ -1010,7 +1262,8 @@ function materializePerRowKey(table, rowId, dbHandle) {
   var spec = perRowKeyTables[table];
   if (!spec) return null;
   if (!dbHandle || typeof dbHandle.prepare !== "function") {
-    throw new Error("materializePerRowKey: dbHandle (b.db) is required");
+    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 existing = dbHandle.prepare(
@@ -1066,7 +1319,8 @@ function materializePerRowKey(table, rowId, dbHandle) {
 function destroyPerRowKey(table, rowId, dbHandle) {
   if (!perRowKeyTables[table]) return { destroyed: 0 };
   if (!dbHandle || typeof dbHandle.prepare !== "function") {
-    throw new Error("destroyPerRowKey: dbHandle (b.db) is required");
+    throw new CryptoFieldError("crypto-field/destroy-per-row-key-no-db",
+      "destroyPerRowKey: dbHandle (b.db) is required");
   }
   var result = dbHandle.prepare(
     'DELETE FROM "_blamejs_per_row_keys" WHERE tableName = ? AND rowId = ?'
@@ -1105,6 +1359,9 @@ module.exports = {
   getSealedFields:  getSealedFields,
   sealRow:          sealRow,
   unsealRow:        unsealRow,
+  configureUnsealRateCap: configureUnsealRateCap,
+  clearRateCapForTest:    clearRateCapForTest,
+  CryptoFieldRateError:   CryptoFieldRateError,
   // _aadParts — the column-AAD builder the seal/unseal path uses. Exported
   // (internal) so the vault-key rotation pipeline reconstructs the IDENTICAL
   // AAD tuple a cell was sealed under — one source of truth, no drift