@webdecoy/fcaptcha 1.12.0 → 1.14.0

package/package.json

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

package/server.js

@@ -18,6 +18,43 @@ const SECRET_KEY = process.env.FCAPTCHA_SECRET || 'dev-secret-change-in-producti
 const PORT = process.env.PORT || 3000;
 const TRUSTED_JA4_HEADERS = detection.getTrustedJA4HeaderNames();
 
+// Verdict logging is off by default: a self-hosted FCaptcha emits no per-request
+// logs unless the operator opts in via FCAPTCHA_LOG_VERDICTS (1/true/yes/on).
+// When on, each /api/verify and /api/score logs one privacy-safe JSON line
+// (score, recommendation, category scores, and per-hit category/score/confidence)
+// for observability and tuning. It deliberately omits IP, user agent, raw
+// signals, and the free-text detection `reason`, which can interpolate
+// visitor-derived data (reverse-DNS hostname, UA/header fragments, field ids).
+//
+// FCAPTCHA_LOG_VERDICTS_INCLUDE_RAW additionally includes that free-text reason.
+// Separate and off by default because reasons can carry visitor-derived data —
+// only enable in trusted debugging contexts with no privacy obligations.
+const envFlag = (name) => ['1', 'true', 'yes', 'on']
+  .includes(String(process.env[name] || '').trim().toLowerCase());
+const VERDICT_LOGGING_ENABLED = envFlag('FCAPTCHA_LOG_VERDICTS');
+const VERDICT_LOG_INCLUDE_RAW = envFlag('FCAPTCHA_LOG_VERDICTS_INCLUDE_RAW');
+if (VERDICT_LOGGING_ENABLED && VERDICT_LOG_INCLUDE_RAW) {
+  console.warn('WARNING: FCAPTCHA_LOG_VERDICTS_INCLUDE_RAW enabled — verdict logs include free-text detection reasons that may contain visitor-derived data (hostnames, UA/header fragments, field ids). Do not enable where you have privacy obligations.');
+}
+
+function logVerdict(endpoint, siteKey, result) {
+  if (!VERDICT_LOGGING_ENABLED || !result) return;
+  console.log(JSON.stringify({
+    event: 'verdict',
+    endpoint,
+    siteKey,
+    success: result.success,
+    score: result.score,
+    recommendation: result.recommendation,
+    categoryScores: result.categoryScores,
+    detections: (result.detections || []).map((d) => {
+      const det = { category: d.category, score: d.score, confidence: d.confidence };
+      if (VERDICT_LOG_INCLUDE_RAW) det.reason = d.reason;
+      return det;
+    })
+  }));
+}
+
 // Serve the browser widget alongside the API so deployments expose a single
 // origin to integrators (the implicit contract behind <serverUrl>/fcaptcha.js).
 // Set FCAPTCHA_SERVE_CLIENT=false to opt out — useful when hosting the widget
@@ -458,6 +495,39 @@ function detectHeadless(signals, userAgent) {
   return detections;
 }
 
+// Flags anti-detection patch traces collected by the client. FALSE-POSITIVE-
+// SAFE: a genuine browser never produces these (internal contradictions /
+// native-function tampering, not environment-shape heuristics that would
+// misfire on real Linux/VPN users). Targets stealth agents (e.g. Manus AI)
+// driving real-but-patched Chromium. Only the two FP-safe signals are scored;
+// the client also collects privacy-extension-ambiguous artifacts (patched_*)
+// for observability that are intentionally NOT scored. Keep in sync with Go/Py.
+function detectStealthArtifacts(signals) {
+  const detections = [];
+  const env = signals.environmental || {};
+
+  // Function.prototype.toString proxied — the signature move of stealth
+  // frameworks (used to make their other native overrides look untouched).
+  const artifactSignals = (env.stealthArtifacts && env.stealthArtifacts.signals) || [];
+  if (artifactSignals.includes('tostring_proxied')) {
+    detections.push({
+      category: 'headless', score: 0.9, confidence: 0.85,
+      reason: 'Function.prototype.toString is proxied (stealth automation patch)'
+    });
+  }
+
+  // Notification.permission === 'denied' while the Permissions API reports
+  // 'prompt': a state a real browser cannot reach (classic headless tell).
+  if (env.permissionProbe && env.permissionProbe.contradiction === true) {
+    detections.push({
+      category: 'headless', score: 0.85, confidence: 0.85,
+      reason: 'Notification permission contradicts Permissions API (headless/stealth tell)'
+    });
+  }
+
+  return detections;
+}
+
 function detectAutomation(signals) {
   const detections = [];
   const env = signals.environmental || {};
@@ -1061,6 +1131,7 @@ function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash
   detections.push(
     ...detectVisionAI(signals),
     ...detectHeadless(signals, userAgent),
+    ...detectStealthArtifacts(signals),
     ...detectAutomation(signals),
     ...detectCDP(signals),
     ...detectBehavioral(signals),
@@ -1168,6 +1239,7 @@ app.post('/api/verify', (req, res) => {
   }
 
   const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming);
+  logVerdict('verify', siteKey, result);
   res.json(result);
 });
 
@@ -1191,6 +1263,7 @@ app.post('/api/score', (req, res) => {
   }
 
   const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming);
+  logVerdict('score', siteKey, result);
   res.json({
     success: result.success,
     score: result.score,