@blamejs/core 0.15.14 → 0.15.16

package/lib/network-proxy.js

@@ -7,6 +7,7 @@ var nodeTls = require("node:tls");
 
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
+var safeBuffer = require("./safe-buffer");
 var safeUrl = require("./safe-url");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
@@ -19,6 +20,23 @@ var IPV4_PREFIX_MAX_BITS = C.BYTES.bytes(32);   // RFC 791 §3.1 IPv4 address bi
 var DEFAULT_HTTPS_PORT   = 443;                 // RFC 9110 §4.2.2
 var DEFAULT_HTTP_PORT    = C.BYTES.bytes(80);   // RFC 9110 §4.2.1
 
+// Bound the CONNECT-reply framing buffer (mirrors ws-client's handshake
+// cap). A proxy that streams bytes without ever sending the CRLFCRLF
+// header terminator would otherwise grow `buf` without limit and OOM the
+// process; CONNECT replies are tiny, 64 KiB is generous headroom.
+var TUNNEL_HEADER_MAX_BYTES = C.BYTES.kib(64);
+// Wall-clock bound on the proxy connect + CONNECT handshake. Without it a
+// proxy that accepts the socket but never replies (or trickles forever)
+// hangs the tunnel indefinitely.
+var TUNNEL_CONNECT_TIMEOUT_MS = C.TIME.seconds(30);
+// Test-only override of the connect deadline so a unit test can prove the
+// absolute-timeout behavior without a 30s wall-clock wait. null = use the
+// real default. Cleared by _resetForTest.
+var _testConnectTimeoutMs = null;
+function _connectTimeoutMs() {
+  return typeof _testConnectTimeoutMs === "number" ? _testConnectTimeoutMs : TUNNEL_CONNECT_TIMEOUT_MS;
+}
+
 var observability = lazyRequire(function () { return require("./observability"); });
 // Lazy so pqc-agent's TLS/audit graph isn't pulled into every process that
 // imports network-proxy but never proxies an https upstream. Used only to audit
@@ -169,7 +187,27 @@ function _connectThroughTunnel(proxyUrl, targetHost, targetPort, callback) {
       })
     : net.connect({ host: proxyUrl.hostname, port: proxyPort });
   var settled = false;
