Basic rate-limiting middleware for Express. Use to limit repeated requests to public APIs and/or endpoints such as password reset.
A brute-force protection middleware for express routes that rate-limits incoming requests, increasing the delay with each request in a fibonacci-like sequence.
Here is the full control functions;
storeAn instance of
ExpressBrute.MemoryStoreor some other ExpressBrute store (see a list of known stores below).
freeRetriesThe number of retires the user has before they need to start waiting (default: 2)
minWaitThe initial wait time (in milliseconds) after the user runs out of retries (default: 500 milliseconds)
maxWaitThe maximum amount of time (in milliseconds) between requests the user needs to wait (default: 15 minutes). The wait for a given request is determined by adding the time the user needed to wait for the previous two requests.
lifetimeThe length of time (in seconds since the last request) to remember the number of requests that have been made by an IP. By default it will be set to
maxWait * the number of attempts before you hit maxWaitto discourage simply waiting for the lifetime to expire before resuming an attack. With default values this is about 6 hours.
failCallbackGets called with (
nextValidRequestDate) when a request is rejected (default: ExpressBrute.FailForbidden)
attachResetToRequestSpecify whether or not a simplified reset method should be attached at
req.brute.reset. The simplified method takes only a callback, and resets all
ExpressBrutemiddleware that was called on the current request. If multiple instances of
ExpressBrutehave middleware on the same request, only those with
attachResetToRequestset to true will be reset (default: true)
refreshTimeoutOnRequestDefines whether the
lifetimecounts from the time of the last request that ExpressBrute didn’t prevent for a given IP (true) or from of that IP’s first request (false). Useful for allowing limits over fixed periods of time, for example: a limited number of requests per day. (Default: true). More info
handleStoreErrorGets called whenever an error occurs with the persistent store from which ExpressBrute cannot recover. It is passed an object containing the properties
message(a description of the message),
parent(the error raised by the session store), and [
ip] or [
next] depending on whether or the error occurs during
resetor in the middleware itself.
For an API-only server where the rate-limiter should be applied to all requests:
For a “regular” web server (e.g. anything that uses
express.static()), where the rate-limiter should only apply to certain requests:
Create multiple instances to apply different rules to different routes:
req.rateLimit property is added to all requests with the
remainingnumber of requests for usage in your application code.
- windowMs: milliseconds – how long to keep records of requests in memory. Defaults to
- delayAfter: max number of connections during
windowMsbefore starting to delay responses. Defaults to
1. Set to
0to disable delaying.
- delayMs: milliseconds – how long to delay the response, multiplied by (number of recent hits –
delayAfter). Defaults to
1000(1 second). Set to
0to disable delaying.
- max: max number of connections during
windowMsmilliseconds before sending a 429 response. Defaults to
5. Set to
- message: Error message returned when
maxis exceeded. Defaults to
'Too many requests, please try again later.'
- statusCode: HTTP status code returned when
maxis exceeded. Defaults to
- headers: Enable headers for request limit (
X-RateLimit-Limit) and current usage (
X-RateLimit-Remaining) on all responses and time to wait before retrying (
- skipFailedRequests: when
truefailed requests (response status >= 400) won’t be counted. Defaults to
- keyGenerator: Function used to generate keys. By default user IP address (req.ip) is used. Defaults:
- skip: Function used to skip requests. Returning true from the function will skip limiting for that request. Defaults:
- handler: The function to execute once the max limit is exceeded. It receives the request and the response objects. The “next” param is available if you need to pass to the next middleware. Defaults:
- onLimitReached: Function to listen each time the limit is reached. You can use it to debug/log. Defaults:
- store: The storage to use when persisting rate limit attempts. By default, the MemoryStore is used. It must implement the following in order to function:
Avaliable data stores are:
- MemoryStore: (default)Simple in-memory option. Does not share state when app has multiple processes or servers.
delayMs options were written for human-facing pages such as login and password reset forms. For public APIs, setting these to
0 (disabled) and relying on only
max for rate-limiting usually makes the most sense.
- resetKey(key): Resets the rate limiting for a given key. (Allow users to complete a captcha or whatever to reset their rate limit, then call this method.)
v2 uses a less precise but less resource intensive method of tracking hits from a given IP. v2 also adds the
limiter.resetKey() API and removes the
global: true option.