@blamejs/core 0.8.59 → 0.8.64

package/lib/session.js

@@ -53,10 +53,29 @@ var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
 var { generateToken, sha3Hash } = require("./crypto");
 var cryptoField = require("./crypto-field");
+var lazyRequire = require("./lazy-require");
 var requestHelpers = require("./request-helpers");
 var safeJson = require("./safe-json");
 var { SessionError } = require("./framework-error");
 
+// vault is initialized at boot before sessions; lazyRequire keeps the
+// load order independent of module-import order. Used to seal/unseal
+// the cookie-side sid so the wire token is ciphertext rather than
+// plaintext (sealed-cookie default since v0.8.61).
+var vault = lazyRequire(function () { return require("./vault"); });
+
+// Pluggable session-storage backend. Default uses cluster-storage (which
+// in turn dispatches to the framework's main DB or external DB). An
+// operator can switch to an isolated backend (e.g. an in-memory or
+// tmpfs SQLite via `b.session.stores.localDbThin`) so heavy session
+// churn doesn't fight the main DB's WAL fsync + at-rest re-encryption
+// cycle. Set once at boot via `b.session.useStore(store)`; the store
+// must expose `execute(sql, params)` and `executeOne(sql, params)`
+// returning the same `{ rowCount, rows? }` / row-or-null shape the
+// cluster-storage path returns.
+var _store = null;
+function _currentStore() { return _store || clusterStorage; }
+
 var _err = SessionError.factory;
 
 var DEFAULT_TTL_MS = C.TIME.days(7);
@@ -109,6 +128,41 @@ function _hashSid(sid) {
   return sha3Hash(SID_NAMESPACE + sid);
 }
 
+// Sealed-cookie format. `b.vault.seal` produces a `vault:`-prefixed
+// envelope (ML-KEM-1024 + P-384 hybrid + XChaCha20-Poly1305). Pre-
+// v0.8.61 the framework returned the plaintext sid to the caller; the
+// sealed default since v0.8.61 keeps the wire token as ciphertext. The
+// DB still keys on `sha3('bj-session:' || sid)` — sealing is a
+// wire-format upgrade, not a storage change.
+//
+// Pre-v1.0 the framework ships no backwards-compat path: raw-format
+// cookies from before v0.8.61 fail to unseal here and the affected
+// caller force-logs-out (re-auths and gets a sealed cookie). The
+// upgrade is operator-visible and documented in the release notes.
+var SEALED_COOKIE_PREFIX = "vault:";
+
+function _sealCookieToken(sid) {
+  // vault.seal is idempotent on already-sealed input. Defensive null
+  // pass-through matches vault's contract — feed it the raw sid only.
+  return vault().seal(sid);
+}
+
+function _unsealCookieToken(token) {
+  if (typeof token !== "string" || token.length === 0) return null;
+  if (token.indexOf(SEALED_COOKIE_PREFIX) !== 0) {
+    // Pre-v0.8.61 raw-sid format — refused under the sealed-cookie
+    // default. Returning null surfaces as "session not found" at the
+    // verify call site so the caller force-logs-out cleanly.
+    return null;
+  }
+  try { return vault().unseal(token); }
+  catch (_e) {
+    // Tampered cookie / wrong keypair / vault rotation skew — treat as
+    // not-found. The caller already handles `null` (re-auth flow).
+    return null;
+  }
+}
+
 // Build a sealed row object with all SESSION_COLS keys present (null
 // where not set). The cryptoField.sealRow call seals userId/data and
 // produces userIdHash from userId.
