@fastify/cookie 9.3.0 → 9.4.0

package/README.md

@@ -96,8 +96,16 @@ fastify.get('/', (req, reply) => {
   - An `Array` can be passed if key rotation is desired. Read more about it in [Rotating signing secret](#rotating-secret).
   - More sophisticated cookie signing mechanisms can be implemented by supplying an `Object`. Read more about it in [Custom cookie signer](#custom-cookie-signer).
 
+- `hook`: the [Fastify Hook](https://fastify.dev/docs/latest/Reference/Lifecycle/#lifecycle) to register the parsing of cookie into. Default: `onRequest`.
+
+- `algorithm`: the [algorithm](https://nodejs.org/api/crypto.html#cryptogethashes) to use to sign the cookies. Default: `sha256`.
+
 - `parseOptions`: An `Object` 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
@@ -151,6 +159,20 @@ attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not.
 
 More information about can be found in [the proposal](https://github.com/privacycg/CHIPS).
 
+
+##### priority
+
+Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+
+  - `'low'` will set the `Priority` attribute to `Low`.
+  - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
+  - `'high'` will set the `Priority` attribute to `High`.
+
+More information about the different priority levels can be found in
+[the specification](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+
+⚠️ **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](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.4). By default, the path

package/cookie.js

@@ -152,6 +152,26 @@ function serialize (name, val, opt) {
     str += '; Path=' + opt.path
   }
 
+  if (opt.priority) {
+    const priority = typeof opt.priority === 'string'
+      ? opt.priority.toLowerCase()
+      : opt.priority
+
+    switch (priority) {
+      case 'low':
+        str += '; Priority=Low'
+        break
+      case 'medium':
+        str += '; Priority=Medium'
+        break
+      case 'high':
+        str += '; Priority=High'
+        break
+      default:
+        throw new TypeError('option priority is invalid')
+    }
+  }
+
   if (opt.expires) {
     if (typeof opt.expires.toUTCString !== 'function') {
       throw new TypeError('option expires is invalid')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/cookie",
-  "version": "9.3.0",
+  "version": "9.4.0",
   "description": "Plugin for fastify to add support for cookies",
   "main": "plugin.js",
   "type": "commonjs",
@@ -44,11 +44,11 @@
     "@types/node": "^20.1.0",
     "benchmark": "^2.1.4",
     "fastify": "^4.0.0",
-    "sinon": "^17.0.0",
+    "sinon": "^18.0.0",
     "snazzy": "^9.0.0",
     "standard": "^17.0.0",
     "tap": "^16.0.0",
-    "tsd": "^0.30.0"
+    "tsd": "^0.31.0"
   },
   "dependencies": {
     "fastify-plugin": "^4.0.0",

package/plugin.js

@@ -22,7 +22,7 @@ function fastifyCookieSetCookie (reply, name, value, options) {
   }
 
   if (opts.secure === 'auto') {
-    if (isConnectionSecure(reply.request)) {
+    if (reply.request.protocol === 'https') {
       opts.secure = true
     } else {
       opts.sameSite = 'lax'
@@ -187,13 +187,6 @@ function getHook (hook = 'onRequest') {
   return hooks[hook]
 }
 
-function isConnectionSecure (request) {
-  return (
-    request.raw.socket?.encrypted === true ||
-    request.headers['x-forwarded-proto'] === 'https'
-  )
-}
-
 const fastifyCookie = fp(plugin, {
   fastify: '4.x',
   name: '@fastify/cookie'

package/test/cookie-module.test.js

@@ -203,3 +203,21 @@ test('unencoded', (t) => {
   }), /argument val is invalid/)
   t.end()
 })
+
+test('serializer: priority', (t) => {
+  t.plan(8)
+  t.same(cookie.serialize('foo', 'bar', { priority: 'Low' }), 'foo=bar; Priority=Low')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'low' }), 'foo=bar; Priority=Low')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'Medium' }), 'foo=bar; Priority=Medium')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'medium' }), 'foo=bar; Priority=Medium')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'High' }), 'foo=bar; Priority=High')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'high' }), 'foo=bar; Priority=High')
+
+  t.throws(cookie.serialize.bind(cookie, 'foo', 'bar', {
+    priority: 'foo'
+  }), /option priority is invalid/)
+  t.throws(cookie.serialize.bind(cookie, 'foo', 'bar', {
+    priority: true
+  }), /option priority is invalid/)
+  t.end()
+})

package/test/cookie.test.js

