@webdecoy/fcaptcha 1.14.0 → 1.16.0

package/clientip.js

@@ -0,0 +1,229 @@
+/**
+ * Client IP resolution.
+ *
+ * Every IP-derived signal in FCaptcha — datacenter ranges, Tor/VPN, rate
+ * limiting, token IP binding, PoW difficulty — is only as trustworthy as the
+ * address it is handed. X-Forwarded-For and X-Real-IP are set by whoever is on
+ * the other end of the socket, so honouring them unconditionally lets any
+ * caller claim a clean residential IP and walk past all of it. They are
+ * credible only when the peer that sent them is a proxy we put there.
+ *
+ * TRUSTED_PROXIES holds the peers allowed to speak for someone else, as a
+ * comma-separated list of CIDRs and bare IPs. Unset means the private and
+ * loopback defaults below. '*' trusts every peer (only correct when an edge you
+ * control always overwrites the headers). 'none' trusts nobody, so the socket
+ * address is always used.
+ */
+
+const ipaddr = require('ipaddr.js');
+
+/**
+ * Fallback trust set: loopback plus the private and link-local ranges. A server
+ * exposed directly to the internet sees public peer addresses, which are not in
+ * this set, so forged headers are ignored. A server behind a sidecar or
+ * in-cluster reverse proxy (nginx, Railway, Fly, Kubernetes ingress) sees a
+ * loopback or private peer and behaves as before.
+ */
+const DEFAULT_TRUSTED_PROXY_CIDRS = [
+  '127.0.0.0/8',
+  '::1/128',
+  '10.0.0.0/8',
+  '172.16.0.0/12',
+  '192.168.0.0/16',
+  '169.254.0.0/16',
+  'fe80::/10',
+  'fc00::/7'
+];
+
+// hostOnly strips a trailing :port or wrapping brackets. Node's
+// socket.remoteAddress carries no port, but X-Forwarded-For hops sometimes do.
+function hostOnly(value) {
+  const s = String(value).trim();
+  if (s.startsWith('[')) {
+    const end = s.indexOf(']');
+    return end === -1 ? s : s.slice(1, end);
+  }
+  // A bare IPv6 address has several colons; only strip a port from host:port.
+  const first = s.indexOf(':');
+  if (first !== -1 && s.indexOf(':', first + 1) === -1) return s.slice(0, first);
+  return s;
+}
+
+// normalizeIP validates an address and renders IPv4-mapped IPv6
+// (::ffff:1.2.3.4) in dotted form, so the CIDR checks in detection.js match
+// either spelling. Returns null when the value is not an IP.
+function normalizeIP(value) {
+  if (!value) return null;
+  try {
+    return ipaddr.process(hostOnly(value)).toString();
+  } catch {
+    return null;
+  }
+}
+
+// Node merges repeated headers into one comma-joined string for everything
+// except set-cookie, but accept an array defensively.
+function headerValue(req, name) {
+  const raw = req.headers?.[name];
+  if (Array.isArray(raw)) return raw.join(',');
+  return raw || '';
+}
+
+// Bounds the misconfiguration hint below. A directly exposed server sees spoof
+// attempts continuously, and that is working as intended — the operator needs
+// the hint once, not a running commentary.
+const MAX_PROXY_MISCONFIG_WARNINGS = 10;
+
+/** Decides which peers may set client-identifying headers. */
+class ProxyTrust {
+  /**
+   * @param {string} spec comma-separated CIDRs and bare IPs, or '*' / 'none'.
+   * Invalid entries are warned about and skipped rather than thrown: a typo in
+   * one entry should narrow trust, not take the server down.
+   */
+  constructor(spec) {
+    this.trustAll = false;
+    this.ranges = [];
+    this.warnings = 0;
+
+    for (const raw of String(spec ?? '').split(',')) {
+      const entry = raw.trim();
+      if (!entry || entry.toLowerCase() === 'none') continue;
+      if (entry === '*') {
+        this.trustAll = true;
+        continue;
+      }
+      try {
+        if (entry.includes('/')) {
+          this.ranges.push(ipaddr.parseCIDR(entry));
+        } else {
+          // A bare IP is a single-host range.
+          const addr = ipaddr.process(entry);
+          this.ranges.push([addr, addr.kind() === 'ipv4' ? 32 : 128]);
+        }
+      } catch {
+        console.warn(`warning: ignoring invalid TRUSTED_PROXIES entry "${raw}"`);
+      }
+    }
+  }
+
+  /** Builds the trust set from TRUSTED_PROXIES, defaulting when unset. An
+   * explicitly empty value means "trust nothing", so unset and empty differ. */
+  static fromEnv(env = process.env) {
+    const spec = env.TRUSTED_PROXIES === undefined
+      ? DEFAULT_TRUSTED_PROXY_CIDRS.join(',')
+      : env.TRUSTED_PROXIES;
+    return new ProxyTrust(spec);
+  }
+
+  /** Renders the trust set for the startup log. */
+  describe() {
+    if (this.trustAll) return '* (all peers)';
+    if (this.ranges.length === 0) return 'none (forwarding headers ignored)';
+    return this.ranges.map(([addr, bits]) => `${addr.toString()}/${bits}`).join(', ');
+  }
+
+  /** Reports whether an address belongs to a configured proxy. */
+  trusts(ip) {
+    if (!ip) return false;
+    if (this.trustAll) return true;
+    let addr;
+    try {
+      addr = ipaddr.process(ip);
+    } catch {
+      return false;
+    }
+    for (const range of this.ranges) {
+      // match() throws when the address families differ, so skip those.
+      if (range[0].kind() !== addr.kind()) continue;
+      if (addr.match(range)) return true;
+    }
+    return false;
+  }
+
+  /** Reports whether the immediate peer may speak for another client. */
+  peerTrusted(req) {
+    return this.trusts(normalizeIP(req.socket?.remoteAddress));
+  }
+
+  /**
+   * Returns a header value only when the peer is a trusted proxy, and ''
+   * otherwise. Used for X-JA3-Hash: a client free to state its own TLS
+   * fingerprint would just present a stock Chrome one and erase the signal.
+   */
+  trustedHeader(req, name) {
+    if (!this.peerTrusted(req)) return '';
+    return headerValue(req, name);
+  }
+
+  /**
+   * Flags the one misconfiguration this design can cause. A peer that sends
+   * forwarding headers but is not in the trust set is either a real reverse
+   * proxy the operator forgot to list — in which case every visitor is now
+   * collapsed onto that proxy's address, silently wrecking rate limiting and IP
+   * reputation — or a client spoofing them, which is exactly what we want
+   * ignored. The two are indistinguishable here, so say both and name the peer
+   * so it can be pasted into TRUSTED_PROXIES.
+   */
+  _warnUntrustedForwarding(peer, req) {
+    if (!headerValue(req, 'x-forwarded-for') && !headerValue(req, 'x-real-ip')) return;
+    if (this.warnings >= MAX_PROXY_MISCONFIG_WARNINGS) return;
+    this.warnings++;
+    const suffix = this.warnings === MAX_PROXY_MISCONFIG_WARNINGS
+      ? ' (further warnings suppressed)'
+      : '';
+    console.warn(
+      `warning: ignoring forwarding headers from untrusted peer ${peer}. ` +
+      `If that is your reverse proxy, add it to TRUSTED_PROXIES — until then every ` +
+      `visitor is attributed to ${peer}. If not, a client is spoofing them and they ` +
+      `are correctly ignored.${suffix}`
+    );
+  }
+
+  /**
+   * Resolves the address to attribute the request to. Forwarding headers are
+   * read only when the peer is trusted; otherwise the socket address wins.
+   */
+  clientIP(req) {
+    const peer = normalizeIP(req.socket?.remoteAddress);
+    // No usable socket address means nothing to trust and nothing to forward.
+    if (!peer) return '127.0.0.1';
+    if (!this.trusts(peer)) {
+      this._warnUntrustedForwarding(peer, req);
+      return peer;
+    }
+
+    // A trusted proxy sets X-Real-IP to the address it accepted the connection
+    // from, so it needs no chain walking.
+    const realIP = normalizeIP(headerValue(req, 'x-real-ip'));
+    if (realIP) return realIP;
+
+    // Otherwise walk X-Forwarded-For right to left. Each proxy appends the peer
+    // it saw, so the rightmost entries are the ones our own infrastructure
+    // wrote. The first entry that is not a proxy we trust is the closest thing
+    // to a real client; everything to its left was supplied by that client and
+    // cannot be believed.
+    const forwarded = headerValue(req, 'x-forwarded-for');
+    if (forwarded) {
+      const parts = forwarded.split(',');
+      for (let i = parts.length - 1; i >= 0; i--) {
+        const entry = parts[i].trim();
+        if (!entry) continue;
+        const ip = normalizeIP(entry);
+        // A malformed hop makes everything to its left unreadable, so stop and
+        // fall back to the peer rather than guess.
+        if (!ip) break;
+        if (this.trusts(ip)) continue;
+        return ip;
+      }
+    }
+
+    return peer;
+  }
+}
+
+module.exports = {
+  ProxyTrust,
+  DEFAULT_TRUSTED_PROXY_CIDRS,
+  normalizeIP
+};

