@fastify/helmet

Important security headers for Fastify. It is a tiny wrapper around helmet.

Install

npm i @fastify/helmet

Usage

Simply require this plugin, and the basic security headers will be set.

1const fastify = require('fastify')()
2const helmet = require('@fastify/helmet')
3
4fastify.register(
5  helmet,
6  // Example disables the `contentSecurityPolicy` middleware but keeps the rest.
7  { contentSecurityPolicy: false }
8)
9
10fastify.listen({ port: 3000 }, err => {
11  if (err) throw err
12})

How it works

@fastify/helmet is a tiny wrapper around helmet that adds an 'onRequest' hook and a reply.helmet decorator.

It accepts the same options as helmet, and you can see more in the helmet documentation.

Apply Helmet to all your application routes

By passing { global: true } into the options, @fastify/helmet allows you to register Helmet for all your application routes by default. If you want a more granular control on how to apply Helmet to your application you can choose to disable it on a global scope by passing { global: false } to the options. By default, this option is set to true.

Example - enable @fastify/helmet globally

1fastify.register(helmet)
2// or
3fastify.register(helmet, { global: true })

Example - disable @fastify/helmet globally

1// register the package with the `{ global: false }` option
2fastify.register(helmet, { global: false })
3
4fastify.get('/route-with-disabled-helmet', async (request, reply) => {
5  return { message: 'helmet is not enabled here' }
6})
7
8fastify.get('/route-with-enabled-helmet', {
9  // We enable and configure helmet for this route only
10  helmet: {
11    dnsPrefetchControl: {
12      allow: true
13    },
14    frameguard: {
15      action: 'foo'
16    },
17    referrerPolicy: false
18  }
19}, async (request, reply) => {
20  return { message: 'helmet is enabled here' }
21})
22
23// helmet is disabled on this route but we have access to `reply.helmet` decorator
24// that allows us to apply helmet conditionally
25fastify.get('/here-we-use-helmet-reply-decorator', async (request, reply) => {
26  if (condition) {
27    // we apply the default options
28    await reply.helmet()
29  } else {
30    // we apply customized options
31    await reply.helmet({ frameguard: false })
32  }
33
34  return {
35    message: 'we use the helmet reply decorator to conditionally apply helmet middlewares'
36  }
37})

helmet route option

@fastify/helmet allows you to enable, disable, and customize helmet for each one of your application hooks by using the helmet shorthand route option when you register your application routes.

If you want to disable helmet for a specific endpoint you must pass { helmet: false } to your route options.

If you want to enable or customize helmet for a specific endpoint you must pass a helmet configuration object to your route options. E.g.: { helmet: { frameguard: false } }.

Example - @fastify/helmet configuration using the helmet shorthand route option

1// register the package with the `{ global: true }` option
2fastify.register(helmet, { global: true })
3
4fastify.get('/route-with-disabled-helmet', { helmet: false }, async (request, reply) => {
5  return { message: 'helmet is not enabled here' }
6})
7
8fastify.get('/route-with-enabled-helmet', async (request, reply) => {
9  return { message: 'helmet is enabled by default here' }
10})
11
12fastify.get('/route-with-custom-helmet-configuration', {
13  // We change the helmet configuration for this route only
14  helmet: {
15    enableCSPNonces: true,
16    contentSecurityPolicy: {
17      directives: {
18        'directive-1': ['foo', 'bar']
19      },
20      reportOnly: true
21    },
22    dnsPrefetchControl: {
23      allow: true
24    },
25    frameguard: {
26      action: 'foo'
27    },
28    hsts: {
29      maxAge: 1,
30      includeSubDomains: true,
31      preload: true
32    },
33    permittedCrossDomainPolicies: {
34      permittedPolicies: 'foo'
35    },
36    referrerPolicy: false
37  }
38}, async (request, reply) => {
39  return { message: 'helmet is enabled with a custom configuration on this route' }
40})

Content-Security-Policy Nonce

@fastify/helmet provide a simple way for csp nonces generation. You can enable this behavior by passing { enableCSPNonces: true } into the options. Then, you can retrieve the nonces through reply.cspNonce.

Note: This feature is implemented inside this module. It is not a valid option or supported by helmet. If you need to use helmet feature only for csp nonce you can follow the example here.

Example - Generate by options

1fastify.register(
2  helmet,
3  // enable csp nonces generation with default content-security-policy option
4  { enableCSPNonces: true }
5)
6
7fastify.register(
8  helmet,
9  // customize content security policy with nonce generation
10  {
11    enableCSPNonces: true,
12    contentSecurityPolicy: {
13      directives: {
14        ...
15      }
16    }
17  }
18)
19
20fastify.get('/', function(request, reply) {
21  // retrieve script nonce
22  reply.cspNonce.script
23  // retrieve style nonce
24  reply.cspNonce.style
25})

Example - Generate by helmet

1fastify.register(
2  helmet,
3  {
4    contentSecurityPolicy: {
5      directives: {
6        defaultSrc: ["'self'"],
7        scriptSrc: [
8          function (req, res) {
9            // "res" here is actually "reply.raw" in fastify
10            res.scriptNonce = crypto.randomBytes(16).toString('hex')
11            // make sure to return nonce-... directive to helmet, so it can be sent in the headers
12            return `'nonce-${res.scriptNonce}'`
13          }
14        ],
15        styleSrc: [
16          function (req, res) {
17            // "res" here is actually "reply.raw" in fastify
18            res.styleNonce = crypto.randomBytes(16).toString('hex')
19            // make sure to return nonce-... directive to helmet, so it can be sent in the headers
20            return `'nonce-${res.styleNonce}'`
21          }
22        ]
23      }
24    }
25  }
26)
27
28fastify.get('/', function(request, reply) {
29  // you can access the generated nonce by "reply.raw"
30  reply.raw.scriptNonce
31  reply.raw.styleNonce
32})
33

Disable Default helmet Directives

By default, helmet will add a default set of CSP directives to the response. This behavior can be disabled by setting useDefaults: false in the contentSecurityPolicy configuration.

1fastify.register(
2  helmet,
3  {
4    contentSecurityPolicy: {
5      useDefaults: false,
6      directives: {
7        'default-src': ["'self'"]
8      }
9    }
10  }
11)

License

MIT