http-protect package

Rate limiting and IP banning for express-like HTTP servers, backed by Redis.

HttpProtect counts requests per client IP and, past two configurable thresholds, first answers 429 and then adds the address to a persistent block list answered with 418. Mount it as HttpProtect.jsonMiddleware(), HttpProtect.textMiddleware() or HttpProtect.middleware(), or call HttpProtect.verify() yourself and act on the VerificationStatus it returns.

Remarks

Three things about this package are load-bearing and none of them is visible in a signature.

A ban is permanent. Addresses go into a Redis set that is never given an expiry and never written to again, and there is no method here that removes one — so an address stays banned until something outside this package deletes it from Redis. Read HttpProtect.banLimit before choosing a value for it.

The request counter measures a continuous stream, not a fixed window. Its TTL is pushed back to HttpProtect.ttl on every request, so the count only resets after a full ttl of silence from that address. A client that keeps making requests accumulates indefinitely, which is why the default HttpProtect.maxRequests of 200 stops a steady 1-per-second client after about 200 seconds and not just a 200-request burst.

Everything is keyed by the client IP, and by default that comes from proxy headers a client can set. See HttpProtectOptions.getClientIp before exposing this to the internet behind a proxy you do not control.

Example 1

import HttpProtect from '@imqueue/http-protect';

// 429 then 418, as JSON, using default thresholds and a local Redis
app.use(new HttpProtect().jsonMiddleware());

Example 2

import HttpProtect, { VerificationStatus } from '@imqueue/http-protect';

const protect = new HttpProtect({ ttl: 60, maxRequests: 600, banLimit: 5000 });
const { status, httpCode } = await protect.verify(req);

if (status !== VerificationStatus.SAFE) {
    res.status(httpCode).end();
}

Classes

Enumerations

Interfaces

Read this page as plain markdown — no HTML, no navigation. For pasting into an LLM, or for an agent to fetch.