web-agent-bridge 3.3.0 → 3.8.1

package/server/security/dry-run.js

@@ -1,180 +1,180 @@
-'use strict';
-
-/**
- * WAB Safety Shield — Mandatory Dry-Run
- *
- * Implements WAB SPEC §8.10. For commands the site classifies as
- * destructive (or which match the SPEC default destructive verb list,
- * see token-scope.js), the Bridge MUST refuse `dry_run: false` until a
- * preceding `dry_run: true` plan has been produced AND has not expired.
- *
- * Wire format:
- *   - Request:  body.dry_run === true | false   (default: undefined)
- *               body.plan_id   (required when dry_run === false)
- *   - Response (dry_run=true):
- *       { type:'success', result:{ dry_run:true, plan_id, expires_at,
- *         simulated:{ would_affect:[...], side_effects:[...], reversible:bool }}}
- *
- * Plan expiry:
- *   - Plans are short-lived (default 5 min, max 60 min) so an attacker
- *     who steals a session cannot replay an old plan against a changed
- *     target.
- *   - Plans are bound to (sessionToken, siteId, actionName, paramsHash)
- *     — any drift invalidates them.
- *
- * Errors:
- *   DRY_RUN_REQUIRED         — destructive action invoked without a plan
- *   DRY_RUN_PLAN_NOT_FOUND   — plan_id supplied but unknown / expired
- *   DRY_RUN_PLAN_MISMATCH    — plan exists but params/action drifted
- *   DRY_RUN_PLAN_EXPIRED     — plan past TTL
- *
- * The simulator is a pluggable function passed by the caller — this
- * module only owns the policy + plan-store. Sites/adapters provide the
- * actual "what would this do" answer.
- */
-
-const crypto = require('crypto');
-const { isDestructiveAction } = require('./token-scope');
-
-const DEFAULT_TTL_MS = 5 * 60 * 1000;       // 5 min
-const MAX_TTL_MS = 60 * 60 * 1000;          // 60 min hard cap
-const PLAN_STORE_MAX = 5000;                // LRU bound
-
-// ─── Plan store (in-memory, single-process) ──────────────────────────
-// In a multi-process deployment this should be backed by Redis; the
-// interface is intentionally minimal so swap-out is trivial.
-
-const _plans = new Map();   // plan_id -> entry
-
-function _evictIfFull() {
-  if (_plans.size <= PLAN_STORE_MAX) return;
-  // Evict ~10% of oldest entries.
-  const drop = Math.ceil(PLAN_STORE_MAX * 0.1);
-  let i = 0;
-  for (const k of _plans.keys()) {
-    if (i++ >= drop) break;
-    _plans.delete(k);
-  }
-}
-
-function _hashParams(params) {
-  const canon = JSON.stringify(_canonicalize(params || {}));
-  return crypto.createHash('sha256').update(canon).digest('hex').slice(0, 24);
-}
-
-function _canonicalize(value) {
-  if (value === null || typeof value !== 'object') return value;
-  if (Array.isArray(value)) return value.map(_canonicalize);
-  const out = {};
-  for (const k of Object.keys(value).sort()) out[k] = _canonicalize(value[k]);
-  return out;
-}
-
-// ─── Public API ──────────────────────────────────────────────────────
-
-/**
- * Decide whether `actionName` requires dry-run. Site config may EXPAND
- * the default destructive list (token-scope.DEFAULT_DESTRUCTIVE_VERBS)
- * via `destructiveActions[]` and may SUPPRESS via `nonDestructiveActions[]`.
- *
- * Sites can also explicitly opt OUT (rare, usually only for read-only
- * mirror/staging sandboxes) by setting `dryRunPolicy: "off"`.
- * They can opt IN universally with `dryRunPolicy: "always"`.
- */
-function requiresDryRun(actionName, siteConfig = {}) {
-  const policy = String(siteConfig.dryRunPolicy || 'auto').toLowerCase();
-  if (policy === 'off') return false;
-  if (policy === 'always') return true;
-  // auto = use destructive-verb classification.
-  return isDestructiveAction(actionName, siteConfig);
-}
-
-/**
- * Create a plan. Returns the plan envelope to be sent back to the agent.
- *
- * @param {object} ctx        { sessionToken, siteId, actionName, params }
- * @param {object} simulation { would_affect, side_effects, reversible, summary? }
- * @param {object} opts       { ttlMs }
- */
-function createPlan(ctx, simulation, opts = {}) {
-  const ttl = Math.min(Math.max(opts.ttlMs || DEFAULT_TTL_MS, 1_000), MAX_TTL_MS);
-  const plan_id = 'wabp_' + crypto.randomBytes(16).toString('hex');
-  const now = Date.now();
-  const params_hash = _hashParams(ctx.params);
-  const entry = {
-    plan_id,
-    session_fingerprint: _sessionFingerprint(ctx.sessionToken),
-    site_id: ctx.siteId,
-    action_name: ctx.actionName,
-    params_hash,
-    simulation: {
-      would_affect: simulation.would_affect || [],
-      side_effects: simulation.side_effects || [],
-      reversible: simulation.reversible !== false,
-      summary: simulation.summary || null,
-    },
-    created_at: now,
-    expires_at: now + ttl,
-  };
-  _plans.set(plan_id, entry);
-  _evictIfFull();
-  return {
-    dry_run: true,
-    plan_id,
-    expires_at: new Date(entry.expires_at).toISOString(),
-    simulated: entry.simulation,
-  };
-}
-
-/**
- * Validate a plan against a real (dry_run=false) request.
- *
- * Returns { ok: true, plan } on success; otherwise
- * { ok: false, code, message }.
- */
-function consumePlan(planId, ctx) {
-  if (!planId) return { ok: false, code: 'DRY_RUN_REQUIRED', message: 'destructive action requires a prior dry_run plan' };
-  const entry = _plans.get(planId);
-  if (!entry) return { ok: false, code: 'DRY_RUN_PLAN_NOT_FOUND', message: 'plan_id unknown or already consumed' };
-  const now = Date.now();
-  if (now > entry.expires_at) {
-    _plans.delete(planId);
-    return { ok: false, code: 'DRY_RUN_PLAN_EXPIRED', message: 'plan expired, please re-run dry_run' };
-  }
-  if (entry.session_fingerprint !== _sessionFingerprint(ctx.sessionToken)) {
-    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued to a different session' };
-  }
-  if (entry.site_id !== ctx.siteId) {
-    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued for a different site' };
-  }
-  if (entry.action_name !== ctx.actionName) {
-    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued for a different action' };
-  }
-  if (entry.params_hash !== _hashParams(ctx.params)) {
-    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'parameters changed since plan was generated' };
-  }
-  // Single-use: consume.
-  _plans.delete(planId);
-  return { ok: true, plan: entry };
-}
-
-/** Test helper. */
-function _resetForTests() {
-  _plans.clear();
-}
-
-function _sessionFingerprint(token) {
-  if (!token) return null;
-  return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 16);
-}
-
-module.exports = {
-  requiresDryRun,
-  createPlan,
-  consumePlan,
-  // helpers exposed for tests
-  _resetForTests,
-  _hashParams,
-  DEFAULT_TTL_MS,
-  MAX_TTL_MS,
-};
+'use strict';
+
+/**
+ * WAB Safety Shield — Mandatory Dry-Run
+ *
+ * Implements WAB SPEC §8.10. For commands the site classifies as
+ * destructive (or which match the SPEC default destructive verb list,
+ * see token-scope.js), the Bridge MUST refuse `dry_run: false` until a
+ * preceding `dry_run: true` plan has been produced AND has not expired.
+ *
+ * Wire format:
+ *   - Request:  body.dry_run === true | false   (default: undefined)
+ *               body.plan_id   (required when dry_run === false)
+ *   - Response (dry_run=true):
+ *       { type:'success', result:{ dry_run:true, plan_id, expires_at,
+ *         simulated:{ would_affect:[...], side_effects:[...], reversible:bool }}}
+ *
+ * Plan expiry:
+ *   - Plans are short-lived (default 5 min, max 60 min) so an attacker
+ *     who steals a session cannot replay an old plan against a changed
+ *     target.
+ *   - Plans are bound to (sessionToken, siteId, actionName, paramsHash)
+ *     — any drift invalidates them.
+ *
+ * Errors:
+ *   DRY_RUN_REQUIRED         — destructive action invoked without a plan
+ *   DRY_RUN_PLAN_NOT_FOUND   — plan_id supplied but unknown / expired
+ *   DRY_RUN_PLAN_MISMATCH    — plan exists but params/action drifted
+ *   DRY_RUN_PLAN_EXPIRED     — plan past TTL
+ *
+ * The simulator is a pluggable function passed by the caller — this
+ * module only owns the policy + plan-store. Sites/adapters provide the
+ * actual "what would this do" answer.
+ */
+
+const crypto = require('crypto');
+const { isDestructiveAction } = require('./token-scope');
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;       // 5 min
+const MAX_TTL_MS = 60 * 60 * 1000;          // 60 min hard cap
+const PLAN_STORE_MAX = 5000;                // LRU bound
+
+// ─── Plan store (in-memory, single-process) ──────────────────────────
+// In a multi-process deployment this should be backed by Redis; the
+// interface is intentionally minimal so swap-out is trivial.
+
+const _plans = new Map();   // plan_id -> entry
+
+function _evictIfFull() {
+  if (_plans.size <= PLAN_STORE_MAX) return;
+  // Evict ~10% of oldest entries.
+  const drop = Math.ceil(PLAN_STORE_MAX * 0.1);
+  let i = 0;
+  for (const k of _plans.keys()) {
+    if (i++ >= drop) break;
+    _plans.delete(k);
+  }
+}
+
+function _hashParams(params) {
+  const canon = JSON.stringify(_canonicalize(params || {}));
+  return crypto.createHash('sha256').update(canon).digest('hex').slice(0, 24);
+}
+
+function _canonicalize(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(_canonicalize);
+  const out = {};
+  for (const k of Object.keys(value).sort()) out[k] = _canonicalize(value[k]);
+  return out;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Decide whether `actionName` requires dry-run. Site config may EXPAND
+ * the default destructive list (token-scope.DEFAULT_DESTRUCTIVE_VERBS)
+ * via `destructiveActions[]` and may SUPPRESS via `nonDestructiveActions[]`.
+ *
+ * Sites can also explicitly opt OUT (rare, usually only for read-only
+ * mirror/staging sandboxes) by setting `dryRunPolicy: "off"`.
+ * They can opt IN universally with `dryRunPolicy: "always"`.
+ */
+function requiresDryRun(actionName, siteConfig = {}) {
+  const policy = String(siteConfig.dryRunPolicy || 'auto').toLowerCase();
+  if (policy === 'off') return false;
+  if (policy === 'always') return true;
+  // auto = use destructive-verb classification.
+  return isDestructiveAction(actionName, siteConfig);
+}
+
+/**
+ * Create a plan. Returns the plan envelope to be sent back to the agent.
+ *
+ * @param {object} ctx        { sessionToken, siteId, actionName, params }
+ * @param {object} simulation { would_affect, side_effects, reversible, summary? }
+ * @param {object} opts       { ttlMs }
+ */
+function createPlan(ctx, simulation, opts = {}) {
+  const ttl = Math.min(Math.max(opts.ttlMs || DEFAULT_TTL_MS, 1_000), MAX_TTL_MS);
+  const plan_id = 'wabp_' + crypto.randomBytes(16).toString('hex');
+  const now = Date.now();
+  const params_hash = _hashParams(ctx.params);
+  const entry = {
+    plan_id,
+    session_fingerprint: _sessionFingerprint(ctx.sessionToken),
+    site_id: ctx.siteId,
+    action_name: ctx.actionName,
+    params_hash,
+    simulation: {
+      would_affect: simulation.would_affect || [],
+      side_effects: simulation.side_effects || [],
+      reversible: simulation.reversible !== false,
+      summary: simulation.summary || null,
+    },
+    created_at: now,
+    expires_at: now + ttl,
+  };
+  _plans.set(plan_id, entry);
+  _evictIfFull();
+  return {
+    dry_run: true,
+    plan_id,
+    expires_at: new Date(entry.expires_at).toISOString(),
+    simulated: entry.simulation,
+  };
+}
+
+/**
+ * Validate a plan against a real (dry_run=false) request.
+ *
+ * Returns { ok: true, plan } on success; otherwise
+ * { ok: false, code, message }.
+ */
+function consumePlan(planId, ctx) {
+  if (!planId) return { ok: false, code: 'DRY_RUN_REQUIRED', message: 'destructive action requires a prior dry_run plan' };
+  const entry = _plans.get(planId);
+  if (!entry) return { ok: false, code: 'DRY_RUN_PLAN_NOT_FOUND', message: 'plan_id unknown or already consumed' };
+  const now = Date.now();
+  if (now > entry.expires_at) {
+    _plans.delete(planId);
+    return { ok: false, code: 'DRY_RUN_PLAN_EXPIRED', message: 'plan expired, please re-run dry_run' };
+  }
+  if (entry.session_fingerprint !== _sessionFingerprint(ctx.sessionToken)) {
+    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued to a different session' };
+  }
+  if (entry.site_id !== ctx.siteId) {
+    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued for a different site' };
+  }
+  if (entry.action_name !== ctx.actionName) {
+    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'plan was issued for a different action' };
+  }
+  if (entry.params_hash !== _hashParams(ctx.params)) {
+    return { ok: false, code: 'DRY_RUN_PLAN_MISMATCH', message: 'parameters changed since plan was generated' };
+  }
+  // Single-use: consume.
+  _plans.delete(planId);
+  return { ok: true, plan: entry };
+}
+
+/** Test helper. */
+function _resetForTests() {
+  _plans.clear();
+}
+
+function _sessionFingerprint(token) {
+  if (!token) return null;
+  return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 16);
+}
+
+module.exports = {
+  requiresDryRun,
+  createPlan,
+  consumePlan,
+  // helpers exposed for tests
+  _resetForTests,
+  _hashParams,
+  DEFAULT_TTL_MS,
+  MAX_TTL_MS,
+};