package/detection.js

@@ -131,10 +131,16 @@ const DECLARED_AI_AGENT_PATTERNS = [
   /\bYouBot\b/i
 ];
 
-// checkDeclaredAIAgent flags self-identifying AI agents via the User-Agent and
-// detects Web Bot Auth signed requests (RFC 9421 HTTP Message Signatures). Both
-// are high-confidence identifications surfaced as the declared_ai category so
-// callers can apply an allow/block policy instead of relying on a hard score.
+// checkDeclaredAIAgent flags self-identifying AI agents via the User-Agent as
+// the declared_ai category, so callers can apply an allow/block policy instead
+// of relying on a hard score.
+//
+// Web Bot Auth signed requests (RFC 9421 HTTP Message Signatures) used to be
+// detected here by header presence alone. That moved to webbotauth.js, which
+// cryptographically verifies the signature against the agent's published key
+// directory — a presence check can't tell a real signer from three spoofed
+// headers. Verification needs the raw request, so it runs in the route handler;
+// the headers argument is retained for signature parity with the Go server.
 function checkDeclaredAIAgent(userAgent, headers = {}) {
   const detections = [];
   const ua = userAgent || '';
@@ -153,20 +159,6 @@ function checkDeclaredAIAgent(userAgent, headers = {}) {
     }
   }
 
