@webdecoy/fcaptcha 1.20.0 → 1.22.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.22.0",
   "description": "Open source CAPTCHA with PoW, bot detection, and Vision AI protection",
   "main": "index.js",
   "exports": {
@@ -15,8 +15,10 @@
     "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 siteverify.test.js && node --test suspicion.test.js",
+    "test:siteverify": "node siteverify.test.js",
+    "test:forensics": "node inputforensics.test.js",
+    "test:suspicion": "node --test suspicion.test.js"
   },
   "dependencies": {
     "cors": "^2.8.5",

package/server.js

@@ -12,13 +12,51 @@ 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 {
+  ERROR_CODES,
+  HostnameAllowlist,
+  IdempotencyStore,
+  requestHostname,
+  sanitizeAction,
+  sanitizeCdata,
+  secretMatches,
+  siteverify
+} = require('./siteverify');
 
 const app = express();
 app.use(cors());
 app.use(express.json());
+// The siteverify contract accepts form-encoded bodies as well as JSON, and most
+// PHP and Python integrations in the wild post form-encoded. Parsing both here
+// costs nothing on the JSON path.
+app.use(express.urlencoded({ extended: false }));
 
 const SECRET_KEY = process.env.FCAPTCHA_SECRET || 'dev-secret-change-in-production';
+
+// The credential a backend presents to validate a token. Defaults to the signing
+// key, which is what the README has always documented, but can be separated:
+// the signing key is a long-lived secret that must never leave the server, while
+// this one is handed to every backend that verifies. Splitting them means a
+// leaked verify credential does not let the holder mint tokens.
+const VERIFY_SECRET = process.env.FCAPTCHA_VERIFY_SECRET || SECRET_KEY;
+
+// Token verification used to accept anyone who could reach the endpoint: all
+// three servers read `secret` out of the body and dropped it. Enforcing it is a
+// breaking change for deployments that never sent one, so there is one release
+// of escape hatch before the parameter becomes mandatory outright.
+const LEGACY_UNAUTH_VERIFY = /^(1|true|yes|on)$/i.test(
+  process.env.FCAPTCHA_LEGACY_UNAUTH_VERIFY || ''
+);
+
+// Optional: restrict which page origins may mint tokens. Off by default so
+// zero-config self-hosting keeps working. See siteverify.js.
+const ALLOWED_HOSTNAMES = HostnameAllowlist.fromEnv();
+
+// Lets a caller retry a validation that timed out without burning the token.
+const IDEMPOTENCY = new IdempotencyStore();
+
 const PORT = process.env.PORT || 3000;
 const TRUSTED_JA4_HEADERS = detection.getTrustedJA4HeaderNames();
 
@@ -32,6 +70,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 +139,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 +152,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 +225,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() {
@@ -1169,13 +1221,26 @@ function applyDispositiveFloor(score, detections) {
   return selfDeclared ? Math.max(score, DISPOSITIVE_FLOOR) : score;
 }
 
-function generateToken(ip, siteKey, score) {
+// Bind the token to the page that minted it and to the action it was minted
+// for. All three ride inside the signed payload, so a token issued for
+// `action=login` on example.com cannot be replayed against a password-reset
+// endpoint or presented from a site that lifted the key — the backend compares
+// what siteverify reports against what it expected.
+//
+// Empty strings rather than omitted keys: the signing payload is a sorted-key
+// JSON serialisation, so a token whose key set varies with what the browser
+// happened to send would be a second payload shape to keep in sync across three
+// languages. Fixed shape, empty when unknown.
+function generateToken(ip, siteKey, score, binding = {}) {
   const ipHash = crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8);
   const data = {
     site_key: siteKey,
     timestamp: Math.floor(Date.now() / 1000),
     score: Math.round(score * 1000) / 1000,
-    ip_hash: ipHash
+    ip_hash: ipHash,
+    hostname: binding.hostname || '',
+    action: binding.action || '',
+    cdata: binding.cdata || ''
   };
 
   const payload = JSON.stringify(data, Object.keys(data).sort());
@@ -1219,12 +1284,19 @@ function verifyToken(token, ip = null) {
     // Mark token as used (prevents replay)
     tokenStore.markUsed(sig);
 
+    // hostname/action/cdata default to '' so a token minted before they existed
+    // still verifies and reports the same shape. The signature covers whatever
+    // keys the token actually carries, so old four-key tokens validate
+    // unchanged — this is additive, not a format break.
     return {
       valid: true,
       site_key: decoded.site_key,
       timestamp: decoded.timestamp,
       score: decoded.score,
-      ip_hash: decoded.ip_hash
+      ip_hash: decoded.ip_hash,
+      hostname: decoded.hostname || '',
+      action: decoded.action || '',
+      cdata: decoded.cdata || ''
     };
   } catch (e) {
     return { valid: false, reason: e.message };
@@ -1311,14 +1383,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
@@ -1406,8 +1490,29 @@ function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash
   else if (finalScore < 0.6) recommendation = 'challenge';
   else recommendation = 'block';
 
-  const success = finalScore < 0.5;
-  const token = success ? generateToken(ip, siteKey, finalScore) : null;
+  // The hostname comes from the request headers rather than the request body:
+  // it is what the browser reported about the page, not what the page claimed
+  // about itself.
+  const hostname = requestHostname(headers);
+
+  // An unlisted hostname withholds the token but does not touch the score. The
+  // visitor is not the problem — a key registered to another site is — so the
+  // detection layer has nothing to say about it and the refusal is reported as
+  // its own reason rather than smuggled in as a bot verdict.
+  const hostnameAllowed = ALLOWED_HOSTNAMES.permits(hostname);
+  const success = finalScore < 0.5 && hostnameAllowed;
+
+  const token = success
+    ? generateToken(ip, siteKey, finalScore, {
+        hostname,
+        action: sanitizeAction(opts.action),
+        cdata: sanitizeCdata(opts.cdata)
+      })
+    : 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,
@@ -1416,7 +1521,8 @@ function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash
     timestamp: Math.floor(Date.now() / 1000),
     recommendation,
     categoryScores,
-    detections
+    detections,
+    ...(hostnameAllowed ? {} : { reason: 'hostname_not_allowed', hostname })
   };
 }
 
@@ -1444,7 +1550,7 @@ function collectHeaders(req) {
 }
 
 app.post('/api/verify', async (req, res) => {
-  const { siteKey: rawSiteKey, signals, powSolution, signalsJson, powTiming } = req.body;
+  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).
   const siteKey = SITE_KEYS.normalize(rawSiteKey, ip);
@@ -1460,13 +1566,13 @@ app.post('/api/verify', async (req, res) => {
   // Web Bot Auth verification needs the raw request; its verdict is scored.
   const webBotAuth = await verifyWebBotAuth(req);
 
-  const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming, webBotAuth, { peerTrusted });
+  const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming, webBotAuth, { peerTrusted, action, cdata });
   logVerdict('verify', siteKey, result);
   res.json(result);
 });
 
 app.post('/api/score', async (req, res) => {
-  const { siteKey: rawSiteKey, signals, action, powSolution, signalsJson, powTiming } = req.body;
+  const { siteKey: rawSiteKey, signals, action, cdata, powSolution, signalsJson, powTiming } = req.body;
   const ip = PROXY_TRUST.clientIP(req);
   const siteKey = SITE_KEYS.normalize(rawSiteKey, ip);
   const userAgent = req.headers['user-agent'] || '';
@@ -1481,19 +1587,35 @@ app.post('/api/score', async (req, res) => {
   // Web Bot Auth verification needs the raw request; its verdict is scored.
   const webBotAuth = await verifyWebBotAuth(req);
 
-  const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming, webBotAuth, { peerTrusted });
+  const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming, webBotAuth, { peerTrusted, action, cdata });
   logVerdict('score', siteKey, result);
   res.json({
     success: result.success,
     score: result.score,
     token: result.token,
-    action: action || '',
+    // Echo the sanitized form, not the raw input: this is what got signed into
+    // the token, so a caller comparing the two sees the same value.
+    action: sanitizeAction(action),
+    cdata: sanitizeCdata(cdata),
     recommendation: result.recommendation
   });
 });
 
 app.post('/api/token/verify', (req, res) => {
-  const { token } = req.body;
+  const { token, secret } = req.body;
+
+  // The secret gate. This endpoint is the boundary between "a browser finished a
+  // challenge" and "my backend believes it", so it is server-to-server and needs
+  // a credential — without one, anyone who can reach the host can spend a token
+  // they observed, and the single-use guard then denies the real user.
+  if (!LEGACY_UNAUTH_VERIFY) {
+    if (!secret) {
+      return res.status(401).json({ valid: false, reason: 'missing_secret' });
+    }
+    if (!secretMatches(secret, VERIFY_SECRET)) {
+      return res.status(401).json({ valid: false, reason: 'invalid_secret' });
+    }
+  }
 
   // Extract client IP for verification
   const ip = PROXY_TRUST.clientIP(req);
@@ -1501,30 +1623,47 @@ app.post('/api/token/verify', (req, res) => {
   res.json(verifyToken(token, ip));
 });
 
+// Turnstile / reCAPTCHA / hCaptcha drop-in compatibility.
+//
+// Same contract, three paths, because the path is hardcoded in the SDKs and
+// plugins we want to be usable against FCaptcha: pointing an existing
+// integration at this server should be a base-URL change and nothing else.
+// See siteverify.js for the adapter itself.
+function siteverifyHandler(req, res) {
+  res.json(
+    siteverify({
+      body: req.body,
+      // Bind to this server's token store, so replay state is shared with the
+      // native endpoint rather than kept in a parallel universe.
+      verifyToken,
+      expectedSecret: VERIFY_SECRET,
+      idempotencyStore: IDEMPOTENCY,
+      requireSecret: !LEGACY_UNAUTH_VERIFY
+    })
+  );
+}
+
+app.post('/turnstile/v0/siteverify', siteverifyHandler);
+app.post('/recaptcha/api/siteverify', siteverifyHandler);
+app.post('/siteverify', siteverifyHandler);
+
 // PoW Challenge endpoint - client fetches this on page load
 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 +1671,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/siteverify.js

@@ -0,0 +1,331 @@
+'use strict';
+
+/**
+ * Drop-in compatibility with the Turnstile / reCAPTCHA / hCaptcha siteverify
+ * contract.
+ *
+ * Every one of those services validates a token the same way: a server-to-server
+ * POST carrying `secret` and `response`, answered with a small JSON object whose
+ * shape has been stable for a decade. Every backend SDK, CMS plugin and Stack
+ * Overflow snippet in circulation speaks it:
+ *
+ *     POST /turnstile/v0/siteverify        (form-encoded or JSON)
+ *       secret, response, remoteip, idempotency_key
+ *     -> {success, challenge_ts, hostname, action, cdata, error-codes}
+ *
+ * FCaptcha's native endpoint (`POST /api/token/verify` -> `{valid, score, ...}`)
+ * is a different shape, which means none of that existing integration work
+ * applies. Serving the familiar contract alongside the native one turns a
+ * migration into a base-URL change, so this module is deliberately an *adapter*
+ * over `verifyToken` rather than a second verification path — there is one
+ * implementation of token validity and this translates its vocabulary.
+ *
+ * Three things the native endpoint did not do, which the contract requires:
+ *
+ *   - `secret` is checked. All three servers previously accepted the parameter
+ *     and ignored it, so anyone who could reach the endpoint could verify
+ *     tokens. The README documented sending it, which made the omission worse:
+ *     integrators believed they were authenticated.
+ *   - `hostname` is reported, so the caller can confirm the token was minted on
+ *     a page they actually serve. This is what stops a lifted site key from
+ *     being used against someone else's deployment.
+ *   - `idempotency_key` makes retries safe. Tokens are single-use, so a network
+ *     timeout on the first validation would otherwise burn the token and fail
+ *     the user's request on the retry.
+ *
+ * Mirrors server-go/siteverify.go and server-python/siteverify.py.
+ */
+
+const crypto = require('crypto');
+const { BoundedMap } = require('./limits');
+
+// How long a validation result stays replayable under its idempotency key.
+// Matched to the token lifetime: past that the token is expired anyway, so a
+// retry has nothing left to be idempotent about.
+const IDEMPOTENCY_TTL_SECONDS = 300;
+
+// Bounded because the key is caller-supplied. Same reasoning as limits.js:
+// anything keyed on a value the client chooses needs a ceiling.
+const MAX_IDEMPOTENCY_ENTRIES = 10000;
+
+// `action` and `cdata` are echoed back verbatim, so they are attacker-controlled
+// output. Length-capped to keep them from bloating the token, and in cdata's
+// case to keep it a label rather than a smuggling channel.
+const MAX_ACTION_LENGTH = 32;
+const MAX_CDATA_LENGTH = 255;
+
+/**
+ * The error-code vocabulary. These strings are the contract — integrators
+ * branch on them — so they match Cloudflare's spelling exactly, hyphens and all.
+ */
+const ERROR_CODES = {
+  MISSING_SECRET: 'missing-input-secret',
+  INVALID_SECRET: 'invalid-input-secret',
+  MISSING_RESPONSE: 'missing-input-response',
+  INVALID_RESPONSE: 'invalid-input-response',
+  BAD_REQUEST: 'bad-request',
+  TIMEOUT_OR_DUPLICATE: 'timeout-or-duplicate',
+  INTERNAL_ERROR: 'internal-error',
+};
+
+/**
+ * How `verifyToken`'s internal `reason` maps onto that vocabulary.
+ *
+ * The collapse is lossy on purpose. A caller learning *why* a token failed
+ * learns something about the signing key or the replay window, so every
+ * structural failure reports the same `invalid-input-response`, and expiry and
+ * replay share `timeout-or-duplicate` exactly as Cloudflare's do.
+ */
+const REASON_TO_ERROR_CODE = {
+  expired: ERROR_CODES.TIMEOUT_OR_DUPLICATE,
+  token_already_used: ERROR_CODES.TIMEOUT_OR_DUPLICATE,
+  invalid_signature: ERROR_CODES.INVALID_RESPONSE,
+  invalid_encoding: ERROR_CODES.INVALID_RESPONSE,
+  invalid_json: ERROR_CODES.INVALID_RESPONSE,
+  missing_signature: ERROR_CODES.INVALID_RESPONSE,
+  ip_mismatch: ERROR_CODES.INVALID_RESPONSE,
+  hostname_not_allowed: ERROR_CODES.INVALID_RESPONSE,
+};
+
+function reasonToErrorCode(reason) {
+  return REASON_TO_ERROR_CODE[reason] || ERROR_CODES.INVALID_RESPONSE;
+}
+
+/**
+ * Pull the host out of a URL-shaped header value.
+ *
+ * Returns '' rather than throwing on anything unparseable, including the
+ * literal `null` that browsers send as Origin from a sandboxed iframe or a
+ * file:// page. An opaque origin is genuinely the absence of a hostname, not an
+ * error — the token simply carries no host binding.
+ */
+function hostFromUrl(value) {
+  if (!value || typeof value !== 'string') return '';
+  if (value === 'null') return '';
+  try {
+    // URL.hostname excludes the port and keeps IPv6 brackets, which is the
+    // normalisation we want: example.com:8443 and example.com are one host.
+    return new URL(value).hostname.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The hostname a token should be bound to, from the headers of the request that
+ * mints it.
+ *
+ * Origin first: the widget's verification call is a CORS POST, so browsers
+ * attach it, and unlike Referer it is not suppressed by referrer policy. Referer
+ * is the fallback for same-origin deployments where Origin may be absent on some
+ * request shapes. Neither is trustworthy against a non-browser caller — anything
+ * that can forge one can forge both — so this binds the *browser* case, which is
+ * the case that matters: it stops a site key lifted from your page from minting
+ * tokens that your own backend will accept.
+ */
+function requestHostname(headers) {
+  if (!headers) return '';
+  return hostFromUrl(headers['origin']) || hostFromUrl(headers['referer']) || '';
+}
+
+/** Trim a caller-supplied label to something safe to sign and echo. */
+function sanitizeLabel(value, maxLength) {
+  if (typeof value !== 'string') return '';
+  // Control characters would ride through into the JSON response and any log
+  // line that records it.
+  return value.replace(/[\x00-\x1f\x7f]/g, '').slice(0, maxLength);
+}
+
+function sanitizeAction(value) {
+  return sanitizeLabel(value, MAX_ACTION_LENGTH);
+}
+
+function sanitizeCdata(value) {
+  return sanitizeLabel(value, MAX_CDATA_LENGTH);
+}
+
+/**
+ * Constant-time secret comparison.
+ *
+ * timingSafeEqual demands equal-length buffers and throws otherwise, which would
+ * itself leak length, so both sides are hashed to a fixed width first.
+ */
+function secretMatches(provided, expected) {
+  if (typeof provided !== 'string' || typeof expected !== 'string') return false;
+  const a = crypto.createHash('sha256').update(provided).digest();
+  const b = crypto.createHash('sha256').update(expected).digest();
+  return crypto.timingSafeEqual(a, b);
+}
+
+/**
+ * Optional allowlist of hostnames permitted to mint tokens.
+ *
+ * Off by default so zero-config self-hosting keeps working, and reported rather
+ * than enforced when a request carries no derivable Origin — a native mobile
+ * client or a server-side integration legitimately has none, and refusing those
+ * would break them for no security gain.
+ */
+class HostnameAllowlist {
+  constructor(hostnames = []) {
+    this.hostnames = new Set(
+      hostnames
+        .map((h) => String(h).trim().toLowerCase())
+        .filter(Boolean)
+    );
+  }
+
+  static fromEnv(env = process.env) {
+    const raw = env.FCAPTCHA_ALLOWED_HOSTNAMES || '';
+    return new HostnameAllowlist(raw.split(',').filter(Boolean));
+  }
+
+  get enabled() {
+    return this.hostnames.size > 0;
+  }
+
+  /**
+   * Whether a hostname may mint tokens. An empty hostname passes: see the class
+   * comment — absence of an Origin is not evidence of a bad one.
+   */
+  permits(hostname) {
+    if (!this.enabled) return true;
+    if (!hostname) return true;
+    return this.hostnames.has(hostname);
+  }
+
+  describe() {
+    return this.enabled ? [...this.hostnames].join(', ') : 'any (unrestricted)';
+  }
+}
+
+/**
+ * Caches validation results so a retried siteverify returns the first answer
+ * instead of tripping the single-use guard.
+ *
+ * Keyed on the idempotency key *and* the token: reusing one key across different
+ * tokens is a caller bug, and answering the second one from the first one's
+ * cache entry would report success for a token nobody validated. Binding both
+ * degrades that case to an ordinary fresh verification.
+ */
+class IdempotencyStore {
+  constructor({ ttlSeconds = IDEMPOTENCY_TTL_SECONDS, maxEntries = MAX_IDEMPOTENCY_ENTRIES } = {}) {
+    this.ttlMs = ttlSeconds * 1000;
+    this.entries = new BoundedMap(maxEntries);
+  }
+
+  _key(idempotencyKey, token) {
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex').slice(0, 32);
+    return `${idempotencyKey}:${tokenHash}`;
+  }
+
+  get(idempotencyKey, token) {
+    if (!idempotencyKey) return null;
+    const entry = this.entries.get(this._key(idempotencyKey, token));
+    if (!entry) return null;
+    // >= so that a zero TTL means "never replay" rather than "replay once".
+    if (Date.now() - entry.storedAt >= this.ttlMs) return null;
+    return entry.response;
+  }
+
+  set(idempotencyKey, token, response) {
+    if (!idempotencyKey) return;
+    this.entries.set(this._key(idempotencyKey, token), {
+      storedAt: Date.now(),
+      response,
+    });
+  }
+}
+
+/** A failing siteverify response carrying the given codes. */
+function failure(...codes) {
+  return { success: false, 'error-codes': codes };
+}
+
+/**
+ * Read the siteverify parameters out of a request body.
+ *
+ * Both encodings are accepted because the contract accepts both, and callers in
+ * the wild are split: PHP and Python examples overwhelmingly post form-encoded,
+ * Node and Go examples post JSON.
+ */
+function readParams(body) {
+  if (!body || typeof body !== 'object') return {};
+  const str = (v) => (typeof v === 'string' ? v : v == null ? '' : String(v));
+  return {
+    secret: str(body.secret),
+    response: str(body.response),
+    remoteip: str(body.remoteip),
+    idempotencyKey: str(body.idempotency_key),
+  };
+}
+
+/**
+ * Run a siteverify request.
+ *
+ * `verifyToken` is injected rather than imported so the standalone server and
+ * the library export can each supply their own — they hold separate token
+ * stores, and this module should not decide which one is authoritative.
+ */
+function siteverify({
+  body,
+  verifyToken,
+  expectedSecret,
+  idempotencyStore,
+  requireSecret = true,
+}) {
+  const { secret, response, remoteip, idempotencyKey } = readParams(body);
+
+  if (requireSecret) {
+    if (!secret) return failure(ERROR_CODES.MISSING_SECRET);
+    if (!secretMatches(secret, expectedSecret)) return failure(ERROR_CODES.INVALID_SECRET);
+  }
+
+  if (!response) return failure(ERROR_CODES.MISSING_RESPONSE);
+
+  const cached = idempotencyStore && idempotencyStore.get(idempotencyKey, response);
+  if (cached) return cached;
+
+  let result;
+  try {
+    // remoteip is passed through to the IP-binding check. Empty means the caller
+    // declined to assert one, which the token verifier treats as "don't check".
+    result = verifyToken(response, remoteip || null);
+  } catch {
+    // Never surface an exception's text: it can carry key material or internals.
+    return failure(ERROR_CODES.INTERNAL_ERROR);
+  }
+
+  const out = result && result.valid
+    ? {
+        success: true,
+        challenge_ts: new Date((result.timestamp || 0) * 1000).toISOString(),
+        hostname: result.hostname || '',
+        action: result.action || '',
+        cdata: result.cdata || '',
+        'error-codes': [],
+        // Not part of the upstream contract, but the whole reason to run
+        // FCaptcha: a caller that only wants pass/fail can ignore it, and one
+        // that wants to risk-band on the score has it without a second call.
+        score: typeof result.score === 'number' ? result.score : null,
+      }
+    : failure(reasonToErrorCode(result && result.reason));
+
+  if (idempotencyStore) idempotencyStore.set(idempotencyKey, response, out);
+  return out;
+}
+
+module.exports = {
+  ERROR_CODES,
+  HostnameAllowlist,
+  IdempotencyStore,
+  hostFromUrl,
+  requestHostname,
+  reasonToErrorCode,
+  sanitizeAction,
+  sanitizeCdata,
+  secretMatches,
+  siteverify,
+  MAX_ACTION_LENGTH,
+  MAX_CDATA_LENGTH,
+  IDEMPOTENCY_TTL_SECONDS,
+};

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
+};