package/server/security/human-gate-rate-limit.js

@@ -1,147 +1,147 @@
-'use strict';
-
-/**
- * WAB Safety Shield — IP rate-limiter for /human-gate/approve (SPEC §8.11)
- *
- * Module 1's per-challenge 5-attempt lockout is sufficient against a
- * single attacker spamming one challenge_id. But it does NOT prevent an
- * attacker from rotating across many challenge_ids (or guessing on
- * leaked ones) at high rate. This sliding-window IP limiter caps the
- * approval rate per-IP across all challenges.
- *
- * Defaults — tuned for human use:
- *   • 30 attempts per 10 minutes per IP  (≈1 every 20s)
- *   • 5  approvals  per 10 minutes per IP (success-only sub-cap)
- *
- * Pure in-memory; safe for single-process pm2 deployment we use today.
- * For multi-process scale-out, swap the store for Redis ZSET (TODO).
- */
-
-const DEFAULT_ATTEMPT_WINDOW_MS = 10 * 60 * 1000;
-const DEFAULT_ATTEMPT_LIMIT = 30;
-const DEFAULT_SUCCESS_LIMIT = 5;
-const STORE_MAX_IPS = 10_000;
-
-const _attempts = new Map();   // ip -> [timestamps]
-const _successes = new Map();  // ip -> [timestamps]
-
-let _config = {
-  windowMs: DEFAULT_ATTEMPT_WINDOW_MS,
-  attemptLimit: DEFAULT_ATTEMPT_LIMIT,
-  successLimit: DEFAULT_SUCCESS_LIMIT,
-};
-
-function configure(opts = {}) {
-  const w = Number.isFinite(opts.windowMs) ? opts.windowMs : _config.windowMs;
-  const a = Number.isFinite(opts.attemptLimit) ? opts.attemptLimit : _config.attemptLimit;
-  const s = Number.isFinite(opts.successLimit) ? opts.successLimit : _config.successLimit;
-  _config = {
-    windowMs: Math.max(10, Math.min(60 * 60 * 1000, w)),
-    attemptLimit: Math.max(1, a),
-    successLimit: Math.max(1, s),
-  };
-}
-
-function _prune(map, ip, windowMs, now) {
-  const arr = map.get(ip);
-  if (!arr) return [];
-  const cutoff = now - windowMs;
-  const fresh = arr.filter((t) => t > cutoff);
-  if (fresh.length === 0) map.delete(ip);
-  else map.set(ip, fresh);
-  return fresh;
-}
-
-function _evictIfFull(map) {
-  if (map.size <= STORE_MAX_IPS) return;
-  const drop = Math.ceil(STORE_MAX_IPS * 0.1);
-  let i = 0;
-  for (const k of map.keys()) {
-    if (i++ >= drop) break;
-    map.delete(k);
-  }
-}
-
-/**
- * Returns one of:
- *   { allowed: true,  remaining_attempts, remaining_successes }
- *   { allowed: false, code: 'RATE_LIMIT_TOO_MANY_ATTEMPTS', retry_after_ms }
- *   { allowed: false, code: 'RATE_LIMIT_TOO_MANY_APPROVALS', retry_after_ms }
- *
- * Call BEFORE attempting humanGate.approveChallenge().
- */
-function checkBeforeAttempt(ip) {
-  if (!ip) return { allowed: true, remaining_attempts: _config.attemptLimit, remaining_successes: _config.successLimit };
-  const now = Date.now();
-  const attempts = _prune(_attempts, ip, _config.windowMs, now);
-  const successes = _prune(_successes, ip, _config.windowMs, now);
-
-  if (successes.length >= _config.successLimit) {
-    return {
-      allowed: false,
-      code: 'RATE_LIMIT_TOO_MANY_APPROVALS',
-      retry_after_ms: _config.windowMs - (now - successes[0]),
-    };
-  }
-  if (attempts.length >= _config.attemptLimit) {
-    return {
-      allowed: false,
-      code: 'RATE_LIMIT_TOO_MANY_ATTEMPTS',
-      retry_after_ms: _config.windowMs - (now - attempts[0]),
-    };
-  }
-  return {
-    allowed: true,
-    remaining_attempts: _config.attemptLimit - attempts.length,
-    remaining_successes: _config.successLimit - successes.length,
-  };
-}
-
-/**
- * Record an attempt outcome AFTER calling approveChallenge.
- *  - Always records the attempt timestamp.
- *  - Additionally records a success timestamp when ok===true.
- */
-function recordAttempt(ip, ok) {
-  if (!ip) return;
-  const now = Date.now();
-  const arr = _attempts.get(ip) || [];
-  arr.push(now);
-  _attempts.set(ip, arr);
-  _evictIfFull(_attempts);
-  if (ok) {
-    const sarr = _successes.get(ip) || [];
-    sarr.push(now);
-    _successes.set(ip, sarr);
-    _evictIfFull(_successes);
-  }
-}
-
-function _resetForTests() {
-  _attempts.clear();
-  _successes.clear();
-  _config = {
-    windowMs: DEFAULT_ATTEMPT_WINDOW_MS,
-    attemptLimit: DEFAULT_ATTEMPT_LIMIT,
-    successLimit: DEFAULT_SUCCESS_LIMIT,
-  };
-}
-
-function _stats() {
-  return {
-    config: { ..._config },
-    ips_with_attempts: _attempts.size,
-    ips_with_successes: _successes.size,
-  };
-}
-
-module.exports = {
-  configure,
-  checkBeforeAttempt,
-  recordAttempt,
-  _resetForTests,
-  _stats,
-  DEFAULT_ATTEMPT_WINDOW_MS,
-  DEFAULT_ATTEMPT_LIMIT,
-  DEFAULT_SUCCESS_LIMIT,
-};
+'use strict';
+
+/**
+ * WAB Safety Shield — IP rate-limiter for /human-gate/approve (SPEC §8.11)
+ *
+ * Module 1's per-challenge 5-attempt lockout is sufficient against a
+ * single attacker spamming one challenge_id. But it does NOT prevent an
+ * attacker from rotating across many challenge_ids (or guessing on
+ * leaked ones) at high rate. This sliding-window IP limiter caps the
+ * approval rate per-IP across all challenges.
+ *
+ * Defaults — tuned for human use:
+ *   • 30 attempts per 10 minutes per IP  (≈1 every 20s)
+ *   • 5  approvals  per 10 minutes per IP (success-only sub-cap)
+ *
+ * Pure in-memory; safe for single-process pm2 deployment we use today.
+ * For multi-process scale-out, swap the store for Redis ZSET (TODO).
+ */
+
+const DEFAULT_ATTEMPT_WINDOW_MS = 10 * 60 * 1000;
+const DEFAULT_ATTEMPT_LIMIT = 30;
+const DEFAULT_SUCCESS_LIMIT = 5;
+const STORE_MAX_IPS = 10_000;
+
+const _attempts = new Map();   // ip -> [timestamps]
+const _successes = new Map();  // ip -> [timestamps]
+
+let _config = {
+  windowMs: DEFAULT_ATTEMPT_WINDOW_MS,
+  attemptLimit: DEFAULT_ATTEMPT_LIMIT,
+  successLimit: DEFAULT_SUCCESS_LIMIT,
+};
+
+function configure(opts = {}) {
+  const w = Number.isFinite(opts.windowMs) ? opts.windowMs : _config.windowMs;
+  const a = Number.isFinite(opts.attemptLimit) ? opts.attemptLimit : _config.attemptLimit;
+  const s = Number.isFinite(opts.successLimit) ? opts.successLimit : _config.successLimit;
+  _config = {
+    windowMs: Math.max(10, Math.min(60 * 60 * 1000, w)),
+    attemptLimit: Math.max(1, a),
+    successLimit: Math.max(1, s),
+  };
+}
+
+function _prune(map, ip, windowMs, now) {
+  const arr = map.get(ip);
+  if (!arr) return [];
+  const cutoff = now - windowMs;
+  const fresh = arr.filter((t) => t > cutoff);
+  if (fresh.length === 0) map.delete(ip);
+  else map.set(ip, fresh);
+  return fresh;
+}
+
+function _evictIfFull(map) {
+  if (map.size <= STORE_MAX_IPS) return;
+  const drop = Math.ceil(STORE_MAX_IPS * 0.1);
+  let i = 0;
+  for (const k of map.keys()) {
+    if (i++ >= drop) break;
+    map.delete(k);
+  }
+}
+
+/**
+ * Returns one of:
+ *   { allowed: true,  remaining_attempts, remaining_successes }
+ *   { allowed: false, code: 'RATE_LIMIT_TOO_MANY_ATTEMPTS', retry_after_ms }
+ *   { allowed: false, code: 'RATE_LIMIT_TOO_MANY_APPROVALS', retry_after_ms }
+ *
+ * Call BEFORE attempting humanGate.approveChallenge().
+ */
+function checkBeforeAttempt(ip) {
+  if (!ip) return { allowed: true, remaining_attempts: _config.attemptLimit, remaining_successes: _config.successLimit };
+  const now = Date.now();
+  const attempts = _prune(_attempts, ip, _config.windowMs, now);
+  const successes = _prune(_successes, ip, _config.windowMs, now);
+
+  if (successes.length >= _config.successLimit) {
+    return {
+      allowed: false,
+      code: 'RATE_LIMIT_TOO_MANY_APPROVALS',
+      retry_after_ms: _config.windowMs - (now - successes[0]),
+    };
+  }
+  if (attempts.length >= _config.attemptLimit) {
+    return {
+      allowed: false,
+      code: 'RATE_LIMIT_TOO_MANY_ATTEMPTS',
+      retry_after_ms: _config.windowMs - (now - attempts[0]),
+    };
+  }
+  return {
+    allowed: true,
+    remaining_attempts: _config.attemptLimit - attempts.length,
+    remaining_successes: _config.successLimit - successes.length,
+  };
+}
+
+/**
+ * Record an attempt outcome AFTER calling approveChallenge.
+ *  - Always records the attempt timestamp.
+ *  - Additionally records a success timestamp when ok===true.
+ */
+function recordAttempt(ip, ok) {
+  if (!ip) return;
+  const now = Date.now();
+  const arr = _attempts.get(ip) || [];
+  arr.push(now);
+  _attempts.set(ip, arr);
+  _evictIfFull(_attempts);
+  if (ok) {
+    const sarr = _successes.get(ip) || [];
+    sarr.push(now);
+    _successes.set(ip, sarr);
+    _evictIfFull(_successes);
+  }
+}
+
+function _resetForTests() {
+  _attempts.clear();
+  _successes.clear();
+  _config = {
+    windowMs: DEFAULT_ATTEMPT_WINDOW_MS,
+    attemptLimit: DEFAULT_ATTEMPT_LIMIT,
+    successLimit: DEFAULT_SUCCESS_LIMIT,
+  };
+}
+
+function _stats() {
+  return {
+    config: { ..._config },
+    ips_with_attempts: _attempts.size,
+    ips_with_successes: _successes.size,
+  };
+}
+
+module.exports = {
+  configure,
+  checkBeforeAttempt,
+  recordAttempt,
+  _resetForTests,
+  _stats,
+  DEFAULT_ATTEMPT_WINDOW_MS,
+  DEFAULT_ATTEMPT_LIMIT,
+  DEFAULT_SUCCESS_LIMIT,
+};