@blamejs/core 0.15.14 → 0.15.16

package/lib/session.js

@@ -182,6 +182,49 @@ function _validFromConflictRefs(dialect, table) {
   };
 }
 
+// CREATE TABLE IF NOT EXISTS for the valid-from boundary, matching the
+// framework schema in db.js (single-node) / framework-schema.js (cluster mode):
+// subjectHash PRIMARY KEY, validFromEpoch + updatedAt NOT NULL. The pluggable
+// store is always a dedicated node:sqlite file (b.session.stores.localDbThin —
+// see session-stores.js), so the dialect is the literal "sqlite". Used to
+// provision the table on demand in a store-backed-only deployment (a
+// b.session.useStore consumer that never ran b.db.init(), so the framework db
+// — the default home of this table — is not initialized).
+function _validFromSchemaSql() {
+  return sql.createTable(_validFromSqlTable(), [
+    { name: "subjectHash",    type: "text", primaryKey: true },
+    { name: "validFromEpoch", type: "int",  notNull: true },
+    { name: "updatedAt",      type: "int",  notNull: true },
+  ], { dialect: "sqlite" }).sql;
+}
+
+// Run a valid-from boundary operation (bump write / validFrom read / check
+// read) against the correct backend. The boundary lives in the FRAMEWORK db
+// (clusterStorage) — it is a stateless-token revocation primitive shared across
+// every issuer, not per-session data — so that is always the first choice and a
+// present db is never silently bypassed. ONLY when the framework db is not
+// initialized (single-node, b.db.init() never awaited) AND an operator store is
+// configured (b.session.useStore) does the boundary fall back to that store, so
+// a store-backed-only deployment's logout-everywhere still raises (and honors)
+// the stateless boundary instead of 500ing on db/not-initialized (#340). With
+// neither a framework db nor a store, db/not-initialized is a real
+// misconfiguration and propagates unchanged (fail closed — the boundary is
+// never silently dropped). The store provisions the table on demand because a
+// session-data store (localDbThin) does not ship the valid-from DDL.
+async function _runValidFrom(runner) {
+  try {
+    return await runner(clusterStorage);
+  } catch (e) {
+    if (e && e.code === "db/not-initialized" && _store) {
+      // Framework db absent, operator store present: route through the store,
+      // provisioning the boundary table first (idempotent CREATE IF NOT EXISTS).
+      await _store.execute(_validFromSchemaSql(), []);
+      return await runner(_store);
+    }
+    throw e;
+  }
+}
+
 // 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).
