express-brute

1.0.1 verified Sat Apr 25 auth: no javascript

A brute-force protection middleware for Express.js that rate-limits incoming requests using a Fibonacci sequence for increasing delays. Current stable version is 1.0.1. It provides flexible options like freeRetries, minWait, maxWait, lifetime, and custom failure callbacks. The package supports various persistent stores (e.g., Memcached, Redis) via community modules, and includes built-in MemoryStore for development. It is released under the MIT license.

Common errors

error Error: Cannot find module 'express-brute' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install express-brute' in your project directory.

error TypeError: ExpressBrute.MemoryStore is not a constructor ↓

cause Importing incorrectly with ES module syntax or destructuring.

fix

Use 'const ExpressBrute = require('express-brute');' then 'new ExpressBrute.MemoryStore();'.

error Error: Most persistent stores cannot find the session store. ↓

cause Using MemoryStore in production or missing peer dependencies for your chosen store.

fix

Install a persistent store module (e.g., 'npm install express-brute-memcached') and use its store constructor.

Warnings

breaking proxyDepth option removed in v1.0.0; use app.set('trust proxy', x) instead. ↓

fix Remove proxyDepth option from ExpressBrute constructor and set trust proxy via app.set('trust proxy', <value>).

breaking getIPFromRequest method removed in v1.0.0; use req.ip instead. ↓

fix Replace any calls to instance.getIPFromRequest(req) with req.ip.

deprecated Express 3.x support dropped; peer dependency is express 4.x. ↓

fix Upgrade your project to use Express 4.x.

gotcha MemoryStore should not be used in production; it does not persist across server restarts. ↓

fix Use a persistent store like express-brute-memcached, express-brute-redis, or express-brute-mongoose.

breaking In v0.6.0, .reset callbacks are always called asynchronously, even with MemoryStore. ↓

fix Ensure any code relying on synchronous callback execution is updated to handle async behavior.

gotcha Default failCallback is ExpressBrute.FailForbidden which returns 403; consider using FailTooManyRequests for 429. ↓

fix Explicitly set failCallback: ExpressBrute.FailTooManyRequests in options for proper rate-limit status code.

Install

npm install express-brute

yarn add express-brute

pnpm add express-brute

Imports

ExpressBrute
wrong
```
import ExpressBrute from 'express-brute';
```
correct
```
const ExpressBrute = require('express-brute');
```
express-brute is a CommonJS package; it does not provide ESM exports. Use require() in Node.js.
ExpressBrute.MemoryStore
wrong
```
import { MemoryStore } from 'express-brute';
```
correct
```
const store = new ExpressBrute.MemoryStore();
```
MemoryStore is a property of the ExpressBrute constructor, not a named export.

ExpressBrute.FailTooManyRequests

wrong

const bruteforce = new ExpressBrute(store, { failCallback: 'FailTooManyRequests' });

correct

const bruteforce = new ExpressBrute(store, { failCallback: ExpressBrute.FailTooManyRequests });

FailTooManyRequests is a built-in callback function, not a string. It returns HTTP 429 status.

Quickstart

Sets up a basic Express server with express-brute to rate-limit the /auth route, using MemoryStore and a Fibonacci backoff.

const express = require('express');
const ExpressBrute = require('express-brute');

const app = express();
const store = new ExpressBrute.MemoryStore(); // only for development, use persistent store in production
const bruteforce = new ExpressBrute(store, {
  freeRetries: 2,
  minWait: 500, // milliseconds
  maxWait: 15 * 60 * 1000, // 15 minutes
  failCallback: ExpressBrute.FailTooManyRequests
});

app.post('/auth',
  bruteforce.prevent,
  (req, res) => {
    res.send('Success!');
  }
);

app.listen(3000);