https://github.com/cityssm/express-abuse-points
Express.js middleware for tracking and blocking abusive behaviour.
https://github.com/cityssm/express-abuse-points
abuse block express express-middleware expressjs middleware nodejs security
Last synced: 5 months ago
JSON representation
Express.js middleware for tracking and blocking abusive behaviour.
- Host: GitHub
- URL: https://github.com/cityssm/express-abuse-points
- Owner: cityssm
- License: mit
- Created: 2020-12-11T20:56:06.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-10-28T00:07:33.000Z (9 months ago)
- Last Synced: 2025-11-24T01:26:25.345Z (8 months ago)
- Topics: abuse, block, express, express-middleware, expressjs, middleware, nodejs, security
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@cityssm/express-abuse-points
- Size: 1.23 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# express-abuse-points
[](https://www.npmjs.com/package/@cityssm/express-abuse-points)
[](https://app.deepsource.com/gh/cityssm/express-abuse-points/)
[](https://codecov.io/gh/cityssm/express-abuse-points)
[](https://github.com/cityssm/express-abuse-points/actions/workflows/coverage.yml)
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
```bash
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
```javascript
import { abuseCheck } from '@cityssm/express-abuse-points'
app.use(abuseCheck())
```
### Recording Abuse
```javascript
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.