@webdecoy/fcaptcha 1.39.1 → 1.41.0

package/config.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { EXPERIMENTAL_POLICY } = require('./experimental');
+
 const INSECURE_DEFAULT_SECRET = 'dev-secret-change-in-production';
 
 // The library constructs the secret more than once per process (the challenge
@@ -28,4 +30,12 @@ function signingSecret(explicit, env = process.env) {
   return signingSecretFromEnv(env);
 }
 
-module.exports = { INSECURE_DEFAULT_SECRET, signingSecret, signingSecretFromEnv };
+function experimentalBlockingEnabled(explicit, env = process.env) {
+  if (explicit !== undefined && explicit !== false && typeof explicit !== 'string') {
+    throw new TypeError('experimentalBlocking must be a policy name or false');
+  }
+  const policy = explicit === undefined ? env.FCAPTCHA_EXPERIMENTAL_BLOCKING : explicit;
+  return typeof policy === 'string' && policy.trim() === EXPERIMENTAL_POLICY;
+}
+
+module.exports = { INSECURE_DEFAULT_SECRET, signingSecret, signingSecretFromEnv, experimentalBlockingEnabled };

package/detection.js

@@ -894,16 +894,6 @@ function analyzeWebRTC(webrtcInfo) {
     });
   }
 
-  // Check local IP detection - VMs and some headless setups may not expose local IPs
-  if (webrtcInfo.hasLocalIP === false && !webrtcInfo.localIPError) {
-    detections.push({
-      category: 'headless',
-      score: 0.4,
-      confidence: 0.5,
-      reason: 'No local IP addresses detected via WebRTC'
-    });
-  }
-
   return detections;
 }
 
@@ -956,14 +946,17 @@ function analyzeWorkerConsistency(workerConsistency) {
 
   const detections = [];
 
-  // Mismatches indicate fingerprint spoofing
-  if (!workerConsistency.consistent && workerConsistency.mismatchCount > 0) {
-    const score = Math.min(0.9, 0.3 + (workerConsistency.mismatchCount * 0.15));
+  // Mismatches indicate fingerprint spoofing. hardwareConcurrency is scored
+  // separately (engine.js detectStealthArtifacts); counting it here as well
+  // would count the same mismatch twice.
+  const mismatches = (workerConsistency.mismatches || []).filter((m) => m !== 'hardwareConcurrency');
+  if (!workerConsistency.consistent && mismatches.length > 0) {
+    const score = Math.min(0.9, 0.3 + (mismatches.length * 0.15));
     detections.push({
       category: 'bot',
       score: score,
       confidence: 0.85,
-      reason: `Worker/main thread mismatch detected: ${workerConsistency.mismatches.join(', ')}`
+      reason: `Worker/main thread mismatch detected: ${mismatches.join(', ')}`
     });
   }
 

package/engine.js

@@ -502,6 +502,19 @@ function detectStealthArtifacts(signals) {
     });
   }
 
+  // The page and a Worker disagree on hardwareConcurrency. Stealth tooling
+  // patches the page's value and not the worker's. Contributory only: Chrome's
+  // DevTools hardware-concurrency override produces the same disagreement with
+  // native getters and an attached console, so a developer testing that
+  // setting is indistinguishable from the patch.
+  const worker = env.workerConsistency;
+  if (worker && Array.isArray(worker.mismatches) && worker.mismatches.includes('hardwareConcurrency')) {
+    detections.push({
+      category: 'bot', score: 0.45, confidence: 0.85,
+      reason: 'Page and Worker disagree on hardwareConcurrency'
+    });
+  }
+
   return detections;
 }
 