@@ -854,7 +854,7 @@ test('create signed cookie manually using signCookie decorator', async (t) => {
 })
 
 test('handle secure:auto of cookieOptions', async (t) => {
-  const fastify = Fastify()
+  const fastify = Fastify({ trustProxy: true })
 
   await fastify.register(plugin)
 

package/types/plugin.d.ts

@@ -115,22 +115,26 @@ declare namespace fastifyCookie {
     domain?: string;
     /** 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. */
     encode?(val: string): string;
-    /**  The expiration `date` used for the `Expires` attribute. If both `expires` and `maxAge` are set, then `expires` is used. */
+    /** The expiration `date` used for the `Expires` attribute. */
     expires?: Date;
-    /**  The `boolean` value of the `HttpOnly` attribute. Defaults to true. */
+    /** Add the `HttpOnly` attribute. Defaults to `false`. */
     httpOnly?: boolean;
-    /**  A `number` in seconds that specifies the `Expires` attribute by adding the specified seconds to the current date. If both `expires` and `maxAge` are set, then `expires` is used. */
+    /** A `number` in seconds that specifies the `Max-Age` attribute. */
     maxAge?: number;
+    /** A `boolean` indicating whether the cookie is tied to the top-level site where it's initially set and cannot be accessed from elsewhere. */
     partitioned?: boolean;
-    /**  The `Path` attribute. Defaults to `/` (the root path).  */
+    /** The `Path` attribute. */
     path?: string;
     /** A `boolean` or one of the `SameSite` string attributes. E.g.: `lax`, `none` or `strict`.  */
     sameSite?: 'lax' | 'none' | 'strict' | boolean;
-    /**  The `boolean` value of the `Secure` attribute. Set this option to false when communicating over an unencrypted (HTTP) connection. Value can be set to `auto`; in this case the `Secure` attribute will be set to false for HTTP request, in case of HTTPS it will be set to true.  Defaults to true. */
+    /** One of the `Priority` string attributes (`low`, `medium` or `high`) specifying a retention priority for HTTP cookies that will be respected by user agents during cookie eviction. */
+    priority?: 'low' | 'medium' | 'high';
+    /** Add the `Secure` attribute. Defaults to `false`. */
     secure?: boolean;
   }
 
   export interface CookieSerializeOptions extends Omit<SerializeOptions, 'secure'> {
+    /** Add the `Secure` attribute. Value can be set to `"auto"`; in this case the `Secure` attribute will only be added for HTTPS requests. Defaults to `false`. */
     secure?: boolean | 'auto';
     signed?: boolean;
   }
@@ -151,10 +155,14 @@ declare namespace fastifyCookie {
   export type Unsign = (input: string, secret: string | Buffer, algorithm?: string) => UnsignResult;
   export type SignerFactory = (secrets: string | string[] | Buffer | Buffer[], algorithm?: string) => SignerBase;
 
-  export interface UnsignResult {
-    valid: boolean;
+  export type UnsignResult = {
+    valid: true;
     renew: boolean;
-    value: string | null;
+    value: string;
+  } | {
+    valid: false;
+    renew: false;
+    value: null;
   }
 
   export const signerFactory: SignerFactory;

package/types/plugin.test-d.ts

@@ -150,11 +150,15 @@ appWithRotationSecret.register(cookie, {
 appWithRotationSecret.after(() => {
   server.get('/', (request, reply) => {
     reply.unsignCookie(request.cookies.test!);
-    const { valid, renew, value } = reply.unsignCookie('test');
+    const unsigned = reply.unsignCookie('test');
 
-    expectType<boolean>(valid);
-    expectType<boolean>(renew);
-    expectType<string | null>(value);
+    expectType<boolean>(unsigned.valid);
+    if (unsigned.valid) {
+      expectType<string>(unsigned.value);
+    } else {
+      expectType<null>(unsigned.value);
+    }
+    expectType<boolean>(unsigned.renew);
 
     reply.send({ hello: 'world' });
   });
@@ -182,11 +186,15 @@ appWithParseOptions.register(cookie, {
 });
 appWithParseOptions.after(() => {
   server.get('/', (request, reply) => {
-    const { valid, renew, value } = reply.unsignCookie(request.cookies.test!);
+    const unsigned = reply.unsignCookie(request.cookies.test!);
 
-    expectType<boolean>(valid);
-    expectType<boolean>(renew);
-    expectType<string | null>(value);
+    expectType<boolean>(unsigned.valid);
+    if (unsigned.valid) {
+      expectType<string>(unsigned.value);
+    } else {
+      expectType<null>(unsigned.value);
+    }
+    expectType<boolean>(unsigned.renew);
   });
 });
 
@@ -204,11 +212,15 @@ appWithCustomSigner.register(cookie, {
 appWithCustomSigner.after(() => {
   server.get('/', (request, reply) => {
     reply.unsignCookie(request.cookies.test!)
-    const { valid, renew, value } = reply.unsignCookie('test')
+    const unsigned = reply.unsignCookie('test')
 
-    expectType<boolean>(valid)
-    expectType<boolean>(renew)
-    expectType<string | null>(value)
+    expectType<boolean>(unsigned.valid);
+    if (unsigned.valid) {
+      expectType<string>(unsigned.value);
+    } else {
+      expectType<null>(unsigned.value);
+    }
+    expectType<boolean>(unsigned.renew);
 
     reply.send({ hello: 'world' })
   })