express-ip-access-control

Express IP Access Control
=========================
An express middleware for access control base on IP addresses.

Installation
------------

> npm i express-ip-access-control

Features
--------

* Control who can access resources base on IP addresses.
* Support Express 4.
* Support IPv4, IPv6, CIDR format & IPv4 mapped IPv6 addresses (using ipaddr.js).
* Deny mode (Blacklist) & Allow mode (Whitelist).
* Choose from connection address or real address. You may find it useful if you are behind proxy and needed to reject direct access.
* Custom action on denied. (Redirect or show error message)
* Custom log function.

Usage
-----

> You may want to know somethings about Express and Express's middleware first.

``javascript
var AccessControl = require('express-ip-access-control');

// Create middleware.
var middleware = AccessControl(options);

// Or directly load it into the app.
var express = require('express');
var app = express();
app.use(AccessControl(options));
`

Options
-------

`javascript
var options = {
mode: 'deny',
denys: [],
allows: [],
forceConnectionAddress: false,
log: function(clientIp, access) {
console.log(clientIp + (access ? ' accessed.' : ' denied.'));
},

statusCode: 401,
redirectTo: '',
message: 'Unauthorized'
};
`

$3

#### 'deny' mode (Blacklist)

Allow by default, only deny IPs in the blacklist (denys) and not excluded by the whitelist (allows).

#### 'allow' mode (Whilelist)

Deny by default, only allow IPs in the whitelist (allows) and not excluded by the blacklist (denys).

$3

The blacklist. Works differently in different mode. Support IPv4, IPv6, CIDR format or mixed. IPv4 mapped IPv6 addresses will be converted into IPv4.

$3

The whitelist. Works differently in different mode. Support IPv4, IPv6, CIDR format or mixed. IPv4 mapped IPv6 addresses will be converted into IPv4.

$3

If set to true, the connection address (req.connection.remoteAddress) will be used even express.set('trust proxy', []) set the req.ip. So that you can reject direct access if you are behind proxy and needed to do so.

$3

Pass a log function or false to disable log.
The function should have signature like this Function(String clientIp, Boolean access).

$3

The HTTP status code sent when denied. Set to 301 or 302 means redirect to redirectTo. Will be parseInt(statusCode, 10) to ensure it is a integer.

$3

The URL to redirect when denied and statusCode is set to redirect. It will be passed into res.redirect(statusCode, redirectTo) directly, without any validation or manipulation.

$3

The message sent when denied and statusCode is not set to redirect. It will be passed into res.send(message) directly, without any validation or manipulation.

Functions

$3

`javascript
AccessControl.ipMatch(clientIp, list);
`

Return true if clientIp is in the list, false if not. The function will return false if the clientIp is not valid or the list is empty.

* (String) clientIp is the IP address (IPv4 / IPv6) to check. IPv4 mapped IPv6 addresses will be converted into IPv4.
* (Array of String) list` is the list / range of IP address. Support IPv4, IPv6, CIDR format or mixed. IPv4 mapped IPv6 addresses will be converted into IPv4.

Repository
----------

You may find the source code on GitHub. Please feel free to report bugs and contribute your changes.

License
-------

MIT