@brightcove/hono-sessions

Hono Sessions

A session manager for Hono that uses DynamoDB as session storage by default. Supports session retrieval by cookie or access token.

Install

npm install @brightcove/hono-sessions --save

Usage

A middleware is provided that allows configuration of the session options and adds the object sessions to the Hono context.

import { Hono } from 'hono';
import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { sessions, DynamoDBAdapter } from '@brightcove/hono-sessions';

const client = new DynamoDBClient({
    endpoint: 'http://localhost:4566',
    region: 'us-east-1'
});
const document = DynamoDBDocument.from(client);

const app = new Hono();

app.use(sessions({
    adapter: new DynamoDBAdapter({
        tableName: 'my-table',
        primaryKey: 'pk',
        sortKey: 'sk',
        expiresAttr: 'expires',
        document
    })
    ...
}));

app.get('/my_route', async (c, next) => {
    const session = c.get('session');
});

Session Storage

DynamoDBAdapter is provided by default for use with DynamoDB as the storage backend, but alternate backends can be used if they conform to Adapter

export interface Adapter {
    get: (key: Record<string, string>) => Promise<{ session: any, cookie?: any, token?: any } | undefined>;
    set: (key: Record<string, string>, data: any, cookie?: any, token?: string, expires?: number) => Promise<void>;
    delete: (key: Record<string, string>) => Promise<void>;
    defaultKeyFn: () => (sessionId: string) => Record<string, string>;
}

Session Retrieval

Cookie

When configured to use cookies the library automatically manages setting/unsetting any any options configured

app.use(sessions({
    adapter: new DynamoDBAdapter({
        tableName: 'my-table',
        primaryKey: 'pk',
        sortKey: 'sk',
        expiresAttr: 'expires',
        document
    }),
    cookie: {
        name: 'session_storage',
        maxAge: 60000,
        secure: true
    }
}));

Access Token

When configured to use tokens, the library looks for a token in the header Authorization: Bearer <token> or in the query parameter token.

Note: If both are included, the query parameter takes precedence

app.use(sessions({
    adapter: new DynamoDBAdapter({
        tableName: 'my-table',
        primaryKey: 'pk',
        sortKey: 'sk',
        expiresAttr: 'expires',
        document
    }),
    token: {
        maxAge: 60000,
        payload: (session) => ({ user_id: session.user.id })
    }
}));

Options

DynamoDBAdapter Options

Param	Type	Description	Required	Default
tableName	string	DynamoDB table name	yes
primaryKey	string	DynamoDB primary key	no	pk
sortKey	string	DynamoDB sort key	no	sk
expiresAttr	string	DynamoDB TTL attribute name. This will be used for setting session expiration and auto expiration behavior	no	expires
document	DynamoDBDocument	https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/Class/DynamoDBDocument	yes

Middleware Options

Param	Type	Description	Required	Default
adapter	Adapter	A valid Adapter instance	yes
cookie	object	Accepts all the Hono cookie options	yes
cookie.name	string	The session cookie name	no	sid.bgs
secret	string	The secret used for signing cookies	yes, if cookie.secure or token, otherwise no
logger	Logger	What will be used for logging errors (ie. logger.error()). console is used by default if not specified	no	console
token.maxAge	number	The token expiration in seconds from the time it's generated	yes, if using token
token.queryParam	Function	Specifies the query param that is checked for the token	no	token
token.payload	Function	By default tokens only contain the sid and exp in the payload, but this allows additional data to be included with a function with the signature (session) => object.	no
allowOverwrite	boolean	Determines whether a new session can be started when the current one hasn't been ended	no	true

Starting a session

This creates the session item in the database, initialized with a serialized version of any data passed into the function (must be serializable or this will fail) and sets the session cookie on the response.

import { startSession } from '@brightcove/hono-sessions';

app.get('/my_route', async (c, next) => {
    await startSession(c, {
        user_id: 1234,
        name: 'user'
    });
    ...
});

Updating a session

The context exposes both the session and sessionCookie, which can freely be edited.

app.get('/my_route', async (c, next) => {
    const session = c.get('session');
    const cookie = c.get('sessionCookie');

    session.newField = 'new value';
    ...
});

If any of the updated cookie options are invalid, this will fail.

When the request is finalizing, if either has been updated the changes will automatically be synced back to storage.

If any of the cookie options were updated an updated cookie will be set in the response.

Ending a session

This deletes the session from the database and the session cookie in the response.

import { endSession } from '@brightcove/hono-sessions';

app.get('/my_route', async (c, next) => {
    await endSession(c);
    ...
});

Getting the access token

If the library is configured to use token retrieval, and there's a valid session, the access token can be found in the context

app.get('/my_route', async (c, next) => {
    const token = c.get('sessionToken');
    ...
});