@byu-oit-sdk/session-dynamo

Requirements:

• Node.js 18+
  • or Node.js 10+ with fetch and crypto polyfills
• npm v9+

Installing

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

Introduction

Use this module with a server package like @byu-oit-sdk/express or @byu-oit-sdk/fastify to store user session data in AWS DynamoDB. This is designed to be used for frontend interfaces to cache a users login session.

Options

| Option | Type | Default | Description | |---------------------------|--------|------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | tableName | string | | Required. The name to use for the session table. | | client | string | new DynamoDBClient({}) | Optional. The DynamoDBClient to use for interacting with the session table. | | maxLockTime | number | 10 | Optional. The max amount of seconds that a row can be locked before it is allowed to be forcibly unlocked. | | lockVerificationProperty | string | refresh_token | Optional. The name of the property in the session to check for when locking a row. For most purposes this should be refresh_token, as defined in RFC 6749 |

Note that the billing mode of the dynamo table is set to PAY_PER_REQUEST because that is sufficient for the uses of BYU OIT. Using the PROVISIONED billing mode is not currently supported.

Usage

This package creates and interacts with a dynamo table for you, but the server must have AWS permissions to create the table. Otherwise, the table must already exist the same key schema as the one created by this package.

Use this code example for how to initialize the package in combination with a server package. This example uses @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 { DynamoSessionStore } from '@byu-oit-sdk/session-dynamo'
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'

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

export const fastify = Fastify()

/**
 * 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 })
  
// set up the rest of the server