@react-foundry/fastify-consent-cookies 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (C) 2019-2025 Crown Copyright
+Copyright (C) 2019-2026 Daniel A.C. Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+React Foundry - Fastify Consent-Cookies
+=======================================
+
+Fastify plugin to parse and set cookies only with user consent. This
+aids compliance with European regulations.
+
+Also provides a session via a cookie. (Accessible by reading and writing
+to `req.session`.)
+
+Features
+--------
+
+- Essential cookies
+- Optional cookies with opt-in system
+- Sessions
+- Encryption (except when `httpOnly` is set to false)
+- Secure by default
+
+
+Using this package
+------------------
+
+First install the package into your project:
+
+```shell
+npm install -S @react-foundry/fastify-consent-cookies
+```
+
+Then use it in your code as follows:
+
+```ts
+import Fastify from 'fastify';
+import { type Cookie, type FastifyConsentCookiesOptions, fastifyConsentCookies } from '@react-foundry/fastify-consent-cookies';
+
+const myCookies = [
+  {
+    name: 'ga',
+    description: 'Enables us to track you use of the site and helps us to optimise your experience.',
+    group: 'Analytics',
+    httpOnly: false
+  },
+  {
+    name: 'seen,
+    description: 'Allows us to know whether you have visited the site before.',
+    group: 'Analytics'
+  }
+];
+
+const httpd = Fastify();
+
+httpd.register(fastifyConsentCookies, {
+  cookies: myCookies,
+  secret: 'changeme' // Change this to a secret string that is shared across instances of your application
+});
+
+httpd.get('/', async (req, reply) => {
+  const seen = req.cookies['seen'] || false;
+  const message = (
+    seen
+      ? 'Hello!'
+      : 'Welcome back.'
+  );
+
+  reply.setCookie('seen', true);
+
+  return message;
+});
+
+await httpd.listen({
+  host: '::'
+  port: 8080
+});
+```
+
+Route handlers and subsequent hooks will be able to discover the cookies
+available for use via `req.cookiesMeta` as well as the current cookies of
+enabled cookies via `req.cookies`. New cookies can be set with
+`reply.setCookie()`.
+
+
+### `fastifyConsentCookies`
+
+A Fastify plugin which can be 'registered' with the following options.
+
+Options object:
+
+- **`cookies: object`**
+  A description of all the cookies your application uses. Only cookies
+  described here will be available for reading and writing.
+  - **`name: string`**
+    The name of the cookie.
+  - **`description: string`**
+    A description of the cookies purpose. (To be shown to the user.)
+  - **`group?: string`**
+    The category that an optional cookie belongs to. e.g. 'Analytics'. If
+    the cookie is mandatory, do not define this and the cookie will
+    always be available.
+  - **`httpOnly?: boolean = true`**
+    Whether the cookie can be accessed on the client. Unlike other cookie
+    options, this _must_ be defined here and cannot be provided later,
+    when setting the cookie. This is because consent-cookies will encrypt
+    all httpOnly cookies as a security precaution and so needs to know
+    whether to decrypt them when reading them.
+  - **Other `cookie.serialize()` options besides `encode`**
+    See: https://www.npmjs.com/package/cookie
+- **`secret: string`**
+  A secret that is used to encrypt your cookies. You should ensure that
+  you set this in production to ensure that they cannot be decrypted by
+  an attacker. If you horizontally scale your application, you must
+  ensure that the secret is shared between each instance, so that they
+  can decrypt cookies that were set by other instances.
+- **`cookie.serialize()` options besides `encode` and `httpOnly`**
+  These will become the defaults within your application. Note that we
+  set some sensible defaults for your with a 'secure by default' mindset,
+  so you should only need to provide these options in order to loosen up
+  the security.
+  See: https://www.npmjs.com/package/cookie
+
+
+### `reply.setCookie(name: string, value: any[, options: object])`
+
+Sets a cookie.
+
+- **`name: string`**
+  The name of the cookie you wish to set.
+  **Note:** If this cookie has not been consented to and is not
+  mandatory, an exception will be thrown.
+- **`value: any`**
+  The value you wish to set for the cookie. This can be anything that
+  `JSON.stringify` can serialise but must fit within the size limits of
+  cookies.
+- **`options: object`**
+  Any `cookie.serialize()` option besides `encode` and `httpOnly`.
+  (To set `httpOnly` you must declare it when initially describing the
+  cookie.)
+  See: https://www.npmjs.com/package/cookie
+
+
+### `req.cookies`
+
+An object containing the data from all active cookies.
+
+
+### `req.cookiesMeta`
+
+An object that contains a description of all supported cookies and
+whether the user has consented to them.
+
+
+Working on this package
+-----------------------
+
+Before working on this package you must install its dependencies using
+the following command:
+
+```shell
+pnpm install
+```
+
+
+### Building
+
+Build the package by compiling the source code.
+
+```shell
+npm run build
+```
+
+
+### Clean-up
+
+Remove any previously built files.
+
+```shell
+npm run clean
+```

