README.md

koa-ip-filter

Middleware for koa that filters IPs against glob patterns, RegExp, string or array of globs. Support custom 403 Forbidden message and custom ID.

Install

npm i koa-ip-filter --save

Features

• custom message when 403 Forbidden response, through opts.forbidden
• custom identifier different than default this.ip, through opts.id
  • you may want to add opts.strict: false if it's not IP
• filter IP using glob patterns, regexp, string, array or function
• blacklist with negative glob patterns, whitelist with positive
• would restrict all to 403 Forbidden that not match to filter

Notice: In the next middleware you will have this.filter method which is ip-filter and this.identifier - the IP/ID that passed the given filter

Usage

For more use-cases see the tests

const koaIpFilter = require('koa-ip-filter')

koaIpFilter

Filtering incoming request with glob patterns array, regexp, string or matcher function

Params

• options {Object}
  • id {Function}: custom identifier, defaults to this.ip
  • strict {Boolean}: to throw when not valid IPv4/IPv6? default true
  • filter {Array|String|RegExp|Function}: black/white list filter
  • forbidden {String|Function}: custom message when 403 Forbidden response
• returns {GeneratorFunction}

Example

'use strict'

var koa = require('koa')
var ipFilter = require('koa-ip-filter')
var helloWorld = require('koa-hello-world')

var app = koa()

app
.use(ipFilter({
  forbidden: '403: Get out of here!',
  filter: ['127.??.6*.12', '!1.2.*.4']
}))
.use(helloWorld())

app.listen(1234)
console.log('koa server start listening on http://localhost:1234')

// if your IP is `127.43.65.12` you will see `Hello World`
// otherwise you will see `403: Get out of here!`

One more example

If you want to allow all IPs, but want to restrict only some range

'use strict'

var koa = require('koa')
var ipFilter = require('koa-ip-filter')
var helloWorld = require('koa-hello-world')

var app = koa()

app
.use(ipFilter({
  forbidden: '403: Get out of here!',
  filter: ['*', '!213.15.*']
}))
.use(helloWorld())

app.listen(1234)
console.log('koa server start listening on http://localhost:1234')

// only user with IP starting with `213.15.*` 
// will see the message `403: Get out of here!`

Related

• ip-filter: Filters valid IPv4 or IPv6 against glob pattern, array, string and etc… more | homepage
• is-match-ip: Matching IPs using micromatch and ip-filter - glob patterns, RegExp, string or… more | homepage
• is-match: Create a matching function from a glob pattern, regex, string, array, object… more | homepage
• koa-better-body: Full-featured koa body parser! Support parsing text, buffer, json, json patch, json… more | homepage
• koa-ip-filter: koa middleware to filter request IPs or custom ID with glob patterns… more | homepage
• micromatch: Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch… more | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
But before doing anything, please read the CONTRIBUTING.md guidelines.

Charlike Make Reagent