A DynamoDB Adapter For lucia-auth

This is a fork of lucida-adapter-dynamodb.

These modifications were made to suit some specific needs which include

• An exp column containing the seconds since epoch when the session expires which can be used with DynamoDB's TTL feature
• Support to fetch user data from an external source
• Support to fetch sessions with consistent read to DynamoDB
• Modifications to the original schema to reduce the number of calls to DynamoDB
• Modifications to table to reduce storage and data transfer requirements.
• Enforced field names to provide an opinionated schema

Install

pnpm add @nr1e/lucia-adapter-dynamodb

Usage

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBAdapter} from 'lucia-adapter-dynamodb';

const client = new DynamoDBClient({});

const adapter = new DynamoDBAdapter(client, {
    // options
});

// pass the adapter to lucia

DynamoDB Table Schemas

Session Schema

Field	Value	Type	Note
sid	Session ID	string	Pk
uid	User ID	string	Gs1 - pk
exp	Expiration	number	Gs2 - sk
typ	'Session'	string	Gs2 - pk

Table Creation Example

Here is an example of creating such a table with @aws-sdk/client-dynamodb:

const client = new DynamoDBClient({
    // DynamoDB configs
});

await client.send(
    new CreateTableCommand({
        TableName: 'LuciaAuthTable',
        AttributeDefinitions: [
            {AttributeName: 'sid', AttributeType: 'S'},
            {AttributeName: 'uid', AttributeType: 'S'},
            {AttributeName: 'typ', AttributeType: 'S'},
            {AttributeName: 'exp', AttributeType: 'N'},
        ],
        KeySchema: [
            {AttributeName: 'sid', KeyType: 'HASH'}, // primary key
        ],
        GlobalSecondaryIndexes: [
            {
                IndexName: 'Gs1',
                Projection: {ProjectionType: 'ALL'},
                KeySchema: [
                    {AttributeName: 'uid', KeyType: 'HASH'}, // GSI primary key
                ],
            },
            {
                IndexName: 'Gs2',
                Projection: {ProjectionType: 'ALL'},
                KeySchema: [
                    {AttributeName: 'typ', KeyType: 'HASH'}, // GSI primary key
                    {AttributeName: 'exp', KeyType: 'RANGE'}, // GSI sort key
                ],
            },
        ],
        BillingMode: 'PAY_PER_REQUEST',
    }),
);

await client.send(
    new UpdateTimeToLiveCommand({
        TableName: 'LuciaAuthTable',
        TimeToLiveSpecification: {
            AttributeName: 'exp',
            Enabled: true,
        },
    }),
);

Constructor Options

The adapter constructor takes a DynamoDBClient instance from @aws-sdk/client-dynamodb as the first argument. A configuration object can be passed as the second argument.

class DynamoDBAdapter {
    constructor(client: DynamoDBClient, options?: DynamoDBAdapterOptions);
}

The configuration object can be specified as follows:

Option Object Attribute	Type	Default Value	Usage
tableName	string	LuciaAuthTable	DynamoDB table name
extraUserAttributes	string[]	[]	Names of non-key attributes in the DynamoDB table to be excluded from DatabaseUser objects
extraSessionAttributes	string[]	[]	Names of non-key attributes in the DynamoDB table to be excluded from DatabaseSession objects