express-abuse-points

Express.js middleware for tracking and blocking abusive behaviour.

Need to block a user repeatedly entering incorrect passwords into a login form?

Need to stop a user testing invalid product SKUs and coupon codes in an online store?

Need to discourage a user from testing out functions they don't have permission to use?

This middleware is for you!

Installation

npm install @cityssm/express-abuse-points

Usage

It is recommended to include the middleware as early as possible in the middleware chain to enforce the block as soon as possible.

Initializing

import { abuseCheck } from "@cityssm/express-abuse-points";

app.use(abuseCheck());

Recording Abuse

import { recordAbuse } from "@cityssm/express-abuse-points";

if (userDidSomethingBad) {
  recordAbuse(req, 3);
}

API

abuseCheck([options: {}])

The function to include in the Express application setup to initialize the middleware. It accepts the following options.

Property Name	Description	Default Value
byIP	Whether or not abuse points should be tracked by IP address.	true
byXForwardedFor	Whether or not abuse points should be tracked by the X-Forwarded-For header (proxy situations).	false
abusePoints	The default number of points assigned to an abuse event.	1
expiryMillis	The default number of milliseconds an abuse record is enforced before expiring.	300000 (five minutes)
abusePointsMax	The total number of points a user can accumulate before being blocked.	10
clearIntervalMillis	The frequency the memory is cleared of expired abuse records.	3600000

recordAbuse(req: Request, [abusePoints: number, [expiryMillis: number]])

The function to include in the Express handlers to record abusive behaviours.

An optional abusePoints parameter is available if the record should have more or less weight than the default abusePoints.

An optional expiryMillis parameter is available if the record should expiry sooner or later than the default expiryMillis.

isAbuser(req: Request)

Returns true if the given requestor has reached the abuse points threshold.

clearAbuse(req: Request)

Clears all abuse records for the given requestor, expired or not. Helpful if, for example, abuse was tracked for incorrect password attempts, but the user was finally successful.