whitelistip/Readme.md

Whitelist middleware for express routing function. When present it allows request comming from the whitelisted IPs only. A 403 Forbidden error is sent to all other IP addresses.

# Whitelist IP

A middleware for express routing function. When used it allows request comming from IPs present in the whitelist to pass.

### Features

 * Block non whitelisted IPs from accessing API endpoints
 * If blocked, return a __403 Forbidden__ error and __stop__ the request.
 * Unified whitelist allover the app
 * Can be applied on a route basis


### Installation

```sh
npm install --save whitelistip
```

### Test

```sh
npm test
```

### Example Usage

```js
//Required packages
var express = require('express'),
	whitelistIP = require('whitelistip');
    
//Create an express app
var server = express();

//Allow only requests from localhost
server.whitelistIP = whitelistIP([
	"127.0.0.1", 
    "::ffff:127.0.0.1", 
    "::1"
]);

//Add a public endpoint no IP restriction
server.all('/public', publicHandler);

//Add a restricted endpoint, only whitelisted IPs are allowed
server.get(
	'/restricted', 
	server.whitelistIP.restrict(),
    restrictedHandler
);

//Start the server
server.listen(3000, function (err) {
    if (err) console.log(err);
});
```

When trying to access the `/restricted` endpoint from another machine, a __403 Forbidden__ message will be returned.

### Options
The middleware accepts two types of options:

1. `String`  a string containing a valid IP v4 or v6 addresse
2. `[String]` an array of strings containing a valid IP v4 or v6 addresses

_NB: If no options are passed, all requests will be rejected_