package/dist/common.d.ts

@@ -0,0 +1,25 @@
+import type { SerializeOptions } from 'cookie';
+import type { FastifyInstance, FastifyRequest as _Request, FastifyReply as _Reply } from 'fastify';
+import type { Promised } from '@react-foundry/types-helpers';
+export type CookieOptions = Omit<SerializeOptions, 'encode'>;
+export type SetCookie = (this: ReplyFull, name: string, value: any, options?: Omit<CookieOptions, 'httpOnly'>) => void;
+export type SetCookieConsent = (this: ReplyFull, value: string[]) => void;
+export type RequestExtras = {
+    cookies: Record<string, Cookie>;
+    cookiesMeta: object;
+};
+export type Request = _Request & Partial<RequestExtras>;
+export type RequestFull = Request & RequestExtras;
+type ReplyExtras = {
+    setCookie: SetCookie;
+    setCookieConsent: SetCookieConsent;
+};
+export type Reply = _Reply & Partial<ReplyExtras>;
+export type ReplyFull = _Reply & ReplyExtras;
+export type RouteHandlerMethod = (this: FastifyInstance, request: RequestFull, reply: ReplyFull) => Promised<unknown | void>;
+export type Cookie = CookieOptions & {
+    name: string;
+    description: string;
+    group?: string;
+};
+export {};

package/dist/common.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/common.mjs

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { FastifyPluginCallback } from 'fastify';
+import type { Cookie, CookieOptions } from './common';
+export type FastifyConsentCookiePluginOptions = CookieOptions & {
+    cookies: Cookie[];
+    secret: string;
+};
+export declare const defaultSecret = "changeme";
+export declare const fastifyConsentCookies: FastifyPluginCallback<FastifyConsentCookiePluginOptions>;
+export default fastifyConsentCookies;
+export type { FastifyConsentCookiePluginOptions as FastifyConsentCookiesOptions };
+export type { Cookie, CookieOptions, RouteHandlerMethod, Request, RequestFull, Reply, ReplyFull } from './common';

package/dist/index.js

