@byu-oit-sdk/session-fastify

Requirements:

• Node.js 20+
• npm v9+
• Fastify v5
• @fastify/cookie v11+

Breaking Changes

• @byu-oit-sdk/session-fastify now requires Node.js 20 or newer.
• @byu-oit-sdk/session-fastify now targets Fastify 5 and @fastify/cookie 11 or newer.

Installing

npm install @byu-oit-sdk/session-fastify

npm install @fastify/cookie @byu-oit-sdk/session-fastify

Introduction

Use this module to facilitate session authentication, used primarily in conjunction with the @byu-oit-sdk/fastify package.

Options

The only option given to the SessionPlugin plugin (see the example below) is an object where the following options can be set:

| Option | Type | Default | Description | |--------|--------------|------------------|------------------------------------------------------------------------------| | store | SessionStore | Stored in memory | The store object that will be used to store and retrieve session information | | name | string | 'sessionId' | The name of the cookie used to store the session Id in the browser storage | | maxAge | number | 1200 | The maximum age of the session, in seconds. |

None of the options are required to be overridden for testing, but store must be overridden for production use.

Usage

Register SessionPlugin as a fastify plugin:

import { ByuLogger } from '@byu-oit/logger'
import { AuthorizationCodeFlow } from '@byu-oit-sdk/fastify'
import fastifyCookie from '@fastify/cookie'
import { SessionPlugin } from '@byu-oit-sdk/session-fastify'
import Fastify from 'fastify'
import env from 'env-var'
import { decodeJwt } from 'jose'
import { DynamoSessionStore } from '@byu-oit-sdk/session-dynamo'
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'

declare module '@byu-oit-sdk/fastify' {
    interface UserInfo {
        /**
         * Declare your user info properties here
         */
    }
}

const isProduction = env.get('NODE_ENV').default('development').asEnum(['production', 'development']) === 'production'

export const fastify = Fastify({ logger: ByuLogger() })

/**
 * Must register the \@fastify/cookie plugin. The \@fastify/jwt module depends on \@fastify/cookie.
 */
await fastify.register(fastifyCookie)

let store
if (isProduction) {
  const client = new DynamoDBClient({
    region: env.get('AWS_REGION').required().asString(),
    endpoint: 'http://localhost:8000'
  })
  store = new DynamoSessionStore({ client, tableName: 'sessions' })
}

/**
 *  Must register the \@byu-oit-sdk/session-fastify plugin. You must pass in a session storage option for production environments.
 *  Using the default in-memory storage is highly discouraged because it will cause memory leaks.
 */
await fastify.register(SessionPlugin, { store })

await fastify.register(AuthorizationCodeFlow, {
    /**
     * A user info callback function can be supplied to implement a custom way to return the user info data.
     * the default behavior is to decode the access token returned from the oauth provider token endpoint.
     * The context of the `userInfoCallback` function is bound to the FastifyAuthorizationCodeProvider instance.
     */
    userInfoCallback (token) {
        if (typeof token.additional.id_token !== 'string') {
            /** The id token property must exist in the token response body */
            throw Error('Missing or mal-formatted ID token in response from token endpoint. Did you set the right scopes?')
        }
        /** Decode the `id_token` property, which should return the user info object. */
        return decodeJwt(token.additional.id_token)
    }
})

/**
 * To require authentication for a route, just specify the authenticate function on the request object in the onRequest hook.
 */
fastify.get('/auth/user', { onRequest: [fastify.authenticate] }, (req, reply) => {
    return req.session.user
})