@@ -256,130 +299,48 @@ function _sealForInsert(row) {
 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;                                                                  // bits per byte; protocol constant, not a byte size
-var IPV4_OCTET_COUNT      = 4;
-var IPV4_OCTET_RANGE      = 256;                                                                // 0..255 inclusive; v4 octet domain
-var IPV4_TOTAL_BITS       = 32;                                                                 // IPv4 address width in bits
-var IPV4_DEFAULT_PREFIX   = 24;                                                                 // /24 carrier-NAT pool stride
-var IPV6_GROUP_COUNT      = 8;                                                                  // 8 16-bit groups in v6
-var IPV6_BYTE_COUNT       = 16;                                                                 // 16 bytes in v6
-var IPV6_DEFAULT_PREFIX   = 64;                                                                 // /64 customer LAN per RFC 4291 §2.5.4
-var BYTE_MASK             = 0xff;
-var HEX_RADIX             = 16;                                                                 // 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) || "";
+// 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 the /24 (IPv4) + /64 (IPv6) subnet bucket instead — drift
+// across the bucket is meaningfully suspicious, drift within is not. The
+// masking lives in requestHelpers.ipPrefix (the IP-utilities home, next to
+// clientIp / trustedClientIp); operators with stricter needs pass a
+// function-form fingerprint field and reuse requestHelpers.ipPrefix for a
+// custom mask width.
+
+// Resolve the per-call client-IP function for the clientIp / clientIpPrefix
+// fingerprint fields. With { trustedProxies } (an array/string of CIDRs) or a
+// custom { clientIpResolver }, the IP is peer-gated through
+// requestHelpers.trustedClientIp so a deployment behind a trusted proxy binds
+// the session to the real client and not the proxy address (which silently
+// defeats the IP component of the fingerprint). With neither, it falls back to
+// the bare-socket peer — the historical default, preserved so existing
+// fingerprints don't change and log users out. The SAME option must be passed
+// to create / verify / rotate (exactly like fingerprintFields) or the
+// fingerprint won't match across the session lifecycle. An invalid CIDR throws
+// at the call (config-time entry-point validation).
+function _clientIpResolver(opts) {
+  if (opts && (opts.trustedProxies != null || typeof opts.clientIpResolver === "function")) {
+    return requestHelpers.trustedClientIp({
+      trustedProxies:   opts.trustedProxies,
+      clientIpResolver: opts.clientIpResolver,
+    }).resolve;
   }
-  if (ip.indexOf(":") !== -1) return _maskIpv6(ip, IPV6_DEFAULT_PREFIX) || "";
-  if (ip.indexOf(".") !== -1) return _maskIpv4(ip, IPV4_DEFAULT_PREFIX) || "";
-  return "";
+  return requestHelpers.clientIp;
 }
 
-function _buildFingerprintInputs(req, fields) {
+function _buildFingerprintInputs(req, fields, resolveIp) {
   if (!req) return null;
+  resolveIp = resolveIp || requestHelpers.clientIp;
   var headers = req.headers || {};
   var inputs = {};
   for (var i = 0; i < fields.length; i++) {
     var f = fields[i];
     if (f === "clientIp") {
-      inputs.clientIp = requestHelpers.clientIp(req) || "";
+      inputs.clientIp = resolveIp(req) || "";
     } else if (f === "clientIpPrefix") {
-      // /24 v4 + /64 v6 — see _ipPrefix() commentary.
-      inputs.clientIpPrefix = _ipPrefix(requestHelpers.clientIp(req) || "");
+      // /24 v4 + /64 v6 — see requestHelpers.ipPrefix commentary.
+      inputs.clientIpPrefix = requestHelpers.ipPrefix(resolveIp(req) || "");
     } else if (f === "userAgent") {
       inputs.userAgent = String(headers["user-agent"] || "");
     } else if (f === "acceptLanguage") {
@@ -482,7 +443,7 @@ async function create(opts) {
   var dataObj = opts.data ? Object.assign({}, opts.data) : null;
   var fpFields = Array.isArray(opts.fingerprintFields) && opts.fingerprintFields.length > 0
     ? opts.fingerprintFields : DEFAULT_FINGERPRINT_FIELDS;
-  var fpInputs = _buildFingerprintInputs(opts.req, fpFields);
+  var fpInputs = _buildFingerprintInputs(opts.req, fpFields, _clientIpResolver(opts));
   if (fpInputs) {
     if (!dataObj) dataObj = {};
     dataObj.__bj_fingerprint = _hashFingerprint(sid, fpInputs);
@@ -660,7 +621,7 @@ async function verify(token, verifyOpts) {
   if (storedFingerprint && verifyOpts.req) {
     var fpFields = Array.isArray(verifyOpts.fingerprintFields) && verifyOpts.fingerprintFields.length > 0
       ? verifyOpts.fingerprintFields : DEFAULT_FINGERPRINT_FIELDS;
-    var currentInputs = _buildFingerprintInputs(verifyOpts.req, fpFields);
+    var currentInputs = _buildFingerprintInputs(verifyOpts.req, fpFields, _clientIpResolver(verifyOpts));
     var currentHash = _hashFingerprint(sid, currentInputs);
     if (currentHash !== storedFingerprint) {
       fingerprintDrift = true;
@@ -868,21 +829,23 @@ async function destroyAllForUser(userId) {
   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.
+  // b.session.check) too, not only the store-backed rows just deleted. bump()
+  // writes to the framework db when one is initialized, otherwise to the
+  // configured store (b.session.useStore) — so a store-backed-only consumer who
+  // never ran b.db.init() still raises the boundary here instead of 500ing on
+  // db/not-initialized (#340). The only state in which bump still surfaces
+  // db/not-initialized is the default store (no useStore) with an uninitialized
+  // framework db — but the store DELETE above (also via clusterStorage) would
+  // have already thrown, so this rewrap is defensive belt-and-suspenders.
   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);
+        "logout-everywhere also revokes sealed-cookie / JWT sessions). No storage is " +
+        "available: call b.db.init() at boot, OR configure a session store via " +
+        "b.session.useStore. The store-backed rows were already deleted.", true);
     }
     throw e;
   }
@@ -1058,7 +1021,7 @@ async function rotate(oldToken, opts) {
           "so the device binding can be re-keyed to the new session id", true);
       }
       if (!newDataObj) newDataObj = {};
-      newDataObj.__bj_fingerprint = _hashFingerprint(newSid, _buildFingerprintInputs(opts.req, fpFields));
+      newDataObj.__bj_fingerprint = _hashFingerprint(newSid, _buildFingerprintInputs(opts.req, fpFields, _clientIpResolver(opts)));
     }
 
     var dataJson = newDataObj ? JSON.stringify(newDataObj) : null;
@@ -1422,21 +1385,27 @@ async function bump(subjectId, opts) {
     .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];
-  }
+  // DDL), NOT session data — it executes against clusterStorage (the framework
+  // db) whenever one is initialized, never _currentStore(). When the framework
+  // db is NOT initialized but an operator store IS configured (a store-backed-
+  // only b.session.useStore deployment that never ran b.db.init()), the boundary
+  // falls back to that store — provisioned on demand — so logout-everywhere
+  // still raises the stateless boundary instead of throwing db/not-initialized
+  // (#340). _runValidFrom resolves the target; never silently drops the boundary
+  // when a db is present, and propagates db/not-initialized when neither exists.
+  var row = await _runValidFrom(async function (target) {
+    if (built.readbackSql) {
+      // MySQL: ON DUPLICATE KEY UPDATE has no RETURNING — run the upsert, then
+      // the readback SELECT b.sql emits (keyed on subjectHash). MySQL only ever
+      // runs against the framework cluster db; the localDbThin fallback store is
+      // sqlite (RETURNING), so this branch never routes through it.
+      await target.execute(built.sql, built.params);
+      var readback = await target.execute(built.readbackSql.sql, built.readbackSql.params);
+      return readback.rows && readback.rows[0];
+    }
+    var result = await target.execute(built.sql, built.params);
+    return result.rows && result.rows[0];
+  });
   var effective = row ? Number(row.validFromEpoch) : epochMs;
 
   // Best-effort audit — matches the file's emit convention (safeEmit is
@@ -1475,10 +1444,16 @@ async function validFrom(subjectId) {
     .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);
+  // Framework valid-from table — read from clusterStorage (the framework db)
+  // when one is initialized, falling back to the configured store only when it
+  // is not (the same store bump() wrote the boundary to in a store-backed-only
+  // deployment). _runValidFrom keeps the read on the SAME backend the write
+  // chose, so a boundary raised via destroyAllForUser/bump is the one read back
+  // here. See bump() for the full rationale (#340).
+  var row = await _runValidFrom(async function (target) {
+    var result = await target.execute(built.sql, built.params);
+    return result.rows && result.rows.length > 0 ? result.rows[0] : null;
+  });
   return row ? Number(row.validFromEpoch) : 0;
 }
 

package/lib/sql.js

@@ -798,6 +798,17 @@ class Predicate {
       return this._add(joiner, qc + " " + op + " NULL", []);
     }
 
+    // `col = NULL` / `col != NULL` is UNKNOWN in SQL — never true. Emitting it
+    // (e.g. from where({ col: null })) silently matches zero rows; worse, a null
+    // accidentally passed where a real value was expected (where({ ownerId }))
+    // would, if rewritten to `IS NULL`, return orphan rows — an authorization
+    // footgun. Refuse it and direct the caller to the explicit NULL predicates.
+    if (value === null && (op === "=" || op === "!=" || op === "<>")) {
+      throw _err("where(" + JSON.stringify(col) + ", '" + op + "', null) is never true in SQL " +
+        "(col " + op + " NULL is UNKNOWN); use whereNull(col) / whereNotNull(col) to test for NULL",
+        "sql-builder/null-equality");
+    }
+
     if ((op === "LIKE" || op === "NOT LIKE") && typeof value === "string") {
       return this._add(joiner, qc + " " + op + " ? ESCAPE '~'", [_escapeLike(value)]);
     }
@@ -948,6 +959,17 @@ class Predicate {
     if (!Array.isArray(values) || values.length === 0) {
       throw _err("whereInArray requires a non-empty array of values", "sql-builder/empty-in");
     }
+    // Validate each element is a bindable parameter. On the non-Postgres IN-list
+    // path every element is its own `?`, so the driver rejects an undefined at
+    // execute; the Postgres `= ANY(?)` path binds the WHOLE array as one param,
+    // where an undefined is silently coerced to NULL — diverging per dialect.
+    // Reject undefined here so every backend fails the same way, at build.
+    for (var vi = 0; vi < values.length; vi += 1) {
+      if (values[vi] === undefined) {
+        throw _err("whereInArray value[" + vi + "] is undefined (not a bindable parameter)",
+          "sql-builder/bad-in-value");
+      }
+    }
     this._gate(col);
     var qc = _qualifiedColumn(col, this._dialect());
     if (this._dialect() === "postgres") {

package/lib/ws-client.js

@@ -585,6 +585,7 @@ class WsClient extends EventEmitter {
     this._reconnectAttempt = 0;
     this._fragmentChunks = [];
     this._fragmentOpcode = null;
+    this._fragmentBytes = 0;
 
     this._startHeartbeat();
     if (this._opts.auditOn) {
@@ -623,6 +624,14 @@ class WsClient extends EventEmitter {
   }
 
   _handleFrame(frame) {
+    // Once the connection has been torn down (e.g. a prior frame in the same
+    // parsed batch tripped maxMessageBytes and called _teardown, which sets
+    // _closed synchronously), drop any remaining buffered frames — processing
+    // them would emit a spurious cascade of protocol errors (a stray
+    // continuation after the fragment state reset). A graceful close keeps
+    // _closed false until the handshake completes, so the peer's CLOSE frame
+    // is still processed and the normal close code surfaces.
+    if (this._closed) return;
     // RFC 6455 §5.5: control frames MUST be <= 125 bytes AND non-fragmented.
     var isControl = frame.opcode === OPCODE_PING ||
                     frame.opcode === OPCODE_PONG ||
@@ -692,6 +701,7 @@ class WsClient extends EventEmitter {
       this._fragmentOpcode = frame.opcode;
       this._fragmentRsv1   = frame.rsv1 === true;
       this._fragmentChunks = [frame.payload];
+      this._fragmentBytes  = safeBuffer.byteLengthOf(frame.payload);
     } else if (frame.opcode === OPCODE_CONT) {
       if (this._fragmentOpcode == null) {
         this._handleSocketError(new WsClientError("ws-client/protocol-error",
@@ -699,6 +709,21 @@ class WsClient extends EventEmitter {
         return;
       }
       this._fragmentChunks.push(frame.payload);
+      this._fragmentBytes += safeBuffer.byteLengthOf(frame.payload);
+    }
+    // Enforce maxMessageBytes on the RUNNING fragment total, not only at FIN:
+    // a peer that streams continuation frames and never sets FIN would
+    // otherwise grow _fragmentChunks without bound, one maxFrameBytes-sized
+    // frame at a time (CWE-770 / CWE-400). The per-frame parser cap bounds a
+    // single frame, never the sum.
+    if (this._fragmentOpcode != null && this._fragmentBytes > this._opts.maxMessageBytes) {
+      this._fragmentChunks = [];
+      this._fragmentOpcode = null;
+      this._fragmentRsv1   = false;
+      this._fragmentBytes  = 0;
+      this._handleSocketError(new WsClientError("ws-client/message-too-big",
+        "incoming message exceeds maxMessageBytes (" + this._opts.maxMessageBytes + ")"));
+      return;
     }
     if (frame.fin) {
       var fullPayload = Buffer.concat(this._fragmentChunks);                              // allow:handrolled-buffer-collect — bounded by maxMessageBytes below
@@ -712,6 +737,7 @@ class WsClient extends EventEmitter {
       this._fragmentChunks = [];
       this._fragmentOpcode = null;
       this._fragmentRsv1 = false;
+      this._fragmentBytes = 0;
       if (this._negotiatedDeflate && firstFrameRsv1) {
         try {
           var zlib = require("node:zlib");                                                     // allow:inline-require — zlib only on deflate-negotiated path

package/lib/x509-chain.js

@@ -1,33 +1,80 @@
 "use strict";
+/**
+ * @module b.x509Chain
+ * @nav    Crypto
+ * @title  X.509 chain (CA-bit issuer test)
+ *
+ * @intro
+ *   The basicConstraints-enforcing issuer test the framework's own
+ *   certificate-chain walkers route through (<code>b.tsa.verifyToken</code>,
+ *   <code>b.mail.bimi</code> VMC/CMC, <code>b.mail.crypto.smime</code>,
+ *   <code>b.mdoc</code>, <code>b.contentCredentials</code>,
+ *   <code>b.auth.fido</code>). It exists because node:crypto's
+ *   <code>X509Certificate.checkIssued()</code> validates the issuer/subject
+ *   DN match, the AKI/SKI linkage, and — only when a keyUsage extension is
+ *   present — keyCertSign, but it does <strong>not</strong> enforce
+ *   basicConstraints cA:TRUE. A leaf / end-entity certificate (cA:FALSE)
+ *   that omits keyUsage is therefore wrongly accepted as a signing CA for
+ *   the next certificate in the chain — the classic basicConstraints bypass
+ *   (CVE-2002-0862 class). Every in-tree walker routes its issuer test
+ *   through these helpers so the cA enforcement can never be forgotten in
+ *   one walker but present in another.
+ *
+ *   Exposed so a consumer validating an X.509 chain <em>outside</em> a TLS
+ *   handshake — an operator-uploaded CA bundle, a non-handshake PQ-signed
+ *   certificate — has the same hardened, fail-closed test instead of being
+ *   pushed toward the raw <code>checkIssued()</code> path this module
+ *   exists to prevent. Both helpers fail closed: any malformed input or
+ *   unsupported key type returns false rather than throwing.
+ *
+ * @card
+ *   basicConstraints cA:TRUE-enforcing X.509 issuer test, fail-closed —
+ *   the hardened alternative to node's checkIssued() for chains built
+ *   outside a TLS handshake.
+ */
 
-// Internal X.509 path-validation helpers shared by the framework's
-// certificate-chain walkers (b.tsa.verifyToken, b.mail.bimi VMC/CMC,
-// b.mail.crypto.smime.verify). They exist because node:crypto's
-// X509Certificate.checkIssued() validates the issuer/subject DN match,
-// the AKI/SKI linkage, and — when a keyUsage extension is present —
-// keyCertSign, but it does NOT enforce basicConstraints cA:TRUE. A
-// leaf / end-entity certificate (cA:FALSE) that omits keyUsage is
-// therefore wrongly accepted as a signing CA for the next cert in the
-// chain — the classic basicConstraints bypass (CVE-2002-0862 class).
-// Every chain walker routes its issuer test through these helpers so the
-// cA enforcement can never be forgotten in one walker but present in
-// another.
-
-// True only when `cert` asserts basicConstraints cA:TRUE. node's
-// X509Certificate exposes `.ca` (a boolean); a cert with no
-// basicConstraints extension or with cA:FALSE returns false. A missing
-// cert or a non-boolean `.ca` (parse failure / unsupported runtime)
-// fails closed.
+/**
+ * @primitive b.x509Chain.isCaCert
+ * @signature b.x509Chain.isCaCert(cert)
+ * @since     0.15.15
+ * @status    stable
+ * @related   b.x509Chain.issuerValidlyIssued
+ *
+ * True only when <code>cert</code> asserts basicConstraints cA:TRUE.
+ * node's <code>X509Certificate</code> exposes <code>.ca</code> (a boolean);
+ * a certificate with no basicConstraints extension or with cA:FALSE
+ * returns false. A missing cert or a non-boolean <code>.ca</code> (parse
+ * failure / unsupported runtime) fails closed to false.
+ *
+ * @example
+ *   var crypto = require("crypto");
+ *   var ca = new crypto.X509Certificate(caPem);
+ *   b.x509Chain.isCaCert(ca);   // → true only if basicConstraints cA:TRUE
+ */
 function isCaCert(cert) {
   return !!cert && cert.ca === true;
 }
 
-// True when `issuer` validly issued `subject` AND is itself a CA: the
-// DN / AKI-SKI / keyUsage linkage (checkIssued), the cryptographic
-// signature (verify), and basicConstraints cA:TRUE (isCaCert). The cA
-// check runs first so a non-CA cert is rejected before the expensive
-// signature verification. Any exception (malformed cert, unsupported
-// key type) fails closed to false.
+/**
+ * @primitive b.x509Chain.issuerValidlyIssued
+ * @signature b.x509Chain.issuerValidlyIssued(issuer, subject)
+ * @since     0.15.15
+ * @status    stable
+ * @related   b.x509Chain.isCaCert
+ *
+ * True when <code>issuer</code> validly issued <code>subject</code> AND is
+ * itself a CA: the DN / AKI-SKI / keyUsage linkage (checkIssued), the
+ * cryptographic signature (verify), and basicConstraints cA:TRUE
+ * (isCaCert). The cA check runs first so a non-CA certificate is rejected
+ * before the expensive signature verification. Any exception (malformed
+ * cert, unsupported key type) fails closed to false.
+ *
+ * @example
+ *   var crypto = require("crypto");
+ *   var issuer  = new crypto.X509Certificate(issuerPem);
+ *   var subject = new crypto.X509Certificate(leafPem);
+ *   b.x509Chain.issuerValidlyIssued(issuer, subject);   // → boolean
+ */
 function issuerValidlyIssued(issuer, subject) {
   try {
     return isCaCert(issuer) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.15.14",
+  "version": "0.15.16",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:81a205f2-938f-47e5-9426-3245e2ac5859",
+  "serialNumber": "urn:uuid:159d260a-cc7c-4a49-a436-d1f67804241f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-21T13:24:58.132Z",
+    "timestamp": "2026-06-22T13:53:37.425Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.15.14",
+      "bom-ref": "@blamejs/core@0.15.16",
       "type": "application",
       "name": "blamejs",
-      "version": "0.15.14",
+      "version": "0.15.16",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.15.14",
+      "purl": "pkg:npm/%40blamejs/core@0.15.16",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.15.14",
+      "ref": "@blamejs/core@0.15.16",
       "dependsOn": []
     }
   ]