*

* Design decisions:

* - Pure in-memory Map – no external dependencies; suitable for a single

* gateway process. The Map is periodically pruned to avoid unbounded

* growth.

* gateway process. The Map is periodically pruned and capped to avoid

* unbounded growth.

* - Loopback addresses (127.0.0.1 / ::1) are exempt by default so that local

* CLI sessions are never locked out.

* - The module is side-effect-free: callers create an instance via

* {@link createAuthRateLimiter} and pass it where needed.

*/

import { resolveTimerTimeoutMs } from "../shared/number-coercion.js";

import { resolveIntegerOption, resolveTimerTimeoutMs } from "../shared/number-coercion.js";

import { isLoopbackAddress, resolveClientIp } from "./net.js";

// ---------------------------------------------------------------------------

exemptLoopback?: boolean;

/** Background prune interval in milliseconds; set <= 0 to disable auto-prune. @default 60_000 */

pruneIntervalMs?: number;

/** Maximum tracked client identities before old unlocked entries are evicted. @default 10_000 */

maxEntries?: number;

}

export const AUTH_RATE_LIMIT_SCOPE_DEFAULT = "default";

const DEFAULT_WINDOW_MS = 60_000; // 1 minute

const DEFAULT_LOCKOUT_MS = 300_000; // 5 minutes

const PRUNE_INTERVAL_MS = 60_000; // prune stale entries every minute

const DEFAULT_MAX_ENTRIES = 10_000;

// ---------------------------------------------------------------------------

// Implementation

const lockoutMs = resolveTimerTimeoutMs(config?.lockoutMs, DEFAULT_LOCKOUT_MS, 0);

const exemptLoopback = config?.exemptLoopback ?? true;

const pruneIntervalMs = resolvePruneIntervalMs(config?.pruneIntervalMs);

const maxEntries = resolveIntegerOption(config?.maxEntries, DEFAULT_MAX_ENTRIES, { min: 1 });

const entries = new Map<string, RateLimitEntry>();

let overflowLockedUntil: number | undefined;

// Periodic cleanup to avoid unbounded map growth.

const pruneTimer = pruneIntervalMs > 0 ? setInterval(() => prune(), pruneIntervalMs) : null;

const entry = entries.get(key);

if (!entry) {

const overflowLock = checkOverflowLock(now);

if (overflowLock) {

return overflowLock;

}

return { allowed: true, remaining: maxAttempts, retryAfterMs: 0 };

}

let entry = entries.get(key);

if (!entry) {

if (!enforceMaxEntries(now)) {

overflowLockedUntil = Math.max(overflowLockedUntil ?? 0, now + lockoutMs);

return;

}

entry = { attempts: [] };

entries.set(key, entry);

}

entries.delete(key);

}

function prune(): void {

const now = Date.now();

function pruneExpiredEntries(now: number): void {

for (const [key, entry] of entries) {

// If locked out, keep the entry until the lockout expires.

if (entry.lockedUntil && now < entry.lockedUntil) {

}

}

function checkOverflowLock(now: number): RateLimitCheckResult | undefined {

if (!overflowLockedUntil) {

return undefined;

}

if (now >= overflowLockedUntil) {

overflowLockedUntil = undefined;

return undefined;

}

if (entries.size >= maxEntries) {

pruneExpiredEntries(now);

}

if (entries.size < maxEntries) {

overflowLockedUntil = undefined;

return undefined;

}

return {

allowed: false,

remaining: 0,

retryAfterMs: overflowLockedUntil - now,

};

}

function enforceMaxEntries(now: number): boolean {

if (entries.size < maxEntries) {

return true;

}

pruneExpiredEntries(now);

if (entries.size < maxEntries) {

return true;

}

// Preserve active lockouts so a flood cannot evict the attacker's own block.

for (const [entryKey, entry] of entries) {

if (!entry.lockedUntil || now >= entry.lockedUntil) {

entries.delete(entryKey);

return true;

}

}

return false;

}

function prune(): void {

pruneExpiredEntries(Date.now());

}

function size(): number {

return entries.size;

}

clearInterval(pruneTimer);

}

entries.clear();

overflowLockedUntil = undefined;

}

return { check, recordFailure, reset, size, prune, dispose };