@webdecoy/fcaptcha 1.31.0 → 1.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.31.0",
+  "version": "1.33.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 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",
     "test:siteverify": "node siteverify.test.js",
     "test:forensics": "node inputforensics.test.js",
     "test:suspicion": "node --test suspicion.test.js"

package/redis-state.js

@@ -0,0 +1,173 @@
+'use strict';
+
+const crypto = require('crypto');
+const { createClient } = require('redis');
+
+const PREFIX = 'fcaptcha:v1:';
+const POW_TTL_MS = 5 * 60 * 1000;
+const SPENT_TTL_MS = 10 * 60 * 1000;
+const IDEMPOTENCY_TTL_MS = 5 * 60 * 1000;
+const DETECTION_TTL_MS = 15 * 60 * 1000;
+
+const CLAIM_CHALLENGE = `
+if redis.call('EXISTS', KEYS[1]) == 0 then return 0 end
+if redis.call('SET', KEYS[2], '1', 'NX', 'PX', ARGV[1]) == false then return -1 end
+redis.call('DEL', KEYS[1])
+return 1
+`;
+const RATE_CHECK = `
+redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', ARGV[1])
+local count = redis.call('ZCARD', KEYS[1])
+local added = 0
+if count < tonumber(ARGV[3]) then
+  redis.call('ZADD', KEYS[1], ARGV[2], ARGV[4])
+  count = count + 1
+  added = 1
+end
+redis.call('PEXPIRE', KEYS[1], ARGV[5])
+return {count, added}
+`;
+const SITEKEY_CLAIM = `
+if redis.call('SISMEMBER', KEYS[1], ARGV[1]) == 1 then
+  redis.call('PEXPIRE', KEYS[1], ARGV[3])
+  return 1
+end
+if redis.call('SCARD', KEYS[1]) >= tonumber(ARGV[2]) then return 0 end
+redis.call('SADD', KEYS[1], ARGV[1])
+redis.call('PEXPIRE', KEYS[1], ARGV[3])
+return 1
+`;
+
+class RedisState {
+  constructor(url, client = null) {
+    this.client = client || createClient({ url });
+    this.client.on?.('error', (err) => console.error('[redis]', err.message));
+  }
+
+  async connect() {
+    if (!this.client.isOpen) await this.client.connect();
+    await this.client.ping();
+  }
+
+  challengeKey(id) {
+    return `${PREFIX}pow:challenge:${id}`;
+  }
+
+  opaqueKey(kind, value) {
+    const digest = crypto.createHash('sha256').update(value).digest('hex');
+    return `${PREFIX}${kind}:${digest}`;
+  }
+
+  async putChallenge(challenge) {
+    const ttl = challenge.expiresAt - Date.now();
+    if (ttl <= 0) throw new Error('challenge already expired');
+    // challengeId is the canonical cross-runtime field used by Go and Node.
+    const stored = { ...challenge, challengeId: challenge.id };
+    delete stored.id;
+    await this.client.set(this.challengeKey(challenge.id), JSON.stringify(stored), { PX: ttl });
+  }
+
+  async getChallenge(id) {
+    const payload = await this.client.get(this.challengeKey(id));
+    if (!payload) return null;
+    const challenge = JSON.parse(payload);
+    return { ...challenge, id: challenge.challengeId };
+  }
+
+  async claimChallenge(challengeId, solutionKey) {
+    const result = Number(await this.client.eval(CLAIM_CHALLENGE, {
+      keys: [this.challengeKey(challengeId), `${PREFIX}pow:spent:${solutionKey}`],
+      arguments: [String(SPENT_TTL_MS)]
+    }));
+    if (result === 1) return { claimed: true };
+    return {
+      claimed: false,
+      reason: result === -1 ? 'solution_already_used' : 'challenge_not_found'
+    };
+  }
+
+  async claimToken(signature) {
+    return Boolean(await this.client.set(
+      `${PREFIX}token:spent:${signature}`,
+      '1',
+      { NX: true, PX: SPENT_TTL_MS }
+    ));
+  }
+
+  idempotencyKey(idempotencyKey, token) {
+    const tokenHash = crypto.createHash('sha256').update(token).digest('hex').slice(0, 32);
+    const composite = `${idempotencyKey}:${tokenHash}`;
+    const opaque = crypto.createHash('sha256').update(composite).digest('hex');
+    return `${PREFIX}siteverify:idempotency:${opaque}`;
+  }
+
+  async getIdempotency(idempotencyKey, token) {
+    if (!idempotencyKey) return null;
+    const payload = await this.client.get(this.idempotencyKey(idempotencyKey, token));
+    return payload ? JSON.parse(payload) : null;
+  }
+
+  async setIdempotency(idempotencyKey, token, response) {
+    if (!idempotencyKey) return;
+    await this.client.set(
+      this.idempotencyKey(idempotencyKey, token),
+      JSON.stringify(response),
+      { PX: IDEMPOTENCY_TTL_MS }
+    );
+  }
+
+  async rateCheck(key, windowSeconds, maxRequests) {
+    const now = Date.now();
+    const result = await this.client.eval(RATE_CHECK, {
+      keys: [this.opaqueKey('rate', key)],
+      arguments: [
+        String(now - windowSeconds * 1000), String(now), String(maxRequests),
+        `${now}:${crypto.randomBytes(8).toString('hex')}`, String(windowSeconds * 1000 + 1000)
+      ]
+    });
+    return [Number(result[1]) === 0, Number(result[0])];
+  }
+
+  async recordSuspicion(siteKey, ip) {
+    const now = Date.now();
+    const key = this.opaqueKey('suspicion', `${siteKey}|${ip}`);
+    await this.client.multi()
+      .zRemRangeByScore(key, '-inf', now - DETECTION_TTL_MS)
+      .zAdd(key, { score: now, value: `${now}:${crypto.randomBytes(8).toString('hex')}` })
+      .zRemRangeByRank(key, 0, -17)
+      .pExpire(key, DETECTION_TTL_MS)
+      .exec();
+  }
+
+  async suspicionCount(siteKey, ip) {
+    const key = this.opaqueKey('suspicion', `${siteKey}|${ip}`);
+    await this.client.zRemRangeByScore(key, '-inf', Date.now() - DETECTION_TTL_MS);
+    return Number(await this.client.zCard(key));
+  }
+
+  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();
+  }
+
+  async ipFingerprintCount(ip) {
+    return Number(await this.client.sCard(this.opaqueKey('fingerprint:fps', ip)));
+  }
+
+  async fingerprintIpCount(fingerprint, siteKey) {
+    return Number(await this.client.sCard(this.opaqueKey('fingerprint:ips', `${siteKey}|${fingerprint}`)));
+  }
+
+  async claimSiteKey(siteKey, ip, maxPerIp) {
+    return Number(await this.client.eval(SITEKEY_CLAIM, {
+      keys: [this.opaqueKey('sitekeys', ip)],
+      arguments: [this.opaqueKey('value:sitekey', siteKey), String(maxPerIp), String(60 * 60 * 1000)]
+    })) === 1;
+  }
+}
+
+module.exports = { RedisState, PREFIX, POW_TTL_MS, SPENT_TTL_MS, IDEMPOTENCY_TTL_MS };

