@fastify/secure-session

To support key rotation, pass an array of keys to the key option.

1. Signing: The library always signs and encrypts new sessions using the first key in the array.
2. Decoding: If decoding fails with the first key, the library attempts to decode using every subsequent key in the array.
3. Automatic Rotation: When a session is successfully decoded using an older key (one not at index 0), the library automatically re-signs the cookie with the newest key (the first key in the array) upon the next request. This improves performance for subsequent calls.

Best Practice: It is recommended to keep only 2 keys in the array at a time to minimize the performance cost of multiple decode attempts during a rotation period.

const key1 = fs.readFileSync(path.join(__dirname, 'secret-key1'))
const key2 = fs.readFileSync(path.join(__dirname, 'secret-key2'))

fastify.register(require('@fastify/secure-session'), {
  // key1 is the new key used for signing
  // key2 is the old key used for fallback decoding
  key: [key1, key2],
  cookie: {
    path: '/'
  }
})

Register the plugin with your Fastify instance. You can provide a single configuration object or an array of objects to support multiple sessions.

Key Configuration Options:

• sessionName: The name of the attribute decorated on the request object (defaults to 'session').
• cookieName: The name of the session cookie (defaults to the value of sessionName).
• key: A Buffer containing the secret key. If using multiple sessions, sessionName is mandatory.
• expiry: The amount of time (in seconds) the session is considered valid. This is independent of cookie expiration.
• cookie: An object containing options for @fastify/cookie (e.g., path, httpOnly, secure, sameSite).

const fastify = require('fastify')({ logger: false })
const fs = require('node:fs')
const path = require('node:path')

fastify.register(require('@fastify/secure-session'), {
  sessionName: 'session',
  cookieName: 'my-session-cookie',
  key: fs.readFileSync(path.join(__dirname, 'secret-key')),
  expiry: 24 * 60 * 60, // 1 day
  cookie: {
    path: '/'
  }
})

To enable secure sessions in your Fastify application, register the @fastify/secure-session plugin. You can provide a single configuration object or an array of configuration objects to support multiple independent sessions.

Each configuration object can define:

• sessionName: The name of the property attached to the request object (defaults to 'session').
• cookieName: The name of the cookie sent to the client (defaults to the sessionName).
• expiry: Session expiry in seconds (defaults to 86401, which is 24 hours).
• cookieOptions or cookie: Standard cookie options. httpOnly defaults to true if not specified.
• secret: A string or Buffer used to derive a key via sodium.crypto_pwhash. Must be at least 32 bytes. If using a secret, you can optionally provide a salt (must match sodium.crypto_pwhash_SALTBYTES).
• key: A single key (Buffer or base64 string) or an array of keys for rotation. Keys must be exactly sodium.crypto_secretbox_KEYBYTES bytes long.

const fastify = require('fastify')()
const fastifySecureSession = require('@fastify/secure-session')

fastify.register(fastifySecureSession, {
  secret: 'your-at-least-32-byte-long-secret-string',
  cookieName: 'my-session-cookie'
})

For systems that do not use standard Fastify Request objects (such as @fastify/websocket), you can use the plugin's decorators to manually manage session lifecycle.

• fastify.createSecureSession(data): Creates a new session object for manipulating data via .get() and .set().
• fastify.encodeSecureSession(session, [sessionName]): Returns the signed and encrypted cookie string.
• fastify.decodeSecureSession(cookieString, [cookieOptions], [sessionName]): Returns a Session object if decoding is successful, or null otherwise.

Note: If you are using multiple sessions, you must provide the sessionName to both the encoding and decoding methods.

fastify.createSecureSession({ foo: 'bar' })
// => Session returns a session object for manipulating with .get and .set to then be encoded with encodeSecureSession

fastify.encodeSecureSession(request.session)
// => "abcdefg" returns the signed and encrypted cookie string, suitable for passing to a Set-Cookie header

fastify.decodeSecureSession(request.cookies['session'])
// => Session | null  returns a session object which you can use to .get values from if decoding is successful, and null otherwise