fastify-sessions

Features

Session plugin for fastify supporting both stateless and stateful sessions, fork of @mgcrea/fastify-session adding a lot of features while keeping compatibility.

• Requires @fastify/cookie to handle cookies.

• Works with fastify ^4.0.0 starting from >=0.16.0.

• Can leverage crypto addons like @mgcrea/fastify-session-sodium-crypto to perform crypto.

• Can leverage store addons like:

  • @mgcrea/fastify-session-redis-store
  • @mgcrea/fastify-session-prisma-store
  • fastify-session-sqlite-store

• Built with TypeScript for static type checking with exported types along the library.

Install

1npm install fastify-sessions @fastify/cookie
2# or
3pnpm add fastify-sessions @fastify/cookie

Quickstart

Basic example (signed session with hmac stored in a volatile in-memory store)

Defaults to a volatile in-memory store for sessions (great for tests), with HMAC for signature.

1import createFastify, { FastifyInstance, FastifyServerOptions } from "fastify";
2import fastifyCookie from "@fastify/cookie";
3import fastifySessions from "fastify-sessions";
4
5const SESSION_SECRET = "a secret with minimum length of 32 characters";
6const SESSION_TTL = 86400; // 1 day in seconds
7
8export const buildFastify = (options?: FastifyServerOptions): FastifyInstance => {
9  const fastify = createFastify(options);
10
11  fastify.register(fastifyCookie);
12  fastify.register(fastifySessions, {
13    secret: SESSION_SECRET,
14    cookie: { maxAge: SESSION_TTL },
15  });
16
17  return fastify;
18};

Production example (signed session with sodium stored in redis)

For better performance/security, you can use the @mgcrea/fastify-session-sodium-crypto addon:

Leveraging an external redis store, the session id (generated with nanoid) is signed using a secret-key with libsodium's crypto_auth

1import createFastify, { FastifyInstance, FastifyServerOptions } from "fastify";
2import fastifyCookie from "@fastify/cookie";
3import fastifySessions from "fastify-sessions";
4import { SODIUM_AUTH } from "@mgcrea/fastify-session-sodium-crypto";
5
6const SESSION_KEY = "Egb/g4RUumlD2YhWYfeDlm5MddajSjGEBhm0OW+yo9s=";
7const SESSION_TTL = 86400; // 1 day in seconds
8const REDIS_URI = process.env.REDIS_URI || "redis://localhost:6379/1";
9
10export const buildFastify = (options?: FastifyServerOptions): FastifyInstance => {
11  const fastify = createFastify(options);
12
13  fastify.register(fastifyCookie);
14  fastify.register(fastifySessions, {
15    key: Buffer.from(SESSION_KEY, "base64"),
16    crypto: SODIUM_AUTH,
17    store: new RedisStore({ client: new Redis(REDIS_URI), ttl: SESSION_TTL }),
18    cookie: { maxAge: SESSION_TTL },
19  });
20
21  return fastify;
22};

Stateless example (encrypted session with sodium not using a store)

No external store required, the entire session data is encrypted using a secret-key with libsodium's crypto_secretbox_easy

Here we used a secret instead of providing a key, key derivation will happen automatically on startup.

1import createFastify, { FastifyInstance, FastifyServerOptions } from "fastify";
2import fastifyCookie from "@fastify/cookie";
3import fastifySessions from "fastify-sessions";
4import { SODIUM_SECRETBOX } from "@mgcrea/fastify-session-sodium-crypto";
5
6const SESSION_TTL = 86400; // 1 day in seconds
7
8export const buildFastify = (options?: FastifyServerOptions): FastifyInstance => {
9  const fastify = createFastify(options);
10
11  fastify.register(fastifyCookie);
12  fastify.register(fastifySessions, {
13    secret: "a secret with minimum length of 32 characters",
14    crypto: SODIUM_SECRETBOX,
15    cookie: { maxAge: SESSION_TTL },
16  });
17
18  return fastify;
19};

Stateless example with custom data serialization

Here we used msgpackr to serialize the data instead of the default JSON and also disabled generating/saving the session ID.

1import createFastify, { FastifyInstance, FastifyServerOptions } from "fastify";
2import fastifyCookie from "@fastify/cookie";
3import fastifySessions, { StatelessStore } from "fastify-sessions";
4import { SODIUM_SECRETBOX } from "@mgcrea/fastify-session-sodium-crypto";
5import { pack, unpack } from "msgpackr";
6
7const SESSION_KEY = 'Egb/g4RUumlD2YhWYfeDlm5MddajSjGEBhm0OW+yo9s=';
8const SESSION_TTL = 86400; // 1 day in seconds
9
10export const buildFastify = (options?: FastifyServerOptions): FastifyInstance => {
11  const fastify = createFastify(options);
12
13  fastify.register(fastifyCookie);
14  fastify.register(fastifySessions, {
15    key: Buffer.from(SESSION_KEY, 'base64'),
16    crypto: SODIUM_SECRETBOX,
17    store: new StatelessStore({
18      serialize: async (session: T): Promise<Buffer> => pack(session),
19      deserialize: async (session: Buffer): Promise<T> => unpack(session),
20      useId: false
21    }),
22    cookie: { maxAge: SESSION_TTL },
23  });
24
25  return fastify;
26};

Benchmarks

Session crypto sealing

1npm run benchmark:cryptoSeal

1SODIUM_SECRETBOX#sealMsgpack x 653,658 ops/sec ±0.25% (90 runs sampled)
2SODIUM_SECRETBOX#sealJson x 647,044 ops/sec ±0.25% (93 runs sampled)
3SODIUM_AUTH#sealJson x 421,055 ops/sec ±0.18% (95 runs sampled)
4HMAC#sealJson x 195,364 ops/sec ±0.35% (92 runs sampled)
5Fastest is SODIUM_SECRETBOX#sealMsgpack

Session crypto unsealing

1npm run benchmark:cryptoUnseal

1SODIUM_SECRETBOX#unsealMsgpack x 527,228 ops/sec ±0.36% (89 runs sampled)
2SODIUM_SECRETBOX#unsealJson x 507,172 ops/sec ±0.29% (92 runs sampled)
3SODIUM_AUTH#unsealJson x 347,371 ops/sec ±0.24% (93 runs sampled)
4HMAC#unsealJson x 108,809 ops/sec ±0.76% (92 runs sampled)
5Fastest is SODIUM_SECRETBOX#unsealMsgpack

Session crypto serializing

1npm run benchmark:cryptoSerialize

1SODIUM_SECRETBOX#serializeMsgpack x 473,983 ops/sec ±0.31% (93 runs sampled)
2SODIUM_SECRETBOX#serializeJson x 327,130 ops/sec ±0.26% (92 runs sampled)
3Fastest is SODIUM_SECRETBOX#serializeMsgpack

Session crypto deserializing

1npm run benchmark:cryptoDeserialize

1SODIUM_SECRETBOX#deserializeMsgpack x 372,287 ops/sec ±0.24% (91 runs sampled)
2SODIUM_SECRETBOX#deserializeJson x 318,034 ops/sec ±0.24% (89 runs sampled)
3Fastest is SODIUM_SECRETBOX#deserializeMsgpack

Authors

• dmkng <susan@themaking.party>

Credits

Heavily inspired from

• @mgcrea/fastify-session by Olivier Louvignes
• fastify-secure-session by Matteo Collina
• fastify-session by Denis Fäcke
• express-session by Douglas Wilson
• cookie-signature by TJ Holowaychuk