-  // Web Bot Auth: presence of HTTP Message Signature headers identifies a
-  // (claimed) verified agent. v1 detects/identifies only; signature verification
-  // against the agent's published JWKS is a follow-up before trusting it.
-  const h = headers || {};
-  if (h['signature'] && h['signature-input'] && h['signature-agent']) {
-    detections.push({
-      category: 'declared_ai',
-      score: 0.4,
-      confidence: 0.95,
-      reason: `Signed agent request (Web Bot Auth): ${h['signature-agent']}`,
-      details: { signatureAgent: h['signature-agent'], verified: false }
-    });
-  }
-
   return detections;
 }
 

package/index.js

@@ -11,6 +11,7 @@
 
 const crypto = require('crypto');
 const detection = require('./detection');
+const { ProxyTrust } = require('./clientip');
 
 // =============================================================================
 // PoW Challenge Store (can be extended with Redis)
@@ -719,28 +720,25 @@ class ScoringEngine {
 
 function createMiddleware(options = {}) {
   const engine = new ScoringEngine(options);
+  const proxyTrust = options.trustedProxies !== undefined
+    ? new ProxyTrust(options.trustedProxies)
+    : ProxyTrust.fromEnv();
 
   return {
     engine,
+    proxyTrust,
 
-    // Middleware to extract IP from request
-    getIP: (req) => {
-      let ip = req.headers['x-real-ip'] || '';
-      if (!ip) {
-        const forwarded = req.headers['x-forwarded-for'];
-        if (forwarded) {
-          ip = forwarded.split(',')[0].trim();
-        } else {
-          ip = req.socket?.remoteAddress || '127.0.0.1';
-        }
-      }
-      return ip;
-    },
+    // Middleware to extract IP from request. Forwarding headers are honoured
+    // only from a peer in the trusted-proxy set (TRUSTED_PROXIES, or the
+    // private/loopback defaults) — otherwise any caller could claim a clean
+    // residential IP and skip the datacenter, Tor/VPN and rate-limit checks.
+    // Pass options.trustedProxies to override the env for this instance.
+    getIP: (req) => proxyTrust.clientIP(req),
 
     // Challenge route handler
     challengeHandler: (req, res) => {
       const siteKey = req.query.siteKey || 'default';
-      const ip = options.getIP ? options.getIP(req) : module.exports.createMiddleware({}).getIP(req);
+      const ip = options.getIP ? options.getIP(req) : proxyTrust.clientIP(req);
       const challenge = engine.generateChallenge(siteKey, ip);
 
       res.json({
@@ -755,7 +753,7 @@ function createMiddleware(options = {}) {
     // Verify route handler
     verifyHandler: (req, res) => {
       const { siteKey, signals, powSolution } = req.body;
-      const ip = options.getIP ? options.getIP(req) : module.exports.createMiddleware({}).getIP(req);
+      const ip = options.getIP ? options.getIP(req) : proxyTrust.clientIP(req);
       const userAgent = req.headers['user-agent'] || '';
 
       const headers = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Open source CAPTCHA with PoW, bot detection, and Vision AI protection",
   "main": "index.js",
   "exports": {
@@ -10,12 +10,16 @@
   },
   "scripts": {
     "start": "node server.js",
-    "dev": "node --watch server.js"
+    "dev": "node --watch server.js",
+    "test:webbotauth": "node webbotauth.test.js",
+    "test:clientip": "node clientip.test.js"
   },
   "dependencies": {
-    "express": "^4.18.2",
     "cors": "^2.8.5",
-    "redis": "^4.6.12"
+    "express": "^4.18.0",
+    "ipaddr.js": "^2.4.0",
+    "redis": "^4.6.12",
+    "web-bot-auth": "^0.1.3"
   },
   "peerDependencies": {
     "express": "^4.18.0"

package/server.js

@@ -9,6 +9,8 @@ const cors = require('cors');
 const crypto = require('crypto');
 const path = require('path');
 const detection = require('./detection');
+const webbotauth = require('./webbotauth');
+const { ProxyTrust } = require('./clientip');
 
 const app = express();
 app.use(cors());
@@ -18,6 +20,14 @@ const SECRET_KEY = process.env.FCAPTCHA_SECRET || 'dev-secret-change-in-producti
 const PORT = process.env.PORT || 3000;
 const TRUSTED_JA4_HEADERS = detection.getTrustedJA4HeaderNames();
 
+// Which peers may speak for another client via X-Forwarded-For / X-Real-IP and
+// the TLS-fingerprint headers. See clientip.js.
+const PROXY_TRUST = ProxyTrust.fromEnv();
+
+// Express's own `trust proxy` would re-derive req.ip from the same headers on
+// its own terms; IP resolution goes through PROXY_TRUST.clientIP exclusively.
+app.set('trust proxy', false);
+
 // 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
@@ -1044,8 +1054,24 @@ function verifyToken(token, ip = null) {
   }
 }
 
-function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash = null, powSolution = null, signalsJson = null, powTiming = null) {
-  const detections = [];
+// verifyWebBotAuth runs Web Bot Auth verification and never throws into the
+// request path: any unexpected error degrades to no detection (fail open), so a
+// verification bug can't turn a scoring request into a 500.
+async function verifyWebBotAuth(req) {
+  try {
+    return await webbotauth.checkWebBotAuth(req);
+  } catch (e) {
+    console.error('[webbotauth] verification error:', e && e.message);
+    return [];
+  }
+}
+
+// preDetections are detections computed by the caller (the route handler) that
+// require the raw request — currently Web Bot Auth signature verification, which
+// needs the accurately-reconstructed signed request. They are seeded into the
+// detection set so they participate in scoring like any other detection.
+function runVerification(signals, ip, siteKey, userAgent, headers = {}, ja3Hash = null, powSolution = null, signalsJson = null, powTiming = null, preDetections = []) {
+  const detections = Array.isArray(preDetections) ? [...preDetections] : [];
 
   // Verify signal commitment (signalsJson hash must match powSolution.signalsHash)
   const clientSignalsHash = powSolution?.signalsHash || null;
@@ -1218,51 +1244,55 @@ app.get('/health', (req, res) => {
   res.json({ status: 'ok' });
 });
 
-app.post('/api/verify', (req, res) => {
-  const { siteKey, signals, powSolution, signalsJson, powTiming } = req.body;
-  let ip = req.headers['x-real-ip'] || '';
-  if (!ip) {
-    const forwarded = req.headers['x-forwarded-for'];
-    if (forwarded) {
-      ip = forwarded.split(',')[0].trim();
-    } else {
-      ip = req.socket.remoteAddress;
-    }
+// collectHeaders lowercases the request headers for the detectors, dropping the
+// TLS-fingerprint headers when the peer is not a proxy we trust. TRUSTED_JA4_HEADERS
+// is an allowlist of header *names*, which says nothing about who set them — without
+// this gate a client could send cf-ja4 itself and present a clean fingerprint.
+function collectHeaders(req) {
+  const peerTrusted = PROXY_TRUST.peerTrusted(req);
+  const headers = {};
+  for (const [key, value] of Object.entries(req.headers)) {
+    const name = key.toLowerCase();
+    if (!peerTrusted && TRUSTED_JA4_HEADERS.includes(name)) continue;
+    headers[name] = Array.isArray(value) ? value[0] : value;
   }
+  return headers;
+}
+
+app.post('/api/verify', async (req, res) => {
+  const { siteKey, signals, powSolution, signalsJson, powTiming } = req.body;
+  const ip = PROXY_TRUST.clientIP(req);
   const userAgent = req.headers['user-agent'] || '';
-  const ja3Hash = req.headers['x-ja3-hash'] || null;
+  // Only honoured from a trusted proxy: a client that can state its own TLS
+  // fingerprint would just claim a stock Chrome one.
+  const ja3Hash = PROXY_TRUST.trustedHeader(req, 'x-ja3-hash') || null;
 
   // Collect headers for analysis
-  const headers = {};
-  for (const [key, value] of Object.entries(req.headers)) {
-    headers[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
-  }
+  const headers = collectHeaders(req);
+
+  // 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);
+  const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming, webBotAuth);
   logVerdict('verify', siteKey, result);
   res.json(result);
 });
 
-app.post('/api/score', (req, res) => {
+app.post('/api/score', async (req, res) => {
   const { siteKey, signals, action, powSolution, signalsJson, powTiming } = req.body;
-  let ip = req.headers['x-real-ip'] || '';
-  if (!ip) {
-    const forwarded = req.headers['x-forwarded-for'];
-    if (forwarded) {
-      ip = forwarded.split(',')[0].trim();
-    } else {
-      ip = req.socket.remoteAddress;
-    }
-  }
+  const ip = PROXY_TRUST.clientIP(req);
   const userAgent = req.headers['user-agent'] || '';
-  const ja3Hash = req.headers['x-ja3-hash'] || null;
+  const ja3Hash = PROXY_TRUST.trustedHeader(req, 'x-ja3-hash') || null;
 
   const headers = {};
   for (const [key, value] of Object.entries(req.headers)) {
     headers[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
   }
 
-  const result = runVerification(signals, ip, siteKey, userAgent, headers, ja3Hash, powSolution, signalsJson, powTiming);
+  // 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);
   logVerdict('score', siteKey, result);
   res.json({
     success: result.success,
@@ -1277,15 +1307,7 @@ app.post('/api/token/verify', (req, res) => {
   const { token } = req.body;
 
   // Extract client IP for verification
-  let ip = req.headers['x-real-ip'] || '';
-  if (!ip) {
-    const forwarded = req.headers['x-forwarded-for'];
-    if (forwarded) {
-      ip = forwarded.split(',')[0].trim();
-    } else {
-      ip = req.socket.remoteAddress;
-    }
-  }
+  const ip = PROXY_TRUST.clientIP(req);
 
   res.json(verifyToken(token, ip));
 });
@@ -1294,15 +1316,7 @@ app.post('/api/token/verify', (req, res) => {
 app.get('/api/pow/challenge', (req, res) => {
   const siteKey = req.query.siteKey || 'default';
 
-  let ip = req.headers['x-real-ip'] || '';
-  if (!ip) {
-    const forwarded = req.headers['x-forwarded-for'];
-    if (forwarded) {
-      ip = forwarded.split(',')[0].trim();
-    } else {
-      ip = req.socket.remoteAddress;
-    }
-  }
+  const ip = PROXY_TRUST.clientIP(req);
 
   // Difficulty scaling based on IP reputation
   let difficulty = 4; // Default: ~100-500ms on average hardware
@@ -1350,4 +1364,5 @@ app.get('/api/challenge', (req, res) => {
 
 app.listen(PORT, () => {
   console.log(`FCaptcha server running on port ${PORT}`);
+  console.log(`Trusted proxies: ${PROXY_TRUST.describe()}`);
 });

package/webbotauth.js

@@ -0,0 +1,364 @@
+'use strict';
+
+// Web Bot Auth (RFC 9421 HTTP Message Signatures) verification for signed AI
+// agents. Built on Cloudflare's web-bot-auth crypto primitives; mirrors the Go
+// server's ScoringEngine.CheckWebBotAuth verdict model:
+//
+//   - verified   → declared_ai (verified:true, high confidence): a trustworthy
+//                  signed identity (e.g. OpenAI Operator). A policy signal.
+//   - forged     → bot (low confidence, contributory): the request claimed an
+//                  agent identity and the signature failed cryptographic
+//                  verification. Only a genuine crypto failure counts.
+//   - otherwise  → fail open to a presence-only declared_ai signal identical to
+//                  the pre-verification behavior. A directory we could not fetch
+//                  (unreachable, blocked, timed out) is not proof of spoofing,
+//                  so it must never be scored as one.
+//
+// The signer's key directory is named by the untrusted Signature-Agent header,
+// so every fetch is treated as an SSRF vector: https-only, a DNS-lookup guard
+// that refuses any non-global-unicast address (blocks loopback, private,
+// link-local — including the 169.254.169.254 cloud metadata endpoint — CGNAT,
+// ULA, and IPv4-mapped IPv6), a response-size cap, a short timeout, and no
+// redirect following. Directories are cached with a TTL.
+//
+// The upstream package (cloudflare/web-bot-auth) is the reference implementation
+// the Go module (WebDecoy/web-bot-auth) is cross-validated against, so the two
+// servers agree on verdicts. Python has no maintained equivalent and stays
+// presence-only.
+
+const https = require('https');
+const dns = require('dns');
+const { URL } = require('url');
+
+const ipaddr = require('ipaddr.js');
+const {
+  verify,
+  jwkToKeyID,
+  helpers,
+  HTTP_MESSAGE_SIGNATURES_DIRECTORY,
+} = require('web-bot-auth');
+const { verifierFromJWK } = require('web-bot-auth/crypto');
+
+const VERIFY_TIMEOUT_MS = 3000;
+const MAX_DIRECTORY_BYTES = 1 << 20; // 1 MiB, matches the Go client's cap
+const DIRECTORY_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+// The exact message web-bot-auth/crypto throws when crypto.subtle.verify()
+// returns false. This — and only this — is affirmative evidence of a forged
+// signature. Everything else (fetch failure, expiry, missing key) fails open.
+const CRYPTO_FAILURE_MESSAGE = 'invalid signature';
+
+// origin (https://host[:port]) → { keys: JsonWebKey[], fetchedAt: number }
+const directoryCache = new Map();
+
+// FetchFailure marks failures that are NOT cryptographic — the caller treats
+// them as "could not verify" (fail open), never as a forged-signature signal.
+class FetchFailure extends Error {}
+
+// --- SSRF guard ---------------------------------------------------------------
+
+// isPublicUnicast reports whether an IP literal is a globally-routable unicast
+// address. ipaddr.process() un-maps IPv4-mapped IPv6 first, so an address like
+// ::ffff:10.0.0.1 is classified by its embedded v4 range ('private'), not as a
+// v6 unicast. Only 'unicast' (public) is allowed; every other range is refused.
+function isPublicUnicast(ip) {
+  let addr;
+  try {
+    addr = ipaddr.process(ip);
+  } catch {
+    return false;
+  }
+  return addr.range() === 'unicast';
+}
+
+// guardedLookup resolves a hostname and hands the socket a vetted IP. Passing
+// the concrete address (not the hostname) to connect closes the DNS-rebinding
+// window: the socket connects to exactly the address we validated.
+function guardedLookup(hostname, options, callback) {
+  const opts = typeof options === 'number' ? { family: options } : options || {};
+  dns.lookup(hostname, { all: true, verbatim: true }, (err, addresses) => {
+    if (err) {
+      callback(err);
+      return;
+    }
+    const list = Array.isArray(addresses)
+      ? addresses
+      : [{ address: addresses, family: opts.family || 0 }];
+    for (const a of list) {
+      if (isPublicUnicast(a.address)) {
+        callback(null, a.address, a.family);
+        return;
+      }
+    }
+    callback(new FetchFailure(`refusing to connect to non-global address for ${hostname}`));
+  });
+}
+
+// --- directory fetching -------------------------------------------------------
+
+function fetchDirectory(directoryUrl) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = new URL(directoryUrl);
+    } catch {
+      reject(new FetchFailure('invalid directory URL'));
+      return;
+    }
+    if (url.protocol !== 'https:') {
+      reject(new FetchFailure('directory URL is not https'));
+      return;
+    }
+
+    const req = https.get(
+      directoryUrl,
+      {
+        lookup: guardedLookup,
+        timeout: VERIFY_TIMEOUT_MS,
+        headers: {
+          accept: 'application/http-message-signatures-directory+json, application/json',
+        },
+      },
+      (res) => {
+        // https.get does not follow redirects; anything but 200 is a failure.
+        if (res.statusCode !== 200) {
+          res.resume();
+          reject(new FetchFailure(`directory returned ${res.statusCode}`));
+          return;
+        }
+        let len = 0;
+        const chunks = [];
+        res.on('data', (chunk) => {
+          len += chunk.length;
+          if (len > MAX_DIRECTORY_BYTES) {
+            req.destroy(new FetchFailure('directory exceeds size cap'));
+            return;
+          }
+          chunks.push(chunk);
+        });
+        res.on('end', () => {
+          try {
+            const doc = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            resolve(Array.isArray(doc.keys) ? doc.keys : []);
+          } catch {
+            reject(new FetchFailure('directory is not valid JSON'));
+          }
+        });
+      },
+    );
+
+    req.on('timeout', () => {
+      req.destroy(new FetchFailure('directory fetch timed out'));
+    });
+    req.on('error', (e) => {
+      reject(e instanceof FetchFailure ? e : new FetchFailure(`directory fetch: ${e.message}`));
+    });
+  });
+}
+
+async function getDirectory(directoryUrl) {
+  const now = Date.now();
+  const cached = directoryCache.get(directoryUrl);
+  if (cached && now - cached.fetchedAt < DIRECTORY_CACHE_TTL_MS) {
+    return cached.keys;
+  }
+  const keys = await fetchDirectory(directoryUrl);
+  directoryCache.set(directoryUrl, { keys, fetchedAt: now });
+  return keys;
+}
+
+// resolveKey fetches the directory named by the Signature-Agent header and
+// returns the JWK whose RFC 7638 thumbprint matches keyid (the Web Bot Auth
+// keyid IS the thumbprint, not the JWK's `kid`). A reachable directory that
+// lacks the key throws a FetchFailure — treated as fail-open, matching the Go
+// engine, which counts only a crypto failure as forgery.
+async function resolveKey(signatureAgentHeader, keyid) {
+  const origin = directoryOriginFromHeader(signatureAgentHeader);
+  if (!origin) {
+    throw new FetchFailure('no resolvable Signature-Agent directory');
+  }
+  const keys = await getDirectory(origin + HTTP_MESSAGE_SIGNATURES_DIRECTORY);
+  for (const jwk of keys) {
+    let thumbprint;
+    try {
+      thumbprint = await jwkToKeyID(jwk, helpers.WEBCRYPTO_SHA256, helpers.BASE64URL_DECODE);
+    } catch {
+      continue; // unsupported/malformed key in the set — skip it
+    }
+    if (thumbprint === keyid) {
+      return jwk;
+    }
+  }
+  throw new FetchFailure('keyid not found in directory');
+}
+
+// --- header + request helpers -------------------------------------------------
+
+// unwrapSfString extracts the value from a Signature-Agent header, which is an
+// RFC 8941 String — bare (`"https://a"`) or a dictionary member
+// (`sig1="https://a"`) as some signers emit.
+function unwrapSfString(raw) {
+  if (!raw) return '';
+  const s = String(raw).trim();
+  const m = s.match(/^(?:[A-Za-z0-9_-]+=)?"(.*)"$/);
+  return (m ? m[1] : s).trim();
+}
+
+function displayAgent(raw) {
+  return unwrapSfString(raw) || 'unknown';
+}
+
+function directoryOriginFromHeader(raw) {
+  const val = unwrapSfString(raw);
+  if (!val) return null;
+  let u;
+  try {
+    u = new URL(val);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== 'https:') return null;
+  return u.origin;
+}
+
+function forwardedScheme(req) {
+  const xfp = req.headers && req.headers['x-forwarded-proto'];
+  if (xfp) return String(xfp).split(',')[0].trim().toLowerCase();
+  if (req.protocol) return req.protocol; // express sets this
+  return req.socket && req.socket.encrypted ? 'https' : 'http';
+}
+
+// --- detections (shape mirrors detection.js / the Go DetectionResult) ---------
+
+function verifiedDetection(agent, keyId, algorithm) {
+  return {
+    category: 'declared_ai',
+    score: 0.5,
+    confidence: 0.99,
+    reason: `Verified AI agent (Web Bot Auth): ${agent}`,
+    details: { signatureAgent: agent, verified: true, keyId, algorithm },
+  };
+}
+
+function forgedDetection(agent, err) {
+  return {
+    category: 'bot',
+    score: 0.5,
+    confidence: 0.5,
+    reason: `Forged Web Bot Auth signature (crypto verification failed): ${agent}`,
+    details: { signatureAgent: agent, verified: false, error: err && err.message },
+  };
+}
+
+function presenceDetection(agent) {
+  return {
+    category: 'declared_ai',
+    score: 0.4,
+    confidence: 0.95,
+    reason: `Signed agent request (Web Bot Auth, unverified): ${agent}`,
+    details: { signatureAgent: agent, verified: false },
+  };
+}
+
+// --- entry point --------------------------------------------------------------
+
+// checkWebBotAuth verifies a Web Bot Auth signed request and returns detections
+// (empty when the request carries no signature). Async because verification may
+// fetch the signer's key directory. Give it the Express request so the signed
+// URL is reconstructed accurately — a mis-derived authority would make a genuine
+// signature fail crypto verification and false-positive a real agent.
+async function checkWebBotAuth(req) {
+  const headers = (req && req.headers) || {};
+  if (!headers.signature || !headers['signature-input']) {
+    return [];
+  }
+
+  const sigAgentRaw = headers['signature-agent'];
+  const agent = displayAgent(sigAgentRaw);
+
+  const host = headers.host;
+  if (!host) {
+    // Cannot reconstruct @authority → cannot verify. Fail open.
+    return [presenceDetection(agent)];
+  }
+  const path = req.originalUrl || req.url || '/';
+  const message = {
+    method: (req.method || 'POST').toUpperCase(),
+    url: `${forwardedScheme(req)}://${host}${path}`,
+    headers,
+  };
+
+  let cryptoFailed = false;
+  let resolvedKeyId = '';
+  let resolvedAlg = '';
+
+  try {
+    await withTimeout(
+      verify(message, async (data, signature, params) => {
+        if (!sigAgentRaw) {
+          throw new FetchFailure('no Signature-Agent to resolve key');
+        }
+        const jwk = await resolveKey(sigAgentRaw, params.keyid);
+        resolvedKeyId = params.keyid;
+        resolvedAlg = jwk.alg || (jwk.crv === 'Ed25519' ? 'ed25519' : '');
+        const verifyFn = await verifierFromJWK(jwk);
+        try {
+          await verifyFn(data, signature, params);
+        } catch (e) {
+          if (e && e.message === CRYPTO_FAILURE_MESSAGE) {
+            cryptoFailed = true;
+          }
+          throw e;
+        }
+      }),
+      VERIFY_TIMEOUT_MS,
+    );
+    return [verifiedDetection(agent, resolvedKeyId, resolvedAlg)];
+  } catch (e) {
+    if (cryptoFailed) {
+      return [forgedDetection(agent, e)];
+    }
+    // Fetch/structural/timeout/expiry failure: not proof of forgery. Fail open.
+    return [presenceDetection(agent)];
+  }
+}
+
+// withTimeout bounds the whole verification, a backstop over the per-fetch
+// timeout so a stalled directory can never hold the scoring path open.
+function withTimeout(promise, ms) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new FetchFailure('verification timed out')), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+module.exports = {
+  checkWebBotAuth,
+  // Exported for unit tests only.
+  _internal: {
+    isPublicUnicast,
+    directoryOriginFromHeader,
+    displayAgent,
+    verifiedDetection,
+    forgedDetection,
+    presenceDetection,
+    // Seeds the directory cache so an end-to-end verify can exercise resolveKey
+    // without a network fetch (the SSRF guard refuses the loopback address a
+    // local test server would listen on). Test-only.
+    seedDirectoryCache(origin, keys) {
+      directoryCache.set(origin + HTTP_MESSAGE_SIGNATURES_DIRECTORY, {
+        keys,
+        fetchedAt: Date.now(),
+      });
+    },
+  },
+};