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 |