@blamejs/core 0.14.19 → 0.14.21

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

package/lib/dora.js

@@ -248,8 +248,8 @@ function _validateReportInput(input) {
  *
  * @opts
  *   audit:          boolean (default true; set false to skip audit emits),
- *   observability:  boolean (reserved — observability counter is always
- *                  best-effort and ignored on failure),
+ *   observability:  boolean (default true; set false to skip the
+ *                  best-effort observability counter on report),
  *
  * @example
  *   var dora = b.dora.create({ audit: true });
@@ -276,6 +276,7 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, ["audit", "observability"], "dora.create");
   var auditOn = opts.audit !== false;
+  var obsOn   = opts.observability !== false;
 
   function _emit(action, info) {
     if (!auditOn) return;
@@ -354,9 +355,11 @@ function create(opts) {
         stage:          record.stage,
       },
     });
-    try { observability().count("dora.incident.reported", 1, {
-      classification: record.classification, stage: record.stage,
-    }); } catch (_e) { /* obs best-effort */ }
+    if (obsOn) {
+      observability().safeEvent("dora.incident.reported", 1, {
+        classification: record.classification, stage: record.stage,
+      });
+    }
     return record;
   }
 

package/lib/dsr.js

@@ -279,8 +279,8 @@ function create(opts) {
   validateOpts(opts, [
     "ticketStore", "posture", "identityResolver",
     "sources", "audit", "retentionFloorMs",
-    "deadlineMs", "observability",
-    "verificationLevel", "verifyContext",
+    "deadlineMs",
+    "verificationLevel",
     "receiptSigner", "minVerificationByType",
   ], "dsr.create");
 

package/lib/flag-evaluation-context.js

@@ -77,6 +77,13 @@ function fromRequest(req, opts) {
     if (typeof req.user.email === "string") ctx.email  = req.user.email;
     if (req.user.tenantId != null)          ctx.tenantId = req.user.tenantId;
   }
+  // Explicit tenantKey overrides the tenant id derived from req.user —
+  // the sibling of userKey for the tenant axis. Operators behind a
+  // gateway that resolves tenancy out-of-band (subdomain, mTLS SAN,
+  // signed header) pass it directly rather than depending on req.user.
+  if (typeof opts.tenantKey === "string" && opts.tenantKey.length > 0) {
+    ctx.tenantId = opts.tenantKey;
+  }
   var headers = req.headers || {};
   if (typeof headers["accept-language"] === "string") {
     ctx.locale = headers["accept-language"].split(",")[0].split(";")[0].trim();

package/lib/guard-html-wcag-aria.js

@@ -58,8 +58,10 @@ function audit(html, opts) {
     ? KNOWN_ROLES.concat(opts.allowedRoles)
     : KNOWN_ROLES;
 
-  var findings = [];
-  function _add(f) { findings.push(f); }
+  // Per-finding scopeUrl stamping — shared collector in tagwalk.
+  var collector = tagwalk.makeScopedFindings(opts.scopeUrl);
+  var findings = collector.findings;
+  var _add = collector.add;
 
   var declaredIds = Object.create(null);
   var idRe = /\bid\s*=\s*["']([^"']+)["']/gi;

package/lib/guard-html-wcag-forms.js

@@ -55,8 +55,10 @@ function audit(html, opts) {
     ? AUTOCOMPLETE_TOKENS.concat(opts.allowedAutocomplete)
     : AUTOCOMPLETE_TOKENS;
 
-  var findings = [];
-  function _add(f) { findings.push(f); }
+  // Per-finding scopeUrl stamping — shared collector in tagwalk.
+  var collector = tagwalk.makeScopedFindings(opts.scopeUrl);
+  var findings = collector.findings;
+  var _add = collector.add;
 
   // Pre-scan: is there a <legend> inside any <fieldset>?
   // We track fieldset → has-legend by forward-scanning each fieldset.

package/lib/guard-html-wcag-tables.js

@@ -29,8 +29,10 @@ function audit(html, opts) {
     throw new TypeError("tables.audit: html must be a string");
   }
 
-  var findings = [];
-  function _add(f) { findings.push(f); }
+  // Per-finding scopeUrl stamping — shared collector in tagwalk.
+  var collector = tagwalk.makeScopedFindings(opts.scopeUrl);
+  var findings = collector.findings;
+  var _add = collector.add;
 
   // Walk the tag stream, tracking nesting state for tables + their
   // children. We don't build a full DOM; we track the open-tag stack

package/lib/guard-html-wcag-tagwalk.js

@@ -36,9 +36,29 @@ function lineColAt(html, offset) {
   return { line: line, column: offset - lastNl };
 }
 
+// Shared findings collector for the sub-scanners' audit(html, opts)
+// entry points. scopeUrl annotates every finding with the page it came
+// from so a direct caller of a sub-scanner (aria/forms/tables) can
+// correlate a finding back to its source document; the parent
+// wcag.audit also records scopeUrl at report level, but stamping
+// per-finding keeps the value useful when a sub-scanner is invoked on
+// its own. Returns { findings, add } — push findings through add() so
+// the stamp applies uniformly.
+function makeScopedFindings(scopeUrlOpt) {
+  var scopeUrl = (typeof scopeUrlOpt === "string" && scopeUrlOpt.length > 0)
+    ? scopeUrlOpt : null;
+  var findings = [];
+  function add(f) {
+    if (scopeUrl !== null) f.scopeUrl = scopeUrl;
+    findings.push(f);
+  }
+  return { findings: findings, add: add };
+}
+
 module.exports = {
   TAG_RE:       TAG_RE,
   ATTR_RE:      ATTR_RE,
   parseAttrs:   parseAttrs,
   lineColAt:    lineColAt,
+  makeScopedFindings: makeScopedFindings,
 };

package/lib/guard-html-wcag.js

@@ -345,7 +345,7 @@ function _checkAnchors(html, scheduled, report) {
 function audit(html, opts) {
   opts = opts || {};
   validateOpts(opts, [
-    "level", "ignore", "checkAll", "scopeUrl",
+    "level", "ignore", "scopeUrl",
     "skipAria", "allowedRoles", "skipTables",
     "skipForms", "allowedAutocomplete",
   ], "guardHtml.wcag.audit");

package/lib/honeytoken.js

@@ -89,6 +89,17 @@ function create(opts) {
   opts = opts || {};
   validateOpts(opts, ["audit"], "honeytoken.create");
 
+  // Honor the operator-supplied audit sink when present (the documented
+  // `audit: b.audit` injection); fall back to the module's lazyRequire so
+  // a caller that omits the sink still emits to the default audit log.
+  var auditSink = (opts.audit && typeof opts.audit.safeEmit === "function")
+    ? opts.audit : null;
+  function _emit(record) {
+    var sink = auditSink || audit();
+    try { sink.safeEmit(record); }
+    catch (_e) { /* audit best-effort */ }
+  }
+
   var registry = new Map();   // value → { id, kind, metadata, issuedAt }
 
   function issue(spec) {
@@ -110,13 +121,11 @@ function create(opts) {
       issuedAt:  Date.now(),
     });
     registry.set(value, record);
-    try {
-      audit().safeEmit({
-        action: "honeytoken.issued",
-        outcome: "success",
-        metadata: { id: id, kind: kind },
-      });
-    } catch (_e) { /* audit best-effort */ }
+    _emit({
+      action: "honeytoken.issued",
+      outcome: "success",
+      metadata: { id: id, kind: kind },
+    });
     return { id: id, value: value };
   }
 
@@ -124,19 +133,17 @@ function create(opts) {
     if (typeof value !== "string" || value.length === 0) return null;
     var record = registry.get(value);
     if (!record) return null;
-    try {
-      audit().safeEmit({
-        action: "honeytoken.tripped",
-        outcome: "failure",
-        metadata: {
-          id:             record.id,
-          kind:           record.kind,
-          metadata:       record.metadata,
-          observedAt:     Date.now(),
-          observedActor:  observedActor || null,
-        },
-      });
-    } catch (_e) { /* audit best-effort */ }
+    _emit({
+      action: "honeytoken.tripped",
+      outcome: "failure",
+      metadata: {
+        id:             record.id,
+        kind:           record.kind,
+        metadata:       record.metadata,
+        observedAt:     Date.now(),
+        observedActor:  observedActor || null,
+      },
+    });
     return record;
   }