@webdecoy/fcaptcha 1.12.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.12.0",
+  "version": "1.13.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
@@ -1168,6 +1205,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 +1229,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,