express-ip-access-control

1.1.3 verified Sat Apr 25 auth: no javascript maintenance

An Express.js middleware for IP-based access control, supporting whitelist/blacklist modes, IPv4, IPv6, CIDR, and IPv4-mapped IPv6 addresses. Current stable version is 1.1.3, released June 2018, with no recent updates. Key features include force connection address, custom deny actions (redirect or message), custom logging, and Node.js/Express 4 compatibility. Differentiators: lightweight, zero dependencies besides ipaddr.js (bundled), simple API for common IP filtering patterns.

Common errors

error TypeError: AccessControl is not a function ↓

cause Using ESM import instead of CommonJS require.

fix

Use const AccessControl = require('express-ip-access-control');

error Error: Cannot find module 'express' ↓

cause express is a peer dependency, not automatically installed.

fix

Run npm install express

error Cannot read property 'denys' of undefined ↓

cause Forgetting to pass options object or passing undefined.

fix

Ensure options object is provided: AccessControl({ denys: [...], ... })

error Invalid IP address: ... ↓

cause Providing an invalid IP string or empty string in denys/allows list.

fix

Ensure all IP strings are valid IPv4, IPv6, or CIDR notation (e.g., '192.168.1.1', '::1', '10.0.0.0/24').

Warnings

breaking Options object's 'denys' and 'allows' are misspelled (denys vs denies, allows vs allows). These are the correct property names; any alternative spelling will be ignored. ↓

fix Use exact property names: denys and allows (with 'y' and double 'l').

deprecated Package not actively maintained; last release June 2018. May have unpatched vulnerabilities or incompatibility with newer Express/Node versions. ↓

fix Consider alternatives like express-ipfilter or write custom middleware using ipaddr.js directly.

gotcha When using 'redirectTo', statusCode must be 301 or 302; otherwise res.send() will be used. Non-redirect status codes with redirectTo set will silently ignore redirectTo. ↓

fix Set statusCode to 301 or 302 along with redirectTo for redirect behavior.

gotcha IPv4 mapped IPv6 addresses (e.g., ::ffff:192.0.2.1) are automatically converted to IPv4. If your list contains IPv6 addresses, they will match IPv4-mapped counterparts, which may cause unexpected matches. ↓

fix Be explicit in your lists: use pure IPv4 or pure IPv6 addresses; understand that conversion happens automatically.

gotcha If mode is 'allow' (whitelist), the 'denys' list acts as an exception (blacklist) within the whitelist. This inverted logic can be confusing. ↓

fix In 'allow' mode, only IPs in 'allows' (minus any in 'denys') are allowed. Use the mode that matches your mental model: 'deny' for blacklist, 'allow' for whitelist.

Install

npm install express-ip-access-control

yarn add express-ip-access-control

pnpm add express-ip-access-control

Imports

default
```
const AccessControl = require('express-ip-access-control');
```
Package is CJS-only, no ESM or TypeScript type declarations shipped. Use require for Node.js.
default
wrong
```
import AccessControl from 'express-ip-access-control';
```
correct
```
const AccessControl = require('express-ip-access-control');
```
No default export for ESM; CJS require works. Use dynamic import if needed: import('express-ip-access-control').then(...)

ipMatch

wrong

const { ipMatch } = require('express-ip-access-control');

correct

const AccessControl = require('express-ip-access-control');
AccessControl.ipMatch(...);

ipMatch is attached to the default export function, not a separate named export.

Quickstart

Shows basic setup: require the package, configure options for deny mode, block specific IPs and CIDR ranges, apply middleware to Express app.

const express = require('express');
const AccessControl = require('express-ip-access-control');

const app = express();

const options = {
  mode: 'deny',           // Blacklist mode: allow all except listed denies
  denys: ['192.168.1.100', '10.0.0.0/8'],  // IPs to block
  allows: [],             // No whitelist exceptions
  forceConnectionAddress: false,  // Use req.ip (trust proxy aware)
  statusCode: 403,        // Forbidden
  message: 'Access denied',
  log: (clientIp, access) => {
    console.log(`${clientIp} ${access ? 'accessed' : 'denied'}`);
  }
};

app.use(AccessControl(options));

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

app.listen(3000);