Rate Limit

Turn the limiter on. Defaults to on whenever Redis is configured (the limiter is only instantiated when Redis is present); set false to disable throttling entirely.

The counting algorithm. sliding-window smooths bursts across the window boundary; fixed-window is cheapest but allows edge bursts; token-bucket permits controlled bursting up to a refill rate.

• sliding-window— Accurate, burst-resistant. Recommended.
• fixed-window— Cheapest; can allow 2× bursts at window edges.
• token-bucket— Allows bursts up to a bucket size, refilled over time.

Redis key prefix for limiter counters — isolate multiple apps on one Redis.

Behaviour when the Redis backend errors (not a missing key). true = deny (fail closed) for all categories; false = allow (fail open) for all. Default (unset): fail closed for auth routes only — so a Redis outage can't open a brute-force window on login/register/reset/magic-link — and fail open elsewhere.

Count requests per client IP.

Intended to count requests per authenticated user, but this dimension is NOT active in the default request pipeline — the built-in middleware runs before authentication and passes no userId, so shipped limiting is effectively per-IP / per-endpoint. Only meaningful for direct RateLimiter.check() calls you make yourself with a userId.

Track each endpoint separately so a busy route doesn't exhaust another's budget.

A RateLimiter-service capability (implemented via decrement()) that is NOT applied by the default request middleware — enabling it has no effect on shipped behaviour unless you call the service yourself.

Budgets for authentication endpoints: a shared default plus stricter per-route overrides. Each override is { window, max } and the sensitive ones add blockDuration — a cooldown that locks the client out after the limit trips.

Budget applied to unauthenticated/public endpoints.

Budget applied to authenticated endpoints.

Custom names for the rate-limit response headers (remaining quota, reset time, total limit) so clients can back off gracefully. Defaults: remaining 'X-RateLimit-Remaining', reset 'X-RateLimit-Reset' (emitted as a Unix epoch-seconds timestamp), limit 'X-RateLimit-Limit'.

Identifiers (e.g. IPs) that bypass rate limiting entirely.

Identifiers that are always blocked, regardless of budget. Entries are exact strings or * glob wildcards (not CIDR); blacklisted IPs are refused with a fixed 24h Retry-After.

IPs/CIDRs of trusted reverse proxies or load balancers. The client IP is taken from the TCP socket peer, and X-Forwarded-For (falling back to X-Real-IP) is honored only when the peer matches a trustedProxies entry, walking the chain right-to-left past trusted hops. Behind a proxy you MUST set this, or every client collapses into the proxy's single bucket.

Keeps the timestamps of recent hits and drops any older than the window on each check — a precise rolling count with no bucket-boundary bursts. The default strategy.

Increments a counter keyed by the current window id (now / windowMs). Cheapest, but allows up to 2× max across a boundary.

Refills tokens at max/window and spends one per request, allowing controlled bursts up to the bucket size while smoothing the sustained rate.

When an auth route with a blockDuration trips its limit, a {key}:blocked marker is written with an until timestamp; subsequent requests are refused with a retryAfter until it expires — so brute-forcing login costs the attacker a real lockout, not just a slow drip. Caveat: blockDuration is honored only by the sliding-window and fixed-window strategies; the token-bucket strategy never writes a :blocked marker, so switching strategy to 'token-bucket' disables auth lockout.

When enabled, a request that ultimately succeeds is refunded (a timestamp popped / the counter decremented), so only failed attempts erode the budget — ideal for login where you want to punish wrong passwords, not correct ones.

whitelist and blacklist entries support * wildcards (compiled to a regex). Whitelisted IPs bypass entirely; blacklisted IPs are refused for 24h before any counting happens.