@blamejs/core 0.9.49 → 0.10.1

package/lib/agent-stream.js

@@ -138,6 +138,14 @@ function _makeIterator(ctx) {
   var done       = false;
   var closed     = false;
   var drained    = false;
+  // SUBSTRATE-14 — track the cursor of the LAST row actually yielded
+  // to the consumer. The prior shape called cursor.lastSeenCursor()
+  // at drain-marker emit, which returned the position of the last
+  // FETCHED batch — clients resuming from that cursor SKIPPED every
+  // row still in `buffer` that hadn't been yielded yet. Now we record
+  // the per-row cursor at yield time so the marker carries the
+  // correct resume point.
+  var lastYieldedCursor = null;
   _safeAudit(ctx.audit, "agent.stream.opened", ctx.actor, { kind: ctx.kind, streamId: streamId });
 
   async function _closeOnce(reason) {
@@ -159,6 +167,13 @@ function _makeIterator(ctx) {
       try {
         if (buffer.length > 0) {
           var row = buffer.shift();
+          // SUBSTRATE-14 — record the cursor for this yielded row so a
+          // drain that fires BETWEEN buffered yields emits a marker
+          // whose lastSeenCursor matches what the client actually
+          // received. The cursor extraction shape mirrors the
+          // operator's `cursor.lastSeenCursor()` contract: row carries
+          // `_cursor` OR the cursor object exposes a per-row helper.
+          lastYieldedCursor = _resumeCursorFor(row, lastYieldedCursor);
           return { value: row, done: false };
         }
         if (done) {
@@ -171,14 +186,18 @@ function _makeIterator(ctx) {
             drained = true;
             var marker = {
               _drainMarker:   true,
-              lastSeenCursor: cursor && typeof cursor.lastSeenCursor === "function"
-                                ? cursor.lastSeenCursor() : null,
+              lastSeenCursor: lastYieldedCursor,
               reason:         "drain",
             };
             _safeAudit(ctx.audit, "agent.stream.drain_marker_emitted", ctx.actor, {
               kind: ctx.kind, streamId: streamId,
+              bufferedRowsDropped: buffer.length,
+              lastSeenCursor: lastYieldedCursor,
             });
             done = true;
+            // Discard any buffered rows so the consumer doesn't see
+            // post-drain rows after the marker.
+            buffer.length = 0;
             return { value: marker, done: false };
           }
           await _closeOnce("drain");
@@ -204,6 +223,7 @@ function _makeIterator(ctx) {
         }
         // Push all but the first into the buffer; return the first.
         for (var i = 1; i < rows.length; i += 1) buffer.push(rows[i]);
+        lastYieldedCursor = _resumeCursorFor(rows[0], lastYieldedCursor);
         return { value: rows[0], done: false };
       } catch (e) {
         // Any error closes the cursor + emits an audit. Re-throw to
@@ -228,6 +248,18 @@ function _safeAudit(auditImpl, action, actor, metadata) {
   agentAudit.safeAudit(auditImpl, action, actor, metadata);
 }
 
+// SUBSTRATE-14 — resolve the resume cursor for a row about to be
+// yielded. Operators may attach the cursor per-row (`row._cursor` /
+// `row.cursor`) OR rely on the cursor's own per-row tracker
+// (`cursor.cursorForRow(row)`) — both shapes supported.
+function _resumeCursorFor(row, fallback) {
+  if (row && typeof row === "object") {
+    if (row._cursor != null) return row._cursor;
+    if (row.cursor  != null) return row.cursor;
+  }
+  return fallback;
+}
+
 module.exports = {
   create:            create,
   AgentStreamError:  AgentStreamError,

package/lib/agent-tenant.js

@@ -58,11 +58,22 @@ var agentAudit       = require("./agent-audit");
 
 var audit            = lazyRequire(function () { return require("./audit"); });
 var cryptoField      = lazyRequire(function () { return require("./crypto-field"); });
+var vault            = lazyRequire(function () { return require("./vault"); });
 
 var AgentTenantError = defineClass("AgentTenantError", { alwaysPermanent: true });
 
 var CROSS_TENANT_ADMIN_SCOPE = "framework-cross-tenant-admin";
 
+// Per-tenant key derivation domain separators. NIST SP 800-108 r1 §5.1
+// KDF-in-Counter shape — fixed "label" + tenantId-as-salt + purpose-as-
+// info. Operator passphrase rotation produces a fresh master, breaking
+// every prior tenant ciphertext (operator intent: rotation = re-seal).
+var TENANT_KDF_LABEL = "blamejs.agent.tenant/v1";
+// 32 bytes — XChaCha20-Poly1305 key length. Distinct from the audit
+// truncation buffer so future key-length bumps don't have to chase a
+// magic constant.
+var TENANT_KEY_BYTES = 32;                                                                              // allow:raw-byte-literal — XChaCha20-Poly1305 key length (256 bits)
+
 /**
  * @primitive b.agent.tenant.create
  * @signature b.agent.tenant.create(opts)
@@ -111,8 +122,8 @@ function create(opts) {
     sealField:   function (tenantId, table, field, plaintext) { return _sealField(tenantId, table, field, plaintext); },
     unsealField: function (tenantId, table, field, ciphertext) { return _unsealField(tenantId, table, field, ciphertext); },
     sealRowForTenant:   function (tenantId, table, row) { return _sealRowForTenant(tenantId, table, row); },
-    unsealRowForTenant: function (tenantId, table, row) { return _unsealRowForTenant(tenantId, table, row); },
-    listArchived: function ()                       { var out = []; ctx.archive.forEach(function (v) { out.push({ tenantId: v.tenantId, archivedAt: v.archivedAt, policy: v.policy }); }); return out; },
+    unsealRowForTenant: function (tenantId, table, row) { return _unsealRowForTenant(ctx, tenantId, table, row); },
+    listArchived: function ()                       { return _listArchived(ctx); },
     CROSS_TENANT_ADMIN_SCOPE: CROSS_TENANT_ADMIN_SCOPE,
     AgentTenantError: AgentTenantError,
     _ctx: ctx,
@@ -160,14 +171,40 @@ async function _unregister(ctx, tenantId, args) {
   }
   // Archive default — retain the key + metadata for retention-mandated
   // restoration. Operator's compliance regime drives archivePolicy.
+  // SUBSTRATE-19 — persist as a `status: "archived"` row in the same
+  // backend rather than only the process-local Map. GDPR Art. 17 +
+  // HIPAA §164.530(j) require the archived state to survive process
+  // restart (auditor pulls a deleted tenant's archival record years
+  // later); a Map-only archive evaporated on every redeploy.
+  var archivedRow = {
+    tenantId:    tenantId,
+    posture:     row.posture,
+    archivePolicy: row.archivePolicy || "default-archive",
+    metadata:    row.metadata,
+    registeredAt: row.registeredAt,
+    archivedAt:  Date.now(),
+    status:      "archived",
+  };
   ctx.archive.set(tenantId, {
-    tenantId: tenantId, archivedAt: Date.now(),
-    policy: row.archivePolicy || "default-archive",
-    row: row,
+    tenantId: tenantId, archivedAt: archivedRow.archivedAt,
+    policy: archivedRow.archivePolicy, row: row,
   });
+  // Two-phase: persist the archived row first, then delete the live
+  // row. If the persist fails, the live row stays and the operator
+  // can retry; the inverse (delete-then-persist) loses the row on
+  // a backend hiccup. Operators wiring a durable backend get
+  // restart-survival for free.
+  if (typeof ctx.backend.archive === "function") {
+    await ctx.backend.archive(tenantId, archivedRow);
+  } else {
+    // Backends without a dedicated archive() API store the archived
+    // row under a sentinel-prefixed key so list() can find it and
+    // lookup() (which checks status) refuses live-row access.
+    await ctx.backend.set("__archived__/" + tenantId, archivedRow);
+  }
   await ctx.backend.delete(tenantId);
   agentAudit.safeAudit(ctx.audit, "agent.tenant.archived", args.actor, {
-    tenantId: tenantId, policy: row.archivePolicy,
+    tenantId: tenantId, policy: archivedRow.archivePolicy,
   });
   return { tenantId: tenantId, mode: "archived" };
 }
@@ -187,7 +224,14 @@ async function _lookup(ctx, tenantId, args) {
 
 async function _list(ctx, args) {
   var rows = await ctx.backend.list();
-  return rows.map(function (r) {
+  return rows.filter(function (r) {
+    // Skip archived rows from the live list; listArchived surfaces
+    // them separately. Backends without an `archive()` API stored the
+    // archived row under "__archived__/<tenantId>" via the fallback;
+    // the row's status === "archived" sentinel is the canonical
+    // discriminator regardless of backend.
+    return r && r.status !== "archived";
+  }).map(function (r) {
     return {
       tenantId:      r.tenantId,
       posture:       r.posture,
@@ -197,6 +241,51 @@ async function _list(ctx, args) {
   });
 }
 
+async function _listArchived(ctx) {
+  // Prefer the operator's `listArchived()` when available — durable
+  // backends that need an index can implement it cheaper than walking
+  // every row. Fall back to scanning list() for `status: "archived"`
+  // rows (the in-memory + sentinel-prefix path).
+  var out = [];
+  if (typeof ctx.backend.listArchived === "function") {
+    var rows = await ctx.backend.listArchived();
+    if (Array.isArray(rows)) {
+      for (var i = 0; i < rows.length; i += 1) {
+        out.push({
+          tenantId:   rows[i].tenantId,
+          archivedAt: rows[i].archivedAt,
+          policy:     rows[i].archivePolicy || rows[i].policy || "default-archive",
+        });
+      }
+    }
+  } else {
+    var allRows = await ctx.backend.list();
+    if (Array.isArray(allRows)) {
+      for (var j = 0; j < allRows.length; j += 1) {
+        var r = allRows[j];
+        if (r && r.status === "archived") {
+          out.push({
+            tenantId:   r.tenantId,
+            archivedAt: r.archivedAt,
+            policy:     r.archivePolicy || "default-archive",
+          });
+        }
+      }
+    }
+  }
+  // Process-local cache (set on archive() in this process) for the
+  // common case of `archive→listArchived` within one boot before the
+  // backend list() index catches up.
+  ctx.archive.forEach(function (v) {
+    var found = false;
+    for (var k = 0; k < out.length; k += 1) {
+      if (out[k].tenantId === v.tenantId) { found = true; break; }
+    }
+    if (!found) out.push({ tenantId: v.tenantId, archivedAt: v.archivedAt, policy: v.policy });
+  });
+  return out;
+}
+
 // ---- Cross-tenant gate ----------------------------------------------------
 
 function _check(ctx, actor, agentTenantId) {
@@ -231,18 +320,78 @@ function _check(ctx, actor, agentTenantId) {
 }
 
 // ---- Per-tenant derived key -----------------------------------------------
+//
+// SUBSTRATE-5 — `namespaceHash(label, tenantId)` is a PUBLIC function
+// over PUBLIC inputs; an attacker who learns `tenantId` (an account id
+// surfaced in URLs / API responses) reconstructs every per-tenant key
+// without any secret material. The defense the docstring promises —
+// "cross-tenant decrypt refused at the vault boundary" — never bound
+// to anything secret.
+//
+// NIST SP 800-108 r1 §5.1 (KDF in Counter / Feedback Mode): a key
+// derivation function MUST consume a secret KDK (Key Derivation Key)
+// alongside the public label + context. GDPR Art. 32 (Security of
+// processing) requires "the pseudonymisation and encryption of
+// personal data" — keys derived purely from public per-record
+// identifiers are pseudonymisation-only, not encryption.
+//
+// New shape: SHAKE256(label || rootKey || tenantId || purpose), where
+// rootKey is SHA3-512(vault.getKeysJson()). Same derivation `b.vault.aad`
+// uses internally — the vault's master keypair PEM is the secret KDK.
+// Rotating the vault passphrase / keypair (b.vaultRotate.rotate)
+// changes rootKey, which changes every derived tenant key — operator
+// intent for rotation IS re-seal.
+//
+// `derivedKey` returns a hex-encoded 32-byte key (64 chars) to keep
+// the wire shape compatible with prior callers. Internal callers that
+// need the raw key use `_tenantFieldKey` directly.
 
-function _derivedKey(tenantId, purpose) {
+function _vaultRootBytes() {
+  // Vault.getKeysJson() throws when the vault hasn't been init'd. That
+  // is the right secure-by-default posture: tenant-derived keys cannot
+  // be produced before the operator has bootstrapped the vault. The
+  // error reaches the caller (sealField / register) so an operator
+  // mis-ordering boot (start agents before vault.init) sees a clear
+  // refusal rather than getting weakened-but-deterministic keys.
+  var keysJson;
+  try { keysJson = vault().getKeysJson(); }
+  catch (e) {
+    throw new AgentTenantError("agent-tenant/vault-not-initialized",
+      "derivedKey: vault must be initialized before per-tenant keys can be " +
+      "derived (vault.getKeysJson threw: " + (e && e.message ? e.message : String(e)) + ")");
+  }
+  return Buffer.from(bCrypto.sha3Hash(keysJson), "hex");
+}
+
+function _deriveTenantKeyBytes(tenantId, purpose) {
   guardTenantId.validate(tenantId);
   if (typeof purpose !== "string" || purpose.length === 0) {
     throw new AgentTenantError("agent-tenant/bad-purpose",
       "derivedKey: purpose required (e.g. 'seal' / 'audit' / 'session')");
   }
-  // Composes b.crypto.namespaceHash for deterministic per-tenant key
-  // derivation. Cross-tenant decrypt is refused at the vault boundary
-  // because each tenant's seal-key derivation differs — even with
-  // disk access an attacker can't cross-decrypt.
-  return bCrypto.namespaceHash("agent.tenant.derive." + purpose, tenantId);
+  // Domain-separated KDF input. NUL separators between fields prevent
+  // (label, tenantId="x\0y", purpose="z") colliding with
+  // (label, tenantId="x", purpose="y\0z") — same byte concatenation,
+  // different logical context.
+  var rootBytes = _vaultRootBytes();
+  var input = Buffer.concat([
+    Buffer.from(TENANT_KDF_LABEL, "utf8"),
+    Buffer.from([0x00]),
+    rootBytes,
+    Buffer.from([0x00]),
+    Buffer.from(tenantId, "utf8"),
+    Buffer.from([0x00]),
+    Buffer.from(purpose, "utf8"),
+  ]);
+  return bCrypto.kdf(input, TENANT_KEY_BYTES);
+}
+
+function _derivedKey(tenantId, purpose) {
+  // Public API — returns hex so the existing wire shape (operators
+  // storing the derived key string in their DB) is unchanged. Internal
+  // AEAD callers use `_deriveTenantKeyBytes` directly to skip the
+  // hex/Buffer round-trip.
+  return _deriveTenantKeyBytes(tenantId, purpose).toString("hex");
 }
 
 // ---- Per-tenant audit -----------------------------------------------------
@@ -323,11 +472,11 @@ function _auditFor(ctx, tenantId) {
 var TENANT_FIELD_PREFIX = "tnt-v1:";
 
 function _tenantFieldKey(tenantId, table) {
-  // 32-byte symmetric key for XChaCha20-Poly1305. namespaceHash returns
-  // a 128-char SHA3-512 hex string (64 bytes); take the first 32 bytes
-  // of the parsed Buffer as the AEAD key.
-  var hexHash = _derivedKey(tenantId, "cryptoField:" + table);
-  return Buffer.from(hexHash, "hex").subarray(0, 32);                                                // allow:raw-byte-literal — XChaCha20-Poly1305 key length (256 bits)
+  // 32-byte symmetric key for XChaCha20-Poly1305. _deriveTenantKeyBytes
+  // returns the raw key bound to the vault master + tenantId + purpose
+  // — see SUBSTRATE-5 commentary above _derivedKey for the threat
+  // model that drove this away from public-input-only derivation.
+  return _deriveTenantKeyBytes(tenantId, "cryptoField:" + table);
 }
 
 function _tenantFieldAad(tenantId, table, field) {
@@ -400,7 +549,7 @@ function _sealRowForTenant(tenantId, table, row) {
   return out;
 }
 
-function _unsealRowForTenant(tenantId, table, row) {
+function _unsealRowForTenant(ctx, tenantId, table, row) {
   if (!row) return row;
   guardTenantId.validate(tenantId);
   var cf = cryptoField();
@@ -415,10 +564,17 @@ function _unsealRowForTenant(tenantId, table, row) {
     var f = fields[i];
     if (out[f] !== undefined && out[f] !== null) {
       try { out[f] = _unsealField(tenantId, table, f, out[f]); }
-      catch (_e) {
-        // Cross-tenant decrypt OR wrong-prefix → null the field
-        // and let the audit chain surface the failure. Matches the
-        // safe-fail posture of b.cryptoField.unsealRow.
+      catch (e) {
+        // BUG-4 — null-on-decrypt-failure was silent; the docstring
+        // promised "audit chain surfaces the failure" but no emit ever
+        // ran. Cross-tenant ciphertext replay / tampered row / wrong-
+        // prefix all hit this path; operator audit pipelines need the
+        // signal to alert. CWE-778 (Insufficient Logging) — defense-
+        // in-depth that the field nulled silently.
+        agentAudit.safeAudit(ctx.audit, "agent.tenant.cross_tenant_decrypt_refused", null, {
+          tenantId: tenantId, table: table, field: f,
+          reason: (e && e.message) || String(e),
+        });
         out[f] = null;
       }
     }

package/lib/agent-trace.js

@@ -63,11 +63,25 @@
 var lazyRequire        = require("./lazy-require");
 var { defineClass }    = require("./framework-error");
 var guardTraceContext  = require("./guard-trace-context");
+var agentAudit         = require("./agent-audit");
 
 var audit              = lazyRequire(function () { return require("./audit"); });
 
 var AgentTraceError = defineClass("AgentTraceError", { alwaysPermanent: true });
 
+// SUBSTRATE-24 — once-per-process audit emit on the first tracer
+// failure each install fires. Operators get the signal even when
+// individual span calls are best-effort suppressed.
+var _failureAuditEmittedFor = Object.create(null);
+function _emitFirstFailureAudit(auditImpl, kind, message) {
+  if (_failureAuditEmittedFor[kind]) return;
+  _failureAuditEmittedFor[kind] = true;
+  agentAudit.safeAudit(auditImpl, "agent.trace.tracer_failure", null, {
+    kind: kind, message: message ? String(message).slice(0, 256) : "",                                  // allow:raw-byte-literal — audit-message char cap
+    rateLimited: "first-occurrence-only",
+  });
+}
+
 /**
  * @primitive b.agent.trace.create
  * @signature b.agent.trace.create(opts)
@@ -103,18 +117,22 @@ function create(opts) {
   var auditImpl = opts.audit || audit();
 
   return {
-    startSpan:           function (name, sopts)             { return _startSpan(opts.tracing, name, sopts || {}); },
+    startSpan:           function (name, sopts)             { return _startSpan(opts.tracing, name, sopts || {}, auditImpl); },
     injectIntoEnvelope:  function (envelope, span)          { return _injectIntoEnvelope(opts.tracing, envelope, span); },
     extractFromEnvelope: function (envelope)                { return _extractFromEnvelope(envelope); },
-    recordResult:        function (span, result, error)     { return _recordResult(span, result, error); },
-    shouldSample:        function (method)                  { return _shouldSample(sampleRate, perMethod, method); },
+    recordResult:        function (span, result, error)     { return _recordResult(span, result, error, auditImpl); },
+    // SUBSTRATE-17 — `shouldSample` now takes a traceId so the same
+    // trace gets the same decision across hops. Operator-supplied
+    // traceId comes from the W3C `traceparent` header at request-
+    // entry; absent that, falls back to Math.random (start of trace).
+    shouldSample:        function (method, traceId)         { return _shouldSample(sampleRate, perMethod, method, traceId); },
     formatAttributes:    function (info)                    { return _formatAttributes(info); },
     AgentTraceError:     AgentTraceError,
     _ctx: { sampleRate: sampleRate, perMethod: perMethod, audit: auditImpl },
   };
 }
 
-function _startSpan(tracing, name, sopts) {
+function _startSpan(tracing, name, sopts, auditImpl) {
   if (typeof name !== "string" || name.length === 0) {
     throw new AgentTraceError("agent-trace/bad-span-name",
       "startSpan: name required");
@@ -123,19 +141,36 @@ function _startSpan(tracing, name, sopts) {
   // on the registry stack so tracing.contextHeaders() / currentSpan()
   // see it, then exposes end() so the agent boundary controls
   // lifetime across publish → consume.
-  if (typeof tracing.manualSpan === "function") {
-    return tracing.manualSpan(name, sopts);
-  }
-  // Operator passed a non-b.tracing object (operator-supplied OTel
-  // tracer directly) — try its native startSpan. Refuse if neither.
-  if (typeof tracing.startSpan === "function") {
-    return tracing.startSpan(name, sopts);
+  try {
+    if (typeof tracing.manualSpan === "function") {
+      return tracing.manualSpan(name, sopts);
+    }
+    if (typeof tracing.startSpan === "function") {
+      return tracing.startSpan(name, sopts);
+    }
+  } catch (e) {
+    // SUBSTRATE-24 — tracer failures should not crash the agent's
+    // method call; surface the first failure to the audit chain
+    // (rate-limited) so operators get the signal.
+    _emitFirstFailureAudit(auditImpl, "startSpan", e && e.message);
+    return _noopSpan();
   }
   throw new AgentTraceError("agent-trace/bad-tracing",
     "startSpan: opts.tracing must expose manualSpan() (b.tracing.create()) " +
     "or startSpan() (raw OTel tracer); neither found");
 }
 
+function _noopSpan() {
+  // Returned when the tracer threw — caller can still call
+  // recordException / setStatus / end without further errors.
+  return {
+    end:             function () {},
+    setStatus:       function () {},
+    recordException: function () {},
+    isNoop:          true,
+  };
+}
+
 function _injectIntoEnvelope(tracing, envelope, span) {
   if (!envelope || typeof envelope !== "object") {
     throw new AgentTraceError("agent-trace/bad-envelope",
@@ -168,32 +203,59 @@ function _extractFromEnvelope(envelope) {
   };
 }
 
-function _recordResult(span, result, error) {
+function _recordResult(span, result, error, auditImpl) {
   if (!span || typeof span !== "object") return;
+  // SUBSTRATE-24 — surface first occurrence of each span-op failure
+  // via audit so the operator gets the signal. Subsequent failures
+  // stay silent (best-effort) per the operational spec.
   if (error) {
     if (typeof span.recordException === "function") {
-      try { span.recordException(error); } catch (_e) { /* best-effort */ }
+      try { span.recordException(error); }
+      catch (e) { _emitFirstFailureAudit(auditImpl, "recordException", e && e.message); }
     }
     if (typeof span.setStatus === "function") {
       try { span.setStatus({ code: 2, message: error.message || String(error) }); }
-      catch (_e) { /* best-effort */ }
+      catch (e) { _emitFirstFailureAudit(auditImpl, "setStatus", e && e.message); }
     }
   } else if (typeof span.setStatus === "function") {
-    try { span.setStatus({ code: 1 }); } catch (_e) { /* best-effort */ }
+    try { span.setStatus({ code: 1 }); }
+    catch (e) { _emitFirstFailureAudit(auditImpl, "setStatus", e && e.message); }
   }
   if (typeof span.end === "function") {
-    try { span.end(); } catch (_e) { /* best-effort */ }
+    try { span.end(); }
+    catch (e) { _emitFirstFailureAudit(auditImpl, "end", e && e.message); }
   }
 }
 
-function _shouldSample(globalRate, perMethod, method) {
+// SUBSTRATE-17 — deterministic sampling per W3C Trace Context §3.2.3.1.
+// `Math.random` makes child-vs-parent sampling decisions non-coherent:
+// a parent span sampled OUT can still have child spans sampled IN,
+// producing orphaned spans operators can't correlate. Hashing the
+// 16-byte trace-id deterministically routes every span in a trace to
+// the same decision. When traceId is absent (start of a trace at
+// request-entry boundary) we still use Math.random as the seeding
+// roll; downstream callers pass the resulting traceId so children
+// inherit the decision.
+function _shouldSample(globalRate, perMethod, method, traceId) {
+  var rate = globalRate;
   if (typeof method === "string" && Object.prototype.hasOwnProperty.call(perMethod, method)) {
     var r = perMethod[method];
-    if (typeof r === "number" && isFinite(r) && r >= 0 && r <= 1) {
-      return Math.random() < r;                                                                       // allow:math-random-noncrypto — sampling is statistical, not security-sensitive
-    }
+    if (typeof r === "number" && isFinite(r) && r >= 0 && r <= 1) rate = r;
+  }
+  if (rate <= 0) return false;
+  if (rate >= 1) return true;
+  if (typeof traceId === "string" && /^[0-9a-fA-F]{32}$/.test(traceId)) {
+    // Use the low 32 bits of the trace-id as the sampling roll
+    // (W3C-compatible). Hash modulo 1e9 → divide by 1e9 puts the
+    // result in [0,1) deterministically.
+    var lo = parseInt(traceId.slice(-8), 16);                                                          // allow:raw-byte-literal — low 32 bits of trace-id hex
+    var roll = (lo >>> 0) / 0x100000000;                                                                // allow:raw-byte-literal — 2^32 normalization divisor
+    return roll < rate;
   }
-  return Math.random() < globalRate;                                                                  // allow:math-random-noncrypto — sampling is statistical, not security-sensitive
+  // No trace-id supplied — start of a new trace. Operators wire
+  // shouldSample(method, ctx.traceId) on every downstream hop so
+  // children inherit the decision deterministically.
+  return Math.random() < rate;                                                                          // allow:math-random-noncrypto — start-of-trace seed only; downstream hops pass traceId for deterministic propagation
 }
 
 function _formatAttributes(info) {
@@ -215,4 +277,5 @@ module.exports = {
   guards: {
     context: guardTraceContext,
   },
+  _resetForTest:    function () { _failureAuditEmittedFor = Object.create(null); },
 };

package/lib/auth/aal.js

@@ -136,12 +136,19 @@ function meets(actualBand, requiredBand) {
 // access tokens with AAL info typically use `acr` / `amr` (RFC 9068
 // §3 / OpenID Connect Core §2). The framework leaves that wiring to
 // the operator — but the constants make the AMR strings consistent.
+// RFC 8176 §2 — registered AMR values. Pre-v0.9.x mapped WEBAUTHN to
+// `fido-u2f`; that's the OLD U2F protocol AMR. Modern WebAuthn
+// authenticators use the `hwk` ("proof-of-possession of a hardware-
+// secured key") AMR — the same one HARDWARE uses, since WebAuthn IS
+// a hardware-cryptographic-authenticator binding. PASSKEY remains a
+// distinct AMR for the synced multi-device case (operators using the
+// FIDO-published "passkey" AMR can disambiguate from one-device hwk).
 var AMR = Object.freeze({
   PASSWORD:  "pwd",
   PIN:       "pin",
   TOTP:      "otp",
   SMS:       "sms",
-  WEBAUTHN:  "fido-u2f",
+  WEBAUTHN:  "hwk",
   PASSKEY:   "passkey",
   HARDWARE:  "hwk",
   MTLS:      "mtls",

package/lib/auth/ciba.js

@@ -561,7 +561,12 @@ function create(opts) {
       throw new AuthError("auth-ciba/bad-notification-req",
         "ciba.parseNotification: req with headers required");
     }
-    var authzHeader = req.headers["authorization"] || req.headers["Authorization"];
+    // Node's http module lowercases all incoming header names per RFC
+    // 7230 §3.2; the capital-A fallback is structurally dead code and a
+    // future-integration footgun (a middleware that bypasses
+    // node:http's normalization could re-introduce the unreachable
+    // branch). Read lowercase only.
+    var authzHeader = req.headers["authorization"];
     if (!authzHeader || authzHeader.indexOf("Bearer ") !== 0) {
       throw new AuthError("auth-ciba/missing-bearer",
         "ciba.parseNotification: Authorization: Bearer header missing");

package/lib/auth/dpop.js

@@ -462,13 +462,18 @@ async function verify(proof, opts) {
     }
   }
 
-  // nonce — when caller supplies expected nonce, payload MUST match
+  // nonce — when caller supplies expected nonce, payload MUST match.
+  // Constant-time compare (audit 2026-05-15): the nonce is a server-
+  // issued secret-shaped value matched against attacker-controlled
+  // payload bytes. RFC 9449 §8 mandates the value be unpredictable;
+  // a leaking compare reveals prefix bytes over many attempts. ath
+  // already used timingSafeEqual; nonce now matches.
   if (typeof opts.nonce === "string" && opts.nonce.length > 0) {
     if (typeof payload.nonce !== "string" || payload.nonce.length === 0) {
       throw new AuthError("auth-dpop/missing-nonce",
         "nonce expected but proof has no nonce claim");
     }
-    if (payload.nonce !== opts.nonce) {
+    if (!bCrypto.timingSafeEqual(payload.nonce, opts.nonce)) {
       throw new AuthError("auth-dpop/nonce-mismatch",
         "payload.nonce does not match expected");
     }

package/lib/auth/fal.js

@@ -121,12 +121,13 @@ function meets(actualBand, requiredBand) {
  * nonce / jti binding before back-channel can claim FAL2.
  *
  * @opts
- *   channel:           "front" | "back",        // REQUIRED
- *   encrypted:         boolean,                  // assertion encrypted to RP
- *   replayProtected:   boolean,                  // nonce / jti / iat binding present
- *   hokBinding:        "mtls" | "dpop" | "saml-hok" | null,
- *                                                // proof-of-possession binding present
- *   bearerOnly:        boolean,                  // alias for hokBinding === null
+ *   channel:                  "front" | "back",   // REQUIRED
+ *   encrypted:                boolean,             // assertion encrypted to RP
+ *   replayProtected:          boolean,             // nonce / jti / iat binding present
+ *   backChannelAuthenticated: boolean,             // back-channel transport-auth'd (mTLS / signed) — required for FAL2 over plain back-channel
+ *   hokBinding:               "mtls" | "dpop" | "saml-hok" | null,
+ *                                                  // proof-of-possession binding present
+ *   bearerOnly:               boolean,             // alias for hokBinding === null
  *
  * @example
  *   var fal = b.auth.fal.fromAssertion({
@@ -166,9 +167,17 @@ function fromAssertion(opts) {
     return FAL3;
   }
 
-  // FAL2 — back-channel OR encrypted front-channel, with replay protection.
+  // AUTH-19 — FAL2 per NIST SP 800-63C-4 §5.2 requires "injection
+  // protection" on the back-channel: either the back-channel itself is
+  // encrypted-and-authenticated (mTLS / signed transport) OR the
+  // assertion is encrypted to the RP. A plain HTTP back-channel with
+  // only nonce/jti replay protection is FAL1 — `replayProtected` alone
+  // doesn't satisfy the §5.2 MUST. Operators using a plain
+  // back-channel set `backChannelAuthenticated: true` when their
+  // transport carries server-to-server mTLS / signed-JWT auth.
   var replaySafe = opts.replayProtected === true;
-  if (replaySafe && (opts.channel === "back" || opts.encrypted === true)) {
+  var injectionProtected = opts.encrypted === true || opts.backChannelAuthenticated === true;
+  if (replaySafe && injectionProtected && (opts.channel === "back" || opts.encrypted === true)) {
     return FAL2;
   }