@webdecoy/fcaptcha 1.28.1 → 1.29.0

package/config.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const INSECURE_DEFAULT_SECRET = 'dev-secret-change-in-production';
+
+function signingSecretFromEnv(env = process.env) {
+  const secret = String(env.FCAPTCHA_SECRET || '').trim();
+  if (secret && secret !== INSECURE_DEFAULT_SECRET) return secret;
+  if (/^(1|true|yes|on)$/i.test(String(env.FCAPTCHA_INSECURE_DEV_MODE || '').trim())) {
+    console.warn('WARNING: FCAPTCHA_INSECURE_DEV_MODE enabled; tokens use a public signing key. Never expose this server to a network.');
+    return INSECURE_DEFAULT_SECRET;
+  }
+  throw new Error('FCAPTCHA_SECRET is required and must not be the public development key. For local-only development, explicitly set FCAPTCHA_INSECURE_DEV_MODE=1.');
+}
+
+function signingSecret(explicit, env = process.env) {
+  if (explicit !== undefined && explicit !== null) {
+    return signingSecretFromEnv({ ...env, FCAPTCHA_SECRET: explicit });
+  }
+  return signingSecretFromEnv(env);
+}
+
+module.exports = { INSECURE_DEFAULT_SECRET, signingSecret, signingSecretFromEnv };

package/index.js

@@ -13,6 +13,7 @@ const crypto = require('crypto');
 const detection = require('./detection');
 const { ProxyTrust } = require('./clientip');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
+const { signingSecret } = require('./config');
 
 // =============================================================================
 // PoW Challenge Store (can be extended with Redis)
@@ -20,7 +21,7 @@ const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./su
 
 class PoWChallengeStore {
   constructor(options = {}) {
-    this.secret = options.secret || 'dev-secret-change-in-production';
+    this.secret = signingSecret(options.secret);
     this.challenges = new Map();
     this.usedSolutions = new Set();
     this.expirationMs = options.expirationMs || 5 * 60 * 1000; // 5 minutes
@@ -212,7 +213,7 @@ const AUTOMATION_UA_PATTERNS = [
 
 class ScoringEngine {
   constructor(options = {}) {
-    this.secret = options.secret || 'dev-secret-change-in-production';
+    this.secret = signingSecret(options.secret);
     this.powStore = options.powStore || new PoWChallengeStore({ secret: this.secret });
     this.rateLimiter = options.rateLimiter || new RateLimiter();
     this.fingerprintStore = options.fingerprintStore || new FingerprintStore();
@@ -246,6 +247,7 @@ class ScoringEngine {
   // Verify signals and return score
   verify(signals, ip, siteKey, userAgent, headers = {}, powSolution = null) {
     const detections = [];
+    let powSatisfied = false;
 
     // Run all detection modules
     detections.push(...this._detectVisionAI(signals));
@@ -272,6 +274,7 @@ class ScoringEngine {
           reason: `PoW verification failed: ${powResult.reason}`
         });
       } else if (powResult.serverElapsed < BASE_MIN_AGE_MS) {
+        powSatisfied = true;
         // Under the universal baseline nothing legitimate can have happened —
         // no human completes an interaction that fast.
         detections.push({
@@ -281,6 +284,7 @@ class ScoringEngine {
           reason: `Challenge solved too fast (${powResult.serverElapsed}ms server-side)`
         });
       } else if (powResult.serverElapsed < powResult.minAgeMs) {
+        powSatisfied = true;
         // 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
@@ -291,6 +295,8 @@ class ScoringEngine {
           confidence: 0.5,
           reason: `Challenge submitted before the required delay for this source (${powResult.serverElapsed}ms of ${powResult.minAgeMs}ms)`
         });
+      } else {
+        powSatisfied = true;
       }
     } else {
       detections.push({
@@ -336,7 +342,12 @@ class ScoringEngine {
     else if (finalScore < 0.6) recommendation = 'challenge';
     else recommendation = 'block';
 
-    const success = finalScore < 0.5;
+    // PoW is a precondition, not weighted evidence. Expressing a missing or
+    // invalid solution only as a bot-category score lets the category weight
+    // dilute it below the allow threshold and used to mint a token for an empty
+    // request. Keep this gate independent of scoring so weight changes cannot
+    // reopen the bypass.
+    const success = finalScore < 0.5 && powSatisfied;
     const token = success ? this._generateToken(ip, siteKey, finalScore) : null;
 
     // Feed the ledger so the next challenge this source asks for is priced on
@@ -350,7 +361,8 @@ class ScoringEngine {
       timestamp: Math.floor(Date.now() / 1000),
       recommendation,
       categoryScores,
-      detections
+      detections,
+      ...(!powSatisfied ? { reason: 'pow_not_satisfied' } : {})
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.28.1",
+  "version": "1.29.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 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": "node config.test.js && 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 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/server.js

@@ -12,6 +12,7 @@ const detection = require('./detection');
 const webbotauth = require('./webbotauth');
 const { ProxyTrust } = require('./clientip');
 const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
+const { signingSecretFromEnv } = require('./config');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
 const { detectInputForensics } = require('./inputforensics');
 const {
@@ -27,13 +28,16 @@ const {
 
 const app = express();
 app.use(cors());
-app.use(express.json());
+// Captured widget payloads are about 10-15 KiB. Four times that leaves ample
+// room for future signals while bounding work done by the public JSON parsers.
+const MAX_REQUEST_BODY_BYTES = 64 * 1024;
+app.use(express.json({ limit: MAX_REQUEST_BODY_BYTES }));
 // 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 }));
+app.use(express.urlencoded({ extended: false, limit: MAX_REQUEST_BODY_BYTES }));
 
-const SECRET_KEY = process.env.FCAPTCHA_SECRET || 'dev-secret-change-in-production';
+const SECRET_KEY = signingSecretFromEnv();
 
 // 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:
@@ -1787,6 +1791,16 @@ app.get('/api/challenge', (req, res) => {
   });
 });
 
+// Express identifies parser limit failures with status 413 / entity.too.large.
+// Handle them explicitly so all three servers expose the same status instead
+// of falling through to Express's HTML error response.
+app.use((err, req, res, next) => {
+  if (err && (err.status === 413 || err.type === 'entity.too.large')) {
+    return res.status(413).json({ error: 'request_too_large' });
+  }
+  return next(err);
+});
+
 // =============================================================================
 // Start
 // =============================================================================