Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zbo14/fastify-net-acl
🚫 Fastify plugin that restricts access to IP addresses/subnets.
https://github.com/zbo14/fastify-net-acl
acl allowlist blocklist fastify ip ip-address ipv4 ipv6 networking
Last synced: 19 days ago
JSON representation
🚫 Fastify plugin that restricts access to IP addresses/subnets.
- Host: GitHub
- URL: https://github.com/zbo14/fastify-net-acl
- Owner: zbo14
- License: mit
- Created: 2021-10-06T04:42:32.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2022-01-25T16:40:02.000Z (almost 3 years ago)
- Last Synced: 2024-12-01T21:03:40.094Z (22 days ago)
- Topics: acl, allowlist, blocklist, fastify, ip, ip-address, ipv4, ipv6, networking
- Language: JavaScript
- Homepage:
- Size: 254 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fastify-net-acl
[](https://standardjs.com/)
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:**
```js
fastify.register(require('fastify-net-acl'), {
blockList: '1.2.3.4'
})
```
**Block multiple IP addresses:**
```js
fastify.register(require('fastify-net-acl'), {
blockList: [
'1.2.3.4',
'2.3.4.5'
]
})
```
**Block subnet:**
```js
fastify.register(require('fastify-net-acl'), {
blockList: '1.2.3.4/24'
})
```
**Block a bunch of stuff:**
```js
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:**
```js
fastify.register(require('fastify-net-acl'), {
allowList: '1.2.3.4'
})
```
**Only allow 1 subnet:**
```js
fastify.register(require('fastify-net-acl'), {
allowList: '1.2.3.4/24'
})
```
**Only allow specified IP addresses and subnets:**
```js
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.
```js
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:**
```js
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`](https://nodejs.org/docs/latest-v16.x/api/net.html#class-netblocklist) 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 a string, array of strings, or object with those values- of IPv4/IPv6 addresses and/or subnets in CIDR format indicating which IPs should be allowed
* `blockList` is a string, array of strings, or object with those values- 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 for `errorCode`)
* `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](./LICENSE).