package/server.js

@@ -15,6 +15,7 @@ const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
 const { signingSecretFromEnv } = require('./config');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
 const { detectInputForensics } = require('./inputforensics');
+const { RedisState } = require('./redis-state');
 const {
   HostnameAllowlist,
   IdempotencyStore,
@@ -22,7 +23,7 @@ const {
   sanitizeAction,
   sanitizeCdata,
   secretMatches,
-  siteverify
+  siteverifyAsync
 } = require('./siteverify');
 
 const app = express();
@@ -37,6 +38,8 @@ app.use(express.json({ limit: MAX_REQUEST_BODY_BYTES }));
 app.use(express.urlencoded({ extended: false, limit: MAX_REQUEST_BODY_BYTES }));
 
 const SECRET_KEY = signingSecretFromEnv();
+const REDIS_URL = process.env.REDIS_URL || '';
+const SHARED_STATE = REDIS_URL ? new RedisState(REDIS_URL) : null;
 
 // 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:
@@ -58,7 +61,12 @@ const LEGACY_UNAUTH_VERIFY = /^(1|true|yes|on)$/i.test(
 const ALLOWED_HOSTNAMES = HostnameAllowlist.fromEnv();
 
 // Lets a caller retry a validation that timed out without burning the token.
-const IDEMPOTENCY = new IdempotencyStore();
+const IDEMPOTENCY = SHARED_STATE
+  ? {
+      get: (key, token) => SHARED_STATE.getIdempotency(key, token),
+      set: (key, token, response) => SHARED_STATE.setIdempotency(key, token, response)
+    }
+  : new IdempotencyStore();
 
 const PORT = process.env.PORT || 3000;
 const TRUSTED_JA4_HEADERS = detection.getTrustedJA4HeaderNames();
@@ -73,9 +81,32 @@ const PROXY_TRUST = ProxyTrust.fromEnv();
 // limits.js — the cap is unconditional; FCAPTCHA_SITE_KEYS adds an allowlist.
 const SITE_KEYS = SiteKeyGuard.fromEnv();
 
+async function normalizeSiteKey(siteKey, ip) {
+  const key = siteKey || 'default';
+  if (SITE_KEYS.allowlist && !SITE_KEYS.allowlist.has(key)) return ' overflow';
+  if (!SHARED_STATE || !ip) return SITE_KEYS.normalize(key, ip);
+  try {
+    return await SHARED_STATE.claimSiteKey(key, ip, SITE_KEYS.maxPerIp) ? key : ' overflow';
+  } catch (_) {
+    return ' overflow';
+  }
+}
+
 // 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();
+const localSuspicionLedger = new SuspicionLedger();
+const suspicionLedger = {
+  async record(siteKey, ip, score) {
+    if (!SHARED_STATE) return localSuspicionLedger.record(siteKey, ip, score);
+    if (score < 0.8 || !ip) return;
+    try { await SHARED_STATE.recordSuspicion(siteKey, ip); } catch (_) { /* fail closed on reads */ }
+  },
+  async count(siteKey, ip) {
+    if (!SHARED_STATE) return localSuspicionLedger.count(siteKey, ip);
+    if (!ip) return 0;
+    try { return await SHARED_STATE.suspicionCount(siteKey, ip); } catch (_) { return 16; }
+  }
+};
 
 // 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.
@@ -142,7 +173,7 @@ const powChallengeStore = {
   usedSolutions: new BoundedSet(),
 
   // Generate a new challenge
-  generate(siteKey, ip, difficulty = 4, minAgeMs = BASE_MIN_AGE_MS) {
+  async 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();
@@ -167,12 +198,16 @@ const powChallengeStore = {
       .update(JSON.stringify(challengeData))
       .digest('hex');
 
-    // Store challenge
-    this.challenges.set(challengeId, {
+    const storedChallenge = {
       ...challengeData,
       ip,
       createdAt: timestamp
-    });
+    };
+    if (SHARED_STATE) {
+      await SHARED_STATE.putChallenge(storedChallenge);
+    } else {
+      this.challenges.set(challengeId, storedChallenge);
+    }
 
     // Cleanup old challenges periodically
     if (Math.random() < 0.1) this._cleanup();
@@ -181,15 +216,22 @@ const powChallengeStore = {
   },
 
   // Verify a PoW solution (signalsHash is optional for backward compat)
-  verify(challengeId, nonce, hash, siteKey, ip, signalsHash = null) {
-    const challenge = this.challenges.get(challengeId);
+  async verify(challengeId, nonce, hash, siteKey, ip, signalsHash = null) {
+    let challenge;
+    try {
+      challenge = SHARED_STATE
+        ? await SHARED_STATE.getChallenge(challengeId)
+        : this.challenges.get(challengeId);
+    } catch (_) {
+      return { valid: false, reason: 'state_unavailable' };
+    }
 
     if (!challenge) {
       return { valid: false, reason: 'challenge_not_found' };
     }
 
     if (Date.now() > challenge.expiresAt) {
-      this.challenges.delete(challengeId);
+      if (!SHARED_STATE) this.challenges.delete(challengeId);
       return { valid: false, reason: 'challenge_expired' };
     }
 
@@ -223,11 +265,22 @@ const powChallengeStore = {
       return { valid: false, reason: 'insufficient_difficulty' };
     }
 
-    // Mark solution as used
-    this.usedSolutions.add(solutionKey);
-
-    // Delete challenge (one-time use)
-    this.challenges.delete(challengeId);
+    if (SHARED_STATE) {
+      try {
+        const claim = await SHARED_STATE.claimChallenge(challengeId, solutionKey);
+        if (!claim.claimed) return { valid: false, reason: claim.reason };
+      } catch (_) {
+        return { valid: false, reason: 'state_unavailable' };
+      }
+    } else {
+      // The local store is synchronous, so this test-and-set is atomic within
+      // one event-loop turn.
+      if (this.usedSolutions.has(solutionKey)) {
+        return { valid: false, reason: 'solution_already_used' };
+      }
+      this.usedSolutions.add(solutionKey);
+      this.challenges.delete(challengeId);
+    }
 
     // Calculate server-side elapsed time (un-spoofable)
     const serverElapsed = Date.now() - challenge.createdAt;
@@ -254,7 +307,11 @@ const powChallengeStore = {
 const rateLimiter = {
   requests: new BoundedMap(),
 
-  check(key, windowSeconds = 60, maxRequests = 10) {
+  async check(key, windowSeconds = 60, maxRequests = 10) {
+    if (SHARED_STATE) {
+      try { return await SHARED_STATE.rateCheck(key, windowSeconds, maxRequests); }
+      catch (_) { return [true, maxRequests]; }
+    }
     const now = Date.now();
     const cutoff = now - (windowSeconds * 1000);
 
@@ -276,7 +333,11 @@ const fingerprintStore = {
   fingerprints: new BoundedMap(),
   ipFingerprints: new BoundedMap(),
 
-  record(fp, ip, siteKey) {
+  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)) {
@@ -292,11 +353,17 @@ const fingerprintStore = {
     this.ipFingerprints.get(ip).add(fp);
   },
 
-  getIpFpCount(ip) {
+  async getIpFpCount(ip) {
+    if (SHARED_STATE) {
+      try { return await SHARED_STATE.ipFingerprintCount(ip); } catch (_) { return 100; }
+    }
     return this.ipFingerprints.get(ip)?.size || 0;
   },
 
-  getFpIpCount(fp, siteKey) {
+  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;
   }
@@ -351,7 +418,7 @@ const {
 } = require('./engine');
 
 // Stateful detectors stay here: they read the module-level stores below.
-function detectFingerprint(signals, ip, siteKey) {
+async function detectFingerprint(signals, ip, siteKey) {
   const detections = [];
   const env = signals.environmental || {};
   const automation = env.automationFlags || {};
@@ -365,10 +432,10 @@ function detectFingerprint(signals, ip, siteKey) {
   ];
   const fp = crypto.createHash('sha256').update(components.join('|')).digest('hex').slice(0, 16);
 
-  fingerprintStore.record(fp, ip, siteKey);
+  await fingerprintStore.record(fp, ip, siteKey);
 
   // IP fingerprint count
-  const ipFpCount = fingerprintStore.getIpFpCount(ip);
+  const ipFpCount = await fingerprintStore.getIpFpCount(ip);
   if (ipFpCount > 5) {
     detections.push({
       category: 'fingerprint', score: 0.6, confidence: 0.6,
@@ -377,7 +444,7 @@ function detectFingerprint(signals, ip, siteKey) {
   }
 
   // Fingerprint IP count
-  const fpIpCount = fingerprintStore.getFpIpCount(fp, siteKey);
+  const fpIpCount = await fingerprintStore.getFpIpCount(fp, siteKey);
   if (fpIpCount > 10) {
     detections.push({
       category: 'fingerprint', score: 0.5, confidence: 0.5,
@@ -397,11 +464,11 @@ function detectFingerprint(signals, ip, siteKey) {
   return detections;
 }
 
-function detectRateAbuse(ip, siteKey) {
+async function detectRateAbuse(ip, siteKey) {
   const detections = [];
   const key = `${siteKey}:${ip}`;
 
-  const [exceeded, count] = rateLimiter.check(key, 60, 10);
+  const [exceeded, count] = await rateLimiter.check(key, 60, 10);
   if (exceeded) {
     detections.push({
       category: 'rate_limit', score: 0.8, confidence: 0.9,
@@ -446,7 +513,7 @@ function generateToken(ip, siteKey, score, binding = {}) {
   return Buffer.from(JSON.stringify(data)).toString('base64url');
 }
 
-function verifyToken(token, ip = null) {
+async function verifyToken(token, ip = null) {
   try {
     const decoded = JSON.parse(Buffer.from(token, 'base64url').toString());
 
@@ -465,11 +532,6 @@ function verifyToken(token, ip = null) {
       return { valid: false, reason: 'invalid_signature' };
     }
 
-    // Check for token replay (single-use tokens)
-    if (tokenStore.isUsed(sig)) {
-      return { valid: false, reason: 'token_already_used' };
-    }
-
     // Verify IP matches (if provided)
     if (ip) {
       const expectedIpHash = crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8);
@@ -478,8 +540,15 @@ function verifyToken(token, ip = null) {
       }
     }
 
-    // Mark token as used (prevents replay)
-    tokenStore.markUsed(sig);
+    let claimed;
+    try {
+      claimed = SHARED_STATE
+        ? await SHARED_STATE.claimToken(sig)
+        : tokenStore.markUsed(sig);
+    } catch (_) {
+      return { valid: false, reason: 'state_unavailable' };
+    }
+    if (!claimed) return { valid: false, reason: 'token_already_used' };
 
     // hostname/action/cdata default to '' so a token minted before they existed
     // still verifies and reports the same shape. The signature covers whatever
@@ -495,8 +564,8 @@ function verifyToken(token, ip = null) {
       action: decoded.action || '',
       cdata: decoded.cdata || ''
     };
-  } catch (e) {
-    return { valid: false, reason: e.message };
+  } catch (_) {
+    return { valid: false, reason: 'invalid_token' };
   }
 }
 
@@ -516,7 +585,7 @@ async function verifyWebBotAuth(req) {
 // require the raw request — currently Web Bot Auth signature verification, which
 // needs the accurately-reconstructed signed request. They are seeded into the
 // detection set so they participate in scoring like any other detection.
-function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash = null, powSolution = null, signalsJson = null, powTiming = null, preDetections = [], opts = {}) {
+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)
@@ -567,7 +636,7 @@ function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash
   let powSatisfied = false;
   let powVerification = null;
   if (powSolution && powSolution.challengeId) {
-    powVerification = powChallengeStore.verify(
+    powVerification = await powChallengeStore.verify(
       powSolution.challengeId,
       powSolution.nonce,
       powSolution.hash,
@@ -658,10 +727,10 @@ function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash
     ...detectInputForensics(signals),
     ...detectTouchAuthenticity(signals, userAgent),
     ...detectSensorEntropy(signals, userAgent),
-    ...detectTouchKinematics(signals),
-    ...detectFingerprint(signals, ip, siteKey),
-    ...detectRateAbuse(ip, siteKey)
+    ...detectTouchKinematics(signals)
   );
+  detections.push(...await detectFingerprint(signals, ip, siteKey));
+  detections.push(...await detectRateAbuse(ip, siteKey));
 
   // Add IP reputation check (async but we'll use sync version for simplicity)
   if (detection.isDatacenterIP(ip)) {
@@ -763,7 +832,7 @@ function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash
 
   // Feed the ledger so the next challenge this source asks for is priced on
   // what it just did.
-  suspicionLedger.record(siteKey, ip, finalScore);
+  await suspicionLedger.record(siteKey, ip, finalScore);
 
   return {
     success,
@@ -805,7 +874,7 @@ app.post('/api/verify', 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).
-  const siteKey = SITE_KEYS.normalize(rawSiteKey, ip);
+  const siteKey = await normalizeSiteKey(rawSiteKey, ip);
   const userAgent = req.headers['user-agent'] || '';
   // Only honoured from a trusted proxy: a client that can state its own TLS
   // fingerprint would just claim a stock Chrome one.
@@ -818,7 +887,7 @@ 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, action, cdata, widgetInteraction: true });
+  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);
 });
@@ -826,7 +895,7 @@ app.post('/api/verify', async (req, res) => {
 app.post('/api/score', async (req, res) => {
   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 siteKey = await normalizeSiteKey(rawSiteKey, ip);
   const userAgent = req.headers['user-agent'] || '';
   const ja3Hash = PROXY_TRUST.trustedHeader(req, 'x-ja3-hash') || null;
 
@@ -840,7 +909,7 @@ app.post('/api/score', async (req, res) => {
   const webBotAuth = await verifyWebBotAuth(req);
 
   // Invisible scoring: no widget, so no click analysis in the signals.
-  const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming, webBotAuth, { peerTrusted, action, cdata, widgetInteraction: false });
+  const result = await runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming, webBotAuth, { peerTrusted, action, cdata, widgetInteraction: false });
   logVerdict('score', siteKey, result);
   res.json({
     success: result.success,
@@ -857,7 +926,7 @@ app.post('/api/score', async (req, res) => {
   });
 });
 
-app.post('/api/token/verify', (req, res) => {
+app.post('/api/token/verify', async (req, res) => {
   const { token, secret, remoteip } = req.body;
 
   // The secret gate. This endpoint is the boundary between "a browser finished a
@@ -876,7 +945,7 @@ app.post('/api/token/verify', (req, res) => {
   // This request comes from the integrating backend, not from the visitor who
   // received the token. Bind only when that trusted backend explicitly supplies
   // the visitor address; using the caller socket here compares unrelated hosts.
-  res.json(verifyToken(token, typeof remoteip === 'string' && remoteip ? remoteip : null));
+  res.json(await verifyToken(token, typeof remoteip === 'string' && remoteip ? remoteip : null));
 });
 
 // Turnstile / reCAPTCHA / hCaptcha drop-in compatibility.
@@ -885,9 +954,9 @@ app.post('/api/token/verify', (req, res) => {
 // 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) {
+async function siteverifyHandler(req, res) {
   res.json(
-    siteverify({
+    await siteverifyAsync({
       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.
@@ -904,22 +973,27 @@ 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) => {
+app.get('/api/pow/challenge', async (req, res) => {
   const ip = PROXY_TRUST.clientIP(req);
-  const siteKey = SITE_KEYS.normalize(req.query.siteKey, ip);
+  const siteKey = await normalizeSiteKey(req.query.siteKey, ip);
 
   // 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);
+  const [exceeded, count] = await rateLimiter.check(rateKey, 60, 20);
   const cost = computeChallengeCost(
-    suspicionLedger.count(siteKey, ip),
+    await suspicionLedger.count(siteKey, ip),
     detection.isDatacenterIP(ip),
     count,
     exceeded
   );
 
-  const challenge = powChallengeStore.generate(siteKey, ip, cost.difficulty, cost.minAgeMs);
+  let challenge;
+  try {
+    challenge = await powChallengeStore.generate(siteKey, ip, cost.difficulty, cost.minAgeMs);
+  } catch (_) {
+    return res.status(503).json({ error: 'state_unavailable' });
+  }
 
   res.json({
     challengeId: challenge.id,
@@ -959,8 +1033,17 @@ app.use((err, req, res, next) => {
 // Start
 // =============================================================================
 
-app.listen(PORT, () => {
-  console.log(`FCaptcha server running on port ${PORT}`);
-  console.log(`Trusted proxies: ${PROXY_TRUST.describe()}`);
-  console.log(`Site keys: ${SITE_KEYS.describe()}`);
+async function start() {
+  if (SHARED_STATE) await SHARED_STATE.connect();
+  app.listen(PORT, () => {
+    console.log(`FCaptcha server running on port ${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'}`);
+  });
+}
+
+start().catch((err) => {
+  console.error(`FCaptcha failed to start: ${err.message}`);
+  process.exit(1);
 });

package/siteverify.js

@@ -314,6 +314,44 @@ function siteverify({
   return out;
 }
 
+// Async form used by Redis-backed servers. Kept separate so the public
+// synchronous adapter remains backward compatible for library callers.
+async function siteverifyAsync({
+  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);
+
+  try {
+    const cached = idempotencyStore && await idempotencyStore.get(idempotencyKey, response);
+    if (cached) return cached;
+    const result = await verifyToken(response, remoteip || null);
+    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': [],
+          score: typeof result.score === 'number' ? result.score : null,
+        }
+      : failure(reasonToErrorCode(result && result.reason));
+    if (idempotencyStore) await idempotencyStore.set(idempotencyKey, response, out);
+    return out;
+  } catch {
+    return failure(ERROR_CODES.INTERNAL_ERROR);
+  }
+}
+
 module.exports = {
   ERROR_CODES,
   HostnameAllowlist,
@@ -325,6 +363,7 @@ module.exports = {
   sanitizeCdata,
   secretMatches,
   siteverify,
+  siteverifyAsync,
   MAX_ACTION_LENGTH,
   MAX_CDATA_LENGTH,
   IDEMPOTENCY_TTL_SECONDS,