@webdecoy/fcaptcha 1.46.2 → 1.47.0

package/README.md

@@ -15,14 +15,21 @@ const { createScoringEngine } = require('@webdecoy/fcaptcha');
 
 // Create a scoring engine
 const engine = createScoringEngine({
-  secret: process.env.FCAPTCHA_SECRET
+  secret: process.env.FCAPTCHA_SECRET,
+  // Required for multiple processes or replicas: provide one implementation
+  // whose claim(signature) operation is atomic and shared (for example Redis).
+  tokenStore: sharedTokenStore
 });
 
 // Generate a PoW challenge
 const challenge = engine.generateChallenge('my-site', clientIP);
 
 // Verify a submission
-const result = engine.verify(signals, clientIP, siteKey, userAgent, headers, powSolution);
+const result = engine.verify(
+  signals, clientIP, siteKey, userAgent, headers, powSolution,
+  signalsJson, powTiming,
+  { hostname: 'app.example.com', action: 'login', cdata: sessionId }
+);
 
 if (result.success) {
   // User passed verification
@@ -31,6 +38,17 @@ if (result.success) {
 }
 ```
 
+Engines in one Node process share the default replay store. Multiple processes
+or replicas must inject one shared atomic `tokenStore`; otherwise no in-memory
+implementation can enforce one-time redemption across them.
+
+`createMiddleware()` binds tokens to the request `Origin`/`Referer` and the
+submitted `action`/`cdata`. Its `tokenVerifyHandler` is server-to-server and
+requires `secret` in the request body. Set `verifySecret` in middleware options
+to split that credential from the signing secret. A relying backend must compare
+the returned `hostname` and `action` with the values expected for the protected
+operation before granting it.
+
 ## Features
 
 - **Proof of Work** - SHA-256 challenges that force compute cost on attackers
@@ -47,6 +65,7 @@ const {
   PoWChallengeStore,    // Challenge storage
   RateLimiter,          // Rate limiting
   FingerprintStore,     // Fingerprint tracking
+  TokenStore,           // Process-local replay store / custom-store interface
   detection,            // Detection utilities
   createScoringEngine,  // Factory function
   createMiddleware,     // Express middleware factory

package/clientip.js

@@ -9,8 +9,8 @@
  * credible only when the peer that sent them is a proxy we put there.
  *
  * TRUSTED_PROXIES holds the peers allowed to speak for someone else, as a
- * comma-separated list of CIDRs and bare IPs. Unset means the private and
- * loopback defaults below. '*' trusts every peer (only correct when an edge you
+ * comma-separated list of CIDRs and bare IPs. Unset trusts loopback only.
+ * '*' trusts every peer (only correct when an edge you
  * control always overwrites the headers). 'none' trusts nobody, so the socket
  * address is always used.
  */
@@ -18,21 +18,13 @@
 const ipaddr = require('ipaddr.js');
 
 /**
- * Fallback trust set: loopback plus the private and link-local ranges. A server
- * exposed directly to the internet sees public peer addresses, which are not in
- * this set, so forged headers are ignored. A server behind a sidecar or
- * in-cluster reverse proxy (nginx, Railway, Fly, Kubernetes ingress) sees a
- * loopback or private peer and behaves as before.
+ * Fallback trust is deliberately loopback-only. Private address space is shared
+ * by unrelated workloads in common clusters and must be explicitly narrowed to
+ * the actual ingress or sidecar ranges.
  */
 const DEFAULT_TRUSTED_PROXY_CIDRS = [
   '127.0.0.0/8',
-  '::1/128',
-  '10.0.0.0/8',
-  '172.16.0.0/12',
-  '192.168.0.0/16',
-  '169.254.0.0/16',
-  'fe80::/10',
-  'fc00::/7'
+  '::1/128'
 ];
 
 // hostOnly strips a trailing :port or wrapping brackets. Node's

package/index.js

@@ -6,7 +6,8 @@
  * Usage:
  *   const fcaptcha = require('@webdecoy/fcaptcha');
  *   const engine = fcaptcha.createScoringEngine({ secret: 'your-secret' });
- *   const result = engine.verify(signals, ip, siteKey, userAgent, headers, powSolution, signalsJson, powTiming);
+ *   const result = engine.verify(signals, ip, siteKey, userAgent, headers,
+ *     powSolution, signalsJson, powTiming, { hostname, action, cdata });
  */
 
 const crypto = require('crypto');
@@ -20,6 +21,13 @@ const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
 const { FingerprintStore } = require('./fingerprint-store');
 const { TokenStore } = require('./token-store');
 const { resolveSignals } = require('./protocol');
+const { requestHostname, sanitizeAction, sanitizeCdata, secretMatches } = require('./siteverify');
+const { canonicalTokenPayload } = require('./token-canonical');
+
+// Independent engines in one process are equivalent redemption authorities.
+// Sharing the default store prevents a token from being spent once per engine.
+// Multi-process/replica deployments must still inject one atomic shared store.
+const DEFAULT_TOKEN_STORE = new TokenStore();
 
 // =============================================================================
 // PoW Challenge Store (can be extended with Redis)
@@ -205,7 +213,10 @@ 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();
+    this.tokenStore = options.tokenStore || DEFAULT_TOKEN_STORE;
+    this.verifySecret = options.verifySecret === undefined
+      ? this.secret
+      : signingSecret(options.verifySecret);
   }
 
   // Generate a PoW challenge
@@ -232,7 +243,7 @@ class ScoringEngine {
   }
 
   // Verify signals and return score
-  verify(signals, ip, siteKey, userAgent, headers = {}, powSolution = null, signalsJson = null, powTiming = null) {
+  verify(signals, ip, siteKey, userAgent, headers = {}, powSolution = null, signalsJson = null, powTiming = null, binding = {}) {
     const resolved = resolveSignals(signals, signalsJson, powSolution?.signalsHash);
     signals = resolved.signals;
     if (powTiming) {
@@ -380,7 +391,7 @@ class ScoringEngine {
     // request. Keep this gate independent of scoring so weight changes cannot
     // reopen the bypass.
     const success = finalScore < 0.5 && powSatisfied && !deviceRateExceeded && !experimentalBlocked;
-    const token = success ? this._generateToken(ip, siteKey, finalScore) : null;
+    const token = success ? this._generateToken(ip, siteKey, finalScore, binding) : null;
 
     // Feed the ledger so the next challenge this source asks for is priced on
     // what it just did.
@@ -412,7 +423,7 @@ class ScoringEngine {
       const sig = decoded.sig;
       delete decoded.sig;
 
-      const payload = JSON.stringify(decoded, Object.keys(decoded).sort());
+      const payload = canonicalTokenPayload(decoded);
       const expectedSig = crypto.createHmac('sha256', this.secret).update(payload).digest('hex');
 
       if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) {
@@ -505,17 +516,21 @@ class ScoringEngine {
     return detections;
   }
 
-  _generateToken(ip, siteKey, score) {
+  _generateToken(ip, siteKey, score, binding = {}) {
     const ipHash = ipBinding(this.secret, ip);
     const data = {
+      v: 2,
       site_key: siteKey,
       jti: crypto.randomBytes(16).toString('hex'),
       timestamp: Math.floor(Date.now() / 1000),
       score: Math.round(score * 1000) / 1000,
-      ip_hash: ipHash
+      ip_hash: ipHash,
+      hostname: typeof binding.hostname === 'string' ? binding.hostname : '',
+      action: sanitizeAction(binding.action),
+      cdata: sanitizeCdata(binding.cdata)
     };
 
-    const payload = JSON.stringify(data, Object.keys(data).sort());
+    const payload = canonicalTokenPayload(data);
     const sig = crypto.createHmac('sha256', this.secret).update(payload).digest('hex');
     data.sig = sig;
 
@@ -540,7 +555,7 @@ function createMiddleware(options = {}) {
 
     // Middleware to extract IP from request. Forwarding headers are honoured
     // only from a peer in the trusted-proxy set (TRUSTED_PROXIES, or the
-    // private/loopback defaults) — otherwise any caller could claim a clean
+    // loopback-only default) — otherwise any caller could claim a clean
     // residential IP and skip the datacenter, Tor/VPN and rate-limit checks.
     // Pass options.trustedProxies to override the env for this instance.
     getIP: (req) => proxyTrust.clientIP(req),
@@ -565,7 +580,7 @@ function createMiddleware(options = {}) {
 
     // Verify route handler
     verifyHandler: (req, res) => {
-      const { siteKey: rawSiteKey, signals, powSolution, signalsJson, powTiming } = req.body;
+      const { siteKey: rawSiteKey, signals, powSolution, signalsJson, powTiming, action, cdata } = 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'] || '';
@@ -575,13 +590,21 @@ function createMiddleware(options = {}) {
         headers[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
       }
 
-      const result = engine.verify(signals, ip, siteKey, userAgent, headers, powSolution, signalsJson, powTiming);
+      const result = engine.verify(signals, ip, siteKey, userAgent, headers, powSolution, signalsJson, powTiming, {
+        hostname: requestHostname(headers),
+        action: sanitizeAction(action),
+        cdata: sanitizeCdata(cdata)
+      });
       res.json(result);
     },
 
     // Token verify route handler
     tokenVerifyHandler: (req, res) => {
-      const { token, remoteip } = req.body;
+      const { token, secret, remoteip } = req.body || {};
+      if (!secret) return res.status(401).json({ valid: false, reason: 'missing_secret' });
+      if (!secretMatches(secret, engine.verifySecret)) {
+        return res.status(401).json({ valid: false, reason: 'invalid_secret' });
+      }
       res.json(engine.verifyToken(token, typeof remoteip === 'string' ? remoteip : null));
     }
   };
@@ -597,6 +620,7 @@ module.exports = {
   PoWChallengeStore,
   RateLimiter,
   FingerprintStore,
+  TokenStore,
 
   // Detection module (re-export)
   detection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.46.2",
+  "version": "1.47.0",
   "description": "Open source CAPTCHA with PoW, bot detection, and Vision AI protection",
   "main": "index.js",
   "exports": {

package/server.js

@@ -20,6 +20,7 @@ const { detectInputForensics } = require('./inputforensics');
 const { RedisState } = require('./redis-state');
 const { FingerprintStore } = require('./fingerprint-store');
 const { TokenStore } = require('./token-store');
+const { canonicalTokenPayload } = require('./token-canonical');
 const { resolveSignals, isObject, invalidRequest } = require('./protocol');
 const {
   HostnameAllowlist,
@@ -457,13 +458,12 @@ async function detectRateAbuse(ip, siteKey) {
 // 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.
+// Empty strings rather than omitted keys keep one fixed signed claim set across
+// all three runtimes.
 function generateToken(ip, siteKey, score, binding = {}) {
   const ipHash = ipBinding(SECRET_KEY, ip);
   const data = {
+    v: 2,
     site_key: siteKey,
     jti: crypto.randomBytes(16).toString('hex'),
     timestamp: Math.floor(Date.now() / 1000),
@@ -474,7 +474,7 @@ function generateToken(ip, siteKey, score, binding = {}) {
     cdata: binding.cdata || ''
   };
 
-  const payload = JSON.stringify(data, Object.keys(data).sort());
+  const payload = canonicalTokenPayload(data);
   data.sig = crypto.createHmac('sha256', SECRET_KEY).update(payload).digest('hex');
 
   return Buffer.from(JSON.stringify(data)).toString('base64url');
@@ -492,7 +492,7 @@ async function verifyToken(token, ip = null) {
     const sig = decoded.sig;
     delete decoded.sig;
 
-    const payload = JSON.stringify(decoded, Object.keys(decoded).sort());
+    const payload = canonicalTokenPayload(decoded);
     const expectedSig = crypto.createHmac('sha256', SECRET_KEY).update(payload).digest('hex');
 
     if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) {

package/token-canonical.js

@@ -0,0 +1,32 @@
+'use strict';
+
+function encodedString(value, field) {
+  if (typeof value !== 'string') throw new TypeError(`${field} must be a string`);
+  return Buffer.from(value, 'utf8').toString('base64url');
+}
+
+/**
+ * Version 2 signs a language-neutral, length-safe representation instead of
+ * reserializing JSON. Native JSON encoders disagree on integral floats and on
+ * escaping Unicode/HTML-sensitive strings, which broke mixed-runtime pools.
+ * Tokens without v=2 retain the legacy canonicalization for a rolling upgrade.
+ */
+function canonicalTokenPayload(data) {
+  if (data.v !== 2) return JSON.stringify(data, Object.keys(data).sort());
+  if (!Number.isSafeInteger(data.timestamp)) throw new TypeError('timestamp must be an integer');
+  if (typeof data.score !== 'number' || !Number.isFinite(data.score)) throw new TypeError('score must be finite');
+
+  return [
+    'fcaptcha-token-v2',
+    encodedString(data.site_key, 'site_key'),
+    encodedString(data.jti, 'jti'),
+    String(data.timestamp),
+    data.score.toFixed(3),
+    encodedString(data.ip_hash, 'ip_hash'),
+    encodedString(data.hostname, 'hostname'),
+    encodedString(data.action, 'action'),
+    encodedString(data.cdata, 'cdata')
+  ].join('\n');
+}
+
+module.exports = { canonicalTokenPayload };