@webdecoy/fcaptcha 1.37.0 → 1.38.0

package/admission.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// Fixed windows bound both request work and limiter memory. A full table denies
+// new sources; it never evicts a source that still has a live quota.
+class AdmissionLimiter {
+  constructor({ maxEntries = 100000, now = Date.now } = {}) {
+    this.entries = new Map();
+    this.maxEntries = maxEntries;
+    this.now = now;
+    this.nextCleanup = 0;
+  }
+
+  allow(key, maximum, seconds = 60) {
+    const now = this.now();
+    if (now >= this.nextCleanup) {
+      for (const [k, entry] of this.entries) if (entry.expires <= now) this.entries.delete(k);
+      this.nextCleanup = now + 60000;
+    }
+    let entry = this.entries.get(key);
+    if (entry && entry.expires <= now) { this.entries.delete(key); entry = null; }
+    if (!entry) {
+      if (this.entries.size >= this.maxEntries) return false;
+      entry = { count: 0, expires: now + seconds * 1000 };
+      this.entries.set(key, entry);
+    }
+    if (entry.count >= maximum) return false;
+    entry.count++;
+    return true;
+  }
+}
+
+// Insertion order is expiry order (all challenges have the same lifetime).
+// Cleanup only visits expired entries, rather than scanning the live map.
+class ChallengeMap extends Map {
+  constructor(maxEntries = 100000) { super(); this.maxEntries = maxEntries; }
+  pruneExpired(now = Date.now()) {
+    for (const [id, challenge] of this) {
+      if (challenge.expiresAt > now) break;
+      this.delete(id);
+    }
+  }
+  set(id, challenge) {
+    this.pruneExpired();
+    if (!this.has(id) && this.size >= this.maxEntries) throw new Error('challenge_store_full');
+    return super.set(id, challenge);
+  }
+  prune() { this.pruneExpired(); }
+}
+
+module.exports = { AdmissionLimiter, ChallengeMap };

package/config.js

