@webdecoy/fcaptcha 1.20.0 → 1.21.0

package/index.js

@@ -12,6 +12,7 @@
 const crypto = require('crypto');
 const detection = require('./detection');
 const { ProxyTrust } = require('./clientip');
+const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
 
 // =============================================================================
 // PoW Challenge Store (can be extended with Redis)
@@ -25,7 +26,7 @@ class PoWChallengeStore {
     this.expirationMs = options.expirationMs || 5 * 60 * 1000; // 5 minutes
   }
 
-  generate(siteKey, ip, difficulty = 4) {
+  generate(siteKey, ip, difficulty = 4, minAgeMs = BASE_MIN_AGE_MS) {
     const challengeId = crypto.randomBytes(16).toString('hex');
     const timestamp = Date.now();
     const expiresAt = timestamp + this.expirationMs;
@@ -36,14 +37,16 @@ class PoWChallengeStore {
       timestamp,
       expiresAt,
       difficulty,
+      // How long the client must hold this challenge before submitting a
+      // solution. Inside the signed payload so it cannot be talked down.
+      minAgeMs,
       prefix: `${challengeId}:${timestamp}:${difficulty}`
     };
 
     // Sign the challenge
     const sig = crypto.createHmac('sha256', this.secret)
       .update(JSON.stringify(challengeData))
-      .digest('hex')
-      .slice(0, 16);
+      .digest('hex');
 
     challengeData.sig = sig;
 
@@ -100,7 +103,13 @@ class PoWChallengeStore {
     this.usedSolutions.add(solutionKey);
     this.challenges.delete(challengeId);
 
-    return { valid: true, difficulty: challenge.difficulty };
+    return {
+      valid: true,
+      difficulty: challenge.difficulty,
+      serverElapsed: Date.now() - challenge.timestamp,
+      // Fall back for challenges issued before adaptive cost existed.
+      minAgeMs: challenge.minAgeMs || BASE_MIN_AGE_MS
+    };
   }
 
   _cleanup() {
@@ -207,29 +216,31 @@ class ScoringEngine {
     this.powStore = options.powStore || new PoWChallengeStore({ secret: this.secret });
     this.rateLimiter = options.rateLimiter || new RateLimiter();
     this.fingerprintStore = options.fingerprintStore || new FingerprintStore();
+    this.suspicion = options.suspicion || new SuspicionLedger();
     this.weights = options.weights || WEIGHTS;
   }
 
   // Generate a PoW challenge
   generateChallenge(siteKey, ip, options = {}) {
+    // See suspicion.js for why the escalation lands almost entirely on
+    // minAgeMs rather than on difficulty.
     let difficulty = options.difficulty || 4;
+    let minAgeMs = BASE_MIN_AGE_MS;
 
     if (options.scaleByReputation !== false) {
-      if (detection.isDatacenterIP(ip)) {
-        difficulty = Math.max(difficulty, 5);
-      }
-
       const rateKey = `pow:${siteKey}:${ip}`;
       const [exceeded, count] = this.rateLimiter.check(rateKey, 60, 20);
-      if (count > 10) {
-        difficulty = Math.min(6, difficulty + 1);
-      }
-      if (exceeded) {
-        difficulty = 6;
-      }
+      const cost = computeChallengeCost(
+        this.suspicion.count(siteKey, ip),
+        detection.isDatacenterIP(ip),
+        count,
+        exceeded
+      );
+      difficulty = Math.max(difficulty, cost.difficulty);
+      minAgeMs = cost.minAgeMs;
     }
 
-    return this.powStore.generate(siteKey, ip, difficulty);
+    return this.powStore.generate(siteKey, ip, difficulty, minAgeMs);
   }
 
   // Verify signals and return score
@@ -260,6 +271,26 @@ class ScoringEngine {
           confidence: 0.8,
           reason: `PoW verification failed: ${powResult.reason}`
         });
+      } else if (powResult.serverElapsed < BASE_MIN_AGE_MS) {
+        // Under the universal baseline nothing legitimate can have happened —
+        // no human completes an interaction that fast.
+        detections.push({
+          category: 'bot',
+          score: 0.8,
+          confidence: 0.85,
+          reason: `Challenge solved too fast (${powResult.serverElapsed}ms server-side)`
+        });
+      } else if (powResult.serverElapsed < powResult.minAgeMs) {
+        // 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.
+        detections.push({
+          category: 'bot',
+          score: 0.5,
+          confidence: 0.5,
+          reason: `Challenge submitted before the required delay for this source (${powResult.serverElapsed}ms of ${powResult.minAgeMs}ms)`
+        });
       }
     } else {
       detections.push({
@@ -308,6 +339,10 @@ class ScoringEngine {
     const success = finalScore < 0.5;
     const token = success ? this._generateToken(ip, siteKey, finalScore) : null;
 
+    // Feed the ledger so the next challenge this source asks for is priced on
+    // what it just did.
+    this.suspicion.record(siteKey, ip, finalScore);
+
     return {
       success,
       score: finalScore,
@@ -332,7 +367,7 @@ class ScoringEngine {
       delete decoded.sig;
 
       const payload = JSON.stringify(decoded, Object.keys(decoded).sort());
-      const expectedSig = crypto.createHmac('sha256', this.secret).update(payload).digest('hex').slice(0, 16);
+      const expectedSig = crypto.createHmac('sha256', this.secret).update(payload).digest('hex');
 
       if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) {
         return { valid: false, reason: 'invalid_signature' };
@@ -707,7 +742,7 @@ class ScoringEngine {
     };
 
     const payload = JSON.stringify(data, Object.keys(data).sort());
-    const sig = crypto.createHmac('sha256', this.secret).update(payload).digest('hex').slice(0, 16);
+    const sig = crypto.createHmac('sha256', this.secret).update(payload).digest('hex');
     data.sig = sig;
 
     return Buffer.from(JSON.stringify(data)).toString('base64url');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "Open source CAPTCHA with PoW, bot detection, and Vision AI protection",
   "main": "index.js",
   "exports": {
@@ -15,8 +15,9 @@
     "test:clientip": "node clientip.test.js",
     "test:limits": "node limits.test.js",
     "test:detection": "node detection.test.js",
-    "test": "node clientip.test.js && node limits.test.js && node detection.test.js && node inputforensics.test.js && node webbotauth.test.js",
-    "test:forensics": "node inputforensics.test.js"
+    "test": "node clientip.test.js && node limits.test.js && node detection.test.js && node inputforensics.test.js && node webbotauth.test.js && node --test suspicion.test.js",
+    "test:forensics": "node inputforensics.test.js",
+    "test:suspicion": "node --test suspicion.test.js"
   },
   "dependencies": {
     "cors": "^2.8.5",

package/server.js

@@ -12,6 +12,7 @@ const detection = require('./detection');
 const webbotauth = require('./webbotauth');
 const { ProxyTrust } = require('./clientip');
 const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
+const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
 const { detectInputForensics } = require('./inputforensics');
 
 const app = express();
@@ -32,6 +33,10 @@ const PROXY_TRUST = ProxyTrust.fromEnv();
 // limits.js — the cap is unconditional; FCAPTCHA_SITE_KEYS adds an allowlist.
 const SITE_KEYS = SiteKeyGuard.fromEnv();
 
+// Recent strong verdicts per source, used to price the next challenge that
+// source asks for. Bounded and short-lived; see suspicion.js.
+const suspicionLedger = new SuspicionLedger();
+
 // Express's own `trust proxy` would re-derive req.ip from the same headers on
 // its own terms; IP resolution goes through PROXY_TRUST.clientIP exclusively.
 app.set('trust proxy', false);
@@ -97,7 +102,7 @@ const powChallengeStore = {
   usedSolutions: new BoundedSet(),
 
   // Generate a new challenge
-  generate(siteKey, ip, difficulty = 4) {
+  generate(siteKey, ip, difficulty = 4, minAgeMs = BASE_MIN_AGE_MS) {
     const challengeId = crypto.randomBytes(16).toString('hex');
     const nonce = crypto.randomBytes(16).toString('hex');
     const timestamp = Date.now();
@@ -110,6 +115,9 @@ const powChallengeStore = {
       timestamp,
       expiresAt,
       difficulty,
+      // How long the client must hold this challenge before submitting a
+      // solution. Inside the signed payload so it cannot be talked down.
+      minAgeMs,
       nonce,
       prefix: `${challengeId}:${timestamp}:${difficulty}`
     };
@@ -180,7 +188,14 @@ const powChallengeStore = {
     // Calculate server-side elapsed time (un-spoofable)
     const serverElapsed = Date.now() - challenge.createdAt;
 
-    return { valid: true, difficulty: challenge.difficulty, serverElapsed, nonce: challenge.nonce };
+    return {
+      valid: true,
+      difficulty: challenge.difficulty,
+      serverElapsed,
+      nonce: challenge.nonce,
+      // Fall back for challenges issued before adaptive cost existed.
+      minAgeMs: challenge.minAgeMs || BASE_MIN_AGE_MS
+    };
   },
 
   _cleanup() {
@@ -1311,14 +1326,26 @@ function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash
       }
     }
 
-    if (powValid && powVerification.serverElapsed < 1500) {
-      // Server-side timing: challenge was solved too fast (un-spoofable)
+    // Server-side timing, the one cost an attacker cannot buy their way out
+    // of. Two thresholds, because they mean different things.
+    if (powValid && powVerification.serverElapsed < BASE_MIN_AGE_MS) {
+      // Under the universal baseline nothing legitimate can have happened.
       detections.push({
         category: 'bot',
         score: 0.8,
         confidence: 0.85,
         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.
+      detections.push({
+        category: 'bot',
+        score: 0.5,
+        confidence: 0.5,
+        reason: `Challenge submitted before the required delay for this source (${powVerification.serverElapsed}ms of ${powVerification.minAgeMs}ms)`
+      });
     }
   } else {
     // No PoW solution provided - hard fail
@@ -1409,6 +1436,10 @@ function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash
   const success = finalScore < 0.5;
   const token = success ? generateToken(ip, siteKey, finalScore) : null;
 
+  // Feed the ledger so the next challenge this source asks for is priced on
+  // what it just did.
+  suspicionLedger.record(siteKey, ip, finalScore);
+
   return {
     success,
     score: finalScore,
@@ -1506,25 +1537,18 @@ app.get('/api/pow/challenge', (req, res) => {
   const ip = PROXY_TRUST.clientIP(req);
   const siteKey = SITE_KEYS.normalize(req.query.siteKey, ip);
 
-  // Difficulty scaling based on IP reputation
-  let difficulty = 4; // Default: ~100-500ms on average hardware
-
-  // Increase difficulty for suspicious IPs
-  if (detection.isDatacenterIP(ip)) {
-    difficulty = 5; // ~1-3 seconds
-  }
-
-  // Check rate - high request rate gets harder challenges
+  // Cost scaling. See suspicion.js for why the escalation lands almost
+  // entirely on minAgeMs rather than on difficulty.
   const rateKey = `pow:${siteKey}:${ip}`;
   const [exceeded, count] = rateLimiter.check(rateKey, 60, 20);
-  if (count > 10) {
-    difficulty = Math.min(6, difficulty + 1); // Up to difficulty 6
-  }
-  if (exceeded) {
-    difficulty = 6; // Maximum difficulty for rate-limited IPs
-  }
+  const cost = computeChallengeCost(
+    suspicionLedger.count(siteKey, ip),
+    detection.isDatacenterIP(ip),
+    count,
+    exceeded
+  );
 
-  const challenge = powChallengeStore.generate(siteKey, ip, difficulty);
+  const challenge = powChallengeStore.generate(siteKey, ip, cost.difficulty, cost.minAgeMs);
 
   res.json({
     challengeId: challenge.id,
@@ -1532,7 +1556,11 @@ app.get('/api/pow/challenge', (req, res) => {
     difficulty: challenge.difficulty,
     expiresAt: challenge.expiresAt,
     nonce: challenge.nonce,
-    sig: challenge.sig
+    sig: challenge.sig,
+    // Tells the client how long to hold a solved challenge before submitting.
+    // Honouring it is how an ordinary visitor pays an elevated cost as a short
+    // wait instead of as a worse score.
+    minAgeMs: challenge.minAgeMs
   });
 });
 

package/suspicion.js

@@ -0,0 +1,172 @@
+'use strict';
+
+/**
+ * Adaptive challenge cost: what a source pays is a function of what that source
+ * has recently been caught doing, rather than a constant.
+ *
+ * Why the cost is mostly time, not hashing
+ * ----------------------------------------
+ * A constant difficulty is strictly dominated: it either fails to inconvenience
+ * an attacker or it does hurt real users. The measurements behind that claim:
+ * browser JS runs 1-3M hash/s, native code 100-500M/s, so difficulty 6 costs a
+ * native solver about a millisecond and a budget Android phone about sixteen
+ * seconds. Raising difficulty is close to a pure tax on the slowest legitimate
+ * devices.
+ *
+ * Wall-clock is the knob that does not have that property. Nobody can make less
+ * time pass, so a minimum challenge age caps how fast one source can mint
+ * tokens no matter what hardware it brings. So suspicion moves the time floor
+ * first and difficulty barely at all.
+ *
+ * What this deliberately is not
+ * -----------------------------
+ * This is not Workstream F 10.1 (cross-session correlation). It stores strong-
+ * verdict timestamps per source, nothing else: no behavioral vectors, no
+ * per-fingerprint history, no traces that survive the window. It is the same
+ * shape and the same privacy class as the rate limiter sitting next to it, and
+ * it should stay that way — 10.1 has a privacy load this does not, and the two
+ * should not be conflated because they happen to both be "server-side memory".
+ */
+
+// The verdict score at or above which a verification counts as evidence.
+// Deliberately high: a marginal verdict is exactly the case where the scoring
+// might be wrong about a real person, and making the next person from that
+// address wait is not worth the guess.
+const STRONG_SCORE = 0.8;
+
+// How long a strong verdict keeps counting. Short enough that a shared egress
+// address recovers on its own within a coffee break.
+const WINDOW_MS = 15 * 60 * 1000;
+
+// Only the count matters and every tier saturates well below this.
+const MAX_HITS = 16;
+
+// Bounds the table. Sources with no strong verdicts never get an entry at all,
+// so this only has to cover addresses actively failing verification.
+const MAX_SOURCES = 50000;
+
+/**
+ * Records recent strong verdicts per source.
+ *
+ * Entries are created only when a source produces a strong verdict, so the
+ * common case — a legitimate visitor — allocates nothing and looks up nothing
+ * but a miss.
+ */
+class SuspicionLedger {
+  constructor() {
+    this.hits = new Map();
+  }
+
+  static _key(siteKey, ip) {
+    return `${siteKey}|${ip}`;
+  }
+
+  /**
+   * Note a verdict. Scores below the strong threshold are ignored entirely
+   * rather than recorded and weighted, so a source that merely looks unusual
+   * never accumulates anything.
+   */
+  record(siteKey, ip, score) {
+    if (!ip || typeof score !== 'number' || score < STRONG_SCORE) return;
+
+    const key = SuspicionLedger._key(siteKey, ip);
+    const now = Date.now();
+    const cutoff = now - WINDOW_MS;
+
+    const kept = (this.hits.get(key) || []).filter((t) => t > cutoff);
+    kept.push(now);
+
+    // Map preserves insertion order, so re-inserting makes this the most
+    // recently touched key and the eviction below drops the stalest source.
+    this.hits.delete(key);
+    this.hits.set(key, kept.length > MAX_HITS ? kept.slice(-MAX_HITS) : kept);
+
+    if (this.hits.size > MAX_SOURCES) {
+      this.hits.delete(this.hits.keys().next().value);
+    }
+  }
+
+  /**
+   * How many strong verdicts this source produced inside the window. Counted
+   * from the timestamps rather than from the entry's existence, so an old hit
+   * actually decays while newer ones keep the entry alive.
+   */
+  count(siteKey, ip) {
+    if (!ip) return 0;
+    const hits = this.hits.get(SuspicionLedger._key(siteKey, ip));
+    if (!hits) return 0;
+
+    const cutoff = Date.now() - WINDOW_MS;
+    const n = hits.filter((t) => t > cutoff).length;
+    if (n === 0) this.hits.delete(SuspicionLedger._key(siteKey, ip));
+    return n;
+  }
+}
+
+// Baseline cost. A clean visitor pays exactly this, which is what the server
+// has always charged everyone.
+const BASE_DIFFICULTY = 4;
+const BASE_MIN_AGE_MS = 1500;
+
+// Caps the compute knob at 5, below the 6 this server used to reach. Difficulty
+// 6 buys about a millisecond of attacker time and spends about sixteen seconds
+// of a budget phone's; the escalation belongs in minAgeMs where an attacker
+// cannot buy their way out of it.
+const MAX_DIFFICULTY = 5;
+
+// Caps the time knob at 15s. At the 1.5s baseline one address can mint roughly
+// 40 tokens a minute; at 15s, four. Pushing further buys little and is felt by
+// anyone sharing a poisoned egress address.
+const MAX_MIN_AGE_MS = 15000;
+
+/**
+ * Maps accumulated suspicion onto a cost.
+ *
+ * Note what does NOT raise difficulty here: being on a datacenter address. That
+ * used to jump straight to difficulty 5, which charges a real person on a
+ * corporate VPN or iCloud Private Relay several seconds of blocked hashing on a
+ * slow phone for the offence of having a shared IP. It now moves the time floor
+ * instead, which a datacenter-hosted scraper feels as reduced throughput and a
+ * person filling in a form does not feel at all.
+ *
+ * @returns {{difficulty: number, minAgeMs: number}}
+ */
+function computeChallengeCost(strongHits, isDatacenter, requestCount, rateExceeded) {
+  let difficulty = BASE_DIFFICULTY;
+  let minAgeMs = BASE_MIN_AGE_MS;
+
+  if (strongHits >= 6) {
+    difficulty = 5;
+    minAgeMs = 15000;
+  } else if (strongHits >= 3) {
+    difficulty = 5;
+    minAgeMs = 8000;
+  } else if (strongHits >= 1) {
+    minAgeMs = 4000;
+  }
+
+  // Floors from signals that are suggestive rather than damning. They raise the
+  // time floor and never the difficulty.
+  const raiseTo = (ms) => {
+    if (minAgeMs < ms) minAgeMs = ms;
+  };
+  if (isDatacenter) raiseTo(3000);
+  if (requestCount > 10) raiseTo(6000);
+  if (rateExceeded) raiseTo(10000);
+
+  return {
+    difficulty: Math.min(difficulty, MAX_DIFFICULTY),
+    minAgeMs: Math.min(minAgeMs, MAX_MIN_AGE_MS)
+  };
+}
+
+module.exports = {
+  SuspicionLedger,
+  computeChallengeCost,
+  STRONG_SCORE,
+  WINDOW_MS,
+  BASE_DIFFICULTY,
+  BASE_MIN_AGE_MS,
+  MAX_DIFFICULTY,
+  MAX_MIN_AGE_MS
+};