@webdecoy/fcaptcha 1.21.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Open source CAPTCHA with PoW, bot detection, and Vision AI protection",
   "main": "index.js",
   "exports": {
@@ -15,7 +15,8 @@
     "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 && node --test suspicion.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"
   },

package/server.js

@@ -14,12 +14,49 @@ 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();
 
@@ -1184,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());
@@ -1234,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 };
@@ -1433,8 +1490,25 @@ 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.
@@ -1447,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 })
   };
 }
 
@@ -1475,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);
@@ -1491,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'] || '';
@@ -1512,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);
@@ -1532,6 +1623,30 @@ 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);

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