@@ -10,7 +10,7 @@ let devModeWarned = false;
 
 function signingSecretFromEnv(env = process.env) {
   const secret = String(env.FCAPTCHA_SECRET || '').trim();
-  if (secret && secret !== INSECURE_DEFAULT_SECRET) return secret;
+  if (Buffer.byteLength(secret) >= 32 && new Set(secret).size >= 8 && secret !== INSECURE_DEFAULT_SECRET) return secret;
   if (/^(1|true|yes|on)$/i.test(String(env.FCAPTCHA_INSECURE_DEV_MODE || '').trim())) {
     if (!devModeWarned) {
       devModeWarned = true;
@@ -18,7 +18,7 @@ function signingSecretFromEnv(env = process.env) {
     }
     return INSECURE_DEFAULT_SECRET;
   }
-  throw new Error('FCAPTCHA_SECRET is required and must not be the public development key. For local-only development, explicitly set FCAPTCHA_INSECURE_DEV_MODE=1.');
+  throw new Error('FCAPTCHA_SECRET is required: use at least 32 random bytes (openssl rand -hex 32), not a short or repetitive password. For local-only development, explicitly set FCAPTCHA_INSECURE_DEV_MODE=1.');
 }
 
 function signingSecret(explicit, env = process.env) {

package/engine.js

@@ -513,12 +513,8 @@ function detectAutomation(signals) {
   // JS execution timing
   const jsTime = getNestedValue(env, 'jsExecutionTime', 'mathOps') || 0;
   if (jsTime > 0) {
-    if (jsTime < 0.1) {
-      detections.push({
-        category: 'automation', score: 0.4, confidence: 0.3,
-        reason: 'JS execution unusually fast'
-      });
-    } else if (jsTime > 50) {
+    // Fast execution is common on real hardware and is not evidence of automation.
+    if (jsTime > 50) {
       detections.push({
         category: 'automation', score: 0.3, confidence: 0.3,
         reason: 'JS execution unusually slow'

package/index.js

@@ -14,6 +14,8 @@ const detection = require('./detection');
 const { ProxyTrust, networkIdentity } = require('./clientip');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
 const { signingSecret } = require('./config');
+const { AdmissionLimiter, ChallengeMap } = require('./admission');
+const { ipBinding } = require('./ip-binding');
 const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
 const { FingerprintStore } = require('./fingerprint-store');
 const { TokenStore } = require('./token-store');
@@ -26,12 +28,14 @@ const { resolveSignals } = require('./protocol');
 class PoWChallengeStore {
   constructor(options = {}) {
     this.secret = signingSecret(options.secret);
-    this.challenges = new BoundedMap();
+    this.challenges = new ChallengeMap();
+    this.issuance = new AdmissionLimiter();
     this.usedSolutions = new BoundedSet();
     this.expirationMs = options.expirationMs || 5 * 60 * 1000; // 5 minutes
   }
 
   generate(siteKey, ip, difficulty = 4, minAgeMs = BASE_MIN_AGE_MS) {
+    if (!this.issuance.allow(ip, 128, Math.ceil(this.expirationMs / 1000))) throw new Error('challenge_quota_exceeded');
     const challengeId = crypto.randomBytes(16).toString('hex');
     const timestamp = Date.now();
     const expiresAt = timestamp + this.expirationMs;
@@ -408,7 +412,7 @@ class ScoringEngine {
         return { valid: false, reason: 'invalid_signature' };
       }
 
-      if (ip && decoded.ip_hash !== crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8)) {
+      if (ip && decoded.ip_hash !== ipBinding(this.secret, ip)) {
         return { valid: false, reason: 'ip_mismatch' };
       }
       const claim = this.tokenStore.claim(sig);
@@ -495,7 +499,7 @@ class ScoringEngine {
   }
 
   _generateToken(ip, siteKey, score) {
-    const ipHash = crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8);
+    const ipHash = ipBinding(this.secret, ip);
     const data = {
       site_key: siteKey,
       jti: crypto.randomBytes(16).toString('hex'),

package/ip-binding.js

@@ -0,0 +1,11 @@
+'use strict';
+const crypto = require('crypto');
+const ipaddr = require('ipaddr.js');
+
+function ipBinding(secret, ip) {
+  let canonical = String(ip);
+  try { canonical = ipaddr.process(canonical).toString(); } catch (_) { /* non-IP test identities */ }
+  const key = crypto.createHmac('sha256', secret).update('fcaptcha:ip-binding:v2').digest();
+  return crypto.createHmac('sha256', key).update(canonical).digest('hex');
+}
+module.exports = { ipBinding };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdecoy/fcaptcha",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "Open source CAPTCHA with PoW, bot detection, and Vision AI protection",
   "main": "index.js",
   "exports": {
@@ -15,14 +15,14 @@
     "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 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",
     "test:siteverify": "node siteverify.test.js",
     "test:forensics": "node inputforensics.test.js",
     "test:suspicion": "node --test suspicion.test.js"
   },
   "dependencies": {
     "cors": "^2.8.5",
-    "express": "^4.18.0",
+    "express": "^4.22.3",
     "ipaddr.js": "^2.4.0",
     "redis": "^4.6.12",
     "web-bot-auth": "^0.1.3"
@@ -36,7 +36,7 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "repository": {
     "type": "git",

package/redis-state.js

@@ -8,6 +8,23 @@ const POW_TTL_MS = 5 * 60 * 1000;
 const SPENT_TTL_MS = 10 * 60 * 1000;
 const IDEMPOTENCY_TTL_MS = 5 * 60 * 1000;
 const DETECTION_TTL_MS = 15 * 60 * 1000;
+const ADMIT = `
+local count = tonumber(redis.call('GET', KEYS[1]) or '0')
+if count >= tonumber(ARGV[1]) then return 0 end
+redis.call('INCR', KEYS[1])
+if count == 0 then redis.call('PEXPIRE', KEYS[1], ARGV[2]) end
+return 1
+`;
+const PUT_CHALLENGE = `
+for i = 2, 3 do redis.call('ZREMRANGEBYSCORE', KEYS[i], '-inf', ARGV[1]) end
+if redis.call('ZCARD', KEYS[2]) >= 100000 or redis.call('ZCARD', KEYS[3]) >= 128 then return 0 end
+if not redis.call('SET', KEYS[1], ARGV[4], 'NX', 'PX', ARGV[3]) then return 0 end
+for i = 2, 3 do
+ redis.call('ZADD', KEYS[i], ARGV[2], KEYS[1])
+ redis.call('PEXPIRE', KEYS[i], ARGV[3])
+end
+return 1
+`;
 
 const CLAIM_CHALLENGE = `
 if redis.call('EXISTS', KEYS[1]) == 0 then return 0 end
@@ -50,8 +67,22 @@ return 1
 
 class RedisState {
   constructor(url, client = null) {
-    this.client = client || createClient({ url });
+    this.client = client || createClient({ url, disableOfflineQueue: true, commandsQueueMaxLength: 1024, socket: { connectTimeout: 2000 } });
     this.client.on?.('error', (err) => console.error('[redis]', err.message));
+    this.commandTimeoutMs = 2000;
+  }
+
+  async deadline(promise) {
+    let timer;
+    try {
+      return await Promise.race([promise, new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error('state_unavailable')), this.commandTimeoutMs);
+      })]);
+    } finally { clearTimeout(timer); }
+  }
+
+  execute(method, ...args) {
+    return this.deadline(Promise.resolve().then(() => this.client[method](...args)));
   }
 
   async connect() {
@@ -59,6 +90,25 @@ class RedisState {
     await this.client.ping();
   }
 
+  async ready(timeoutMs = 2000) {
+    if (this.readinessPending) return this.readinessPending;
+    // node-redis 4's abort signal only handles queued commands and may outlive
+    // their queue nodes. Bound the probe externally instead. Retain a timed-out
+    // probe until it settles so repeated health checks cannot fill the queue.
+    let timer;
+    const ping = Promise.resolve().then(() => this.client.ping());
+    const pending = Promise.race([ping, new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error('state_unavailable')), timeoutMs);
+    })]);
+    this.readinessPending = pending;
+    const settled = () => {
+      clearTimeout(timer);
+      if (this.readinessPending === pending) this.readinessPending = null;
+    };
+    ping.then(settled, settled);
+    return pending;
+  }
+
   challengeKey(id) {
     return `${PREFIX}pow:challenge:${id}`;
   }
@@ -74,18 +124,28 @@ class RedisState {
     // challengeId is the canonical cross-runtime field used by Go and Node.
     const stored = { ...challenge, challengeId: challenge.id };
     delete stored.id;
-    await this.client.set(this.challengeKey(challenge.id), JSON.stringify(stored), { PX: ttl });
+    const added = await this.execute('eval', PUT_CHALLENGE, {
+      keys: [this.challengeKey(challenge.id), `${PREFIX}pow:quota:global`, this.opaqueKey('pow:quota:source', challenge.ip)],
+      arguments: [String(Date.now()), String(challenge.expiresAt), String(ttl), JSON.stringify(stored)]
+    });
+    if (Number(added) !== 1) throw new Error('challenge_quota_exceeded');
+  }
+
+  async admit(key, maximum, seconds = 60) {
+    return Number(await this.execute('eval', ADMIT, {
+      keys: [this.opaqueKey('admission', key)], arguments: [String(maximum), String(seconds * 1000)]
+    })) === 1;
   }
 
   async getChallenge(id) {
-    const payload = await this.client.get(this.challengeKey(id));
+    const payload = await this.execute('get', this.challengeKey(id));
     if (!payload) return null;
     const challenge = JSON.parse(payload);
     return { ...challenge, id: challenge.challengeId };
   }
 
   async claimChallenge(challengeId, solutionKey) {
-    const result = Number(await this.client.eval(CLAIM_CHALLENGE, {
+    const result = Number(await this.execute('eval', CLAIM_CHALLENGE, {
       keys: [this.challengeKey(challengeId), `${PREFIX}pow:spent:${solutionKey}`],
       arguments: [String(SPENT_TTL_MS)]
     }));
@@ -97,7 +157,7 @@ class RedisState {
   }
 
   async claimToken(signature) {
-    return Boolean(await this.client.set(
+    return Boolean(await this.execute('set',
       `${PREFIX}token:spent:${signature}`,
       '1',
       { NX: true, PX: SPENT_TTL_MS }
@@ -113,13 +173,13 @@ class RedisState {
 
   async getIdempotency(idempotencyKey, token) {
     if (!idempotencyKey) return null;
-    const payload = await this.client.get(this.idempotencyKey(idempotencyKey, token));
+    const payload = await this.execute('get', this.idempotencyKey(idempotencyKey, token));
     return payload ? JSON.parse(payload) : null;
   }
 
   async setIdempotency(idempotencyKey, token, response) {
     if (!idempotencyKey) return;
-    await this.client.set(
+    await this.execute('set',
       this.idempotencyKey(idempotencyKey, token),
       JSON.stringify(response),
       { PX: IDEMPOTENCY_TTL_MS }
@@ -128,7 +188,7 @@ class RedisState {
 
   async rateCheck(key, windowSeconds, maxRequests) {
     const now = Date.now();
-    const result = await this.client.eval(RATE_CHECK, {
+    const result = await this.execute('eval', RATE_CHECK, {
       keys: [this.opaqueKey('rate', key)],
       arguments: [
         String(now - windowSeconds * 1000), String(now), String(maxRequests),
@@ -141,39 +201,39 @@ class RedisState {
   async recordSuspicion(siteKey, ip) {
     const now = Date.now();
     const key = this.opaqueKey('suspicion', `${siteKey}|${ip}`);
-    await this.client.multi()
+    await this.deadline(this.client.multi()
       .zRemRangeByScore(key, '-inf', now - DETECTION_TTL_MS)
       .zAdd(key, { score: now, value: `${now}:${crypto.randomBytes(8).toString('hex')}` })
       .zRemRangeByRank(key, 0, -17)
       .pExpire(key, DETECTION_TTL_MS)
-      .exec();
+      .exec());
   }
 
   async suspicionCount(siteKey, ip) {
     const key = this.opaqueKey('suspicion', `${siteKey}|${ip}`);
-    await this.client.zRemRangeByScore(key, '-inf', Date.now() - DETECTION_TTL_MS);
-    return Number(await this.client.zCard(key));
+    await this.execute('zRemRangeByScore', key, '-inf', Date.now() - DETECTION_TTL_MS);
+    return Number(await this.execute('zCard', key));
   }
 
   async recordFingerprint(fingerprint, ip, siteKey) {
     const fpKey = this.opaqueKey('fingerprint:ips', `${siteKey}|${fingerprint}`);
     const ipKey = this.opaqueKey('fingerprint:fps', ip);
-    await this.client.eval(RECORD_FINGERPRINT, {
+    await this.execute('eval', RECORD_FINGERPRINT, {
       keys: [fpKey, ipKey],
       arguments: [this.opaqueKey('value:ip', ip), this.opaqueKey('value:fp', fingerprint), String(DETECTION_TTL_MS)]
     });
   }
 
   async ipFingerprintCount(ip) {
-    return Number(await this.client.sCard(this.opaqueKey('fingerprint:fps', ip)));
+    return Number(await this.execute('sCard', this.opaqueKey('fingerprint:fps', ip)));
   }
 
   async fingerprintIpCount(fingerprint, siteKey) {
-    return Number(await this.client.sCard(this.opaqueKey('fingerprint:ips', `${siteKey}|${fingerprint}`)));
+    return Number(await this.execute('sCard', this.opaqueKey('fingerprint:ips', `${siteKey}|${fingerprint}`)));
   }
 
   async claimSiteKey(siteKey, ip, maxPerIp) {
-    return Number(await this.client.eval(SITEKEY_CLAIM, {
+    return Number(await this.execute('eval', SITEKEY_CLAIM, {
       keys: [this.opaqueKey('sitekeys', ip)],
       arguments: [this.opaqueKey('value:sitekey', siteKey), String(maxPerIp), String(60 * 60 * 1000)]
     })) === 1;

package/server.js

@@ -13,6 +13,8 @@ const webbotauth = require('./webbotauth');
 const { ProxyTrust, networkIdentity } = require('./clientip');
 const { BoundedMap, BoundedSet, SiteKeyGuard } = require('./limits');
 const { signingSecretFromEnv } = require('./config');
+const { AdmissionLimiter, ChallengeMap } = require('./admission');
+const { ipBinding } = require('./ip-binding');
 const { SuspicionLedger, computeChallengeCost, BASE_MIN_AGE_MS } = require('./suspicion');
 const { detectInputForensics } = require('./inputforensics');
 const { RedisState } = require('./redis-state');
@@ -172,11 +174,13 @@ if (process.env.FCAPTCHA_SERVE_CLIENT !== 'false') {
 
 // PoW Challenge Store
 const powChallengeStore = {
-  challenges: new BoundedMap(),
+  challenges: new ChallengeMap(),
+  issuance: new AdmissionLimiter(),
   usedSolutions: new BoundedSet(),
 
   // Generate a new challenge
   async generate(siteKey, ip, difficulty = 4, minAgeMs = BASE_MIN_AGE_MS) {
+    if (!SHARED_STATE && !this.issuance.allow(ip, 128, 300)) throw new Error('challenge_quota_exceeded');
     const challengeId = crypto.randomBytes(16).toString('hex');
     const nonce = crypto.randomBytes(16).toString('hex');
     const timestamp = Date.now();
@@ -451,7 +455,7 @@ async function detectRateAbuse(ip, siteKey) {
 // happened to send would be a second payload shape to keep in sync across three
 // languages. Fixed shape, empty when unknown.
 function generateToken(ip, siteKey, score, binding = {}) {
-  const ipHash = crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8);
+  const ipHash = ipBinding(SECRET_KEY, ip);
   const data = {
     site_key: siteKey,
     jti: crypto.randomBytes(16).toString('hex'),
@@ -490,7 +494,7 @@ async function verifyToken(token, ip = null) {
 
     // Verify IP matches (if provided)
     if (ip) {
-      const expectedIpHash = crypto.createHash('sha256').update(ip).digest('hex').slice(0, 8);
+      const expectedIpHash = ipBinding(SECRET_KEY, ip);
       if (decoded.ip_hash !== expectedIpHash) {
         return { valid: false, reason: 'ip_mismatch' };
       }
@@ -828,7 +832,27 @@ function collectHeaders(req) {
   return headers;
 }
 
-const asyncRoute = (handler) => (req, res, next) => Promise.resolve().then(() => handler(req, res)).catch(next);
+const asyncRoute = (handler) => (req, res, next) => Promise.resolve().then(() => handler(req, res, next)).catch(next);
+
+const admission = new AdmissionLimiter();
+app.use(['/api', '/siteverify', '/turnstile', '/recaptcha'], asyncRoute(async (req, res, next) => {
+  const ip = PROXY_TRUST.clientIP(req);
+  const allow = (key, max) => SHARED_STATE ? SHARED_STATE.admit(key, max) : admission.allow(key, max);
+  try {
+    if (!await allow('global', 20000) || !await allow(`source:${ip}`, 600) ||
+        (req.originalUrl.split('?')[0].replace(/\/+$/, '').toLowerCase() === '/api/pow/challenge' && !await allow(`challenge:${ip}`, 60))) {
+      return res.status(429).set('Retry-After', '60').json({ error: 'rate_limited' });
+    }
+  } catch (_) { return res.status(503).json({ error: 'state_unavailable' }); }
+  next();
+}));
+
+app.get('/ready', asyncRoute(async (req, res) => {
+  try {
+    if (SHARED_STATE) await SHARED_STATE.ready();
+    res.json({ status: 'ok' });
+  } catch (_) { res.status(503).json({ status: 'unavailable' }); }
+}));
 
 function validateScoringRequest(req, res, next) {
   const body = req.body;
@@ -1006,7 +1030,8 @@ app.use((err, req, res, next) => {
 
 async function start() {
   if (SHARED_STATE) await SHARED_STATE.connect();
-  const server = app.listen(PORT, () => {
+  const host = SECRET_KEY === require('./config').INSECURE_DEFAULT_SECRET ? '127.0.0.1' : '0.0.0.0';
+  const server = app.listen(PORT, host, () => {
     console.log(`FCaptcha server running on port ${server.address().port}`);
     console.log(`Trusted proxies: ${PROXY_TRUST.describe()}`);
     console.log(`Site keys: ${SITE_KEYS.describe()}`);

package/webbotauth.js

@@ -65,7 +65,8 @@ const {
 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 directoryAgent = new https.Agent({ keepAlive: true, maxTotalSockets: 16, maxSockets: 2, maxFreeSockets: 2, timeout: VERIFY_TIMEOUT_MS });
+const MAX_DIRECTORY_BYTES = 256 * 1024;
 const DIRECTORY_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 
 // The exact message web-bot-auth/crypto throws when crypto.subtle.verify()
@@ -91,7 +92,11 @@ const REQUIRED_TAG = 'web-bot-auth';
 const MAX_SIGNATURE_LIFETIME_S = 24 * 60 * 60;
 
 // origin (https://host[:port]) → { keys: JsonWebKey[], fetchedAt: number }
-const directoryCache = new Map();
+const { BoundedMap } = require('./limits');
+// Each response is at most 256 KiB. Sixteen entries bound retained payload bytes;
+// limiting parsed keys also bounds key-import work per verification.
+const directoryCache = new BoundedMap(16);
+const directoryInflight = 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.
@@ -159,6 +164,7 @@ function fetchJSON(documentUrl) {
       documentUrl,
       {
         lookup: guardedLookup,
+        agent: directoryAgent,
         timeout: VERIFY_TIMEOUT_MS,
         headers: {
           accept: 'application/http-message-signatures-directory+json, application/json',
@@ -191,6 +197,8 @@ function fetchJSON(documentUrl) {
       },
     );
 
+    const deadline = setTimeout(() => req.destroy(new FetchFailure('directory fetch deadline exceeded')), VERIFY_TIMEOUT_MS);
+    req.on('close', () => clearTimeout(deadline));
     req.on('timeout', () => {
       req.destroy(new FetchFailure('directory fetch timed out'));
     });
@@ -236,11 +244,38 @@ async function getKeys(url, type) {
   const now = Date.now();
   const cached = directoryCache.get(url);
   if (cached && now - cached.fetchedAt < DIRECTORY_CACHE_TTL_MS) {
+    if (cached.error) {
+      if (now - cached.fetchedAt < 30000) throw new FetchFailure('directory temporarily unavailable');
+    } else {
     return cached.keys;
+    }
   }
-  const keys = type === DISCOVERY_CIMD ? await fetchViaCIMD(url) : await fetchKeySet(url);
-  directoryCache.set(url, { keys, fetchedAt: now });
-  return keys;
+  if (directoryInflight.has(url)) return directoryInflight.get(url);
+  if (directoryInflight.size >= 8) throw new FetchFailure('directory fetch capacity reached');
+  const pending = (async () => {
+    try {
+      const rawKeys = type === DISCOVERY_CIMD ? await fetchViaCIMD(url) : await fetchKeySet(url);
+      if (rawKeys.length > 64) throw new FetchFailure('too many directory keys');
+      // Cache only public JWK fields, not arbitrary nested directory metadata.
+      const keys = rawKeys.map(raw => {
+        if (!raw || typeof raw !== 'object') throw new FetchFailure('invalid directory key');
+        const key = {};
+        for (const field of ['kty', 'kid', 'alg', 'crv', 'x', 'y', 'n', 'e', 'use']) {
+          if (raw[field] == null) continue;
+          if (typeof raw[field] !== 'string' || raw[field].length > 4096) throw new FetchFailure('invalid key field');
+          key[field] = raw[field];
+        }
+        return key;
+      });
+      directoryCache.set(url, { keys, fetchedAt: Date.now() });
+      return keys;
+    } catch (error) {
+      directoryCache.set(url, { error: true, fetchedAt: Date.now() });
+      throw error;
+    } finally { directoryInflight.delete(url); }
+  })();
+  directoryInflight.set(url, pending);
+  return pending;
 }
 
 // resolveKey fetches the directory named by the Signature-Agent header and