@fastify/cookie

Install the plugin using npm to add cookie support to your Fastify application.

npm i @fastify/cookie

To protect your application, follow these security best practices when using @fastify/cookie:

• Prevent XSS: Use options.httpOnly: true to prevent client-side scripts from accessing the cookie.
• Prevent Tampering: Use options.signed: true to ensure cookies are not modified by the client.
• Prevent Cookie Tossing: Use the __Host- cookie prefix for sensitive cookies.
• Prevent MITM: Always use HTTPS for your application.

Register the plugin with your Fastify instance. You can configure cookie signing with a secret, specify which Fastify hook to use for cookie parsing via hook, and provide parseOptions for cookie serialization.

Important: Because cookie parsing happens via a Fastify hook, you should register this plugin before any other onRequest hooks that depend on cookie data.

const fastify = require('fastify')()

fastify.register(require('@fastify/cookie'), {
  secret: "my-secret", // for cookies signature
  hook: 'onRequest', // default: 'onRequest'. Options: 'onRequest', 'preParsing', 'preHandler', 'preValidation'.
  parseOptions: {}  // options for parsing cookies
})

The following options are available when registering the plugin:

• secret (String | Array | Buffer | Object): Used to sign cookies. An Array allows for key rotation. An Object allows for custom signing mechanisms.
• hook: The Fastify Hook to register cookie parsing into. Default is 'onRequest'. Valid values: 'onRequest', 'preParsing', 'preHandler', 'preValidation'. Set to false to disable autoparsing.
• algorithm: The hashing algorithm used to sign cookies. Default is 'sha256'.
• parseOptions: An Object used to modify the serialization of set cookies (see parseOptions details below).

To use @fastify/cookie, register it as a plugin in your Fastify instance. You can provide a secret for signing cookies and a hook to determine when cookies are parsed from the request.

Supported values for hook are: false, 'onRequest', 'preParsing', 'preValidation', or 'preHandler'. If set to false, cookies will not be automatically parsed into request.cookies.

If a secret is provided, the plugin decorates the Fastify instance, Request, and Reply with signCookie and unsignCookie methods.

const fastify = require('fastify')
const fastifyCookie = require('@fastify/cookie')

const server = fastify()

server.register(fastifyCookie, {
  secret: 'my-secret-key',
  hook: 'onRequest' // default is 'onRequest'
})

When using TypeScript, import FastifyCookieOptions to type your configuration object.

import type { FastifyCookieOptions } from '@fastify/cookie'
import cookie from '@fastify/cookie'
import fastify from 'fastify'

const app = fastify()

app.register(cookie, {
  secret: "my-secret",
  parseOptions: {}
} as FastifyCookieOptions)

Instead of a string or array of strings, the secret option can accept an object containing sign and unsign functions. This allows you to implement your own cryptographic logic for signing and verifying cookies.

fastify.register(require('@fastify/cookie'), {
  secret: {
    sign: (value) => {
      // custom signing logic
      return signedValue
    },
    unsign: (value) => {
      return {
        valid: true,
        renew: false,
        value: 'unsignedValue'
      }
    }
  }
})

If a secret was provided during plugin registration, the unsignCookie(value) method is available on the fastify instance, the request object, and the reply object. It returns an object containing valid (boolean), renew (boolean), and value (the original value).

fastify.register(require('@fastify/cookie'), { secret: 'my-secret' })

fastify.get('/', (req, rep) => {
  const { valid } = req.unsignCookie(req.cookies.foo)
  
  if (!valid) {
    return rep.send('cookie is invalid')
  }

  rep.send('cookie is valid')
})

The plugin automatically parses cookies in the onRequest Fastify hook and attaches them to the request object as req.cookies. For example, a header Cookie: foo=bar results in req.cookies.foo being 'bar'.

You can configure the underlying cookie parsing behavior by providing a parseOptions object in the plugin configuration.

// Accessing parsed cookies in a handler
fastify.get('/', (req, reply) => {
  const value = req.cookies.foo
})

The parseCookie(cookieHeader) method is available on the fastify instance. It allows you to parse a raw Cookie header string into a JavaScript object without a request context.

const cookies = fastify.parseCookie('sessionId=aYb4uTIhdBXC')
// returns { sessionId: 'aYb4uTIhdBXC' }

The clearCookie(name, options) method is available on the reply object to remove a cookie from the client.

Parameters:

• name: String name of the cookie to clear.
• options: An optional object following the cookie serialize specification (e.g., to match the path or domain used when the cookie was set).

fastify.get('/logout', (req, reply) => {
  reply.clearCookie('foo', { path: '/' })
})