Awesome
@fastify/cookie
A plugin for Fastify that adds support for reading and setting cookies.
This plugin's cookie parsing works via Fastify's onRequest
hook. Therefore,
you should register it prior to any other onRequest
hooks that will depend
upon this plugin's actions.
It is also possible to import the low-level cookie parsing and serialization functions.
@fastify/cookie
v2.x
supports both Fastify@1 and Fastify@2.
@fastify/cookie
v3 only supports Fastify@2.
Installation
npm i @fastify/cookie
or
yarn add @fastify/cookie
Example
const fastify = require('fastify')()
fastify.register(require('@fastify/cookie'), {
secret: "my-secret", // for cookies signature
hook: 'onRequest', // set to false to disable cookie autoparsing or set autoparsing on any of the following hooks: 'onRequest', 'preParsing', 'preHandler', 'preValidation'. default: 'onRequest'
parseOptions: {} // options for parsing cookies
})
fastify.get('/', (req, reply) => {
const aCookieValue = req.cookies.cookieName
// `reply.unsignCookie()` is also available
const bCookie = req.unsignCookie(req.cookies.cookieSigned);
reply
.setCookie('foo', 'foo', {
domain: 'example.com',
path: '/'
})
.cookie('baz', 'baz') // alias for setCookie
.setCookie('bar', 'bar', {
path: '/',
signed: true
})
.send({ hello: 'world' })
})
TypeScript Example
import type { FastifyCookieOptions } from '@fastify/cookie'
import cookie from '@fastify/cookie'
import fastify from 'fastify'
const app = fastify()
app.register(cookie, {
secret: "my-secret", // for cookies signature
parseOptions: {} // options for parsing cookies
} as FastifyCookieOptions)
Importing serialize
and parse
const { serialize, parse } = require('@fastify/cookie')
const fastify = require('fastify')()
fastify.get('/', (req, reply) => {
const cookie = serialize('lang', 'en', {
maxAge: 60_000,
})
reply.header('Set-Cookie', cookie)
reply.send('Language set!')
})
Options
-
secret
(String
|Array
|Buffer
|Object
):- A
String
orBuffer
can be passed to use as secret to sign the cookie usingcookie-signature
. - An
Array
can be passed if key rotation is desired. Read more about it in Rotating signing secret. - More sophisticated cookie signing mechanisms can be implemented by supplying an
Object
. Read more about it in Custom cookie signer.
- A
-
hook
: the Fastify Hook to register the parsing of cookie into. Default:onRequest
. -
algorithm
: the algorithm to use to sign the cookies. Default:sha256
. -
parseOptions
: AnObject
to modify the serialization of set cookies.
:warning: Security Considerations :warning:
It is recommended to use sha256
or stronger hashing algorithm as well as a secret
that is at least 20 bytes long.
parseOptions
domain
Specifies the value for the Domain
Set-Cookie
attribute. By default, no
domain is set, and most clients will consider the cookie to apply to only the current domain.
encode
Specifies a function that will be used to encode a cookie's value. Since value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value.
The default function is the global encodeURIComponent
, which will encode a JavaScript string
into UTF-8 byte sequences and then URL-encode any that fall outside of the cookie range.
expires
Specifies the Date
object to be the value for the Expires
Set-Cookie
attribute.
By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and
will delete it on a condition like exiting a web browser application.
Note: the cookie storage model specification states that if both expires
and
maxAge
are set, then maxAge
takes precedence, but it is possible not all clients by obey this,
so if both are set, they should point to the same date and time.
httpOnly
Specifies the boolean
value for the HttpOnly
Set-Cookie
attribute. When truthy,
the HttpOnly
attribute is set, otherwise it is not. By default, the HttpOnly
attribute is not set.
Note: be careful when setting this to true
, as compliant clients will not allow client-side
JavaScript to see the cookie in document.cookie
.
maxAge
Specifies the number
(in seconds) to be the value for the Max-Age
Set-Cookie
attribute.
The given number will be converted to an integer by rounding down. By default, no maximum age is set.
Note: the cookie storage model specification states that if both expires
and
maxAge
are set, then maxAge
takes precedence, but it is possible not all clients by obey this,
so if both are set, they should point to the same date and time.
partitioned
Specifies the boolean
value for the Partitioned
Set-Cookie
attribute. When truthy, the Partitioned
attribute is set, otherwise it is not. By default, the
Partitioned
attribute is not set.
⚠️ Warning: This is an attribute that has not yet been fully standardized, and may change in the future without reflecting the semver versioning. This also means many clients may ignore the attribute until they understand it.
More information about can be found in the proposal.
priority
Specifies the string
to be the value for the Priority
Set-Cookie
attribute.
'low'
will set thePriority
attribute toLow
.'medium'
will set thePriority
attribute toMedium
, the default priority when not set.'high'
will set thePriority
attribute toHigh
.
More information about the different priority levels can be found in the specification.
⚠️ Warning: This is an attribute that has not yet been fully standardized, and may change in the future without reflecting the semver versioning. This also means many clients may ignore the attribute until they understand it.
path
Specifies the value for the Path
Set-Cookie
attribute. By default, the path
is considered the "default path".
sameSite
Specifies the boolean
or string
to be the value for the SameSite
Set-Cookie
attribute.
true
will set theSameSite
attribute toStrict
for strict same site enforcement.false
will not set theSameSite
attribute.'lax'
will set theSameSite
attribute toLax
for lax same site enforcement.'none'
will set theSameSite
attribute toNone
for an explicit cross-site cookie.'strict'
will set theSameSite
attribute toStrict
for strict same site enforcement.
More information about the different enforcement levels can be found in the specification.
Note: This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.
secure
Specifies the boolean
value for the Secure
Set-Cookie
attribute. When truthy,
the Secure
attribute is set, otherwise it is not. By default, the Secure
attribute is not set.
Note: be careful when setting this to true
, as compliant clients will not send the cookie back to
the server in the future if the browser does not have an HTTPS connection.
API
Parsing
Cookies are parsed in the onRequest
Fastify hook and attached to the request
as an object named cookies
. Thus, if a request contains the header
Cookie: foo=foo
then, within your handler, req.cookies.foo
would equal
'foo'
.
You can pass options to the cookie parse by setting an object named parseOptions
in the plugin config object.
Sending
The method setCookie(name, value, options)
, and its alias cookie(name, value, options)
, are added to the reply
object
via the Fastify decorateReply
API. Thus, in a request handler,
reply.setCookie('foo', 'foo', {path: '/'})
will set a cookie named foo
with a value of 'foo'
on the cookie path /
.
name
: a string name for the cookie to be setvalue
: a string value for the cookieoptions
: an options object as described in the cookie serialize documentationoptions.signed
: the cookie should be signedoptions.secure
: if set totrue
it will set the Secure-flag. If it is set to"auto"
Secure-flag is set when the connection is using tls.
Securing the cookie
Following are some of the precautions that should be taken to ensure the integrity of an application:
- It's important to use
options.httpOnly
cookies to prevent attacks like XSS. - Use signed cookies (
options.signed
) to ensure they are not getting tampered with on client-side by an attacker. - Use
__Host-
Cookie Prefix to avoid Cookie Tossing attacks. - it's important to use HTTPS for your website/app to avoid a bunch of other potential security issues like MITM etc.
Clearing
The method clearCookie(name, options)
is added to the reply
object
via the Fastify decorateReply
API. Thus, in a request handler,
reply.clearCookie('foo', {path: '/'})
will clear a cookie named foo
on the cookie path /
.
name
: a string name for the cookie to be clearedoptions
: an options object as described in the cookie serialize documentation. Its optional to passoptions
object
Manual cookie parsing
The method parseCookie(cookieHeader)
is added to the fastify
instance
via the Fastify decorate
API. Thus, fastify.parseCookie('sessionId=aYb4uTIhdBXC')
will parse the raw cookie header and return an object { "sessionId": "aYb4uTIhdBXC" }
.
<a id="rotating-secret"></a>
Rotating signing secret
Key rotation is when an encryption key is retired and replaced by generating a new cryptographic key. To implement rotation, supply an Array
of keys to secret
option.
Example:
fastify.register(require('@fastify/cookie'), {
secret: [key1, key2]
})
The plugin will always use the first key (key1
) to sign cookies. When parsing incoming cookies, it will iterate over the supplied array to see if any of the available keys are able to decode the given signed cookie. This ensures that any old signed cookies are still valid.
Note:
- Key rotation is only achieved by redeploying the server again with the new
secret
array. - Iterating through all secrets is an expensive process, so the rotation list should contain as few keys as possible. Ideally, only the current key and the most recently retired key.
- Although previously signed cookies are valid even after rotation, cookies should be updated with the new key as soon as possible. See the following example for how to accomplish this.
Example:
fastify.get('/', (req, reply) => {
const result = reply.unsignCookie(req.cookies.myCookie)
if (result.valid && result.renew) {
// Setting the same cookie again, this time plugin will sign it with a new key
reply.setCookie('myCookie', result.value, {
domain: 'example.com', // same options as before
path: '/',
signed: true
})
}
})
<a id="custom-cookie-signer"></a>
Custom cookie signer
The secret
option optionally accepts an object with sign
and unsign
functions. This allows for implementing a custom cookie signing mechanism. See the following example:
Example:
fastify.register(require('@fastify/cookie'), {
secret: {
sign: (value) => {
// sign using custom logic
return signedValue
},
unsign: (value) => {
// unsign using custom logic
return {
valid: true, // the cookie has been unsigned successfully
renew: false, // the cookie has been unsigned with an old secret
value: 'unsignedValue'
}
}
}
})
Manual cookie unsigning
The method unsignCookie(value)
is added to the fastify
instance, to the request
and the reply
object
via the Fastify decorate
, decorateRequest
and decorateReply
APIs, if a secret was provided as option.
Using it on a signed cookie will call the the provided signer's (or the default signer if no custom implementation is provided) unsign
method on the cookie.
Example:
fastify.register(require('@fastify/cookie'), { secret: 'my-secret' })
fastify.get('/', (req, rep) => {
if (fastify.unsignCookie(req.cookie.foo).valid === false) {
rep.send('cookie is invalid')
return
}
rep.send('cookie is valid')
})
Other cases of manual signing
Sometimes the service under test should only accept requests with signed cookies, but it does not generate them itself.
Example:
test('Request requires signed cookie', async () => {
const response = await app.inject({
method: 'GET',
url: '/',
headers: {
cookies : {
'sid': app.signCookie(sidValue)
}
},
});
expect(response.statusCode).toBe(200);
});
Manual signing/unsigning with low level utilities
with Signer
const { Signer } = require('@fastify/cookie');
const signer = new Signer('secret');
const signedValue = signer.sign('test');
const {valid, renew, value } = signer.unsign(signedValue);
with sign/unsign utilities
const { fastifyCookie } = require('@fastify/cookie');
const signedValue = fastifyCookie.sign('test', 'secret');
const unsignedvalue = fastifyCookie.unsign(signedValue, 'secret');