package/experimental.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { calculateCategoryScores, BEHAVIOURAL_CATEGORIES, CORROBORATION_AGREE_AT,
+  CORROBORATION_FLOOR } = require('./engine');
+
+// Change this ID whenever the policy's evidence, thresholds, or scoring semantics
+// change. An old selector must never silently opt an operator into a new policy.
+const EXPERIMENTAL_POLICY = 'stealth-corroboration-v1';
+const ANIMATION_POLICY = 'animation-consistency-v1';
+
+function animationObservation(signals) {
+  const probe = signals.environmental?.animationConsistency;
+  const realm = (value) => {
+    if (value?.status !== 'ok' || !Array.isArray(value.specified) || value.specified.length !== 3 ||
+        !value.specified.every((n) => n === 1000) || !Array.isArray(value.durations) || value.durations.length !== 3 ||
+        !value.durations.every((row) => Array.isArray(row) && row.length === 4 &&
+          row.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 1e9))) return null;
+    return value.durations.every((row, i) => row.every((n) => n === (i === 2 ? 1000 : 0)));
+  };
+  const main = probe?.version === 1 ? realm(probe.main) : null;
+  const frame = probe?.version === 1 ? realm(probe.iframe) : null;
+  const status = main === null || frame === null ? 'unknown' : main && frame ? 'detected' : 'clear';
+  // Always observe: existing policy selectors must never enable new evidence.
+  return { mode: 'observe', status, detections: status === 'detected' ? [{
+    id: 'animation-timing-inconsistency',
+    reason: 'Browser API timing inconsistency; experimental observation, not proof of automation',
+  }] : [] };
+}
+
+// Observe by default. This intentionally measures a known-ambiguous hypothesis:
+// #87's stealth session and a DevTools hardware override can look identical.
+// Never merge these detections into production scoring or state updates. The
+// server's explicit blocking option adds a separate token gate.
+function evaluateExperimental(signals, productionScore, detections, blocking = false) {
+  const worker = signals.environmental?.workerConsistency;
+  const mismatch = worker?.supported === true && worker.consistent === false &&
+    Array.isArray(worker.mismatches) && worker.mismatches.includes('hardwareConcurrency');
+  const categoryScores = calculateCategoryScores(detections.filter((d) => !d.nonCorroborating));
+  const corroboratingCategories = BEHAVIOURAL_CATEGORIES.filter(
+    (c) => (categoryScores[c] || 0) >= CORROBORATION_AGREE_AT - 1e-9);
+  const score = mismatch && corroboratingCategories.length > 0
+    ? Math.max(productionScore, CORROBORATION_FLOOR) : productionScore;
+  return {
+    mode: blocking ? 'block' : 'observe',
+    policy: EXPERIMENTAL_POLICY,
+    score,
+    // Score threshold only; this is not a hypothetical PoW/hostname/rate verdict.
+    wouldBlock: score >= 0.5,
+    detections: mismatch ? [{
+      id: 'worker-hardware-concurrency-mismatch',
+      reason: 'Page and Worker disagree on hardwareConcurrency; also possible with DevTools or privacy tools',
+    }] : [],
+    corroboratingCategories,
+    observations: { [ANIMATION_POLICY]: animationObservation(signals) },
+  };
+}
+
+module.exports = { evaluateExperimental, EXPERIMENTAL_POLICY };

package/index.js

@@ -13,7 +13,7 @@ const crypto = require('crypto');
 const detection = require('./detection');
 const { ProxyTrust, networkIdentity } = require('./clientip');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
-const { signingSecret } = require('./config');
+const { signingSecret, experimentalBlockingEnabled } = require('./config');
 const { AdmissionLimiter, ChallengeMap } = require('./admission');
 const { ipBinding } = require('./ip-binding');
 const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
@@ -194,9 +194,11 @@ const {
   widgetInstance, deviceRateKey, deviceRateDetection, DEVICE_VERIFICATIONS_PER_MINUTE
 } = require('./engine');
 const { detectInputForensics } = require('./inputforensics');