-  function done(err, sock) { if (settled) return; settled = true; callback(err, sock); }
+  var connectDeadline = null;
+  function done(err, sock) {
+    if (settled) return;
+    settled = true;
+    if (connectDeadline) { try { clearTimeout(connectDeadline); } catch (_e) { /* best-effort */ } connectDeadline = null; }
+    callback(err, sock);
+  }
+  // ABSOLUTE wall-clock deadline on the proxy connect + CONNECT handshake. A
+  // proxy that accepts the socket but never sends the CRLFCRLF terminator —
+  // or trickles partial bytes just inside every idle window — must not hang
+  // the tunnel forever. socket.setTimeout is an IDLE timer that such a trickle
+  // resets indefinitely, so a fixed setTimeout (cleared in done()) enforces a
+  // real total-time bound regardless of how the bytes arrive.
+  var connectTimeoutMs = _connectTimeoutMs();
+  connectDeadline = setTimeout(function () {
+    done(new ProxyError("proxy/connect-timeout",
+      "proxy CONNECT to " + targetHost + ":" + targetPort + " timed out after " +
+      connectTimeoutMs + "ms"));
+    try { proxySocket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
+  }, connectTimeoutMs);
+  if (connectDeadline && typeof connectDeadline.unref === "function") connectDeadline.unref();
   proxySocket.on("error", function (e) { done(e); });
   proxySocket.on(proxyUrl.protocol === "https:" ? "secureConnect" : "connect", function () {
     if (proxyUrl.protocol === "https:") {
@@ -191,7 +229,18 @@ function _connectThroughTunnel(proxyUrl, targetHost, targetPort, callback) {
     function onData(chunk) {
       buf = Buffer.concat([buf, chunk]);
       var idx = buf.indexOf("\r\n\r\n");
-      if (idx === -1) return;
+      if (idx === -1) {
+        // No header terminator yet — bound the accumulator so a proxy
+        // that trickles non-CRLFCRLF bytes forever can't OOM the process.
+        if (safeBuffer.byteLengthOf(buf) > TUNNEL_HEADER_MAX_BYTES) {
+          proxySocket.removeListener("data", onData);
+          done(new ProxyError("proxy/connect-headers-too-large",
+            "proxy CONNECT reply exceeded " + TUNNEL_HEADER_MAX_BYTES +
+            " bytes before CRLFCRLF"));
+          try { proxySocket.destroy(); } catch (_e) { /* best-effort socket teardown */ }
+        }
+        return;
+      }
       proxySocket.removeListener("data", onData);
       var head = buf.slice(0, idx).toString("ascii");
       var status = head.split("\r\n")[0] || "";
@@ -271,8 +320,11 @@ function snapshot() {
 function _resetForTest() {
   STATE.http = null; STATE.https = null; STATE.noProxy = []; STATE.auth = null;
   STATE.agentCache.clear();
+  _testConnectTimeoutMs = null;
 }
 
+function _setConnectTimeoutForTest(ms) { _testConnectTimeoutMs = ms; }
+
 module.exports = {
   set:           set,
   fromEnv:       fromEnv,
@@ -281,4 +333,5 @@ module.exports = {
   snapshot:      snapshot,
   ProxyError:    ProxyError,
   _resetForTest: _resetForTest,
+  _setConnectTimeoutForTest: _setConnectTimeoutForTest,
 };

package/lib/object-store/azure-blob-bucket-ops.js

@@ -233,6 +233,7 @@ function create(config) {
       url:              url,
       headers:          headers,
       body:             body,
+      timeoutMs:        timeoutMs,
       idleTimeoutMs:    timeoutMs,
       allowedProtocols: allowedProtocols,
       errorClass:       ObjectStoreError,

package/lib/object-store/gcs-bucket-ops.js

@@ -182,6 +182,7 @@ function create(config) {
       url:              url,
       headers:          headers,
       body:             body,
+      timeoutMs:        timeoutMs,
       idleTimeoutMs:    timeoutMs,
       allowedProtocols: allowedProtocols,
       errorClass:       ObjectStoreError,

package/lib/object-store/http-request.js

@@ -36,6 +36,10 @@ function request(method, url, headers, body, opts) {
     url:              url,
     headers:          headers,
     body:             body,
+    // Both caps from the operator's configured timeout: timeoutMs bounds the
+    // whole request (no slow-trickle hold-open), idleTimeoutMs the zero-progress
+    // window. Undefined leaves httpClient's defaults unchanged.
+    timeoutMs:        opts.timeoutMs,
     idleTimeoutMs:    opts.timeoutMs,
     errorClass:       opts.errorClass || ObjectStoreError,
     allowedProtocols: opts.allowedProtocols,

package/lib/outbox.js

@@ -214,6 +214,35 @@ function create(opts) {
         throw new OutboxError("outbox/bad-externaldb",
           "outbox.create: externalDb must be the b.externalDb namespace (with transaction/query)");
       }
+      // The outbox dual-write guarantee (enqueue runs in the SAME
+      // transaction as the operator's business write) is VOID on a
+      // stateless / autocommit-per-statement backend: BEGIN / the
+      // business write / the enqueue INSERT / COMMIT each land on a
+      // different session, so a crash or rollback can drop the business
+      // row while keeping the event (or vice versa). Refuse at create()
+      // when the backend declares it cannot provide interactive
+      // transactions, rather than constructing an outbox whose core
+      // guarantee silently does not hold. supportsTransactions may be a
+      // boolean (custom externalDb object) or a function (the
+      // b.externalDb namespace probe); only an explicit false refuses —
+      // an absent flag preserves the historical stateful assumption.
+      var cap = v.supportsTransactions;
+      var atomic = true;
+      if (typeof cap === "function") {
+        try { atomic = !!cap(); } catch (_e) { atomic = true; }
+      } else if (cap === false) {
+        atomic = false;
+      }
+      if (!atomic) {
+        throw new OutboxError("outbox/non-atomic-backend",
+          "outbox.create: externalDb backend cannot provide interactive " +
+          "transactions (supportsTransactions: false — a stateless / " +
+          "autocommit-per-statement adapter). The outbox dual-write guarantee " +
+          "requires the business write and the enqueue INSERT to commit " +
+          "atomically in one transaction; on this backend they would not. " +
+          "Supply interactive beginTx / commit / rollback hooks, or a batch " +
+          "adapter, on the externalDb backend first.");
+      }
     },
     table: function (v) {
       validateOpts.requireNonEmptyString(v,

package/lib/pipl-cn.js

@@ -108,14 +108,17 @@ function _requireRecordedAt(value, label) {
  * and determine the lawful mechanism the transfer requires. PIPL Art. 38(1)
  * permits three bases for moving personal information out of the PRC — the
  * CAC standard contract (SCC), a CAC security assessment (Art. 40), or
- * certification by a CAC-accredited body — but the Measures for Security
- * Assessment of Outbound Data Transfers make the security assessment
- * MANDATORY (the operator may NOT self-select the standard contract or
- * certification) when the exporter is a critical-information-infrastructure
- * operator (CIIO), exports "important data", handles personal information
- * of more than 1,000,000 individuals, or has cumulatively exported PI of
- * more than 100,000 individuals or sensitive PI of more than 10,000
- * individuals since 1 January of the preceding year.
+ * certification by a CAC-accredited body. Under the CAC Provisions on
+ * Promoting and Regulating Cross-Border Data Flows (effective 2024, which
+ * relaxed the 2022 thresholds) the security assessment is MANDATORY (the
+ * operator may NOT self-select the standard contract or certification) when
+ * the exporter is a critical-information-infrastructure operator (CIIO),
+ * exports "important data", or — counting cumulatively since 1 January of
+ * the current year — transfers the personal information of more than
+ * 1,000,000 individuals (non-sensitive) or the sensitive personal
+ * information of more than 10,000 individuals. The 100,000–1,000,000
+ * non-sensitive band is the standard-contract / certification tier, NOT a
+ * security-assessment trigger.
  *
  * The builder validates the operator-supplied facts, computes
  * `securityAssessmentRequired` against those thresholds, resolves the

package/lib/queue-sqs.js

@@ -153,6 +153,7 @@ function create(opts) {
       url:              endpointUrl,
       headers:          signed.headers,
       body:             bodyBuf,
+      timeoutMs:        timeoutMs,
       idleTimeoutMs:    timeoutMs,
       allowedProtocols: allowedProtocols,
       errorClass:       QueueError,

package/lib/request-helpers.js

@@ -384,6 +384,153 @@ function trustedClientIp(opts) {
   };
 }
 
+// IP-prefix masking constants — named so the bit-arithmetic stays readable.
+// /24 IPv4 is the original IP-geolocation bucket and matches the legacy
+// carrier-NAT pool stride; /64 IPv6 is the customer LAN every RIR allocates
+// (RFC 4291 §2.5.4), so tightening below it punishes IPv6 privacy-extension
+// address rotation.
+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 IP_BYTE_MASK          = 0xff;
+var IP_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) & IP_BYTE_MASK) + "." +
+         ((masked >>> IP_BITS_PER_BYTE * 2) & IP_BYTE_MASK) + "." +
+         ((masked >>> IP_BITS_PER_BYTE)     & IP_BYTE_MASK) + "." +
+         (masked & IP_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, IP_HEX_RADIX);
+    if (!Number.isInteger(v) || v < 0 || v > 0xffff) return null;
+    bytes.push((v >> IP_BITS_PER_BYTE) & IP_BYTE_MASK);
+    bytes.push(v & IP_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 = (IP_BYTE_MASK << (IP_BITS_PER_BYTE - keepBits)) & IP_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(IP_HEX_RADIX));
+  }
+  return out.join(":") + "/" + prefix;
+}
+
+/**
+ * @primitive b.requestHelpers.ipPrefix
+ * @signature b.requestHelpers.ipPrefix(ip, opts?)
+ * @since     0.15.15
+ * @related   b.requestHelpers.clientIp, b.requestHelpers.trustedClientIp
+ *
+ * Mask a client IP to its subnet bucket: a <code>/24</code> for IPv4 (the
+ * carrier-NAT pool stride) and a <code>/64</code> for IPv6 (the customer-LAN
+ * prefix RIRs allocate, RFC 4291 §2.5.4). Returns the canonical
+ * <code>"network/prefix"</code> string, or <code>""</code> for a non-string /
+ * empty / unparseable input. An IPv4-mapped IPv6 address
+ * (<code>::ffff:1.2.3.4</code>) folds to its dotted form so it buckets the
+ * same regardless of how a proxy reported it.
+ *
+ * This is the masking the session device-fingerprint's built-in
+ * <code>clientIpPrefix</code> field hashes (so roaming carriers that flip the
+ * public IP within a subnet don't log a user out). Exposed so an operator who
+ * drops to a function-form fingerprint field — for a custom mask width, or to
+ * combine the prefix with other signals — reuses this exact algorithm instead
+ * of re-deriving the /24 + /64 masking (and silently diverging). Pass
+ * <code>opts.v4Bits</code> / <code>opts.v6Bits</code> to override the mask
+ * widths (e.g. a device fingerprint that buckets at <code>/48</code> so a
+ * client roaming within its allocation but across a <code>/64</code> doesn't
+ * drift); an out-of-range or absent value falls back to the /24 + /64 default.
+ *
+ * @opts
+ *   v4Bits: number,   // IPv4 mask width in bits (default 24; valid 0..32)
+ *   v6Bits: number,   // IPv6 mask width in bits (default 64; valid 0..128)
+ *
+ * @example
+ *   b.requestHelpers.ipPrefix("203.0.113.47");   // → "203.0.113.0/24"
+ *   b.requestHelpers.ipPrefix("2001:db8::1");     // → "2001:db8:0:0/64"
+ */
+function _resolvePrefixBits(bits, def, max) {
+  if (typeof bits !== "number" || !isFinite(bits) || bits < 0 || bits > max) return def;
+  return bits;
+}
+function ipPrefix(ip, opts) {
+  if (typeof ip !== "string" || ip.length === 0) return "";
+  opts = opts || {};
+  // Configurable mask widths (default /24 + /64); an absent or out-of-range
+  // value falls back to the default. This preserves a caller's documented
+  // prefix width (e.g. a device fingerprint bucketing at /48) instead of
+  // silently forcing /64 — while still canonicalizing the address.
+  var v4 = _resolvePrefixBits(opts.v4Bits, IPV4_DEFAULT_PREFIX, 32);                            // IPv4 max prefix length in bits
+  var v6 = _resolvePrefixBits(opts.v6Bits, IPV6_DEFAULT_PREFIX, 128);                           // IPv6 max prefix length in bits
+  // 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), v4) || "";
+  }
+  if (ip.indexOf(":") !== -1) return _maskIpv6(ip, v6) || "";
+  if (ip.indexOf(".") !== -1) return _maskIpv4(ip, v4) || "";
+  return "";
+}
+
 /**
  * @primitive b.requestHelpers.trustedProtocol
  * @signature b.requestHelpers.trustedProtocol(opts?)
@@ -787,8 +934,6 @@ function captureResponseStatus(res, onEnd) {
   return origEnd;
 }
 
-var Q_VALUE_RE = /(?:^|;|\s)q\s*=\s*([0-9]*\.?[0-9]+)/i;
-
 /**
  * @primitive b.requestHelpers.parseQualityList
  * @signature b.requestHelpers.parseQualityList(headerValue, opts?)
@@ -831,24 +976,30 @@ function parseQualityList(headerValue, opts) {
   if (typeof headerValue !== "string" || headerValue.length === 0) return [];
   opts = opts || {};
   var caseSensitive = opts.caseSensitive === true;
-  var parts = headerValue.split(",");
+  // Quote-aware split: a parameter value may be a quoted-string containing ','
+  // or ';' or 'q=' (RFC 7231 §5.3.1 / RFC 9110), which must not split an element
+  // or be mis-read as the q-value. splitUnquoted respects double-quoted runs.
+  var parts = structuredFields.splitUnquoted(headerValue, ",");
   var out = [];
   for (var i = 0; i < parts.length; i++) {
     var p = parts[i].trim();
     if (p.length === 0) continue;
-    var semi = p.indexOf(";");
-    var value, q;
-    if (semi === -1) {
-      value = caseSensitive ? p : p.toLowerCase();
-      q = 1;
-    } else {
-      var head = p.slice(0, semi).trim();
-      value = caseSensitive ? head : head.toLowerCase();
-      var rest = p.slice(semi + 1).trim();
-      var qm = rest.match(Q_VALUE_RE);
+    var segs = structuredFields.splitUnquoted(p, ";");
+    var head = segs[0].trim();
+    var value = caseSensitive ? head : head.toLowerCase();
+    var q = 1;
+    // The q parameter is the named token `q` separating media-type params from
+    // accept-ext; the FIRST `q` parameter is the quality. Only a parameter
+    // literally named `q` counts — never a `q=`-shaped substring of another
+    // parameter's name or quoted value.
+    for (var s = 1; s < segs.length; s++) {
+      var kv = structuredFields.parseKeyValuePiece(segs[s], "=", true);
+      if (kv.key !== "q") continue;
+      var qm = String(kv.value).trim().match(/^([0-9]*\.?[0-9]+)/);
       q = qm ? parseFloat(qm[1]) : 1;
       if (isNaN(q) || q < 0) q = 0;
       if (q > 1) q = 1;
+      break;
     }
     out.push({ value: value, q: q });
   }
@@ -1067,6 +1218,7 @@ module.exports = {
   // proxy-trust primitives (default refuses forwarded headers)
   clientIp:                  clientIp,
   trustedClientIp:           trustedClientIp,
+  ipPrefix:                  ipPrefix,
   requestProtocol:           requestProtocol,
   trustedProtocol:           trustedProtocol,
   appendVary:                appendVary,

package/lib/safe-json.js

@@ -969,9 +969,35 @@ function _capInt(value, defaultValue, ceiling) {
  *   });
  */
 
+/**
+ * @primitive b.safeJson.isJsonObject
+ * @signature b.safeJson.isJsonObject(value)
+ * @since     0.15.14
+ * @status    stable
+ * @related   b.safeJson.parse
+ *
+ * True iff <code>value</code> is a plain JSON object — not <code>null</code>,
+ * not an array, not a scalar. <code>safeJson.parse</code> accepts the literal
+ * <code>null</code> and scalars / arrays (all valid JSON documents), so a
+ * parsed JWS header, claims set, or document must be re-checked before its
+ * fields are dereferenced. This is that check, shared so the
+ * <code>!x || typeof x !== "object" || Array.isArray(x)</code> idiom isn't
+ * re-rolled (and silently varied) at every call site.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeJson.isJsonObject(b.safeJson.parse('{"a":1}'));   // → true
+ *   b.safeJson.isJsonObject(b.safeJson.parse("null"));      // → false
+ *   b.safeJson.isJsonObject(b.safeJson.parse("[1,2]"));     // → false
+ */
+function isJsonObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 module.exports = {
   parse:          parse,
   parseOrDefault: parseOrDefault,
+  isJsonObject:   isJsonObject,
   stringify:      stringify,
   stringifyForScript: stringifyForScript,
   canonical:      canonical,

package/lib/session-device-binding.js

@@ -52,6 +52,14 @@
  * primitive falls back to b.session.touch metadata when the operator
  * passes session=b.session AND opts in via storeInSession=true.
  *
+ * No store at all: create() with neither bindingStore nor storeInSession
+ * still returns an instance — its stateless fingerprint(req) works (it
+ * touches no store), while bind/verify/unbind throw a clear "no store
+ * configured" error. Operators who only need the soft, store-free digest
+ * (sealed inside a self-validating cookie / JWT that compares it itself)
+ * can also skip create() entirely and call the static
+ * b.sessionDeviceBinding.fingerprint(req, opts).
+ *
  * Audit emissions:
  *
  *   session.device.bound      every successful bind()
@@ -61,7 +69,9 @@
  *
  * Validation policy:
  *   - create() opts → throw at config time
- *   - bind / verify  → throw on bad token / req shape (operator typo)
+ *   - bind / verify / unbind → throw on bad token / req shape (operator
+ *                      typo), and throw "no store configured" when called
+ *                      on a store-free instance
  *   - storage errors  → fail-CLOSED on verify (drift indistinguishable
  *                       from a wiped store, refuse rather than allow)
  *                       fail-OPEN on bind (don't lose a fresh session
@@ -135,28 +145,22 @@ function _normalizeAcceptEncoding(value) {
     .join(",");
 }
 
+// Mask the client IP to its fingerprint bucket. Routes through the shared
+// canonical masker (requestHelpers.ipPrefix) so a `::`-shorthand address and
+// its fully-expanded equivalent (2001:db8::1 vs 2001:db8:0:0:0:0:0:1), or a
+// leading-zero-folded group, collapse to ONE bucket — the hand-rolled textual
+// ':'-group slice this replaced hashed them differently and logged a roaming
+// user out on a false drift. `bits === 0` is the documented "skip the IP check
+// entirely" escape hatch (mobile clients that switch networks), so it returns
+// "" before any masking. `bits` is the family-resolved configured width (cfg
+// .v4Bits for a v4 client, cfg.v6Bits for v6 — default /24 + /48); pass it as
+// BOTH v4Bits and v6Bits so the canonical masker applies the configured width
+// to whichever family it detects, instead of ipPrefix's bare /24 + /64 default
+// (which would drop the configured width AND silently tighten v6 from /48 to /64).
 function _ipPrefix(ip, bits) {
   if (typeof ip !== "string" || ip.length === 0) return "";
   if (bits === 0) return "";
-  // IPv6
-  if (ip.indexOf(":") !== -1) {
-    var v6Bits = bits;
-    var groups = ip.split(":");
-    // Naive expansion — keep the first ceil(v6Bits/16) groups intact
-    // and zero the rest. Sufficient for fingerprint stability; not a
-    // canonical IPv6 representation.
-    var keepGroups = Math.ceil(v6Bits / 16); // IPv6 group width in bits
-    var kept = groups.slice(0, keepGroups).join(":");
-    return "v6:" + kept + "/" + v6Bits;
-  }
-  // IPv4
-  var parts = ip.split(".");
-  if (parts.length !== 4) return "v4:" + ip + "/" + bits;
-  var v4Bits = bits;
-  var keepOctets = Math.floor(v4Bits / 8); // IPv4 octet width in bits
-  var maskedOctets = parts.slice(0, keepOctets);
-  while (maskedOctets.length < 4) maskedOctets.push("0");
-  return "v4:" + maskedOctets.join(".") + "/" + v4Bits;
+  return requestHelpers.ipPrefix(ip, { v4Bits: bits, v6Bits: bits });
 }
 
 // Resolve operator-supplied fingerprintExtras(req) to a stable string. A
@@ -195,6 +199,7 @@ function _computeDeviceFingerprint(req, cfg) {
   var ae = _normalizeAcceptEncoding(headers["accept-encoding"]);
   var ip = "";
   try { ip = requestHelpers.clientIp(req); } catch (_e) { ip = ""; }
+  if (typeof ip !== "string") ip = "";
   var family = ip.indexOf(":") !== -1 ? "v6" : "v4";
   var ipPart = _ipPrefix(ip, family === "v6" ? cfg.v6Bits : cfg.v4Bits);
   var keyPart = "";
@@ -291,10 +296,15 @@ function create(opts) {
   }
 
   var storeInSession = !!opts.storeInSession;
-  if (!storeInSession && !opts.bindingStore) {
-    throw new SessionDeviceBindingError("session-device-binding/bad-opt",
-      "either bindingStore (b.cache-shaped) or storeInSession=true must be set");
-  }
+  // A no-store instance is still useful: the stateless fingerprint() reads no
+  // store and is the soft device-binding building block for self-validating
+  // tokens (a sealed cookie / JWT carrying the fingerprint inside). Rather than
+  // refuse to construct (issue #330 — fingerprint() unreachable without a
+  // store), build the instance and let the persisted bind()/verify() lifecycle
+  // throw a clear "no store configured" when actually called. Operators wanting
+  // ONLY the stateless digest can also use the static
+  // b.sessionDeviceBinding.fingerprint(req, opts) with no create() at all.
+  var hasStore = !!(storeInSession || opts.bindingStore);
   if (opts.bindingStore) _requireBindingStore(opts.bindingStore);
   if (storeInSession && (!opts.session || typeof opts.session.touch !== "function")) {
     throw new SessionDeviceBindingError("session-device-binding/bad-opt",
@@ -351,8 +361,18 @@ function create(opts) {
     return { ok: true, fingerprint: r.fingerprint, components: r.components };
   }
 
+  function _requireStore(stage) {
+    if (!hasStore) {
+      throw new SessionDeviceBindingError("session-device-binding/no-store",
+        stage + ": no store configured — pass bindingStore (b.cache-shaped) or "
+        + "storeInSession=true to create(), or use the stateless "
+        + "b.sessionDeviceBinding.fingerprint(req, opts) for soft binding");
+    }
+  }
+
   async function bind(token, req) {
     _requireToken(token);
+    _requireStore("bind");
     var fp = _computeFingerprint(req);
     if (!fp.ok) {
       _emitObs("session.device.refused", { reason: fp.reason });
@@ -408,6 +428,7 @@ function create(opts) {
 
   async function verify(token, req) {
     _requireToken(token);
+    _requireStore("verify");
     var fpResult = _computeFingerprint(req);
     if (!fpResult.ok) {
       _emitObs("session.device.refused", { reason: fpResult.reason });
@@ -444,6 +465,7 @@ function create(opts) {
 
   async function unbind(token) {
     _requireToken(token);
+    _requireStore("unbind");
     if (bindingStore) {
       try { await bindingStore.del(token); } catch (_e) { /* drop-silent */ }
     }