@webdecoy/fcaptcha 1.15.0 → 1.17.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/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.15.0",
+  "version": "1.17.0",
   "description": "Open source CAPTCHA with PoW, bot detection, and Vision AI protection",
   "main": "index.js",
   "exports": {
@@ -11,7 +11,9 @@
   "scripts": {
     "start": "node server.js",
     "dev": "node --watch server.js",
-    "test:webbotauth": "node webbotauth.test.js"
+    "test:webbotauth": "node webbotauth.test.js",
+    "test:clientip": "node clientip.test.js",
+    "test:limits": "node limits.test.js"
   },
   "dependencies": {
     "cors": "^2.8.5",

package/server.js

@@ -10,6 +10,8 @@ const crypto = require('crypto');
 const path = require('path');
 const detection = require('./detection');
 const webbotauth = require('./webbotauth');
+const { ProxyTrust } = require('./clientip');
+const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
 
 const app = express();
 app.use(cors());
@@ -19,6 +21,20 @@ 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();
+
+// siteKey is client-supplied and validated against no registry, yet it is the
+// first component of every rate-limit, fingerprint and challenge partition key.
+// SITE_KEYS bounds how many distinct values one IP may allocate state for. See
+// limits.js — the cap is unconditional; FCAPTCHA_SITE_KEYS adds an allowlist.
+const SITE_KEYS = SiteKeyGuard.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
@@ -76,8 +92,8 @@ if (process.env.FCAPTCHA_SERVE_CLIENT !== 'false') {
 
 // PoW Challenge Store
 const powChallengeStore = {
-  challenges: new Map(),
-  usedSolutions: new Set(),
+  challenges: new BoundedMap(),
+  usedSolutions: new BoundedSet(),
 
   // Generate a new challenge
   generate(siteKey, ip, difficulty = 4) {
@@ -168,20 +184,15 @@ const powChallengeStore = {
 
   _cleanup() {
     const now = Date.now();
-    for (const [id, challenge] of this.challenges) {
-      if (now > challenge.expiresAt) {
-        this.challenges.delete(id);
-      }
-    }
-    // Cleanup old solutions (keep last hour)
-    if (this.usedSolutions.size > 10000) {
-      this.usedSolutions.clear();
-    }
+    this.challenges.prune((challenge) => now <= challenge.expiresAt);
+    // usedSolutions is a BoundedSet: it evicts its own oldest entries as it
+    // fills. The previous code cleared the whole replay guard once it passed a
+    // threshold, which an attacker could force in order to replay a solution.
   }
 };
 
 const rateLimiter = {
-  requests: new Map(),
+  requests: new BoundedMap(),
 
   check(key, windowSeconds = 60, maxRequests = 10) {
     const now = Date.now();
@@ -202,8 +213,8 @@ const rateLimiter = {
 };
 
 const fingerprintStore = {
-  fingerprints: new Map(),
-  ipFingerprints: new Map(),
+  fingerprints: new BoundedMap(),
+  ipFingerprints: new BoundedMap(),
 
   record(fp, ip, siteKey) {
     const key = `${siteKey}:${fp}`;
@@ -233,7 +244,7 @@ const fingerprintStore = {
 
 // Token Store - prevents token replay attacks
 const tokenStore = {
-  usedTokens: new Set(),
+  usedTokens: new BoundedSet(),
 
   // Mark a token as used (returns false if already used)
   markUsed(tokenSig) {
@@ -252,11 +263,9 @@ const tokenStore = {
   },
 
   _cleanup() {
-    // In production with Redis, use TTL instead
-    // For in-memory, just clear if too large (tokens expire in 5 min)
-    if (this.usedTokens.size > 50000) {
-      this.usedTokens.clear();
-    }
+    // In production with Redis, use TTL instead. In memory usedTokens is a
+    // BoundedSet, so it evicts its oldest entries rather than clearing wholesale
+    // — clearing would let an attacker who forced the threshold replay a token.
   }
 };
 
@@ -1235,25 +1244,33 @@ app.get('/health', (req, res) => {
   res.json({ status: 'ok' });
 });
 
-app.post('/api/verify', async (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: rawSiteKey, signals, powSolution, signalsJson, powTiming } = req.body;
+  const ip = PROXY_TRUST.clientIP(req);
+  // Bound the state an unvalidated siteKey can allocate (limits.js).
+  const siteKey = SITE_KEYS.normalize(rawSiteKey, ip);
   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);
@@ -1264,18 +1281,11 @@ app.post('/api/verify', async (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 { siteKey: rawSiteKey, signals, action, powSolution, signalsJson, powTiming } = req.body;
+  const ip = PROXY_TRUST.clientIP(req);
+  const siteKey = SITE_KEYS.normalize(rawSiteKey, ip);
   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)) {
@@ -1300,32 +1310,15 @@ 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));
 });
 
 // PoW Challenge endpoint - client fetches this on page load
 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);
+  const siteKey = SITE_KEYS.normalize(req.query.siteKey, ip);
 
   // Difficulty scaling based on IP reputation
   let difficulty = 4; // Default: ~100-500ms on average hardware
@@ -1373,4 +1366,6 @@ app.get('/api/challenge', (req, res) => {
 
 app.listen(PORT, () => {
   console.log(`FCaptcha server running on port ${PORT}`);
+  console.log(`Trusted proxies: ${PROXY_TRUST.describe()}`);
+  console.log(`Site keys: ${SITE_KEYS.describe()}`);
 });

package/webbotauth.js

@@ -23,8 +23,33 @@
 //
 // 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.
+// servers agree on verdicts. Python stays presence-only for now, though a
+// maintained RFC 9421 implementation (pyauth/http-message-signatures) now exists
+// and would close that gap.
+//
+// Wire format — draft-meunier-webbotauth-httpsig-protocol-00 (2026-06-26):
+// Signature-Agent is a Structured Fields Dictionary whose member value is the
+// discovery URL and whose optional `type` parameter selects how to resolve keys:
+//
+//   sig1="https://a.test"                          → directory (default)
+//   sig1="https://a.test/jwks.json";type=jwks_uri  → the URL *is* a JWK Set
+//   sig1="https://a.test/card";type=cimd           → Client ID Metadata Document
+//
+// The pre-00 bare-String form ("https://a.test") is still emitted by signers
+// that have not migrated and stays supported. A parser that only understood the
+// bare form silently lost the *verified* verdict for any signer using the two
+// new discovery types, degrading them to presence-only.
+//
+// DOCUMENTED DIVERGENCE — `cimd`. This implementation resolves a Client ID
+// Metadata Document (embedded `jwks`, or a nested `jwks_uri` re-fetched through
+// the same guard). The Go module (WebDecoy/web-bot-auth v0.2.0) parses the type
+// but returns "not resolvable", so Go fails open to presence-only where Node
+// reaches verified. Go is otherwise fully protocol-00 compliant — it honors
+// `directory` and `jwks_uri` and enforces the tag — so this is the single
+// verdict difference. It is currently theoretical: no observed signer uses
+// `cimd` (chatgpt.com and agent.bot.goog both serve `directory`). Parity
+// requires a change in the Go module, not here. Tracked rather than silent, per
+// the CLAUDE.md sync rule.
 
 const https = require('https');
 const dns = require('dns');
@@ -48,6 +73,23 @@ const DIRECTORY_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 // signature. Everything else (fetch failure, expiry, missing key) fails open.
 const CRYPTO_FAILURE_MESSAGE = 'invalid signature';
 
+// Discovery types from protocol-00. `directory` is the default when the header
+// carries no `type` parameter.
+const DISCOVERY_DIRECTORY = 'directory';
+const DISCOVERY_JWKS_URI = 'jwks_uri';
+const DISCOVERY_CIMD = 'cimd';
+
+// protocol-00: `tag` MUST be "web-bot-auth". A signature tagged for some other
+// protocol is not a web-bot-auth signature, so it earns no verified credit.
+const REQUIRED_TAG = 'web-bot-auth';
+
+// protocol-00 RECOMMENDS an expiry no more than 24h out. Because that is a
+// RECOMMENDED and not a MUST, an over-long window is not treated as forgery or
+// as a hard rejection — it just does not earn the *verified* verdict, and the
+// request falls back to presence-only. That bounds the replay window a stolen
+// signature buys without false-positiving a signer who picked a longer TTL.
+const MAX_SIGNATURE_LIFETIME_S = 24 * 60 * 60;
+
 // origin (https://host[:port]) → { keys: JsonWebKey[], fetchedAt: number }
 const directoryCache = new Map();
 
@@ -96,11 +138,14 @@ function guardedLookup(hostname, options, callback) {
 
 // --- directory fetching -------------------------------------------------------
 
-function fetchDirectory(directoryUrl) {
+// fetchJSON retrieves and parses one https document under the SSRF guard, the
+// size cap and the timeout. Shared by directory, jwks_uri and cimd fetches so a
+// new discovery type cannot accidentally bypass the guard.
+function fetchJSON(documentUrl) {
   return new Promise((resolve, reject) => {
     let url;
     try {
-      url = new URL(directoryUrl);
+      url = new URL(documentUrl);
     } catch {
       reject(new FetchFailure('invalid directory URL'));
       return;
@@ -111,7 +156,7 @@ function fetchDirectory(directoryUrl) {
     }
 
     const req = https.get(
-      directoryUrl,
+      documentUrl,
       {
         lookup: guardedLookup,
         timeout: VERIFY_TIMEOUT_MS,
@@ -138,8 +183,7 @@ function fetchDirectory(directoryUrl) {
         });
         res.on('end', () => {
           try {
-            const doc = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-            resolve(Array.isArray(doc.keys) ? doc.keys : []);
+            resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
           } catch {
             reject(new FetchFailure('directory is not valid JSON'));
           }
@@ -156,14 +200,46 @@ function fetchDirectory(directoryUrl) {
   });
 }
 
-async function getDirectory(directoryUrl) {
+// fetchKeySet pulls a JWK Set — the shape served by both the well-known
+// directory and a jwks_uri.
+async function fetchKeySet(url) {
+  const doc = await fetchJSON(url);
+  return doc && Array.isArray(doc.keys) ? doc.keys : [];
+}
+
+// fetchViaCIMD resolves a Client ID Metadata Document, which either embeds the
+// JWK Set inline or points at one. The nested jwks_uri is re-validated and
+// re-fetched through the same guard rather than trusted.
+async function fetchViaCIMD(cimdUrl) {
+  const doc = await fetchJSON(cimdUrl);
+  if (doc && doc.jwks && Array.isArray(doc.jwks.keys)) {
+    return doc.jwks.keys;
+  }
+  if (doc && typeof doc.jwks_uri === 'string') {
+    let nested;
+    try {
+      nested = new URL(doc.jwks_uri);
+    } catch {
+      throw new FetchFailure('cimd jwks_uri is not a URL');
+    }
+    if (nested.protocol !== 'https:') {
+      throw new FetchFailure('cimd jwks_uri is not https');
+    }
+    return fetchKeySet(nested.toString());
+  }
+  throw new FetchFailure('cimd document has no jwks or jwks_uri');
+}
+
+// getKeys caches by resolved URL, so the three discovery types share one cache
+// without colliding.
+async function getKeys(url, type) {
   const now = Date.now();
-  const cached = directoryCache.get(directoryUrl);
+  const cached = directoryCache.get(url);
   if (cached && now - cached.fetchedAt < DIRECTORY_CACHE_TTL_MS) {
     return cached.keys;
   }
-  const keys = await fetchDirectory(directoryUrl);
-  directoryCache.set(directoryUrl, { keys, fetchedAt: now });
+  const keys = type === DISCOVERY_CIMD ? await fetchViaCIMD(url) : await fetchKeySet(url);
+  directoryCache.set(url, { keys, fetchedAt: now });
   return keys;
 }
 
@@ -173,11 +249,11 @@ async function getDirectory(directoryUrl) {
 // 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 source = keySourceFromHeader(signatureAgentHeader);
+  if (!source) {
+    throw new FetchFailure('no resolvable Signature-Agent key source');
   }
-  const keys = await getDirectory(origin + HTTP_MESSAGE_SIGNATURES_DIRECTORY);
+  const keys = await getKeys(source.url, source.type);
   for (const jwk of keys) {
     let thumbprint;
     try {
@@ -194,31 +270,63 @@ async function resolveKey(signatureAgentHeader, keyid) {
 
 // --- 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 '';
+// parseSignatureAgent reads the first member of the Signature-Agent Structured
+// Fields Dictionary, returning its URL and discovery type. Accepts, in order of
+// how signers actually emit them:
+//
+//   sig1="https://a.test/jwks.json";type=jwks_uri   protocol-00, typed
+//   sig1="https://a.test"                           protocol-00, default type
+//   "https://a.test"                                pre-00 bare String
+//
+// The previous implementation anchored on a closing quote at end-of-string, so
+// any trailing parameter fell through to the raw header text and failed to
+// parse as a URL. That silently cost the *verified* verdict.
+function parseSignatureAgent(raw) {
+  if (!raw) return null;
   const s = String(raw).trim();
-  const m = s.match(/^(?:[A-Za-z0-9_-]+=)?"(.*)"$/);
-  return (m ? m[1] : s).trim();
+  if (!s) return null;
+  // Optional `key=` prefix, a quoted SF String, then optional ;params up to the
+  // next dictionary member.
+  const m = s.match(/^(?:[A-Za-z0-9_*-]+\s*=\s*)?"([^"]*)"((?:\s*;[^,]*)?)/);
+  if (!m) return null;
+  const url = m[1].trim();
+  if (!url) return null;
+  const typeMatch = (m[2] || '').match(/;\s*type\s*=\s*"?([A-Za-z0-9_-]+)"?/i);
+  const type = typeMatch ? typeMatch[1].toLowerCase() : DISCOVERY_DIRECTORY;
+  return { url, type };
 }
 
 function displayAgent(raw) {
-  return unwrapSfString(raw) || 'unknown';
+  const parsed = parseSignatureAgent(raw);
+  return (parsed && parsed.url) || 'unknown';
 }
 
-function directoryOriginFromHeader(raw) {
-  const val = unwrapSfString(raw);
-  if (!val) return null;
+// keySourceFromHeader resolves the header to the concrete https URL keys are
+// fetched from, plus the discovery type that says how to interpret it. Returns
+// null for anything unusable — a non-https URL, or a discovery type this build
+// does not implement (guessing would be worse than failing open).
+function keySourceFromHeader(raw) {
+  const parsed = parseSignatureAgent(raw);
+  if (!parsed) return null;
   let u;
   try {
-    u = new URL(val);
+    u = new URL(parsed.url);
   } catch {
     return null;
   }
   if (u.protocol !== 'https:') return null;
-  return u.origin;
+
+  switch (parsed.type) {
+    case DISCOVERY_DIRECTORY:
+      // The member names the signer's origin; keys live at the well-known path.
+      return { url: u.origin + HTTP_MESSAGE_SIGNATURES_DIRECTORY, type: DISCOVERY_DIRECTORY };
+    case DISCOVERY_JWKS_URI:
+    case DISCOVERY_CIMD:
+      // The member names the document itself — path and query are significant.
+      return { url: u.toString(), type: parsed.type };
+    default:
+      return null;
+  }
 }
 
 function forwardedScheme(req) {
@@ -298,6 +406,7 @@ async function checkWebBotAuth(req) {
         if (!sigAgentRaw) {
           throw new FetchFailure('no Signature-Agent to resolve key');
         }
+        assertWebBotAuthParams(params);
         const jwk = await resolveKey(sigAgentRaw, params.keyid);
         resolvedKeyId = params.keyid;
         resolvedAlg = jwk.alg || (jwk.crv === 'Ed25519' ? 'ed25519' : '');
@@ -323,6 +432,51 @@ async function checkWebBotAuth(req) {
   }
 }
 
+// toEpochSeconds normalizes a signature timestamp to epoch seconds. RFC 9421
+// puts integer seconds on the wire, but web-bot-auth hands the verifier callback
+// `Date` objects — so a naive Number() yields milliseconds and any duration
+// comparison is off by 1000×. Accepts Date, seconds, or milliseconds.
+function toEpochSeconds(value) {
+  if (value instanceof Date) return Math.floor(value.getTime() / 1000);
+  const n = Number(value);
+  if (!Number.isFinite(n)) return NaN;
+  // Epoch seconds are ~1.8e9 today; epoch milliseconds ~1.8e12.
+  return n > 1e11 ? Math.floor(n / 1000) : n;
+}
+
+// assertWebBotAuthParams enforces the protocol-00 signature-parameter rules that
+// the underlying library does not.
+//
+// web-bot-auth's own verify() already rejects a wrong `tag`, a `created` in the
+// future, an expired `expires`, and a missing `keyid`. The tag check below is
+// therefore belt-and-braces — kept because it is free and because it documents a
+// MUST that our verdict depends on. What is genuinely additive is the lifetime
+// ceiling: nothing upstream bounds how far out `expires` may sit, and a
+// long-lived signature is a long-lived replay token.
+//
+// Throwing FetchFailure means "not a verifiable web-bot-auth signature", which
+// the caller renders as presence-only — never as forgery, since neither a wrong
+// tag nor a generous TTL is cryptographic proof that anyone spoofed anything.
+function assertWebBotAuthParams(params) {
+  const p = params || {};
+
+  if (p.tag !== REQUIRED_TAG) {
+    throw new FetchFailure(`signature tag is not ${REQUIRED_TAG}`);
+  }
+
+  // `expires` is what bounds replay; a signature without one is unbounded.
+  const expires = toEpochSeconds(p.expires);
+  if (!Number.isFinite(expires)) {
+    throw new FetchFailure('signature has no expires parameter');
+  }
+  const created = Number.isFinite(toEpochSeconds(p.created))
+    ? toEpochSeconds(p.created)
+    : Math.floor(Date.now() / 1000);
+  if (expires - created > MAX_SIGNATURE_LIFETIME_S) {
+    throw new FetchFailure('signature lifetime exceeds 24h');
+  }
+}
+
 // 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) {
@@ -346,19 +500,24 @@ module.exports = {
   // Exported for unit tests only.
   _internal: {
     isPublicUnicast,
-    directoryOriginFromHeader,
+    parseSignatureAgent,
+    keySourceFromHeader,
+    assertWebBotAuthParams,
     displayAgent,
     verifiedDetection,
     forgedDetection,
     presenceDetection,
-    // Seeds the directory cache so an end-to-end verify can exercise resolveKey
+    REQUIRED_TAG,
+    MAX_SIGNATURE_LIFETIME_S,
+    // Seeds the key 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(),
-      });
+    //
+    // Seeds by *origin* for the default directory discovery. Pass a full URL as
+    // `exactUrl` to seed a jwks_uri/cimd source instead.
+    seedDirectoryCache(origin, keys, exactUrl) {
+      const url = exactUrl || origin + HTTP_MESSAGE_SIGNATURES_DIRECTORY;
+      directoryCache.set(url, { keys, fetchedAt: Date.now() });
     },
   },
 };