+const { evaluateExperimental } = require('./experimental');
 
 class ScoringEngine {
   constructor(options = {}) {
+    this.experimentalBlocking = experimentalBlockingEnabled(options.experimentalBlocking);
     this.secret = signingSecret(options.secret);
     this.powStore = options.powStore || new PoWChallengeStore({ secret: this.secret });
     this.rateLimiter = options.rateLimiter || new RateLimiter();
@@ -364,8 +366,11 @@ class ScoringEngine {
       detections
     );
 
+    const experimental = evaluateExperimental(signals, finalScore, detections, this.experimentalBlocking);
+    const experimentalBlocked = this.experimentalBlocking && experimental.wouldBlock && finalScore < 0.5;
     let recommendation;
-    if (finalScore < 0.3) recommendation = 'allow';
+    if (experimentalBlocked) recommendation = 'block';
+    else if (finalScore < 0.3) recommendation = 'allow';
     else if (finalScore < 0.6) recommendation = 'challenge';
     else recommendation = 'block';
 
@@ -374,7 +379,7 @@ class ScoringEngine {
     // 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 && !deviceRateExceeded;
+    const success = finalScore < 0.5 && powSatisfied && !deviceRateExceeded && !experimentalBlocked;
     const token = success ? this._generateToken(ip, siteKey, finalScore) : null;
 
     // Feed the ledger so the next challenge this source asks for is priced on
@@ -384,12 +389,14 @@ class ScoringEngine {
     return {
       success,
       score: finalScore,
+      experimental,
       token,
       timestamp: Math.floor(Date.now() / 1000),
       recommendation,
       categoryScores,
       detections,
-      ...(deviceRateExceeded ? { reason: 'rate_limited' } : !powSatisfied ? { reason: 'pow_not_satisfied' } : {})
+      ...(deviceRateExceeded ? { reason: 'rate_limited' } : !powSatisfied ? { reason: 'pow_not_satisfied' }
+        : experimentalBlocked ? { reason: 'experimental_detection' } : {})
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.39.1",
+  "version": "1.41.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 redis-state.test.js && node index.test.js && node --test admission.test.js suspicion.test.js security.test.js corroboration.test.js device-rate.test.js keyboard-exemption.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 admission.test.js suspicion.test.js security.test.js corroboration.test.js device-rate.test.js keyboard-exemption.test.js experimental.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,7 +12,7 @@ const detection = require('./detection');
 const webbotauth = require('./webbotauth');
 const { ProxyTrust, networkIdentity } = require('./clientip');
 const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
-const { signingSecretFromEnv } = require('./config');
+const { signingSecretFromEnv, experimentalBlockingEnabled } = require('./config');
 const { AdmissionLimiter, ChallengeMap } = require('./admission');
 const { ipBinding } = require('./ip-binding');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
@@ -43,6 +43,7 @@ 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 EXPERIMENTAL_BLOCKING_ENABLED = experimentalBlockingEnabled();
 const REDIS_URL = process.env.REDIS_URL || '';
 const SHARED_STATE = REDIS_URL ? new RedisState(REDIS_URL) : null;
 
@@ -144,6 +145,7 @@ function logVerdict(endpoint, siteKey, result) {
     siteKey,
     success: result.success,
     score: result.score,
+    experimental: result.experimental,
     recommendation: result.recommendation,
     categoryScores: result.categoryScores,
     detections: (result.detections || []).map((d) => {
@@ -375,6 +377,7 @@ const {
   applyCorroborationFloor,
   widgetInstance, deviceRateKey, deviceRateDetection, DEVICE_VERIFICATIONS_PER_MINUTE
 } = require('./engine');
+const { evaluateExperimental } = require('./experimental');
 
 // Stateful detectors stay here: they read the module-level stores below.
 async function detectFingerprint(signals, ip, siteKey) {
@@ -748,8 +751,11 @@ async function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja
     detections
   );
 
+  const experimental = evaluateExperimental(signals, finalScore, detections, EXPERIMENTAL_BLOCKING_ENABLED);
+  const experimentalBlocked = EXPERIMENTAL_BLOCKING_ENABLED && experimental.wouldBlock && finalScore < 0.5;
   let recommendation;
-  if (finalScore < 0.3) recommendation = 'allow';
+  if (experimentalBlocked) recommendation = 'block';
+  else if (finalScore < 0.3) recommendation = 'allow';
   else if (finalScore < 0.6) recommendation = 'challenge';
   else recommendation = 'block';
 
@@ -764,14 +770,14 @@ async function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja
   // its own reason rather than smuggled in as a bot verdict.
   const hostnameAllowed = ALLOWED_HOSTNAMES.permits(hostname);
 
-  // Three independent conditions, deliberately not folded into the score.
+  // Independent gates, deliberately not folded into the baseline score.
   //
   // powSatisfied is the one that matters most: a score threshold answers "how
   // suspicious is this visitor", which is the wrong question to ask of someone
   // who never completed the challenge. Gating here means no future reweighting
   // can reopen the bypass, and it holds even if the dispositive floor is
   // lowered or removed.
-  const success = finalScore < 0.5 && hostnameAllowed && powSatisfied && !deviceRateExceeded;
+  const success = finalScore < 0.5 && hostnameAllowed && powSatisfied && !deviceRateExceeded && !experimentalBlocked;
 
   // Name the failed precondition whenever one fails, not only when the score
   // would otherwise have allowed. Gating it on the score made the PoW case
@@ -783,6 +789,7 @@ async function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja
   if (deviceRateExceeded) withheldReason = 'rate_limited';
   else if (!powSatisfied) withheldReason = 'pow_not_satisfied';
   else if (!hostnameAllowed) withheldReason = 'hostname_not_allowed';
+  else if (experimentalBlocked) withheldReason = 'experimental_detection';
 
   const token = success
     ? generateToken(ip, siteKey, finalScore, {
@@ -799,6 +806,7 @@ async function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja
   return {
     success,
     score: finalScore,
+    experimental,
     token,
     timestamp: Math.floor(Date.now() / 1000),
     recommendation,
@@ -907,6 +915,7 @@ app.post('/api/score', validateScoringRequest, asyncRoute(async (req, res) => {
   res.json({
     success: result.success,
     score: result.score,
+    experimental: result.experimental,
     token: result.token,
     // 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.