@@ -0,0 +1,128 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastifyConsentCookies = exports.defaultSecret = void 0;
+const cookie_1 = __importDefault(require("cookie"));
+const cryptr_1 = __importDefault(require("cryptr"));
+const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
+const consentCookie = {
+    name: 'consent',
+    description: 'A store of the cookies that you have consented to.',
+    httpOnly: false,
+    sameSite: 'lax'
+};
+const id = (v) => v;
+const encodeClear = (v) => JSON.stringify(v);
+const decodeClear = (v, req) => {
+    try {
+        return JSON.parse(v);
+    }
+    catch (e) {
+        const log = (req?.log || console);
+        log.warn('Unable to parse cookie data as JSON');
+        return undefined;
+    }
+};
+const joinSet = (v, s) => Array.from(v).join(s);
+exports.defaultSecret = 'changeme';
+const fastifyConsentCookiesPlugin = async (fastify, { cookies: _cookies, secret = exports.defaultSecret, ...defaults }) => {
+    if (secret === exports.defaultSecret) {
+        fastify.log.warn('Cookie secret has not been set; cookies could be decrypted!');
+    }
+    const cryptr = new cryptr_1.default(secret, { encoding: 'base64' });
+    const encodeSecure = (v) => cryptr.encrypt(encodeClear(v));
+    const decodeSecure = (v, req) => {
+        try {
+            return decodeClear(cryptr.decrypt(v), req);
+        }
+        catch (e) {
+            const log = (req || fastify).log;
+            log.warn('Unable to decrypt cookie data');
+            return undefined;
+        }
+    };
+    const cookies = ([
+        consentCookie,
+        ..._cookies
+    ]).filter(id);
+    fastify.decorateRequest('cookiesMeta');
+    fastify.decorateRequest('cookies');
+    fastify.decorateReply('setCookie');
+    fastify.decorateReply('setCookieConsent');
+    fastify.addHook('preHandler', async (req, reply) => {
+        const cookieData = cookie_1.default.parse(req.headers.cookie || '');
+        const _consent = cookieData[consentCookie.name];
+        const consent = _consent || '';
+        const active = (cookies
+            .filter(e => e.group === undefined || consent.includes(e.name))
+            .reduce((acc, { name, ...cur }) => ({
+            ...acc,
+            [name]: cur
+        }), {}));
+        const decryptedCookies = (Object.keys(cookieData)
+            .filter(e => active[e])
+            .reduce((acc, cur) => ({
+            ...acc,
+            [cur]: (active[cur].httpOnly === false
+                ? decodeClear(cookieData[cur])
+                : decodeSecure(cookieData[cur]))
+        }), {}));
+        const foundCookieNames = new Set(Object.keys(cookieData));
+        const activeNames = new Set(Object.keys(active));
+        const cookieNames = new Set(Object.keys(decryptedCookies));
+        const rejected = foundCookieNames.difference(cookieNames);
+        req.log.debug(`${foundCookieNames.size} cookies found on request; ${joinSet(foundCookieNames, ', ')}`);
+        req.log.debug(`${activeNames.size} cookies are active; ${joinSet(activeNames, ', ')}`);
+        req.log.debug(`${cookieNames.size} cookies are available; ${joinSet(cookieNames, ', ')}`);
+        if (rejected.size) {
+            req.log.warn(`${rejected.size} cookies were rejected; ${joinSet(rejected, ', ')}`);
+        }
+        req.cookiesMeta = cookies.map(({ name, description, group }) => ({
+            name,
+            description,
+            group,
+            consent: consent.includes(name)
+        }));
+        req.cookies = decryptedCookies;
+        const setCookie = function (name, value, options) {
+            if (active[name]) {
+                const { description, group, httpOnly: _httpOnly, ...declaration } = active[name];
+                const httpOnly = _httpOnly !== false;
+                const content = (!httpOnly
+                    ? encodeClear(value)
+                    : encodeSecure(value));
+                const size = content.length;
+                const maxSize = 4096;
+                if (size > maxSize) {
+                    const overrun = size - maxSize;
+                    req.log.warn(`Attempting to set cookie, '${name}', which is ${overrun} bytes larger than allowed (4kiB) and likely to be rejected`);
+                }
+                this.header('Set-Cookie', cookie_1.default.serialize(name, content, {
+                    path: '/',
+                    domain: undefined,
+                    sameSite: 'strict',
+                    secure: true,
+                    ...defaults,
+                    ...declaration,
+                    ...options,
+                    httpOnly
+                }));
+            }
+            else {
+                throw new Error(`No consent for cookie, "${name}".`);
+            }
+        };
+        const setCookieConsent = function (value) {
+            this.setCookie(consentCookie.name, value);
+        };
+        reply.setCookie = setCookie;
+        reply.setCookieConsent = setCookieConsent;
+    });
+};
+exports.fastifyConsentCookies = (0, fastify_plugin_1.default)(fastifyConsentCookiesPlugin, {
+    fastify: '5.x',
+    name: 'consent-cookies',
+});
+exports.default = exports.fastifyConsentCookies;

package/dist/index.mjs

