Skip to content

Latest commit

 

History

History
159 lines (113 loc) · 8.07 KB

README.md

File metadata and controls

159 lines (113 loc) · 8.07 KB

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

code climate standard code style travis build status coverage status dependency status

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')

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

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.

tunnckoCore.tk keybase tunnckoCore tunnckoCore npm tunnckoCore twitter tunnckoCore github