@@ -138,6 +192,120 @@ function _sealForInsert(row) {
 // itself, extended to the fingerprint.
 var DEFAULT_FINGERPRINT_FIELDS = ["clientIp", "userAgent", "acceptLanguage"];
 
+// Subnet binding: roaming carriers (T-Mobile / Verizon / etc.) flip the
+// public client IP every few requests as the device hops cells, so a
+// strict full-IP fingerprint logs out healthy mobile users. The
+// "clientIpPrefix" field hashes a /24 mask for IPv4 (256-address bucket
+// — same Class C-shaped neighborhood) and a /64 mask for IPv6 (the IPv6
+// "site" prefix the RIRs allocate to every ISP customer). Drift across
+// /24 OR /64 is meaningfully suspicious; drift within is not.
+//
+// Per the IPv6 addressing architecture (RFC 4291 §2.5.4) every customer
+// LAN is assigned at least a /64; tightening below /64 punishes IPv6
+// privacy-extension address rotation. /24 IPv4 is the original
+// IP-geolocation bucket size and matches the legacy carrier-NAT pool
+// stride. Operators with stricter needs pass a function-form
+// fingerprint field for custom mask widths.
+//
+// Protocol constants — named so the bit-arithmetic stays readable.
+var IP_BITS_PER_BYTE      = 8;                                                                  // allow:raw-byte-literal — bits per byte; protocol constant, not a byte size
+var IPV4_OCTET_COUNT      = 4;
+var IPV4_OCTET_RANGE      = 256;                                                                // allow:raw-byte-literal — 0..255 inclusive; v4 octet domain
+var IPV4_TOTAL_BITS       = 32;                                                                 // allow:raw-byte-literal — IPv4 address width in bits
+var IPV4_DEFAULT_PREFIX   = 24;                                                                 // allow:raw-byte-literal — /24 carrier-NAT pool stride
+var IPV6_GROUP_COUNT      = 8;                                                                  // allow:raw-byte-literal — 8 16-bit groups in v6
+var IPV6_BYTE_COUNT       = 16;                                                                 // allow:raw-byte-literal — 16 bytes in v6
+var IPV6_DEFAULT_PREFIX   = 64;                                                                 // allow:raw-byte-literal — /64 customer LAN per RFC 4291 §2.5.4
+var BYTE_MASK             = 0xff;
+var HEX_RADIX             = 16;                                                                 // allow:raw-byte-literal — base-16 radix
+var V4_MAPPED_V6_PREFIX   = "::ffff:";
+
+function _maskIpv4(ip, prefix) {
+  // ip = "a.b.c.d"; prefix is bits to keep (1..32).
+  var parts = String(ip).split(".");
+  if (parts.length !== IPV4_OCTET_COUNT) return null;
+  var n = 0;
+  for (var i = 0; i < IPV4_OCTET_COUNT; i++) {
+    var oct = parseInt(parts[i], 10);
+    if (!Number.isInteger(oct) || oct < 0 || oct >= IPV4_OCTET_RANGE) return null;
+    n = (n * IPV4_OCTET_RANGE) + oct;
+  }
+  // Apply prefix mask.
+  var mask = prefix === 0 ? 0 : (-1 >>> (IPV4_TOTAL_BITS - prefix)) << (IPV4_TOTAL_BITS - prefix);
+  // Bitwise on 32-bit unsigned. JS coerces to 32-bit signed, so use
+  // unsigned right shift to recover.
+  var masked = (n & mask) >>> 0;
+  return ((masked >>> IP_BITS_PER_BYTE * 3) & BYTE_MASK) + "." +
+         ((masked >>> IP_BITS_PER_BYTE * 2) & BYTE_MASK) + "." +
+         ((masked >>> IP_BITS_PER_BYTE)     & BYTE_MASK) + "." +
+         (masked & BYTE_MASK) + "/" + prefix;
+}
+
+function _maskIpv6(ip, prefix) {
+  // Expand to 8 16-bit groups. Accept :: shorthand. Reject if invalid.
+  var raw = String(ip).toLowerCase();
+  // Strip an embedded zone id (fe80::1%eth0); not part of the address.
+  var pct = raw.indexOf("%");
+  if (pct !== -1) raw = raw.substring(0, pct);
+  var doubleColonAt = raw.indexOf("::");
+  var groups;
+  if (doubleColonAt === -1) {
+    groups = raw.split(":");
+    if (groups.length !== IPV6_GROUP_COUNT) return null;
+  } else {
+    var left = raw.substring(0, doubleColonAt).split(":");
+    var right = raw.substring(doubleColonAt + 2).split(":");
+    if (left.length === 1 && left[0] === "") left = [];
+    if (right.length === 1 && right[0] === "") right = [];
+    var fillCount = IPV6_GROUP_COUNT - left.length - right.length;
+    if (fillCount < 0) return null;
+    var middle = [];
+    for (var fi = 0; fi < fillCount; fi++) middle.push("0");
+    groups = left.concat(middle).concat(right);
+  }
+  // Each group is 1–4 hex chars.
+  var bytes = [];
+  for (var gi = 0; gi < IPV6_GROUP_COUNT; gi++) {
+    var g = groups[gi];
+    if (typeof g !== "string" || g.length === 0 || g.length > 4 || /[^0-9a-f]/.test(g)) return null;
+    var v = parseInt(g, HEX_RADIX);
+    if (!Number.isInteger(v) || v < 0 || v > 0xffff) return null;
+    bytes.push((v >> IP_BITS_PER_BYTE) & BYTE_MASK);
+    bytes.push(v & BYTE_MASK);
+  }
+  // Apply prefix in bits.
+  var keepBytes = Math.floor(prefix / IP_BITS_PER_BYTE);
+  var keepBits  = prefix % IP_BITS_PER_BYTE;
+  for (var bi = 0; bi < IPV6_BYTE_COUNT; bi++) {
+    if (bi < keepBytes) continue;
+    if (bi === keepBytes && keepBits > 0) {
+      var m = (BYTE_MASK << (IP_BITS_PER_BYTE - keepBits)) & BYTE_MASK;
+      bytes[bi] = bytes[bi] & m;
+    } else {
+      bytes[bi] = 0;
+    }
+  }
+  // Re-emit as colon-hex (no compression — deterministic for hashing).
+  var out = [];
+  for (var oi = 0; oi < IPV6_BYTE_COUNT; oi += 2) {
+    out.push(((bytes[oi] << IP_BITS_PER_BYTE) | bytes[oi + 1]).toString(HEX_RADIX));
+  }
+  return out.join(":") + "/" + prefix;
+}
+
+function _ipPrefix(ip) {
+  if (typeof ip !== "string" || ip.length === 0) return "";
+  // IPv4-mapped IPv6 (::ffff:1.2.3.4) — strip the wrapper so the v4
+  // mask applies. Same bucket regardless of how the proxy reported it.
+  var lower = ip.toLowerCase();
+  if (lower.indexOf(V4_MAPPED_V6_PREFIX) === 0 && lower.indexOf(".") !== -1) {
+    return _maskIpv4(lower.substring(V4_MAPPED_V6_PREFIX.length), IPV4_DEFAULT_PREFIX) || "";
+  }
+  if (ip.indexOf(":") !== -1) return _maskIpv6(ip, IPV6_DEFAULT_PREFIX) || "";
+  if (ip.indexOf(".") !== -1) return _maskIpv4(ip, IPV4_DEFAULT_PREFIX) || "";
+  return "";
+}
+
 function _buildFingerprintInputs(req, fields) {
   if (!req) return null;
   var headers = req.headers || {};
@@ -146,6 +314,9 @@ function _buildFingerprintInputs(req, fields) {
     var f = fields[i];
     if (f === "clientIp") {
       inputs.clientIp = requestHelpers.clientIp(req) || "";
+    } else if (f === "clientIpPrefix") {
+      // /24 v4 + /64 v6 — see _ipPrefix() commentary.
+      inputs.clientIpPrefix = _ipPrefix(requestHelpers.clientIp(req) || "");
     } else if (f === "userAgent") {
       inputs.userAgent = String(headers["user-agent"] || "");
     } else if (f === "acceptLanguage") {
@@ -206,10 +377,33 @@ function _hashFingerprint(sid, inputs) {
  *   res.setHeader("Set-Cookie", "sid=" + s.token + "; HttpOnly; Secure; SameSite=Strict");
  *   // → { token: "9f2c…", expiresAt: 1735689600000 }
  */
+// Anonymous-session prefix. b.session.create({ anonymous: true })
+// auto-mints userId = ANON_PREFIX + crypto.randomUUID() so operators
+// running pre-login flows (cart, partial-funnel telemetry, public
+// landing-page personalization) keep the framework's full sealed-
+// cookie + sealed-userId + sidHash + idle/absolute timeout posture
+// without rolling their own opaque-id pattern. destroyAllForUser
+// refuses anon ids: they're per-session and aren't portable.
+var ANON_PREFIX = "anon:";
+function _isAnonymousUserId(id) {
+  return typeof id === "string" && id.indexOf(ANON_PREFIX) === 0;
+}
+
 async function create(opts) {
   cluster.requireLeader();
-  if (!opts || !opts.userId) {
-    throw _err("INVALID_ARG", "session.create requires { userId }", true);
+  opts = opts || {};
+  if (opts.anonymous === true) {
+    if (opts.userId !== undefined && opts.userId !== null) {
+      throw _err("INVALID_ARG",
+        "session.create: pass either anonymous: true OR userId, not both", true);
+    }
+    // crypto.randomUUID is the framework's existing entropy source
+    // for opaque ids; anon sessions inherit the same 122-bit space.
+    var nodeCryptoForUuid = require("node:crypto");                                                // allow:inline-require — only the anon path needs randomUUID
+    opts = Object.assign({}, opts, { userId: ANON_PREFIX + nodeCryptoForUuid.randomUUID() });
+  }
+  if (!opts.userId) {
+    throw _err("INVALID_ARG", "session.create requires { userId } (or { anonymous: true })", true);
   }
   var ttl = opts.ttlMs !== undefined ? opts.ttlMs : DEFAULT_TTL_MS;
   _validateTtl(ttl, "session.create");
@@ -242,12 +436,12 @@ async function create(opts) {
   var values = SESSION_COLS.map(function (c) { return sealed[c]; });
   var placeholders = SESSION_COLS.map(function () { return "?"; }).join(", ");
   var quoted = SESSION_COLS.map(function (c) { return '"' + c + '"'; }).join(", ");
-  await clusterStorage.execute(
+  await _currentStore().execute(
     "INSERT INTO _blamejs_sessions (" + quoted + ") VALUES (" + placeholders + ")",
     values
   );
 
-  return { token: sid, expiresAt: expiresAt };
+  return { token: _sealCookieToken(sid), expiresAt: expiresAt };
 }
 
 /**
@@ -295,9 +489,14 @@ async function create(opts) {
 async function verify(token, verifyOpts) {
   if (typeof token !== "string" || token.length === 0) return null;
   verifyOpts = verifyOpts || {};
-  var sidHash = _hashSid(token);
+  // Sealed-cookie default — unseal the wire token to recover the sid.
+  // Pre-v0.8.61 raw cookies / tampered envelopes return null and the
+  // caller re-auths. The plaintext sid never leaves this function.
+  var sid = _unsealCookieToken(token);
+  if (sid === null) return null;
+  var sidHash = _hashSid(sid);
 
-  var row = await clusterStorage.executeOne(
+  var row = await _currentStore().executeOne(
     "SELECT sidHash, userId, userIdHash, data, createdAt, expiresAt, lastActivity " +
     "FROM _blamejs_sessions WHERE sidHash = ?",
     [sidHash]
@@ -399,7 +598,7 @@ async function verify(token, verifyOpts) {
     var fpFields = Array.isArray(verifyOpts.fingerprintFields) && verifyOpts.fingerprintFields.length > 0
       ? verifyOpts.fingerprintFields : DEFAULT_FINGERPRINT_FIELDS;
     var currentInputs = _buildFingerprintInputs(verifyOpts.req, fpFields);
-    var currentHash = _hashFingerprint(token, currentInputs);
+    var currentHash = _hashFingerprint(sid, currentInputs);
     if (currentHash !== storedFingerprint) {
       fingerprintDrift = true;
       // Operator-supplied scorer: receives { storedHash, currentInputs,
@@ -474,11 +673,13 @@ async function verify(token, verifyOpts) {
 async function destroy(token) {
   cluster.requireLeader();
   if (typeof token !== "string" || token.length === 0) return false;
-  return await _deleteBySidHash(_hashSid(token));
+  var sid = _unsealCookieToken(token);
+  if (sid === null) return false;
+  return await _deleteBySidHash(_hashSid(sid));
 }
 
 async function _deleteBySidHash(sidHash) {
-  var result = await clusterStorage.execute(
+  var result = await _currentStore().execute(
     "DELETE FROM _blamejs_sessions WHERE sidHash = ?",
     [sidHash]
   );
@@ -506,6 +707,16 @@ async function _deleteBySidHash(sidHash) {
 async function destroyAllForUser(userId) {
   cluster.requireLeader();
   if (!userId) throw _err("INVALID_ARG", "session.destroyAllForUser requires a userId", true);
+  if (_isAnonymousUserId(userId)) {
+    // Anon ids are minted per-session and aren't reused — destroying
+    // "all" anon sessions for one anon id is the same as destroying
+    // that single session. Refuse loudly so the operator doesn't
+    // think they're sweeping across an anon population.
+    throw _err("INVALID_ARG",
+      "session.destroyAllForUser: anonymous-prefix ids (\"anon:...\") are per-session — " +
+      "use destroy(token) for that session, OR purgeExpired() for housekeeping",
+      true);
+  }
   // userId is sealed; look up via derived userIdHash.
   var lookup = cryptoField.lookupHash("_blamejs_sessions", "userId", userId);
   if (!lookup) {
@@ -513,7 +724,7 @@ async function destroyAllForUser(userId) {
       "_blamejs_sessions schema is missing the userIdHash derived hash — framework misconfigured",
       true);
   }
-  var result = await clusterStorage.execute(
+  var result = await _currentStore().execute(
     "DELETE FROM _blamejs_sessions WHERE userIdHash = ?",
     [lookup.value]
   );
@@ -551,7 +762,9 @@ async function touch(token, opts) {
   cluster.requireLeader();
   opts = opts || {};
   if (typeof token !== "string" || token.length === 0) return false;
-  var sidHash = _hashSid(token);
+  var sid = _unsealCookieToken(token);
+  if (sid === null) return false;
+  var sidHash = _hashSid(sid);
   var nowMs = Date.now();
   // Two SQL paths so the SET list stays static (no dynamic column
   // assembly) and matches the call shape clusterStorage expects.
@@ -563,14 +776,14 @@ async function touch(token, opts) {
   if (opts.extendBy !== undefined && opts.extendBy !== null) {
     _validateTtl(opts.extendBy, "session.touch");
     var newExpires = nowMs + opts.extendBy;
-    var result = await clusterStorage.execute(
+    var result = await _currentStore().execute(
       "UPDATE _blamejs_sessions SET lastActivity = ?, expiresAt = ? " +
       "WHERE sidHash = ? AND expiresAt >= ?",
       [nowMs, newExpires, sidHash, nowMs]
     );
     return (result.rowCount || 0) > 0;
   }
-  var result2 = await clusterStorage.execute(
+  var result2 = await _currentStore().execute(
     "UPDATE _blamejs_sessions SET lastActivity = ? " +
     "WHERE sidHash = ? AND expiresAt >= ?",
     [nowMs, sidHash, nowMs]
@@ -618,10 +831,12 @@ async function rotate(oldToken, opts) {
   cluster.requireLeader();
   if (typeof oldToken !== "string" || oldToken.length === 0) return null;
   opts = opts || {};
+  var oldSid = _unsealCookieToken(oldToken);
+  if (oldSid === null) return null;
 
   var newSid       = generateToken(SID_BYTES);
   var newSidHash   = _hashSid(newSid);
-  var oldSidHash   = _hashSid(oldToken);
+  var oldSidHash   = _hashSid(oldSid);
   var nowMs        = Date.now();
   var newExpires = null;
   if (opts.ttlMs !== undefined) {
@@ -646,11 +861,11 @@ async function rotate(oldToken, opts) {
   var sql = "UPDATE _blamejs_sessions SET " + setParts.join(", ") +
             " WHERE sidHash = ? AND expiresAt >= ?";
   var params = setParams.concat([oldSidHash, nowMs]);
-  var result = await clusterStorage.execute(sql, params);
+  var result = await _currentStore().execute(sql, params);
   if ((result.rowCount || 0) === 0) return null;
 
   // Read the row's effective expiresAt to return — single source of truth.
-  var row = await clusterStorage.executeOne(
+  var row = await _currentStore().executeOne(
     'SELECT "expiresAt" FROM _blamejs_sessions WHERE sidHash = ?',
     [newSidHash]
   );
@@ -667,7 +882,7 @@ async function rotate(oldToken, opts) {
     });
   } catch (_e) { /* audit emit best-effort — never block rotate() */ }
 
-  return { token: newSid, expiresAt: expiresAt };
+  return { token: _sealCookieToken(newSid), expiresAt: expiresAt };
 }
 
 /**
@@ -696,7 +911,7 @@ async function rotate(oldToken, opts) {
  */
 async function purgeExpired() {
   cluster.requireLeader();
-  var result = await clusterStorage.execute(
+  var result = await _currentStore().execute(
     "DELETE FROM _blamejs_sessions WHERE expiresAt < ?",
     [Date.now()]
   );
@@ -722,14 +937,82 @@ async function purgeExpired() {
  *   // → 482
  */
 async function count() {
-  var row = await clusterStorage.executeOne(
+  var row = await _currentStore().executeOne(
     "SELECT COUNT(*) AS c FROM _blamejs_sessions WHERE expiresAt >= ?",
     [Date.now()]
   );
   return row ? Number(row.c) : 0;
 }
 
-function _resetForTest() { /* no module state to reset; clusterStorage and cryptoField own theirs */ }
+function _resetForTest() { _store = null; }
+
+/**
+ * @primitive b.session.useStore
+ * @signature b.session.useStore(store)
+ * @since     0.8.61
+ * @status    stable
+ * @related   b.session.stores.localDbThin
+ *
+ * Replace the default `_blamejs_sessions` storage backend (the
+ * framework's main DB / external DB via cluster-storage) with an
+ * operator-supplied store. The store must expose
+ * `execute(sql, params)` and `executeOne(sql, params)` returning the
+ * same `{ rows, rowCount }` / `row | null` shape `b.clusterStorage`
+ * returns. Pass `null` to revert to the default.
+ *
+ * Typical use is to point session writes at an isolated SQLite file
+ * (often tmpfs) so session churn doesn't fight the main DB's encrypted-
+ * at-rest re-flush cycle. The first-party adapter is
+ * `b.session.stores.localDbThin({ file })`.
+ *
+ * Call this once at boot, BEFORE the first `session.create` /
+ * `session.verify`. Switching stores on a running app strands every
+ * existing session in the old store.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   await b.vault.init({ dataDir: "/var/lib/blamejs", mode: "plaintext" });
+ *   await b.db.init({ dataDir: "/var/lib/blamejs" });
+ *   var sessionStore = b.session.stores.localDbThin({ file: "/dev/shm/sessions.db" });
+ *   b.session.useStore(sessionStore);
+ *   // Every b.session.* call now routes through the tmpfs file.
+ */
+function useStore(store) {
+  if (store === null || store === undefined) {
+    _store = null;
+    return;
+  }
+  if (typeof store !== "object" ||
+      typeof store.execute    !== "function" ||
+      typeof store.executeOne !== "function") {
+    throw _err("INVALID_ARG",
+      "session.useStore: store must expose execute(sql,params) and executeOne(sql,params)", true);
+  }
+  _store = store;
+}
+
+/**
+ * @primitive b.session.isAnonymous
+ * @signature b.session.isAnonymous(userId)
+ * @since     0.8.62
+ * @status    stable
+ * @related   b.session.create
+ *
+ * Returns `true` if the supplied userId was minted by
+ * `b.session.create({ anonymous: true })` (i.e., starts with the
+ * `anon:` prefix). Operators use this to gate post-auth behavior
+ * (e.g., refuse a payment confirmation when the session is still
+ * anonymous, or render the "log in to continue" banner).
+ *
+ * @example
+ *   var info = await b.session.verify(req.cookies.sid);
+ *   if (info && b.session.isAnonymous(info.userId)) {
+ *     res.statusCode = 401; res.end("login required"); return;
+ *   }
+ */
+function isAnonymous(userId) {
+  return _isAnonymousUserId(userId);
+}
 
 module.exports = {
   create:               create,
@@ -740,6 +1023,10 @@ module.exports = {
   rotate:               rotate,
   purgeExpired:         purgeExpired,
   count:                count,
+  useStore:             useStore,
+  isAnonymous:          isAnonymous,
+  stores:               require("./session-stores"),                                              // allow:inline-require — session-stores depends on local-db-thin which requires audit lazily; eager require is fine here
   DEFAULT_TTL_MS:       DEFAULT_TTL_MS,
+  ANON_PREFIX:          ANON_PREFIX,
   _resetForTest:        _resetForTest,
 };

package/lib/validate-opts.js

@@ -308,6 +308,46 @@ function makeAuditEmitter(audit) {
   };
 }
 
+// makeNamespacedEmitters — collapses the per-primitive
+//   function _emitAudit(action, outcome, metadata) { audit.safeEmit({...}) }
+//   function _emitMetric(verb)                    { observability.safeEvent(...) }
+// boilerplate into one helper. Every primitive that emits both audit
+// events AND observability metrics under a fixed prefix shares the
+// same shape; pre-v0.8.62 this was inlined in 13+ lib/auth files.
+//
+//   var emit = validateOpts.makeNamespacedEmitters("auth.ciba", { audit, observability });
+//   emit.audit("token_received", "success", { hash: ... });
+//   emit.metric("token-received");
+//
+// The audit/observability arguments are lazyRequire-resolved at the
+// call site so the helper itself adds no module-load coupling.
+function makeNamespacedEmitters(prefix, deps) {
+  if (typeof prefix !== "string" || prefix.length === 0) {
+    throw new Error("makeNamespacedEmitters: prefix must be a non-empty string");
+  }
+  deps = deps || {};
+  function audit(action, outcome, metadata) {
+    var auditMod = deps.audit;
+    if (typeof auditMod === "function") auditMod = auditMod();
+    if (!auditMod || typeof auditMod.safeEmit !== "function") return;
+    try {
+      auditMod.safeEmit({
+        action:   prefix + "." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+  function metric(verb, value, attrs) {
+    var obsMod = deps.observability;
+    if (typeof obsMod === "function") obsMod = obsMod();
+    if (!obsMod || typeof obsMod.safeEvent !== "function") return;
+    try { obsMod.safeEvent(prefix + "." + verb, value || 1, attrs || {}); }
+    catch (_e) { /* observability best-effort */ }
+  }
+  return { audit: audit, metric: metric };
+}
+
 // observabilityShape — operator-supplied `opts.observability` must
 // expose an `event` function. Parallel to auditShape; the n=1 catalog
 // tracks both inline-shape regexes.
@@ -338,3 +378,4 @@ module.exports.observabilityShape = observabilityShape;
 module.exports.requireObject = requireObject;
 module.exports.applyDefaults = applyDefaults;
 module.exports.makeAuditEmitter = makeAuditEmitter;
+module.exports.makeNamespacedEmitters = makeNamespacedEmitters;