@@ -0,0 +1,122 @@
+import cookie from 'cookie';
+import Cryptr from 'cryptr';
+import fp from 'fastify-plugin';
+const consentCookie = {
+    name: 'consent',
+    description: 'A store of the cookies that you have consented to.',
+    httpOnly: false,
+    sameSite: 'lax'
+};
+const id = (v) => v;
+const encodeClear = (v) => JSON.stringify(v);
+const decodeClear = (v, req) => {
+    try {
+        return JSON.parse(v);
+    }
+    catch (e) {
+        const log = (req?.log || console);
+        log.warn('Unable to parse cookie data as JSON');
+        return undefined;
+    }
+};
+const joinSet = (v, s) => Array.from(v).join(s);
+export const defaultSecret = 'changeme';
+const fastifyConsentCookiesPlugin = async (fastify, { cookies: _cookies, secret = defaultSecret, ...defaults }) => {
+    if (secret === defaultSecret) {
+        fastify.log.warn('Cookie secret has not been set; cookies could be decrypted!');
+    }
+    const cryptr = new Cryptr(secret, { encoding: 'base64' });
+    const encodeSecure = (v) => cryptr.encrypt(encodeClear(v));
+    const decodeSecure = (v, req) => {
+        try {
+            return decodeClear(cryptr.decrypt(v), req);
+        }
+        catch (e) {
+            const log = (req || fastify).log;
+            log.warn('Unable to decrypt cookie data');
+            return undefined;
+        }
+    };
+    const cookies = ([
+        consentCookie,
+        ..._cookies
+    ]).filter(id);
+    fastify.decorateRequest('cookiesMeta');
+    fastify.decorateRequest('cookies');
+    fastify.decorateReply('setCookie');
+    fastify.decorateReply('setCookieConsent');
+    fastify.addHook('preHandler', async (req, reply) => {
+        const cookieData = cookie.parse(req.headers.cookie || '');
+        const _consent = cookieData[consentCookie.name];
+        const consent = _consent || '';
+        const active = (cookies
+            .filter(e => e.group === undefined || consent.includes(e.name))
+            .reduce((acc, { name, ...cur }) => ({
+            ...acc,
+            [name]: cur
+        }), {}));
+        const decryptedCookies = (Object.keys(cookieData)
+            .filter(e => active[e])
+            .reduce((acc, cur) => ({
+            ...acc,
+            [cur]: (active[cur].httpOnly === false
+                ? decodeClear(cookieData[cur])
+                : decodeSecure(cookieData[cur]))
+        }), {}));
+        const foundCookieNames = new Set(Object.keys(cookieData));
+        const activeNames = new Set(Object.keys(active));
+        const cookieNames = new Set(Object.keys(decryptedCookies));
+        const rejected = foundCookieNames.difference(cookieNames);
+        req.log.debug(`${foundCookieNames.size} cookies found on request; ${joinSet(foundCookieNames, ', ')}`);
+        req.log.debug(`${activeNames.size} cookies are active; ${joinSet(activeNames, ', ')}`);
+        req.log.debug(`${cookieNames.size} cookies are available; ${joinSet(cookieNames, ', ')}`);
+        if (rejected.size) {
+            req.log.warn(`${rejected.size} cookies were rejected; ${joinSet(rejected, ', ')}`);
+        }
+        req.cookiesMeta = cookies.map(({ name, description, group }) => ({
+            name,
+            description,
+            group,
+            consent: consent.includes(name)
+        }));
+        req.cookies = decryptedCookies;
+        const setCookie = function (name, value, options) {
+            if (active[name]) {
+                const { description, group, httpOnly: _httpOnly, ...declaration } = active[name];
+                const httpOnly = _httpOnly !== false;
+                const content = (!httpOnly
+                    ? encodeClear(value)
+                    : encodeSecure(value));
+                const size = content.length;
+                const maxSize = 4096;
+                if (size > maxSize) {
+                    const overrun = size - maxSize;
+                    req.log.warn(`Attempting to set cookie, '${name}', which is ${overrun} bytes larger than allowed (4kiB) and likely to be rejected`);
+                }
+                this.header('Set-Cookie', cookie.serialize(name, content, {
+                    path: '/',
+                    domain: undefined,
+                    sameSite: 'strict',
+                    secure: true,
+                    ...defaults,
+                    ...declaration,
+                    ...options,
+                    httpOnly
+                }));
+            }
+            else {
+                throw new Error(`No consent for cookie, "${name}".`);
+            }
+        };
+        const setCookieConsent = function (value) {
+            this.setCookie(consentCookie.name, value);
+        };
+        reply.setCookie = setCookie;
+        reply.setCookieConsent = setCookieConsent;
+    });
+};
+export const fastifyConsentCookies = fp(fastifyConsentCookiesPlugin, {
+    fastify: '5.x',
+    name: 'consent-cookies',
+});
+export default fastifyConsentCookies;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@react-foundry/fastify-consent-cookies",
+  "version": "0.1.0",
+  "description": "Fastify plugin to parse and set cookies only with user consent.",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "/dist"
+  ],
+  "author": "Daniel A.C. Martin <npm@daniel-martin.co.uk> (http://daniel-martin.co.uk/)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "fastify": "5.7.1",
+    "jest": "30.2.0",
+    "jest-environment-jsdom": "30.2.0",
+    "ts-jest": "29.4.6",
+    "typescript": "5.9.3",
+    "@react-foundry/types-helpers": "0.1.0"
+  },
+  "dependencies": {
+    "cookie": "^1.1.1",
+    "cryptr": "^6.4.0",
+    "fastify-plugin": "^5.1.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -m es2022 && find dist -name '*.js' -exec sh -c 'mv \"$0\" \"${0%.js}.mjs\"' {} \\;",
+    "build:cjs": "tsc",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "module": "dist/index.mjs",
+  "typings": "dist/index.d.ts"
+}