fastify-net-acl
Fastify plugin that restricts access according to IP address/subnet allow and block lists.
Install
npm i fastify-net-acl
Usage
Blocking
Block IP address:
fastify.register(require('fastify-net-acl'), {
blockList: '1.2.3.4'
})
Block multiple IP addresses:
fastify.register(require('fastify-net-acl'), {
blockList: [
'1.2.3.4',
'2.3.4.5'
]
})
Block subnet:
fastify.register(require('fastify-net-acl'), {
blockList: '1.2.3.4/24'
})
Block a bunch of stuff:
fastify.register(require('fastify-net-acl'), {
blockList: [
'::1',
'4.3.2.1',
'4.2.3.4',
'1.2.3.4/24',
'2.3.4.5/16'
]
})
Allowing
Only allow 1 IP address:
fastify.register(require('fastify-net-acl'), {
allowList: '1.2.3.4'
})
Only allow 1 subnet:
fastify.register(require('fastify-net-acl'), {
allowList: '1.2.3.4/24'
})
Only allow specified IP addresses and subnets:
fastify.register(require('fastify-net-acl'), {
allowList: [
'::1',
'2.3.4.5',
'1.2.3.4/24'
]
})
Route specific rules
Note: you must await
the plugin registration so the decorator function is accessible for the route definition.
await fastify.register(require('fastify-net-acl'), {
blockList: '1.2.3.4/24',
global: false
})
const onRequest = fastify.createNetAclRequestHandler()
fastify.get('/has-blocking', { onRequest }, (req, reply) => {})
fastify.get('/no-blocking', (req, reply) => {})
Use multiple allow/block lists:
await fastify.register(require('fastify-net-acl'), {
allowList: {
foo: '1.2.3.4/24'
},
blockList: {
bar: '2.3.4.5/24'
},
global: false
})
{
const onRequest = fastify.createNetAclRequestHandler('allow:foo')
fastify.get('/foo', { onRequest }, (req, reply) => {})
}
{
const onRequest = fastify.createNetAclRequestHandler('block:bar')
fastify.get('/bar', { onRequest }, (req, reply) => {})
}
fastify.get('/no-blocking', (req, reply) => {})
Reference
This plugin decorates the fastify
instance with allowList
and/or blockList
, depending on which properties are specified in options
. Both are instances of net.BlockList
and determine which IP addresses/subnets are allowed or blocked, respectively.
Note: fastify-net-acl
requires Node >= 15.0.0 since net.Blocklist
was introduced in 15.0.0.
The options
object has the following properties. Either allowList
xor blockList
must be specified if global
is true
. Both may be specified if global
is false
since you may want to use different allow/block lists on different routes.
-
allowList
is an array of IPv4/IPv6 addresses and/or subnets in CIDR format indicating which IPs should be allowed -
blockList
is an array of IPv4/IPv6 addresses and/or subnets in CIDR format indicating which IPs should be blocked -
errorCode
is the HTTP status code when an IP is blocked/not allowed (default:403
) -
errorMessage
is the status message when an IP is blocked/not allowed (default: generic status message forerrorCode
) -
global
is a boolean indicating whether the ACL applies globally, i.e. for all routes (default:true
)
Test
npm test
Lint
npm run lint
or npm run lint:fix
License
Licensed under MIT.