@blamejs/core 0.15.12 → 0.15.14

package/lib/session-device-binding.js

@@ -97,13 +97,8 @@ function _requireFunction(name, val) {
 }
 
 function _requireBindingStore(s) {
-  if (!s || typeof s !== "object" ||
-      typeof s.get !== "function" ||
-      typeof s.set !== "function" ||
-      typeof s.del !== "function") {
-    throw new SessionDeviceBindingError("session-device-binding/bad-opt",
-      "bindingStore must be a b.cache-shaped object (get/set/del)");
-  }
+  validateOpts.requireMethods(s, ["get", "set", "del"],
+    "bindingStore (b.cache-shaped)", SessionDeviceBindingError, "session-device-binding/bad-opt");
 }
 
 function _requireToken(token) {
@@ -164,6 +159,105 @@ function _ipPrefix(ip, bits) {
   return "v4:" + maskedOctets.join(".") + "/" + v4Bits;
 }
 
+// Resolve operator-supplied fingerprintExtras(req) to a stable string. A
+// throwing or non-serializable extractor drops to "" — extras only sharpen the
+// digest, they must never crash fingerprinting.
+function _resolveExtrasFn(fn, req) {
+  if (!fn) return "";
+  var v;
+  try { v = fn(req); } catch (_e) { return ""; }
+  if (v === null || v === undefined) return "";
+  if (typeof v === "string") return v;
+  try { return JSON.stringify(v); } catch (_e) { return ""; }
+}
+
+// Clamp an { v4, v6 } prefix-bits opt to valid IPv4/IPv6 ranges, defaulting
+// each independently.
+function _resolveIpBits(ipBits) {
+  ipBits = ipBits || {};
+  return {
+    v4: (typeof ipBits.v4 === "number" && isFinite(ipBits.v4) && ipBits.v4 >= 0 && ipBits.v4 <= 32)    // IPv4 max prefix length in bits
+      ? ipBits.v4 : DEFAULT_IP_V4_PREFIX,
+    v6: (typeof ipBits.v6 === "number" && isFinite(ipBits.v6) && ipBits.v6 >= 0 && ipBits.v6 <= 128)   // IPv6 max prefix length in bits
+      ? ipBits.v6 : DEFAULT_IP_V6_PREFIX,
+  };
+}
+
+// Pure request-shape device fingerprint — the side-effect-free core shared by
+// the instance lookup and the static fingerprint() entry point. cfg: { v4Bits,
+// v6Bits, extras (string), boundKey (Buffer|null) }. No store, no audit, no
+// session — just headers + masked client IP (+ optional bound key) -> SHAKE256.
+function _computeDeviceFingerprint(req, cfg) {
+  _requireReq(req);
+  var headers = req.headers || {};
+  var ua = typeof headers["user-agent"] === "string" ? headers["user-agent"] : "";
+  var al = _normalizeAcceptLanguage(headers["accept-language"]);
+  var ae = _normalizeAcceptEncoding(headers["accept-encoding"]);
+  var ip = "";
+  try { ip = requestHelpers.clientIp(req); } catch (_e) { ip = ""; }
+  var family = ip.indexOf(":") !== -1 ? "v6" : "v4";
+  var ipPart = _ipPrefix(ip, family === "v6" ? cfg.v6Bits : cfg.v4Bits);
+  var keyPart = "";
+  if (Buffer.isBuffer(cfg.boundKey)) {
+    keyPart = "k:" + nodeCrypto.createHash("sha3-256").update(cfg.boundKey).digest("hex");
+  }
+  var canonical = [
+    "ua=" + ua,
+    "al=" + al,
+    "ae=" + ae,
+    "ip=" + ipPart,
+    "ex=" + (cfg.extras || ""),
+    keyPart,
+  ].join("\n");
+  var hash = nodeCrypto.createHash("shake256", { outputLength: FINGERPRINT_BYTES })
+    .update(canonical)
+    .digest();
+  return { fingerprint: hash, components: {
+    ua: ua, al: al, ae: ae, ip: ipPart, hasBoundKey: !!keyPart,
+  } };
+}
+
+/**
+ * @primitive  b.sessionDeviceBinding.fingerprint
+ * @signature  b.sessionDeviceBinding.fingerprint(req, opts?)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.session.rotate, b.session.create
+ *
+ * Compute the stateless SHAKE256 device-shape digest for a request with no
+ * store, no session, and no side effects — the soft device-binding building
+ * block for self-validating tokens (a sealed cookie, a JWT) that carry the
+ * fingerprint inside the token and compare it themselves. `create()` requires a
+ * bindingStore for the persisted bind()/verify() lifecycle; this static form
+ * skips that gate because it touches no store. Returns a 32-byte Buffer derived
+ * from User-Agent + normalized Accept-Language / Accept-Encoding + the masked
+ * client-IP prefix (+ optional operator extras). Throws only on a missing or
+ * malformed request object.
+ *
+ * @opts
+ *   ipPrefixBits:      { v4: number, v6: number },          // default { v4: 24, v6: 48 } — mask width that survives a roaming IP
+ *   fingerprintExtras: function,                            // (req) => string|object, optional extra signal folded into the digest
+ *
+ * @example
+ *   var fp = b.sessionDeviceBinding.fingerprint(req);
+ *   // seal fp inside the cookie/JWT; on the next request recompute + constant-time compare
+ */
+function fingerprint(req, opts) {
+  opts = opts || {};
+  if (opts.fingerprintExtras !== undefined && opts.fingerprintExtras !== null &&
+      typeof opts.fingerprintExtras !== "function") {
+    throw new SessionDeviceBindingError("session-device-binding/bad-opt",
+      "fingerprint: fingerprintExtras must be a function (req) => string|object");
+  }
+  var bits = _resolveIpBits(opts.ipPrefixBits);
+  return _computeDeviceFingerprint(req, {
+    v4Bits: bits.v4,
+    v6Bits: bits.v6,
+    extras: _resolveExtrasFn(opts.fingerprintExtras, req),
+    boundKey: null,
+  }).fingerprint;
+}
+
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, ALLOWED_OPTS, "sessionDeviceBinding.create");
@@ -215,29 +309,9 @@ function create(opts) {
   var boundKeyResolver = opts.boundKeyResolver || null;
   var fingerprintExtras = opts.fingerprintExtras || null;
 
-  function _emitObs(name, labels) {
-    var sink = obsInst || _safeGlobalObs();
-    if (!sink) return;
-    try { sink.event(name, 1, labels); } catch (_e) { /* drop-silent */ }
-  }
-
-  function _safeGlobalObs() {
-    try { return observability(); } catch (_e) { return null; }
-  }
+  var _emitObs = observability().makeCounterEmitter(obsInst);
 
-  function _emitAudit(action, tokenHash, outcome, metadata, req) {
-    if (!auditInst) return;
-    try {
-      var event = {
-        action:   action,
-        outcome:  outcome,
-        resource: { kind: "session.device", id: tokenHash },
-        metadata: metadata || {},
-      };
-      if (req) event.actor = requestHelpers.extractActorContext(req);
-      auditInst.safeEmit(event);
-    } catch (_e) { /* drop-silent */ }
-  }
+  var _emitAudit = requestHelpers.makeResourceAuditEmitter(auditInst, "session.device");
 
   function _hashTokenForAudit(token) {
     // Don't put the raw session id in the audit log. SHAKE256 to a
@@ -259,51 +333,22 @@ function create(opts) {
   }
 
   function _resolveExtras(req) {
-    if (!fingerprintExtras) return "";
-    var v;
-    try { v = fingerprintExtras(req); }
-    catch (_e) { return ""; }
-    if (v === null || v === undefined) return "";
-    if (typeof v === "string") return v;
-    try { return JSON.stringify(v); } catch (_e) { return ""; }
+    return _resolveExtrasFn(fingerprintExtras, req);
   }
 
   function _computeFingerprint(req) {
     _requireReq(req);
-    var headers = req.headers || {};
-    var ua = typeof headers["user-agent"] === "string" ? headers["user-agent"] : "";
-    var al = _normalizeAcceptLanguage(headers["accept-language"]);
-    var ae = _normalizeAcceptEncoding(headers["accept-encoding"]);
-    var ip = "";
-    try { ip = requestHelpers.clientIp(req); } catch (_e) { ip = ""; }
-    var family = ip.indexOf(":") !== -1 ? "v6" : "v4";
-    var ipPart = _ipPrefix(ip, family === "v6" ? v6Bits : v4Bits);
-    var extras = _resolveExtras(req);
-
     var boundKeyMaybe = _resolveBoundKey(req);
     if (requireBoundKey && (boundKeyMaybe === null || boundKeyMaybe === undefined)) {
       return { ok: false, reason: "missing-bound-key" };
     }
-    var keyPart = "";
-    if (Buffer.isBuffer(boundKeyMaybe)) {
-      keyPart = "k:" + nodeCrypto.createHash("sha3-256").update(boundKeyMaybe).digest("hex");
-    }
-
-    var canonical = [
-      "ua=" + ua,
-      "al=" + al,
-      "ae=" + ae,
-      "ip=" + ipPart,
-      "ex=" + extras,
-      keyPart,
-    ].join("\n");
-
-    var hash = nodeCrypto.createHash("shake256", { outputLength: FINGERPRINT_BYTES })
-      .update(canonical)
-      .digest();
-    return { ok: true, fingerprint: hash, components: {
-      ua: ua, al: al, ae: ae, ip: ipPart, hasBoundKey: !!keyPart,
-    } };
+    var r = _computeDeviceFingerprint(req, {
+      v4Bits:   v4Bits,
+      v6Bits:   v6Bits,
+      extras:   _resolveExtras(req),
+      boundKey: Buffer.isBuffer(boundKeyMaybe) ? boundKeyMaybe : null,
+    });
+    return { ok: true, fingerprint: r.fingerprint, components: r.components };
   }
 
   async function bind(token, req) {
@@ -421,6 +466,7 @@ function create(opts) {
 
 module.exports = {
   create:                  create,
+  fingerprint:             fingerprint,
   SessionDeviceBindingError: SessionDeviceBindingError,
   DEFAULTS:                Object.freeze({
     ttlMs:        DEFAULT_TTL_MS,

package/lib/session.js

@@ -48,6 +48,7 @@
  */
 var audit = require("./audit");
 var canonicalJson = require("./canonical-json");
+var validateOpts = require("./validate-opts");
 var cluster = require("./cluster");
 var clusterStorage = require("./cluster-storage");
 var C = require("./constants");
@@ -149,6 +150,38 @@ function _sessionSqlTable() { return frameworkSchema.tableName(SESSION_TABLE); }
 // dispatch; this controls only the builder-side quoting + idiom selection.
 function _sessionSqlOpts() { return { dialect: clusterStorage.dialect() }; }
 
+// Per-subject valid-from boundary table. A monotonic epoch (ms) the issuer
+// bumps to invalidate every STATELESS self-validating token (sealed cookie
+// with no DB row, JWT) minted before the bump: log-out-everywhere, a
+// right-to-erasure cutoff, a forced re-auth after a credential change. Token
+// readers compare the token's iat against this boundary via check(). Same
+// dual-storage shape as _blamejs_sessions — registered in both db.js's
+// FRAMEWORK_SCHEMA (single-node SQLite) and framework-schema.js (cluster
+// external-db); clusterStorage.execute routes by cluster mode. The subject id
+// is hashed before it becomes the PRIMARY KEY, so the plaintext id never lands
+// in the table (the same sidHash / userIdHash discipline the sessions table
+// follows).
+var VALID_FROM_TABLE = "_blamejs_session_valid_from";   // allow:hand-rolled-sql — canonical logical table-name + reserved schema name
+var VALID_FROM_SUBJECT_NAMESPACE = "bj-session-valid-from-subject:";
+function _validFromSqlTable() { return frameworkSchema.tableName(VALID_FROM_TABLE); }
+function _hashSubjectId(subjectId) { return sha3Hash(VALID_FROM_SUBJECT_NAMESPACE + subjectId); }
+
+// Dialect-aware conflict-row references for the monotonic-max upsert in
+// bump(). Mirrors rate-limit.js's pattern: the proposed row is EXCLUDED
+// (Postgres/SQLite) / VALUES() (MySQL); the existing row is a self-reference.
+function _validFromConflictRefs(dialect, table) {
+  if (dialect === "mysql") {
+    return {
+      proposed: function (col) { return "VALUES(`" + col + "`)"; },
+      existing: function (col) { return "`" + table + "`.`" + col + "`"; },
+    };
+  }
+  return {
+    proposed: function (col) { return "EXCLUDED.\"" + col + "\""; },
+    existing: function (col) { return "\"" + table + "\".\"" + col + "\""; },
+  };
+}
+
 // Column order used for INSERT — kept as a constant so the placeholders
 // list and the values list stay in sync. Must match the session table's
 // schema in db.js (single-node) and framework-schema.js (cluster mode).
@@ -810,8 +843,16 @@ async function destroyAllForUser(userId) {
   // userId is sealed; look up via derived userIdHash.
   var lookup = cryptoField.lookupHash(SESSION_TABLE, "userId", userId);
   if (!lookup) {
+    // The session table's userIdHash derived-hash schema is registered during
+    // b.db.init(). A pluggable-store consumer (b.session.useStore) who never
+    // called b.db.init() lands here first — surface that, not just an opaque
+    // "framework misconfigured", since destroyAllForUser still needs b.db for
+    // the userIdHash index + the stateless valid-from boundary.
     throw _err("MISCONFIGURED",
-      "the session table schema is missing the userIdHash derived hash — framework misconfigured",
+      "session.destroyAllForUser: the session table's userIdHash derived-hash schema is " +
+      "not registered. It is registered during b.db.init() — call b.db.init() at boot even " +
+      "when session data lives in a pluggable store (b.session.useStore). If b.db is already " +
+      "initialized, the session table schema is misconfigured.",
       true);
   }
   // Dual-read across the keyed-MAC flip: a pre-v0.15.0 session row carries
@@ -825,6 +866,26 @@ async function destroyAllForUser(userId) {
     .whereIn("userIdHash", userHashes)
     .toSql();
   var result = await _currentStore().execute(built.sql, built.params);
+  // Also raise the stateless valid-from boundary so a "logout everywhere"
+  // revokes the operator's stateless tokens (sealed cookies / JWTs checked via
+  // b.session.check) too, not only the store-backed rows just deleted. This
+  // bump writes to the FRAMEWORK db (clusterStorage); a pluggable-store consumer
+  // (b.session.useStore) who never ran b.db.init() would otherwise surface the
+  // opaque "db/not-initialized" here, after the store delete already succeeded.
+  // Rethrow it as a session-specific, actionable error.
+  try {
+    await bump(userId);
+  } catch (e) {
+    if (e && e.code === "db/not-initialized") {
+      throw _err("MISCONFIGURED",
+        "session.destroyAllForUser raises the stateless valid-from boundary (so a " +
+        "logout-everywhere also revokes sealed-cookie / JWT sessions), which requires " +
+        "b.db.init() — call it at boot even when session data lives in a pluggable " +
+        "store (b.session.useStore). The store-backed rows were already deleted; rerun " +
+        "after b.db.init() to also raise the stateless boundary.", true);
+    }
+    throw e;
+  }
   return result.rowCount || 0;
 }
 
@@ -1272,12 +1333,8 @@ function useStore(store) {
     _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);
-  }
+  validateOpts.requireMethods(store, ["execute", "executeOne"],
+    "session.useStore: store", SessionError, "INVALID_ARG", true);
   _store = store;
 }
 
@@ -1304,6 +1361,158 @@ function isAnonymous(userId) {
   return _isAnonymousUserId(userId);
 }
 
+/**
+ * @primitive b.session.bump
+ * @signature b.session.bump(subjectId, opts?)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.session.check, b.session.validFrom, b.session.destroyAllForUser
+ *
+ * Revoke every STATELESS self-validating token (sealed cookie carrying no DB
+ * row, JWT) for a subject by raising a durable per-subject valid-from boundary
+ * to now. Any token whose issued-at (`iat`) predates the boundary fails
+ * `b.session.check`. Unlike `destroyAllForUser` — which deletes server-side
+ * session rows — this revokes tokens the framework never stored a row for:
+ * log-out-everywhere, a right-to-erasure cutoff, a forced re-auth after a
+ * password / key change. `destroyAllForUser` calls this for you, so a single
+ * "logout everywhere" covers both store-backed and stateless tokens.
+ *
+ * The boundary is MONOTONIC: it only ever moves forward. A bump to an
+ * `epochMs` at or below the stored value is a no-op — a replayed or
+ * clock-skewed lower value can never widen a revoked window back open. Returns
+ * the boundary in effect after the call. Leader-only. The subject id is stored
+ * hashed; the plaintext id never lands in the table.
+ *
+ * @opts
+ *   epochMs:  number,   // boundary to set; default Date.now(). Tokens with iat < this are revoked.
+ *
+ * @example
+ *   // Force re-auth everywhere for a subject after a password change:
+ *   var boundary = await b.session.bump("user-42");
+ *   // Cut off at a specific instant (right-to-erasure effective time):
+ *   await b.session.bump("user-42", { epochMs: erasureEffectiveMs });
+ */
+async function bump(subjectId, opts) {
+  cluster.requireLeader();
+  if (typeof subjectId !== "string" || subjectId.length === 0) {
+    throw _err("INVALID_ARG", "session.bump requires a non-empty subjectId", true);
+  }
+  opts = opts || {};
+  var epochMs = opts.epochMs === undefined ? Date.now() : opts.epochMs;
+  if (typeof epochMs !== "number" || !isFinite(epochMs) || epochMs < 0) {
+    throw _err("INVALID_ARG",
+      "session.bump: epochMs must be a non-negative finite number, got " + JSON.stringify(epochMs), true);
+  }
+  var subjectHash = _hashSubjectId(subjectId);
+  var t = _validFromSqlTable();
+  var dialect = clusterStorage.dialect();
+  var refs = _validFromConflictRefs(dialect, t);
+
+  // Monotonic-max conflict action: keep the LATER of the proposed and the
+  // stored boundary, so a lower (replayed / clock-skewed) epoch can never move
+  // the boundary backwards and re-open a revoked window.
+  var validFromExpr = "CASE WHEN " + refs.proposed("validFromEpoch") + " > " +
+    refs.existing("validFromEpoch") + " THEN " + refs.proposed("validFromEpoch") +
+    " ELSE " + refs.existing("validFromEpoch") + " END";
+  var built = sql.upsert(t, _sessionSqlOpts())
+    .columns(["subjectHash", "validFromEpoch", "updatedAt"])
+    .values({ subjectHash: subjectHash, validFromEpoch: epochMs, updatedAt: Date.now() })
+    .onConflict(["subjectHash"])
+    .doUpdate({ validFromEpoch: validFromExpr, updatedAt: "?" }, [Date.now()])
+    .returning(["validFromEpoch"])
+    .toSql();
+  // The valid-from boundary is a FRAMEWORK table (FRAMEWORK_SCHEMA / cluster
+  // DDL), NOT session data — it must execute against clusterStorage (the
+  // framework db), never _currentStore(): a pluggable session-data store
+  // (b.session.useStore / localDbThin) does not provision this table, so
+  // routing the bump through it throws "no such table".
+  var row;
+  if (built.readbackSql) {
+    // MySQL: ON DUPLICATE KEY UPDATE has no RETURNING — run the upsert, then
+    // the readback SELECT b.sql emits (keyed on subjectHash).
+    await clusterStorage.execute(built.sql, built.params);
+    var readback = await clusterStorage.execute(built.readbackSql.sql, built.readbackSql.params);
+    row = readback.rows && readback.rows[0];
+  } else {
+    var result = await clusterStorage.execute(built.sql, built.params);
+    row = result.rows && result.rows[0];
+  }
+  var effective = row ? Number(row.validFromEpoch) : epochMs;
+
+  // Best-effort audit — matches the file's emit convention (safeEmit is
+  // already drop-silent internally).
+  try {
+    audit.safeEmit({
+      action:   "auth.session.valid_from_bump",
+      outcome:  "success",
+      metadata: { validFromEpoch: effective },
+    });
+  } catch (_ignored) { /* audit best-effort */ }
+
+  return effective;
+}
+
+/**
+ * @primitive b.session.validFrom
+ * @signature b.session.validFrom(subjectId)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.session.bump, b.session.check
+ *
+ * Read the current valid-from boundary (epoch ms) for a subject. Returns `0`
+ * when the subject has never been bumped — no token is revoked by boundary, so
+ * any non-negative token `iat` passes `b.session.check`. Runs anywhere (leader
+ * or follower) — it only reads. The subject id is hashed before lookup; the
+ * plaintext id never lands in the table.
+ *
+ * @example
+ *   var boundary = await b.session.validFrom("user-42");
+ *   // → 1735689600000  (last bump)   or   0  (never bumped)
+ */
+async function validFrom(subjectId) {
+  if (typeof subjectId !== "string" || subjectId.length === 0) return 0;
+  var built = sql.select(_validFromSqlTable(), _sessionSqlOpts())
+    .columns(["validFromEpoch"])
+    .where("subjectHash", _hashSubjectId(subjectId))
+    .toSql();
+  // Framework valid-from table — read from clusterStorage (the framework db),
+  // not _currentStore(), so a pluggable session-data store cannot divert it (it
+  // does not provision this table). See bump() for the full rationale.
+  var row = await clusterStorage.executeOne(built.sql, built.params);
+  return row ? Number(row.validFromEpoch) : 0;
+}
+
+/**
+ * @primitive b.session.check
+ * @signature b.session.check(subjectId, tokenIatMs)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.session.bump, b.session.validFrom
+ *
+ * Decide whether a stateless self-validating token is still valid against the
+ * subject's valid-from boundary. Returns `true` when the token's issued-at
+ * (`tokenIatMs`, epoch ms) is at or after the boundary; `false` when the token
+ * was issued before the last `bump` (revoked). A subject that was never bumped
+ * has boundary `0`, so any non-negative `iat` is valid. Runs anywhere.
+ *
+ * Fails CLOSED: a non-finite / negative / non-number `tokenIatMs` returns
+ * `false` (treat an unparseable token as revoked rather than admit it). Call
+ * this AFTER the token's own signature + expiry checks pass — it is the
+ * server-side revocation layer those stateless checks otherwise lack.
+ *
+ * @example
+ *   // jwt already signature- and exp-verified; iat is in seconds → ms:
+ *   var ok = await b.session.check(claims.sub, claims.iat * 1000);
+ *   if (!ok) { res.statusCode = 401; res.end("session revoked"); return; }
+ */
+async function check(subjectId, tokenIatMs) {
+  if (typeof tokenIatMs !== "number" || !isFinite(tokenIatMs) || tokenIatMs < 0) {
+    return false;
+  }
+  var boundary = await validFrom(subjectId);
+  return tokenIatMs >= boundary;
+}
+
 module.exports = {
   create:               create,
   verify:               verify,
@@ -1315,6 +1524,9 @@ module.exports = {
   updateData:           updateData,
   purgeExpired:         purgeExpired,
   count:                count,
+  bump:                 bump,
+  validFrom:            validFrom,
+  check:                check,
   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