@webdecoy/fcaptcha 1.34.1 → 1.36.0

package/engine.js

@@ -495,7 +495,10 @@ function detectCDP(signals) {
   if (env.cdpRuntime && env.cdpRuntime.consoleAttached) {
     detections.push({
       category: 'cdp', score: 0.6, confidence: 0.5,
-      reason: 'CDP/DevTools console consumer attached (automation protocol or open DevTools)'
+      reason: 'CDP/DevTools console consumer attached (automation protocol or open DevTools)',
+      // A developer with DevTools open produces exactly this signal, so it
+      // cannot be one of the independent views the corroboration floor counts.
+      nonCorroborating: true
     });
   }
 
@@ -912,33 +915,47 @@ function applyDispositiveFloor(score, detections) {
  * product. It treats absence of environmental evidence as evidence of absence — but
  * on this adversary a clean environment is the attack working, not innocence.
  *
- * The rule: when two or more behavioural categories independently reach 0.5, floor
- * the score at 0.6.
+ * The rule: when two or more behavioural categories independently reach 0.4, floor
+ * the score at 0.6. A signal a developer's own tooling produces is not an
+ * independent view: the DevTools console-attach probe is marked nonCorroborating,
+ * so it still scores but cannot be one of the two that agree.
  *
  * Constants swept over a 40-point grid against the labelled corpus
  * (bench/tools/sweep-corroboration.js), not reasoned about. No human in the
  * 126-sample panel reaches two agreeing behavioural categories at any threshold
- * tested, while 66 of 75 agents do at 0.5. Requiring three fails outright — all
- * sixteen such combinations leave the adversary allowed. The floor value does not
- * affect separation, so 0.6 is a policy choice: the block boundary, kept distinct
- * from the 0.9 reserved for a browser that declares its own automation.
+ * tested, and 0.3, 0.4 and 0.5 catch the same 66 of 75 agents. The bar moved from
+ * 0.5 to 0.4 on a live measurement the corpus cannot make (2026-09-09): an
+ * extension-driven click in a real Chrome on the public demo scored vision_ai 0.40
+ * and behavioral 0.44 with every environmental category clean — weighted sum
+ * 0.189, allowed at 0.5, floored at 0.4. The exclusion is what keeps the lower
+ * bar honest: the human-looking sessions beside it sat at behavioral 0.37 with cdp
+ * 0.30 from the console probe alone. Requiring three fails outright — all sixteen
+ * such combinations leave the adversary allowed. The floor value does not affect
+ * separation, so 0.6 is a policy choice: the block boundary, kept distinct from
+ * the 0.9 reserved for a browser that declares its own automation.
  *
  * Caveat: the adversary is one synthetic, hand-authored sample. This shows the
  * arithmetic works on the shape the corpus describes, not that it works on a real
  * source-patched browser.
  */
-const CORROBORATION_AGREE_AT = 0.5;
+const CORROBORATION_AGREE_AT = 0.4;
 const CORROBORATION_MIN_AGREE = 2;
 const CORROBORATION_FLOOR = 0.6;
+// Absorbs the few ulps a noisy-OR product lands from a round number (0.75×0.8 is
+// 0.3999999999999999, not 0.4), so agreement does not depend on arithmetic order.
+const CORROBORATION_EPSILON = 1e-9;
 
 // Categories a browser trips by how it moves rather than by what it is. A
 // patched binary can hide what it is; it cannot hide that nothing is moving the
 // pointer like a hand.
 const BEHAVIOURAL_CATEGORIES = ['vision_ai', 'behavioral', 'automation', 'cdp'];
 
-function applyCorroborationFloor(score, categoryScores) {
+function applyCorroborationFloor(score, detections) {
+  // Only independent views count. A signal that a developer's own tooling
+  // produces (nonCorroborating) still scores, but cannot be one of the two.
+  const categoryScores = calculateCategoryScores(detections.filter((d) => !d.nonCorroborating));
   const agreeing = BEHAVIOURAL_CATEGORIES
-    .filter((c) => (categoryScores[c] || 0) >= CORROBORATION_AGREE_AT).length;
+    .filter((c) => (categoryScores[c] || 0) >= CORROBORATION_AGREE_AT - CORROBORATION_EPSILON).length;
   return agreeing >= CORROBORATION_MIN_AGREE ? Math.max(score, CORROBORATION_FLOOR) : score;
 }
 

package/fingerprint-store.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const { BoundedMap } = require('./limits');
+
+const WINDOW_MS = 15 * 60 * 1000;
+// Detectors only distinguish >5 and >10. Saturating at 16 preserves those
+// decisions without retaining every attacker-selected value.
+const MAX_MEMBERS = 16;
+
+class FingerprintStore {
+  constructor({ maxEntries = 100000, ttlMs = WINDOW_MS, now = Date.now } = {}) {
+    this.fingerprints = new BoundedMap(maxEntries);
+    this.ipFingerprints = new BoundedMap(maxEntries);
+    this.ttlMs = ttlMs;
+    this.now = now;
+  }
+
+  _get(store, key) {
+    const entry = store.get(key);
+    if (entry && entry.expiresAt <= this.now()) {
+      store.delete(key);
+      return undefined;
+    }
+    return entry;
+  }
+
+  _add(store, key, value) {
+    let entry = this._get(store, key);
+    if (!entry) {
+      entry = { values: new Set(), expiresAt: this.now() + this.ttlMs };
+      store.set(key, entry);
+    }
+    if (entry.values.size < MAX_MEMBERS) entry.values.add(value);
+  }
+
+  record(fp, ip, siteKey) {
+    const entry = this._get(this.ipFingerprints, ip);
+    // Do not allocate more fingerprint keys once this source has saturated.
+    if (entry && entry.values.size >= MAX_MEMBERS && !entry.values.has(fp)) return;
+    this._add(this.ipFingerprints, ip, fp);
+    this._add(this.fingerprints, `${siteKey}:${fp}`, ip);
+  }
+
+  getIpFpCount(ip) {
+    return this._get(this.ipFingerprints, ip)?.values.size || 0;
+  }
+
+  getFpIpCount(fp, siteKey) {
+    return this._get(this.fingerprints, `${siteKey}:${fp}`)?.values.size || 0;
+  }
+}
+
+module.exports = { FingerprintStore, WINDOW_MS, MAX_MEMBERS };

package/index.js

@@ -6,7 +6,7 @@
  * Usage:
  *   const fcaptcha = require('@webdecoy/fcaptcha');
  *   const engine = fcaptcha.createScoringEngine({ secret: 'your-secret' });
- *   const result = engine.verify(signals, ip, siteKey, userAgent, headers, powSolution);
+ *   const result = engine.verify(signals, ip, siteKey, userAgent, headers, powSolution, signalsJson, powTiming);
  */
 
 const crypto = require('crypto');
@@ -14,6 +14,10 @@ const detection = require('./detection');
 const { ProxyTrust, networkIdentity } = require('./clientip');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
 const { signingSecret } = require('./config');
+const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
+const { FingerprintStore } = require('./fingerprint-store');
+const { TokenStore } = require('./token-store');
+const { resolveSignals } = require('./protocol');
 
 // =============================================================================
 // PoW Challenge Store (can be extended with Redis)
@@ -22,8 +26,8 @@ const { signingSecret } = require('./config');
 class PoWChallengeStore {
   constructor(options = {}) {
     this.secret = signingSecret(options.secret);
-    this.challenges = new Map();
-    this.usedSolutions = new Set();
+    this.challenges = new BoundedMap();
+    this.usedSolutions = new BoundedSet();
     this.expirationMs = options.expirationMs || 5 * 60 * 1000; // 5 minutes
   }
 
@@ -41,6 +45,7 @@ class PoWChallengeStore {
       // How long the client must hold this challenge before submitting a
       // solution. Inside the signed payload so it cannot be talked down.
       minAgeMs,
+      nonce: crypto.randomBytes(16).toString('hex'),
       prefix: `${challengeId}:${timestamp}:${difficulty}`
     };
 
@@ -64,7 +69,7 @@ class PoWChallengeStore {
     return challengeData;
   }
 
-  verify(challengeId, nonce, hash, siteKey, ip) {
+  verify(challengeId, nonce, hash, siteKey, ip, signalsHash = null) {
     const challenge = this.challenges.get(challengeId);
 
     if (!challenge) {
@@ -91,7 +96,7 @@ class PoWChallengeStore {
     }
 
     // Verify the hash
-    const input = `${challenge.prefix}:${nonce}`;
+    const input = signalsHash ? `${challenge.prefix}:${signalsHash}:${nonce}` : `${challenge.prefix}:${nonce}`;
     const expectedHash = crypto.createHash('sha256').update(input).digest('hex');
 
     if (hash !== expectedHash) {
@@ -111,6 +116,7 @@ class PoWChallengeStore {
     return {
       valid: true,
       difficulty: challenge.difficulty,
+      nonce: challenge.nonce,
       serverElapsed: Date.now() - challenge.timestamp,
       // Fall back for challenges issued before adaptive cost existed.
       minAgeMs: challenge.minAgeMs || BASE_MIN_AGE_MS
@@ -124,9 +130,6 @@ class PoWChallengeStore {
         this.challenges.delete(id);
       }
     }
-    if (this.usedSolutions.size > 10000) {
-      this.usedSolutions.clear();
-    }
   }
 }
 
@@ -136,7 +139,7 @@ class PoWChallengeStore {
 
 class RateLimiter {
   constructor() {
-    this.requests = new Map();
+    this.requests = new BoundedMap();
   }
 
   check(key, windowSeconds = 60, maxRequests = 10) {
@@ -157,42 +160,6 @@ class RateLimiter {
   }
 }
 
-// =============================================================================
-// Fingerprint Store
-// =============================================================================
-
-class FingerprintStore {
-  constructor() {
-    this.fingerprints = new Map();
-    this.ipFingerprints = new Map();
-  }
-
-  record(fp, ip, siteKey) {
-    const key = `${siteKey}:${fp}`;
-
-    if (!this.fingerprints.has(key)) {
-      this.fingerprints.set(key, { count: 0, ips: new Set() });
-    }
-    const data = this.fingerprints.get(key);
-    data.count++;
-    data.ips.add(ip);
-
-    if (!this.ipFingerprints.has(ip)) {
-      this.ipFingerprints.set(ip, new Set());
-    }
-    this.ipFingerprints.get(ip).add(fp);
-  }
-
-  getIpFpCount(ip) {
-    return this.ipFingerprints.get(ip)?.size || 0;
-  }
-
-  getFpIpCount(fp, siteKey) {
-    const key = `${siteKey}:${fp}`;
-    return this.fingerprints.get(key)?.ips.size || 0;
-  }
-}
-
 // =============================================================================
 // Scoring Engine
 // =============================================================================
@@ -231,6 +198,7 @@ class ScoringEngine {
     this.fingerprintStore = options.fingerprintStore || new FingerprintStore();
     this.suspicion = options.suspicion || new SuspicionLedger();
     this.weights = options.weights || WEIGHTS;
+    this.tokenStore = options.tokenStore || new TokenStore();
   }
 
   // Generate a PoW challenge
@@ -257,8 +225,16 @@ class ScoringEngine {
   }
 
   // Verify signals and return score
-  verify(signals, ip, siteKey, userAgent, headers = {}, powSolution = null) {
+  verify(signals, ip, siteKey, userAgent, headers = {}, powSolution = null, signalsJson = null, powTiming = null) {
+    const resolved = resolveSignals(signals, signalsJson, powSolution?.signalsHash);
+    signals = resolved.signals;
+    if (powTiming) {
+      signals.temporal = signals.temporal || {};
+      signals.temporal.pow = powTiming;
+    }
     const detections = [];
+    if (!resolved.commitmentValid) detections.push({ category: 'bot', score: 0.95,
+      confidence: 0.95, reason: 'Signals tampered after PoW (signalsHash mismatch)' });
     let powSatisfied = false;
 
     // Run all detection modules
@@ -288,7 +264,8 @@ class ScoringEngine {
         powSolution.nonce,
         powSolution.hash,
         siteKey,
-        ip
+        ip,
+        powSolution.signalsHash
       );
 
       if (!powResult.valid) {
@@ -299,7 +276,7 @@ class ScoringEngine {
           reason: `PoW verification failed: ${powResult.reason}`
         });
       } else if (powResult.serverElapsed < BASE_MIN_AGE_MS) {
-        powSatisfied = true;
+        powSatisfied = false;
         // Under the universal baseline nothing legitimate can have happened —
         // no human completes an interaction that fast.
         detections.push({
@@ -309,11 +286,9 @@ class ScoringEngine {
           reason: `Challenge solved too fast (${powResult.serverElapsed}ms server-side)`
         });
       } else if (powResult.serverElapsed < powResult.minAgeMs) {
-        powSatisfied = true;
-        // Between the baseline and this source's own elevated floor is weaker
-        // evidence: a client predating adaptive cost, or one served from a
-        // stale cache, does not know to wait. It contributes rather than
-        // deciding.
+        powSatisfied = false;
+        // Keep the diagnostic weaker than a baseline violation; token issuance
+        // independently requires the full advertised delay.
         detections.push({
           category: 'bot',
           score: 0.5,
@@ -321,7 +296,13 @@ class ScoringEngine {
           reason: `Challenge submitted before the required delay for this source (${powResult.serverElapsed}ms of ${powResult.minAgeMs}ms)`
         });
       } else {
-        powSatisfied = true;
+        powSatisfied = resolved.commitmentValid;
+      }
+      // The server-issued nonce is required even for legacy, uncommitted PoW.
+      if (powResult.valid && powResult.nonce && signals.meta?.challengeNonce !== powResult.nonce) {
+        powSatisfied = false;
+        detections.push({ category: 'bot', score: 0.9, confidence: 0.9,
+          reason: 'Challenge nonce mismatch (signals not bound to challenge)' });
       }
     } else {
       detections.push({
@@ -364,7 +345,7 @@ class ScoringEngine {
     const categoryScores = calculateCategoryScores(detections, this.weights);
     const finalScore = applyCorroborationFloor(
       applyDispositiveFloor(calculateFinalScore(categoryScores, this.weights), detections),
-      categoryScores
+      detections
     );
 
     let recommendation;
@@ -397,7 +378,7 @@ class ScoringEngine {
   }
 
   // Verify a previously issued token
-  verifyToken(token) {
+  verifyToken(token, ip = null) {
     try {
       const decoded = JSON.parse(Buffer.from(token, 'base64url').toString());
 
@@ -415,14 +396,22 @@ class ScoringEngine {
         return { valid: false, reason: 'invalid_signature' };
       }
 
+      if (ip && decoded.ip_hash !== crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8)) {
+        return { valid: false, reason: 'ip_mismatch' };
+      }
+      const claim = this.tokenStore.claim(sig);
+      if (!claim.claimed) return { valid: false, reason: claim.reason };
       return {
         valid: true,
         site_key: decoded.site_key,
         timestamp: decoded.timestamp,
-        score: decoded.score
+        score: decoded.score,
+        hostname: decoded.hostname || '',
+        action: decoded.action || '',
+        cdata: decoded.cdata || ''
       };
     } catch (e) {
-      return { valid: false, reason: e.message };
+      return { valid: false, reason: 'invalid_token' };
     }
   }
 
@@ -497,6 +486,7 @@ class ScoringEngine {
     const ipHash = crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8);
     const data = {
       site_key: siteKey,
+      jti: crypto.randomBytes(16).toString('hex'),
       timestamp: Math.floor(Date.now() / 1000),
       score: Math.round(score * 1000) / 1000,
       ip_hash: ipHash
@@ -516,6 +506,7 @@ class ScoringEngine {
 
 function createMiddleware(options = {}) {
   const engine = new ScoringEngine(options);
+  const siteKeys = SiteKeyGuard.fromEnv();
   const proxyTrust = options.trustedProxies !== undefined
     ? new ProxyTrust(options.trustedProxies)
     : ProxyTrust.fromEnv();
@@ -533,8 +524,9 @@ function createMiddleware(options = {}) {
 
     // Challenge route handler
     challengeHandler: (req, res) => {
-      const siteKey = req.query.siteKey || 'default';
+      const rawSiteKey = req.query.siteKey || 'default';
       const ip = options.getIP ? options.getIP(req) : proxyTrust.clientIP(req);
+      const siteKey = siteKeys.normalize(rawSiteKey, ip);
       const challenge = engine.generateChallenge(siteKey, ip);
 
       res.json({
@@ -542,14 +534,17 @@ function createMiddleware(options = {}) {
         prefix: challenge.prefix,
         difficulty: challenge.difficulty,
         expiresAt: challenge.expiresAt,
-        sig: challenge.sig
+        sig: challenge.sig,
+        nonce: challenge.nonce,
+        minAgeMs: challenge.minAgeMs
       });
     },
 
     // Verify route handler
     verifyHandler: (req, res) => {
-      const { siteKey, signals, powSolution } = req.body;
+      const { siteKey: rawSiteKey, signals, powSolution, signalsJson, powTiming } = req.body;
       const ip = options.getIP ? options.getIP(req) : proxyTrust.clientIP(req);
+      const siteKey = siteKeys.normalize(rawSiteKey || 'default', ip);
       const userAgent = req.headers['user-agent'] || '';
 
       const headers = {};
@@ -557,14 +552,14 @@ function createMiddleware(options = {}) {
         headers[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
       }
 
-      const result = engine.verify(signals, ip, siteKey, userAgent, headers, powSolution);
+      const result = engine.verify(signals, ip, siteKey, userAgent, headers, powSolution, signalsJson, powTiming);
       res.json(result);
     },
 
     // Token verify route handler
     tokenVerifyHandler: (req, res) => {
-      const { token } = req.body;
-      res.json(engine.verifyToken(token));
+      const { token, remoteip } = req.body;
+      res.json(engine.verifyToken(token, typeof remoteip === 'string' ? remoteip : null));
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.34.1",
+  "version": "1.36.0",
   "description": "Open source CAPTCHA with PoW, bot detection, and Vision AI protection",
   "main": "index.js",
   "exports": {
@@ -15,7 +15,7 @@
     "test:clientip": "node clientip.test.js",
     "test:limits": "node limits.test.js",
     "test:detection": "node detection.test.js",
-    "test": "node version.test.js && node config.test.js && node clientip.test.js && node limits.test.js && node detection.test.js && node inputforensics.test.js && node interactionmode.test.js && node exemptions.test.js && node webbotauth.test.js && node siteverify.test.js && node redis-state.test.js && node index.test.js && node --test suspicion.test.js",
+    "test": "node version.test.js && node config.test.js && node clientip.test.js && node limits.test.js && node detection.test.js && node inputforensics.test.js && node interactionmode.test.js && node exemptions.test.js && node webbotauth.test.js && node siteverify.test.js && node redis-state.test.js && node index.test.js && node --test suspicion.test.js security.test.js corroboration.test.js",
     "test:siteverify": "node siteverify.test.js",
     "test:forensics": "node inputforensics.test.js",
     "test:suspicion": "node --test suspicion.test.js"

package/protocol.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function invalidRequest() {
+  return Object.assign(new Error('invalid_request'), { status: 400 });
+}
+
+// Resolve the exact bytes committed by the proof before any detector mutates
+// signals. Legacy proofs without a commitment still use the signals object.
+function resolveSignals(signals, signalsJson, signalsHash) {
+  let commitmentValid = true;
+  if (signalsHash) {
+    if (typeof signalsJson !== 'string' || typeof signalsHash !== 'string') {
+      commitmentValid = false;
+    } else {
+      commitmentValid = crypto.createHash('sha256').update(signalsJson).digest('hex') === signalsHash;
+      try { signals = JSON.parse(signalsJson); } catch { throw invalidRequest(); }
+    }
+  }
+  if (!isObject(signals)) throw invalidRequest();
+  for (const key of ['behavioral', 'environmental', 'temporal', 'meta', 'formAnalysis']) {
+    if (signals[key] != null && !isObject(signals[key])) throw invalidRequest();
+  }
+  return { signals, commitmentValid };
+}
+
+module.exports = { resolveSignals, isObject, invalidRequest };

package/redis-state.js

@@ -38,6 +38,16 @@ redis.call('PEXPIRE', KEYS[1], ARGV[3])
 return 1
 `;
 
+const RECORD_FINGERPRINT = `
+if redis.call('SCARD', KEYS[2]) >= 16 and redis.call('SISMEMBER', KEYS[2], ARGV[2]) == 0 then return 0 end
+if redis.call('SCARD', KEYS[1]) < 16 then redis.call('SADD', KEYS[1], ARGV[1]) end
+if redis.call('SCARD', KEYS[2]) < 16 then redis.call('SADD', KEYS[2], ARGV[2]) end
+for i = 1, 2 do
+  if redis.call('PTTL', KEYS[i]) < 0 then redis.call('PEXPIRE', KEYS[i], ARGV[3]) end
+end
+return 1
+`;
+
 class RedisState {
   constructor(url, client = null) {
     this.client = client || createClient({ url });
@@ -148,10 +158,10 @@ class RedisState {
   async recordFingerprint(fingerprint, ip, siteKey) {
     const fpKey = this.opaqueKey('fingerprint:ips', `${siteKey}|${fingerprint}`);
     const ipKey = this.opaqueKey('fingerprint:fps', ip);
-    await this.client.multi()
-      .sAdd(fpKey, this.opaqueKey('value:ip', ip)).pExpire(fpKey, DETECTION_TTL_MS)
-      .sAdd(ipKey, this.opaqueKey('value:fp', fingerprint)).pExpire(ipKey, DETECTION_TTL_MS)
-      .exec();
+    await this.client.eval(RECORD_FINGERPRINT, {
+      keys: [fpKey, ipKey],
+      arguments: [this.opaqueKey('value:ip', ip), this.opaqueKey('value:fp', fingerprint), String(DETECTION_TTL_MS)]
+    });
   }
 
   async ipFingerprintCount(ip) {

package/server.js

@@ -16,6 +16,9 @@ const { signingSecretFromEnv } = require('./config');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
 const { detectInputForensics } = require('./inputforensics');
 const { RedisState } = require('./redis-state');
+const { FingerprintStore } = require('./fingerprint-store');
+const { TokenStore } = require('./token-store');
+const { resolveSignals, isObject, invalidRequest } = require('./protocol');
 const {
   HostnameAllowlist,
   IdempotencyStore,
@@ -283,7 +286,8 @@ const powChallengeStore = {
     }
 
     // Calculate server-side elapsed time (un-spoofable)
-    const serverElapsed = Date.now() - challenge.createdAt;
+    // timestamp is shared by all Redis writers; createdAt was Node-only.
+    const serverElapsed = Date.now() - challenge.timestamp;
 
     return {
       valid: true,
@@ -329,72 +333,22 @@ const rateLimiter = {
   }
 };
 
+const localFingerprintStore = new FingerprintStore();
 const fingerprintStore = {
-  fingerprints: new BoundedMap(),
-  ipFingerprints: new BoundedMap(),
-
   async record(fp, ip, siteKey) {
-    if (SHARED_STATE) {
-      try { await SHARED_STATE.recordFingerprint(fp, ip, siteKey); } catch (_) { /* reads fail closed */ }
-      return;
-    }
-    const key = `${siteKey}:${fp}`;
-
-    if (!this.fingerprints.has(key)) {
-      this.fingerprints.set(key, { count: 0, ips: new Set() });
-    }
-    const data = this.fingerprints.get(key);
-    data.count++;
-    data.ips.add(ip);
-
-    if (!this.ipFingerprints.has(ip)) {
-      this.ipFingerprints.set(ip, new Set());
-    }
-    this.ipFingerprints.get(ip).add(fp);
+    if (!SHARED_STATE) return localFingerprintStore.record(fp, ip, siteKey);
+    try { await SHARED_STATE.recordFingerprint(fp, ip, siteKey); } catch (_) { /* reads fail closed */ }
   },
-
   async getIpFpCount(ip) {
-    if (SHARED_STATE) {
-      try { return await SHARED_STATE.ipFingerprintCount(ip); } catch (_) { return 100; }
-    }
-    return this.ipFingerprints.get(ip)?.size || 0;
+    if (!SHARED_STATE) return localFingerprintStore.getIpFpCount(ip);
+    try { return await SHARED_STATE.ipFingerprintCount(ip); } catch (_) { return 100; }
   },
-
   async getFpIpCount(fp, siteKey) {
-    if (SHARED_STATE) {
-      try { return await SHARED_STATE.fingerprintIpCount(fp, siteKey); } catch (_) { return 100; }
-    }
-    const key = `${siteKey}:${fp}`;
-    return this.fingerprints.get(key)?.ips.size || 0;
-  }
-};
-
-// Token Store - prevents token replay attacks
-const tokenStore = {
-  usedTokens: new BoundedSet(),
-
-  // Mark a token as used (returns false if already used)
-  markUsed(tokenSig) {
-    if (this.usedTokens.has(tokenSig)) {
-      return false; // Already used
-    }
-    this.usedTokens.add(tokenSig);
-
-    // Cleanup old tokens periodically (tokens expire after 5 min anyway)
-    if (Math.random() < 0.1) this._cleanup();
-    return true;
-  },
-
-  isUsed(tokenSig) {
-    return this.usedTokens.has(tokenSig);
-  },
-
-  _cleanup() {
-    // In production with Redis, use TTL instead. In memory usedTokens is a
-    // BoundedSet, so it evicts its oldest entries rather than clearing wholesale
-    // — clearing would let an attacker who forced the threshold replay a token.
+    if (!SHARED_STATE) return localFingerprintStore.getFpIpCount(fp, siteKey);
+    try { return await SHARED_STATE.fingerprintIpCount(fp, siteKey); } catch (_) { return 100; }
   }
 };
+const tokenStore = new TokenStore();
 
 // Detection patterns, the pure detectors and the scoring aggregation now
 // live in engine.js, shared with the npm library entry point (index.js).
@@ -499,6 +453,7 @@ function generateToken(ip, siteKey, score, binding = {}) {
   const ipHash = crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8);
   const data = {
     site_key: siteKey,
+    jti: crypto.randomBytes(16).toString('hex'),
     timestamp: Math.floor(Date.now() / 1000),
     score: Math.round(score * 1000) / 1000,
     ip_hash: ipHash,
@@ -540,15 +495,15 @@ async function verifyToken(token, ip = null) {
       }
     }
 
-    let claimed;
+    let claim;
     try {
-      claimed = SHARED_STATE
-        ? await SHARED_STATE.claimToken(sig)
-        : tokenStore.markUsed(sig);
+      claim = SHARED_STATE
+        ? { claimed: await SHARED_STATE.claimToken(sig), reason: 'token_already_used' }
+        : tokenStore.claim(sig);
     } catch (_) {
       return { valid: false, reason: 'state_unavailable' };
     }
-    if (!claimed) return { valid: false, reason: 'token_already_used' };
+    if (!claim.claimed) return { valid: false, reason: claim.reason };
 
     // hostname/action/cdata default to '' so a token minted before they existed
     // still verifies and reports the same shape. The signature covers whatever
@@ -588,24 +543,12 @@ async function verifyWebBotAuth(req) {
 async function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash = null, powSolution = null, signalsJson = null, powTiming = null, preDetections = [], opts = {}) {
   const detections = Array.isArray(preDetections) ? [...preDetections] : [];
 
-  // Verify signal commitment (signalsJson hash must match powSolution.signalsHash)
   const clientSignalsHash = powSolution?.signalsHash || null;
-  if (signalsJson && clientSignalsHash) {
-    const computedHash = crypto.createHash('sha256').update(signalsJson).digest('hex');
-    if (computedHash !== clientSignalsHash) {
-      detections.push({
-        category: 'bot',
-        score: 0.95,
-        confidence: 0.95,
-        reason: 'Signals tampered after PoW (signalsHash mismatch)'
-      });
-    }
-    // Use signalsJson as the canonical signals source
-    try {
-      signals = JSON.parse(signalsJson);
-    } catch (e) {
-      // Fall back to parsed signals if signalsJson is invalid
-    }
+  const resolved = resolveSignals(signals, signalsJson, clientSignalsHash);
+  signals = resolved.signals;
+  if (!resolved.commitmentValid) {
+    detections.push({ category: 'bot', score: 0.95, confidence: 0.95,
+      reason: 'Signals tampered after PoW (signalsHash mismatch)' });
   }
 
   // Inject powTiming into signals.temporal.pow for detection functions
@@ -660,7 +603,8 @@ async function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja
         // replays a solution. All ordinary things that happen to real people.
       });
     } else {
-      powSatisfied = true;
+      powSatisfied = resolved.commitmentValid &&
+        powVerification.serverElapsed >= Math.max(BASE_MIN_AGE_MS, powVerification.minAgeMs || 0);
     }
 
     // Verify challenge nonce binding
@@ -692,9 +636,8 @@ async function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja
         reason: `Challenge solved too fast (${powVerification.serverElapsed}ms server-side)`
       });
     } else if (powValid && powVerification.serverElapsed < (powVerification.minAgeMs || BASE_MIN_AGE_MS)) {
-      // Between the baseline and this source's own elevated floor is weaker
-      // evidence: a client predating adaptive cost, or one served from a stale
-      // cache, does not know to wait. It contributes rather than deciding.
+      // Keep the diagnostic weaker than a baseline violation; token issuance
+      // independently requires the full advertised delay.
       detections.push({
         category: 'bot',
         score: 0.5,
@@ -785,7 +728,7 @@ async function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja
   const categoryScores = calculateCategoryScores(detections);
   const finalScore = applyCorroborationFloor(
     applyDispositiveFloor(calculateFinalScore(categoryScores), detections),
-    categoryScores
+    detections
   );
 
   let recommendation;
@@ -870,7 +813,18 @@ function collectHeaders(req) {
   return headers;
 }
 
-app.post('/api/verify', async (req, res) => {
+const asyncRoute = (handler) => (req, res, next) => Promise.resolve().then(() => handler(req, res)).catch(next);
+
+function validateScoringRequest(req, res, next) {
+  const body = req.body;
+  if (!isObject(body) || !isObject(body.signals) ||
+      (body.siteKey != null && typeof body.siteKey !== 'string') ||
+      (body.powSolution != null && !isObject(body.powSolution)) ||
+      (body.powTiming != null && !isObject(body.powTiming))) return next(invalidRequest());
+  next();
+}
+
+app.post('/api/verify', validateScoringRequest, asyncRoute(async (req, res) => {
   const { siteKey: rawSiteKey, signals, powSolution, signalsJson, powTiming, action, cdata } = req.body;
   const ip = PROXY_TRUST.clientIP(req);
   // Bound the state an unvalidated siteKey can allocate (limits.js).
@@ -890,9 +844,9 @@ app.post('/api/verify', async (req, res) => {
   const result = await runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming, webBotAuth, { peerTrusted, action, cdata, widgetInteraction: true });
   logVerdict('verify', siteKey, result);
   res.json(result);
-});
+}));
 
-app.post('/api/score', async (req, res) => {
+app.post('/api/score', validateScoringRequest, asyncRoute(async (req, res) => {
   const { siteKey: rawSiteKey, signals, action, cdata, powSolution, signalsJson, powTiming } = req.body;
   const ip = PROXY_TRUST.clientIP(req);
   const siteKey = await normalizeSiteKey(rawSiteKey, ip);
@@ -924,9 +878,9 @@ app.post('/api/score', async (req, res) => {
     // needs to know which precondition failed.
     ...(result.reason ? { reason: result.reason } : {})
   });
-});
+}));
 
-app.post('/api/token/verify', async (req, res) => {
+app.post('/api/token/verify', asyncRoute(async (req, res) => {
   const { token, secret, remoteip } = req.body;
 
   // The secret gate. This endpoint is the boundary between "a browser finished a
@@ -946,7 +900,7 @@ app.post('/api/token/verify', async (req, res) => {
   // received the token. Bind only when that trusted backend explicitly supplies
   // the visitor address; using the caller socket here compares unrelated hosts.
   res.json(await verifyToken(token, typeof remoteip === 'string' && remoteip ? remoteip : null));
-});
+}));
 
 // Turnstile / reCAPTCHA / hCaptcha drop-in compatibility.
 //
@@ -968,12 +922,13 @@ async function siteverifyHandler(req, res) {
   );
 }
 
-app.post('/turnstile/v0/siteverify', siteverifyHandler);
-app.post('/recaptcha/api/siteverify', siteverifyHandler);
-app.post('/siteverify', siteverifyHandler);
+app.post('/turnstile/v0/siteverify', asyncRoute(siteverifyHandler));
+app.post('/recaptcha/api/siteverify', asyncRoute(siteverifyHandler));
+app.post('/siteverify', asyncRoute(siteverifyHandler));
 
 // PoW Challenge endpoint - client fetches this on page load
-app.get('/api/pow/challenge', async (req, res) => {
+app.get('/api/pow/challenge', asyncRoute(async (req, res) => {
+  if (req.query.siteKey != null && typeof req.query.siteKey !== 'string') throw invalidRequest();
   const ip = PROXY_TRUST.clientIP(req);
   const siteKey = await normalizeSiteKey(req.query.siteKey, ip);
 
@@ -1007,7 +962,7 @@ app.get('/api/pow/challenge', async (req, res) => {
     // wait instead of as a worse score.
     minAgeMs: challenge.minAgeMs
   });
-});
+}));
 
 // Legacy challenge endpoint for backwards compatibility
 app.get('/api/challenge', (req, res) => {
@@ -1026,7 +981,8 @@ app.use((err, req, res, next) => {
   if (err && (err.status === 413 || err.type === 'entity.too.large')) {
     return res.status(413).json({ error: 'request_too_large' });
   }
-  return next(err);
+  const status = err && err.status === 400 ? 400 : 500;
+  res.status(status).json({ error: status === 400 ? 'invalid_request' : 'internal_error' });
 });
 
 // =============================================================================
@@ -1035,15 +991,19 @@ app.use((err, req, res, next) => {
 
 async function start() {
   if (SHARED_STATE) await SHARED_STATE.connect();
-  app.listen(PORT, () => {
-    console.log(`FCaptcha server running on port ${PORT}`);
+  const server = app.listen(PORT, () => {
+    console.log(`FCaptcha server running on port ${server.address().port}`);
     console.log(`Trusted proxies: ${PROXY_TRUST.describe()}`);
     console.log(`Site keys: ${SITE_KEYS.describe()}`);
     console.log(`Shared state: ${SHARED_STATE ? 'Redis (PoW)' : 'in-memory'}`);
   });
+  return server;
 }
 
-start().catch((err) => {
-  console.error(`FCaptcha failed to start: ${err.message}`);
-  process.exit(1);
-});
+if (require.main === module) {
+  start().catch((err) => {
+    console.error(`FCaptcha failed to start: ${err.message}`);
+    process.exit(1);
+  });
+}
+module.exports = { app, start };

package/siteverify.js

@@ -79,6 +79,7 @@ const ERROR_CODES = {
 const REASON_TO_ERROR_CODE = {
   expired: ERROR_CODES.TIMEOUT_OR_DUPLICATE,
   token_already_used: ERROR_CODES.TIMEOUT_OR_DUPLICATE,
+  token_store_full: ERROR_CODES.INTERNAL_ERROR,
   invalid_signature: ERROR_CODES.INVALID_RESPONSE,
   invalid_encoding: ERROR_CODES.INVALID_RESPONSE,
   invalid_json: ERROR_CODES.INVALID_RESPONSE,

package/token-store.js

@@ -0,0 +1,32 @@
+'use strict';
+
+// Spent tokens must not be evicted while they can still verify. If capacity is
+// exhausted, refuse new claims rather than reopening replay of older tokens.
+class TokenStore {
+  constructor({ maxEntries = 100000, now = Date.now } = {}) {
+    this.entries = new Map();
+    this.maxEntries = maxEntries;
+    this.now = now;
+    this.nextCleanup = 0;
+  }
+
+  markUsed(signature) {
+    return this.claim(signature).claimed;
+  }
+
+  claim(signature) {
+    const now = this.now();
+    if (now >= this.nextCleanup) {
+      for (const [key, expiresAt] of this.entries) {
+        if (expiresAt <= now) this.entries.delete(key);
+      }
+      this.nextCleanup = now + 60000;
+    }
+    if (this.entries.has(signature)) return { claimed: false, reason: 'token_already_used' };
+    if (this.entries.size >= this.maxEntries) return { claimed: false, reason: 'token_store_full' };
+    this.entries.set(signature, now + 10 * 60 * 1000);
+    return { claimed: true };
+  }
+}
+
+module.exports = { TokenStore };