https://github.com/sjinks/express-ip-filter-middleware

Express middleware for access control using IP / CIDR lists
https://github.com/sjinks/express-ip-filter-middleware

access access-control express express-js express-middleware expressjs filter ip ip-address middleware

Last synced: about 1 month ago
JSON representation

Express middleware for access control using IP / CIDR lists

• Host: GitHub
• URL: https://github.com/sjinks/express-ip-filter-middleware
• Owner: sjinks
• License: mit
• Created: 2020-05-26T18:08:36.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2024-04-23T01:35:27.000Z (7 months ago)
• Last Synced: 2024-04-24T03:16:52.370Z (7 months ago)
• Topics: access, access-control, express, express-js, express-middleware, expressjs, filter, ip, ip-address, middleware
• Language: TypeScript
• Homepage: https://www.npmjs.com/package/express-ip-filter-middleware
• Size: 2.2 MB
• Stars: 4
• Watchers: 3
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# express-ip-filter-middleware

![Build and Test CI](https://github.com/sjinks/express-ip-filter-middleware/workflows/Build%20and%20Test%20CI/badge.svg)

Express middleware for access control using IP / CIDR lists.

## Installation

```bash

npm install express-ip-filter-middleware 

```

## Usage

```typescript

import { BlockList } from 'node:net';

import express from 'express';

import { ipFilterMiddleware } from 'express-ip-filter-middleware';

const allow = new BlockList();

allow.addSubnet('192.168.0.0', 16);

const deny = new BlockList();

deny.addAddress('192.168.0.1');

const options = {

    mode: 'whitelist',

    allow,

    deny,

};

const app = express();

app.use(ipFilterMiddleware(options))

```

`express-ip-filter-middleware` generates a middleware that allows or blocks access per the specified options.

Options is an object with the following fields:

  * `mode: 'whitelist' | 'blacklist'` (**required**): operation mode. In `blacklist` mode, everything is allowed except for the explicitly blacklisted items (specified in `deny`), unless overridden by `allow`. In `whitelist` mode, everything is forbidden except for explicitly allowed items (specified in `allow`), unless overridden by `deny`;

  * `allow: net.BlockList`: optional list of the allowed addresses;

  * `deny: net.BlockList`: optional list of the denied addresses;

  * `ipOverride: (req: express.Request) => string | undefined`: optional function to retrieve the IP address to check. If this function is not specified, `req.ip` is used. If this function returns an invalid IP address, the middleware bails out with an error.

The mode of operation is similar to Apache's `mod_access` `Order` directive: `whitelist` works like `Order Allow,Deny`: to allow access, the IP address must match the `allow` list, and must not be listed in the `deny` list. Consequently, empty `allow` and `deny` in `allow` mode will result in denied access.

`blacklist` mode works like `Order Deny,Allow`: the request is allowed if the IP address is listed in the `allow` list *or* not listed in the `deny` list.