🛡️ Express-Brute-Guard

A lightweight, customizable, and production-ready rate-limiting middleware for Node.js, designed to protect APIs from brute-force and abuse attacks. Built with in-memory storage and optional headers, with support for auto-cleanup of expired IP entries.

---

🚀 Features

• 🔒 Per-IP rate limiting
• ⏲️ Configurable request window and block duration
• ⚡ Fast in-memory store
• 📡 Customizable response headers
• 🧹 Auto cleanup of expired entries (no cron needed)
• 🧱 Pluggable store system (Redis/DB support planned for v2)

---

📦 Installation

bash

npm install express-brute-guard

---

📚 Usage

typescript

import express from 'express';
import { BruteGuard } from 'express-brute-guard';

const app = express();

const bruteGuard = new BruteGuard({
  maxRequests: 5,
  windowMs: 10 * 60 * 1000, // 10 minutes
  blockDuration: 5 * 60 * 1000, // 5 minutes
  errormessage: 'Too many attempts. Please try again later.',
  headers: true, // Add X-RateLimit-* headers
});

// Apply middleware
app.use((req, res, next) => bruteGuard.createGuard(req, res, next));

// Your routes
app.get('/', (req, res) => {
  res.send('Welcome!');
});

app.listen(3000, () => console.log('Server running on port 3000'));

📦 Default Export (Plug & Play Middleware)

If you just want to use BruteGuard with default or minimal config:

typescript

import bruteGuard from 'express-brute-guard';
import express from 'express';

const app = express();

// Apply brute-force protection globally
app.use(bruteGuard.createGuard());

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

✅ Best for: Quick setup and global protection.

⚙️ Named Export (Custom Configs per Route)

If you need custom configurations (e.g., different rate limits per route):

typescript

import { BruteGuard } from 'express-brute-guard';
import express from 'express';

const app = express();

// Create multiple instances with custom configs
const loginLimiter = new BruteGuard({
  maxRequests: 5,
  windowMs: 60 * 1000, // 1 minute
});

const signupLimiter = new BruteGuard({
  maxRequests: 2,
  windowMs: 5 * 60 * 1000, // 5 minutes
});

// Apply per-route brute-force protection
app.post('/login', loginLimiter.createGuard(), (req, res) => {
  res.send('Login route');
});

app.post('/signup', signupLimiter.createGuard(), (req, res) => {
  res.send('Signup route');
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

🔧 Best for: Apps needing fine-grained control, customization, or testing.

---

⚙️ Options

Option	Type	Default	Description
maxRequests	number	10	Max requests allowed before blocking
windowMs	number	5 * 60 * 1000	Time window for tracking requests (in ms)
blockDuration	number	3 * 60 * 1000	How long to block the IP after limit exceeded (in ms)
statusCode	number	429	HTTP status code for blocked requests
errormessage	string	'Too many Requests'	Message shown when limit is exceeded
headers	boolean	true	Whether to set rate-limit headers
store	any	memoryStore	Optional custom store (e.g., Redis support in v2)

---

🧠 How It Works

• Each IP gets tracked on request.
• If requests exceed maxRequests in windowMs, IP is temporarily blocked.
• If an entry expires, it is automatically cleaned up by a background process using setInterval.

---

🔮 Coming in v2

• ✅ Redis store support
• ✅ Sliding window algorithm
• ✅ Per-route configuration
• ✅ Type-safe middleware usage
• ✅ Dashboard / monitoring integration

---

🧪 Testing

Basic test setup (optional):

bash
npm install --save-dev jest supertest

You can write tests to validate:

• Blocking after limit
• Reset after window
• Cleanup behavior

---

🤝 Contributing

PRs and feature requests are welcome! Open issues or reach out via GitHub.

🧑‍💻 Author

Developed by Taran Mesala

For support or feature requests, open an issue.

---

📄 License

This project is licensed under the MIT License.