@blamejs/blamejs-shop 0.4.55 → 0.4.57

package/lib/vendor/blamejs/lib/scheduler.js

@@ -40,11 +40,12 @@
  */
 
 var lazyRequire = require("./lazy-require");
-var audit  = lazyRequire(function () { return require("./audit"); });
+var auditEmit = require("./audit-emit");
 var log    = lazyRequire(function () { return require("./log").boot("scheduler"); });
 var clusterStorage = require("./cluster-storage");
 var sql = require("./sql");
 var validateOpts = require("./validate-opts");
+var boundedMap = require("./bounded-map");
 var C = require("./constants");
 var { SchedulerError } = require("./framework-error");
 
@@ -417,15 +418,7 @@ function create(opts) {
 
   var _err = SchedulerError.factory;
 
-  function _emit(action, info, outcome) {
-    if (!auditOn) return;
-    audit().safeEmit({
-      action:   action,
-      outcome:  outcome,
-      metadata: info || {},
-      reason:   info && info.reason ? info.reason : null,
-    });
-  }
+  var _emit = auditEmit.gatedReasonEmitter({ audit: auditOn });
 
   function _isLeaderHere() {
     if (!clusterInstance) return true;
@@ -447,10 +440,10 @@ function create(opts) {
     if (typeof spec.name !== "string" || spec.name.length === 0) {
       throw _err("INVALID_NAME", "scheduler.schedule: spec.name is required", true);
     }
-    if (tasks.has(spec.name)) {
+    boundedMap.requireAbsent(tasks, spec.name, function () {
       throw _err("DUPLICATE_NAME",
         "scheduler.schedule: '" + spec.name + "' is already scheduled", true);
-    }
+    });
 
     var hasCron     = typeof spec.cron === "string";
     var hasEvery    = typeof spec.every === "number";

package/lib/vendor/blamejs/lib/sec-cyber.js

@@ -94,45 +94,90 @@ function eightKArtifact(opts) {
     throw SecCyberError.factory("sec-cyber/bad-opts",
       "secCyber.eightKArtifact: opts required");
   }
-  validateOpts.requireNonEmptyString(opts.incidentId,
-    "secCyber.eightKArtifact: incidentId", SecCyberError, "BAD_INCIDENT_ID");
-  if (!opts.registrant || typeof opts.registrant !== "object") {
-    throw SecCyberError.factory("sec-cyber/bad-registrant",
-      "secCyber.eightKArtifact: registrant object required");
-  }
-  validateOpts.requireNonEmptyString(opts.registrant.name,
-    "secCyber.eightKArtifact: registrant.name", SecCyberError, "BAD_REGISTRANT_NAME");
-  validateOpts.requireNonEmptyString(opts.registrant.cik,
-    "secCyber.eightKArtifact: registrant.cik", SecCyberError, "BAD_CIK");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.detectedAt,
-    "secCyber.eightKArtifact: detectedAt", SecCyberError, "BAD_DETECTED_AT");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.materialityDeterminedAt,
-    "secCyber.eightKArtifact: materialityDeterminedAt", SecCyberError, "BAD_MAT_AT");
-
-  if (FINDINGS.indexOf(opts.materialityFinding) === -1) {
-    throw SecCyberError.factory("sec-cyber/bad-finding",
-      "secCyber.eightKArtifact: materialityFinding must be one of " + FINDINGS.join(", "));
-  }
-  validateOpts.requireNonEmptyString(opts.materialityReasoning,
-    "secCyber.eightKArtifact: materialityReasoning", SecCyberError, "BAD_REASONING");
-
-  if (opts.materialityFinding === "material") {
-    validateOpts.requireNonEmptyString(opts.nature,
-      "secCyber.eightKArtifact: nature", SecCyberError, "BAD_NATURE");
-    validateOpts.requireNonEmptyString(opts.scope,
-      "secCyber.eightKArtifact: scope", SecCyberError, "BAD_SCOPE");
-    validateOpts.requireNonEmptyString(opts.timing,
-      "secCyber.eightKArtifact: timing", SecCyberError, "BAD_TIMING");
-    validateOpts.requireNonEmptyString(opts.impact,
-      "secCyber.eightKArtifact: impact", SecCyberError, "BAD_IMPACT");
-  }
+  validateOpts.shape(opts, {
+    incidentId: "required-string",
+    registrant: function (registrant) {
+      if (!registrant || typeof registrant !== "object") {
+        throw SecCyberError.factory("sec-cyber/bad-registrant",
+          "secCyber.eightKArtifact: registrant object required");
+      }
+      validateOpts.requireNonEmptyString(registrant.name,
+        "secCyber.eightKArtifact: registrant.name", SecCyberError, "BAD_REGISTRANT_NAME");
+      validateOpts.requireNonEmptyString(registrant.cik,
+        "secCyber.eightKArtifact: registrant.cik", SecCyberError, "BAD_CIK");
+    },
+    detectedAt: function (detectedAt) {
+      numericBounds.requirePositiveFiniteIntIfPresent(detectedAt,
+        "secCyber.eightKArtifact: detectedAt", SecCyberError, "BAD_DETECTED_AT");
+    },
+    materialityDeterminedAt: function (materialityDeterminedAt) {
+      numericBounds.requirePositiveFiniteIntIfPresent(materialityDeterminedAt,
+        "secCyber.eightKArtifact: materialityDeterminedAt", SecCyberError, "BAD_MAT_AT");
+    },
+    // materialityFinding / materialityReasoning and the material-only fields
+    // (nature/scope/timing/impact) and the AG-delay fields each carry their own
+    // per-field code (BAD_FINDING / BAD_REASONING / BAD_NATURE / ... /
+    // BAD_AG_JUSTIFICATION). Cross-field requiredness (the material-only and
+    // AG-delay fields) lives in the function rule via the 5th `opts` arg, so the
+    // whole contract is enforced inside this one exhaustive shape.
+    materialityFinding: function (v) {
+      if (FINDINGS.indexOf(v) === -1) {
+        throw SecCyberError.factory("sec-cyber/bad-finding",
+          "secCyber.eightKArtifact: materialityFinding must be one of " + FINDINGS.join(", "));
+      }
+    },
+    materialityReasoning: function (v) {
+      validateOpts.requireNonEmptyString(v,
+        "secCyber.eightKArtifact: materialityReasoning", SecCyberError, "BAD_REASONING");
+    },
+    nature: function (v, label, e, c, o) {
+      if (o.materialityFinding === "material") {
+        validateOpts.requireNonEmptyString(v,
+          "secCyber.eightKArtifact: nature", SecCyberError, "BAD_NATURE");
+      } else {
+        validateOpts.optionalNonEmptyString(v, label, e, c);
+      }
+    },
+    scope: function (v, label, e, c, o) {
+      if (o.materialityFinding === "material") {
+        validateOpts.requireNonEmptyString(v,
+          "secCyber.eightKArtifact: scope", SecCyberError, "BAD_SCOPE");
+      } else {
+        validateOpts.optionalNonEmptyString(v, label, e, c);
+      }
+    },
+    timing: function (v, label, e, c, o) {
+      if (o.materialityFinding === "material") {
+        validateOpts.requireNonEmptyString(v,
+          "secCyber.eightKArtifact: timing", SecCyberError, "BAD_TIMING");
+      } else {
+        validateOpts.optionalNonEmptyString(v, label, e, c);
+      }
+    },
+    impact: function (v, label, e, c, o) {
+      if (o.materialityFinding === "material") {
+        validateOpts.requireNonEmptyString(v,
+          "secCyber.eightKArtifact: impact", SecCyberError, "BAD_IMPACT");
+      } else {
+        validateOpts.optionalNonEmptyString(v, label, e, c);
+      }
+    },
+    agDelayRequested:     "optional-boolean",
+    agDelayJustification: function (v, label, e, c, o) {
+      if (o.agDelayRequested === true) {
+        validateOpts.requireNonEmptyString(v,
+          "secCyber.eightKArtifact: agDelayJustification (required when agDelayRequested=true)",
+          SecCyberError, "BAD_AG_JUSTIFICATION");
+      } else {
+        validateOpts.optionalNonEmptyString(v, label, e, c);
+      }
+    },
+    // audit is a boolean toggle (`opts.audit !== false` suppresses emission);
+    // the emit uses the module-level b.audit sink, not this value.
+    audit:                "optional-boolean",
+  }, "secCyber.eightKArtifact", SecCyberError, "BAD_INCIDENT_ID");
 
   var agDelayRequested = opts.agDelayRequested === true;
-  if (agDelayRequested) {
-    validateOpts.requireNonEmptyString(opts.agDelayJustification,
-      "secCyber.eightKArtifact: agDelayJustification (required when agDelayRequested=true)",
-      SecCyberError, "BAD_AG_JUSTIFICATION");
-  }
 
   var matAt = opts.materialityDeterminedAt || Date.now();
   var deadline = agDelayRequested ? null : _addBusinessDays(matAt, 4);

package/lib/vendor/blamejs/lib/seeders.js

@@ -55,6 +55,7 @@
  */
 
 var nodePath = require("node:path");
+var moduleLoader = require("./module-loader");
 var atomicFile = require("./atomic-file");
 var C = require("./constants");
 var dbSchema = require("./db-schema");
@@ -190,18 +191,10 @@ function _listSeedFiles(rootDir, env) {
 }
 
 function _loadSeed(rootDir, env, file) {
-  var fullPath = nodePath.join(_envDir(rootDir, env), file);
-  // Drop require cache for this path so a test rewriting a fixture
-  // between calls picks it up. Production restarts the process anyway.
-  try { delete require.cache[require.resolve(fullPath)]; } catch (_e) { /* not yet cached */ }
-  var mod;
-  // Operator-supplied seed — dynamic by design, can't be bundle-traced.
-  // Host-CLI scope; deploying via SEA / pkg drops this surface.
-  try { mod = require(fullPath); }   // allow:dynamic-require — operator-supplied seed
-  catch (e) {
-    throw _err("LOAD_FAILED",
+  var mod = moduleLoader.requireFresh(nodePath.join(_envDir(rootDir, env), file), function (e) {
+    return _err("LOAD_FAILED",
       "seed '" + env + "/" + file + "' failed to load: " + ((e && e.message) || String(e)));
-  }
+  });
   if (!mod || typeof mod.run !== "function") {
     throw _err("BAD_SEED",
       "seed '" + env + "/" + file + "' must export an async `run(db, ctx)` function");

package/lib/vendor/blamejs/lib/self-update.js

@@ -57,13 +57,12 @@ var bCrypto = require("./crypto");
 var httpClient = require("./http-client");
 var safeJson = require("./safe-json");
 var { URL: NodeUrl } = require("node:url");
-var lazyRequire = require("./lazy-require");
 var C = require("./constants");
 var standaloneVerifier = require("./self-update-standalone-verifier");
 var { boot } = require("./log");
 var { defineClass } = require("./framework-error");
 
-var audit = lazyRequire(function () { return require("./audit"); });
+var auditEmit = require("./audit-emit");
 
 var SelfUpdateError = defineClass("SelfUpdateError", { alwaysPermanent: true });
 var log = boot("self-update");
@@ -76,13 +75,7 @@ var DEFAULT_HASH_ALG  = "sha3-512";
 var DEFAULT_RELEASES_BYTES = C.BYTES.mib(8);     // GitHub releases JSON ~hundreds of KB; 8 MiB caps a malicious response
 
 function _safeAuditEmit(action, outcome, metadata) {
-  try {
-    audit().safeEmit({
-      action:   action,
-      outcome:  outcome || "success",
-      metadata: metadata || {},
-    });
-  } catch (_e) { /* drop-silent — by design */ }
+  auditEmit.emit(action, metadata, outcome);
 }
 
 // ---- semver-shaped comparison (tag_name like "v0.7.30" or "0.7.30") ----
@@ -218,44 +211,66 @@ function _compareTags(a, b) {
 // ---- poll ----
 
 function _validatePollOpts(opts) {
-  validateOpts.requireObject(opts, "selfUpdate.poll", SelfUpdateError, "selfupdate/bad-opts");
-  validateOpts.requireNonEmptyString(opts.releasesUrl,
-    "selfUpdate.poll: opts.releasesUrl", SelfUpdateError, "selfupdate/bad-releases-url");
-  // Scheme enforcement at config-time so the bug surfaces here, not
-  // inside the request loop. Default policy: https only. Operators
-  // wiring against an internal mirror can pass allowedProtocols
-  // explicitly to opt in to http (e.g. a TLS-terminating proxy
-  // upstream of the framework process). The full SSRF / hostname /
-  // length policy still runs inside httpClient.request.
-  var parsedProto;
-  try { parsedProto = new NodeUrl(opts.releasesUrl).protocol; }
-  catch (_e) {
-    throw new SelfUpdateError("selfupdate/bad-releases-url",
-      "selfUpdate.poll: opts.releasesUrl is not parseable as a URL");
-  }
-  var allowedProtocols = Array.isArray(opts.allowedProtocols) && opts.allowedProtocols.length > 0
-    ? opts.allowedProtocols.slice() : ["https:"];
-  if (allowedProtocols.indexOf(parsedProto) === -1) {
-    throw new SelfUpdateError("selfupdate/bad-releases-url",
-      "selfUpdate.poll: opts.releasesUrl protocol '" + parsedProto +
-      "' not in allowedProtocols [" + allowedProtocols.join(", ") + "]");
-  }
-  validateOpts.requireNonEmptyString(opts.currentVersion,
-    "selfUpdate.poll: opts.currentVersion", SelfUpdateError, "selfupdate/bad-current-version");
-  if (opts.assetPattern !== undefined && !(opts.assetPattern instanceof RegExp) &&
-      typeof opts.assetPattern !== "string") {
-    throw new SelfUpdateError("selfupdate/bad-asset-pattern",
-      "selfUpdate.poll: opts.assetPattern must be a RegExp or string when present");
-  }
-  if (opts.signaturePattern !== undefined && !(opts.signaturePattern instanceof RegExp) &&
-      typeof opts.signaturePattern !== "string") {
-    throw new SelfUpdateError("selfupdate/bad-sig-pattern",
-      "selfUpdate.poll: opts.signaturePattern must be a RegExp or string when present");
-  }
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxBytes,
-    "selfUpdate.poll: opts.maxBytes", SelfUpdateError, "selfupdate/bad-max-bytes");
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.timeoutMs,
-    "selfUpdate.poll: opts.timeoutMs", SelfUpdateError, "selfupdate/bad-timeout");
+  validateOpts.shape(opts, {
+    releasesUrl: function (value) {
+      validateOpts.requireNonEmptyString(value,
+        "selfUpdate.poll: opts.releasesUrl", SelfUpdateError, "selfupdate/bad-releases-url");
+      // Scheme enforcement at config-time so the bug surfaces here, not
+      // inside the request loop. Default policy: https only. Operators
+      // wiring against an internal mirror can pass allowedProtocols
+      // explicitly to opt in to http (e.g. a TLS-terminating proxy
+      // upstream of the framework process). The full SSRF / hostname /
+      // length policy still runs inside httpClient.request.
+      var parsedProto;
+      try { parsedProto = new NodeUrl(value).protocol; }
+      catch (_e) {
+        throw new SelfUpdateError("selfupdate/bad-releases-url",
+          "selfUpdate.poll: opts.releasesUrl is not parseable as a URL");
+      }
+      var allowedProtocols = Array.isArray(opts.allowedProtocols) && opts.allowedProtocols.length > 0
+        ? opts.allowedProtocols.slice() : ["https:"];
+      if (allowedProtocols.indexOf(parsedProto) === -1) {
+        throw new SelfUpdateError("selfupdate/bad-releases-url",
+          "selfUpdate.poll: opts.releasesUrl protocol '" + parsedProto +
+          "' not in allowedProtocols [" + allowedProtocols.join(", ") + "]");
+      }
+    },
+    currentVersion: { rule: "required-string", code: "selfupdate/bad-current-version",
+                      label: "selfUpdate.poll: opts.currentVersion" },
+    assetPattern: function (value) {
+      if (value !== undefined && !(value instanceof RegExp) && typeof value !== "string") {
+        throw new SelfUpdateError("selfupdate/bad-asset-pattern",
+          "selfUpdate.poll: opts.assetPattern must be a RegExp or string when present");
+      }
+    },
+    signaturePattern: function (value) {
+      if (value !== undefined && !(value instanceof RegExp) && typeof value !== "string") {
+        throw new SelfUpdateError("selfupdate/bad-sig-pattern",
+          "selfUpdate.poll: opts.signaturePattern must be a RegExp or string when present");
+      }
+    },
+    maxBytes: function (value) {
+      numericBounds.requirePositiveFiniteIntIfPresent(value,
+        "selfUpdate.poll: opts.maxBytes", SelfUpdateError, "selfupdate/bad-max-bytes");
+    },
+    timeoutMs: function (value) {
+      numericBounds.requirePositiveFiniteIntIfPresent(value,
+        "selfUpdate.poll: opts.timeoutMs", SelfUpdateError, "selfupdate/bad-timeout");
+    },
+    // allowedProtocols is consumed locally (the releasesUrl scheme gate
+    // above reads it) and also forwarded to httpClient.request.
+    allowedProtocols: { rule: "optional-string-array", code: "selfupdate/bad-allowed-protocols",
+                        label: "selfUpdate.poll: opts.allowedProtocols" },
+    // headers is merged onto the outbound request headers locally.
+    headers:          { rule: "optional-plain-object", code: "selfupdate/bad-headers",
+                        label: "selfUpdate.poll: opts.headers" },
+    // etag is used locally for the If-None-Match request header.
+    etag:             { rule: "optional-string", code: "selfupdate/bad-etag",
+                        label: "selfUpdate.poll: opts.etag" },
+    // allowedHosts / allowInternal are forwarded verbatim to
+    // httpClient.request, which owns their SSRF-gate validation.
+  }, "selfUpdate.poll", SelfUpdateError, "selfupdate/bad-opts",
+  { allow: ["allowedHosts", "allowInternal"] });
 }
 
 function _matchAsset(name, pattern, fallback) {
@@ -461,21 +476,25 @@ async function poll(opts) {
 // ---- verify ----
 
 function _validateVerifyOpts(opts) {
-  validateOpts.requireObject(opts, "selfUpdate.verify", SelfUpdateError, "selfupdate/bad-opts");
-  validateOpts.requireNonEmptyString(opts.assetPath,
-    "selfUpdate.verify: opts.assetPath", SelfUpdateError, "selfupdate/bad-asset-path");
-  validateOpts.requireNonEmptyString(opts.signaturePath,
-    "selfUpdate.verify: opts.signaturePath", SelfUpdateError, "selfupdate/bad-signature-path");
-  validateOpts.requireNonEmptyString(opts.pubkeyPem,
-    "selfUpdate.verify: opts.pubkeyPem (PEM-encoded public key)",
-    SelfUpdateError, "selfupdate/bad-pubkey");
-  if (opts.hashAlgo !== undefined &&
-      (typeof opts.hashAlgo !== "string" || ALLOWED_HASH_ALGS.indexOf(opts.hashAlgo) === -1)) {
-    throw new SelfUpdateError("selfupdate/bad-hash-algo",
-      "selfUpdate.verify: opts.hashAlgo must be one of " + ALLOWED_HASH_ALGS.join(", "));
-  }
-  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxBytes,
-    "selfUpdate.verify: opts.maxBytes", SelfUpdateError, "selfupdate/bad-max-bytes");
+  validateOpts.shape(opts, {
+    assetPath:     { rule: "required-string", code: "selfupdate/bad-asset-path",
+                     label: "selfUpdate.verify: opts.assetPath" },
+    signaturePath: { rule: "required-string", code: "selfupdate/bad-signature-path",
+                     label: "selfUpdate.verify: opts.signaturePath" },
+    pubkeyPem:     { rule: "required-string", code: "selfupdate/bad-pubkey",
+                     label: "selfUpdate.verify: opts.pubkeyPem (PEM-encoded public key)" },
+    hashAlgo:      function (value) {
+      if (value !== undefined &&
+          (typeof value !== "string" || ALLOWED_HASH_ALGS.indexOf(value) === -1)) {
+        throw new SelfUpdateError("selfupdate/bad-hash-algo",
+          "selfUpdate.verify: opts.hashAlgo must be one of " + ALLOWED_HASH_ALGS.join(", "));
+      }
+    },
+    maxBytes:      function (value) {
+      numericBounds.requirePositiveFiniteIntIfPresent(value,
+        "selfUpdate.verify: opts.maxBytes", SelfUpdateError, "selfupdate/bad-max-bytes");
+    },
+  }, "selfUpdate.verify", SelfUpdateError, "selfupdate/bad-opts");
 }
 
 /**
@@ -565,15 +584,19 @@ async function verify(opts) {
 // ---- swap ----
 
 function _validateSwapOpts(opts, label) {
-  validateOpts.requireObject(opts, "selfUpdate." + label, SelfUpdateError, "selfupdate/bad-opts");
+  // requireObject runs first (shape does it) so an opts-shape error keeps
+  // the selfupdate/bad-opts code. `from` is validated only for swap, and
+  // first to preserve the original field-evaluation order.
+  var schema = {};
   if (label === "swap") {
-    validateOpts.requireNonEmptyString(opts.from,
-      "selfUpdate.swap: opts.from", SelfUpdateError, "selfupdate/bad-from");
+    schema.from = { rule: "required-string", code: "selfupdate/bad-from",
+                    label: "selfUpdate.swap: opts.from" };
   }
-  validateOpts.requireNonEmptyString(opts.to,
-    "selfUpdate." + label + ": opts.to", SelfUpdateError, "selfupdate/bad-to");
-  validateOpts.requireNonEmptyString(opts.backupTo,
-    "selfUpdate." + label + ": opts.backupTo", SelfUpdateError, "selfupdate/bad-backup");
+  schema.to       = { rule: "required-string", code: "selfupdate/bad-to",
+                      label: "selfUpdate." + label + ": opts.to" };
+  schema.backupTo = { rule: "required-string", code: "selfupdate/bad-backup",
+                      label: "selfUpdate." + label + ": opts.backupTo" };
+  validateOpts.shape(opts, schema, "selfUpdate." + label, SelfUpdateError, "selfupdate/bad-opts");
 }
 
 // _safeRollback — best-effort restore of `to` from `backupTo` during

package/lib/vendor/blamejs/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,