/** *
*

Official DynamoDB adapter for Auth.js / NextAuth.js.

* * * *
* * ## Installation * * ```bash npm2yarn2pnpm * npm install next-auth @next-auth/dynamodb-adapter * ``` * * @module @next-auth/dynamodb-adapter */ import { v4 as uuid } from "uuid" import type { BatchWriteCommandInput, DynamoDBDocument, } from "@aws-sdk/lib-dynamodb" import type { Adapter, AdapterSession, AdapterAccount, AdapterUser, VerificationToken, } from "next-auth/adapters" export interface DynamoDBAdapterOptions { tableName?: string partitionKey?: string sortKey?: string indexName?: string indexPartitionKey?: string indexSortKey?: string } /** * ## Setup * * By default, the adapter expects a table with a partition key `pk` and a sort key `sk`, as well as a global secondary index named `GSI1` with `GSI1PK` as partition key and `GSI1SK` as sorting key. To automatically delete sessions and verification requests after they expire using [dynamodb TTL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html) you should [enable the TTL](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/time-to-live-ttl-how-to.html) with attribute name 'expires'. You can set whatever you want as the table name and the billing method. * You can find the full schema in the table structure section below. * * ### Configuring Auth.js * * You need to pass `DynamoDBDocument` client from the modular [`aws-sdk`](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/dynamodb-example-dynamodb-utilities.html) v3 to the adapter. * The default table name is `next-auth`, but you can customise that by passing `{ tableName: 'your-table-name' }` as the second parameter in the adapter. * * ```javascript title="pages/api/auth/[...nextauth].js" * import { DynamoDB, DynamoDBClientConfig } from "@aws-sdk/client-dynamodb" * import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb" * import NextAuth from "next-auth"; * import Providers from "next-auth/providers"; * import { DynamoDBAdapter } from "@next-auth/dynamodb-adapter" * * const config: DynamoDBClientConfig = { * credentials: { * accessKeyId: process.env.NEXT_AUTH_AWS_ACCESS_KEY as string, * secretAccessKey: process.env.NEXT_AUTH_AWS_SECRET_KEY as string, * }, * region: process.env.NEXT_AUTH_AWS_REGION, * }; * * const client = DynamoDBDocument.from(new DynamoDB(config), { * marshallOptions: { * convertEmptyValues: true, * removeUndefinedValues: true, * convertClassInstanceToMap: true, * }, * }) * * export default NextAuth({ * // Configure one or more authentication providers * providers: [ * Providers.GitHub({ * clientId: process.env.GITHUB_ID, * clientSecret: process.env.GITHUB_SECRET, * }), * Providers.Email({ * server: process.env.EMAIL_SERVER, * from: process.env.EMAIL_FROM, * }), * // ...add more providers here * ], * adapter: DynamoDBAdapter( * client * ), * ... * }); * ``` * * (AWS secrets start with `NEXT_AUTH_` in order to not conflict with [Vercel's reserved environment variables](https://vercel.com/docs/environment-variables#reserved-environment-variables).) * * ## Advanced usage * * ### Default schema * * The table respects the single table design pattern. This has many advantages: * * - Only one table to manage, monitor and provision. * - Querying relations is faster than with multi-table schemas (for eg. retrieving all sessions for a user). * - Only one table needs to be replicated if you want to go multi-region. * * > This schema is adapted for use in DynamoDB and based upon our main [schema](https://authjs.dev/reference/adapters#models) * * ![DynamoDB Table](https://i.imgur.com/hGZtWDq.png) * * You can create this table with infrastructure as code using [`aws-cdk`](https://github.com/aws/aws-cdk) with the following table definition: * * ```javascript title=stack.ts * new dynamodb.Table(this, `NextAuthTable`, { * tableName: "next-auth", * partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING }, * sortKey: { name: "sk", type: dynamodb.AttributeType.STRING }, * timeToLiveAttribute: "expires", * }).addGlobalSecondaryIndex({ * indexName: "GSI1", * partitionKey: { name: "GSI1PK", type: dynamodb.AttributeType.STRING }, * sortKey: { name: "GSI1SK", type: dynamodb.AttributeType.STRING }, * }) * ``` * * Alternatively, you can use this cloudformation template: * * ```yaml title=cloudformation.yaml * NextAuthTable: * Type: "AWS::DynamoDB::Table" * Properties: * TableName: next-auth * AttributeDefinitions: * - AttributeName: pk * AttributeType: S * - AttributeName: sk * AttributeType: S * - AttributeName: GSI1PK * AttributeType: S * - AttributeName: GSI1SK * AttributeType: S * KeySchema: * - AttributeName: pk * KeyType: HASH * - AttributeName: sk * KeyType: RANGE * GlobalSecondaryIndexes: * - IndexName: GSI1 * Projection: * ProjectionType: ALL * KeySchema: * - AttributeName: GSI1PK * KeyType: HASH * - AttributeName: GSI1SK * KeyType: RANGE * TimeToLiveSpecification: * AttributeName: expires * Enabled: true * ``` * * ### Using a custom schema * * You can configure your custom table schema by passing the `options` key to the adapter constructor: * * ```javascript * const adapter = DynamoDBAdapter(client, { * tableName: "custom-table-name", * partitionKey: "custom-pk", * sortKey: "custom-sk", * indexName: "custom-index-name", * indexPartitionKey: "custom-index-pk", * indexSortKey: "custom-index-sk", * }) * ``` **/ export function DynamoDBAdapter( client: DynamoDBDocument, options?: DynamoDBAdapterOptions ): Adapter { const TableName = options?.tableName ?? "next-auth" const pk = options?.partitionKey ?? "pk" const sk = options?.sortKey ?? "sk" const IndexName = options?.indexName ?? "GSI1" const GSI1PK = options?.indexPartitionKey ?? "GSI1PK" const GSI1SK = options?.indexSortKey ?? "GSI1SK" return { async createUser(data) { const user: AdapterUser = { ...(data as any), id: uuid(), } await client.put({ TableName, Item: format.to({ ...user, [pk]: `USER#${user.id}`, [sk]: `USER#${user.id}`, type: "USER", [GSI1PK]: `USER#${user.email}`, [GSI1SK]: `USER#${user.email}`, }), }) return user }, async getUser(userId) { const data = await client.get({ TableName, Key: { [pk]: `USER#${userId}`, [sk]: `USER#${userId}`, }, }) return format.from(data.Item) }, async getUserByEmail(email) { const data = await client.query({ TableName, IndexName, KeyConditionExpression: "#gsi1pk = :gsi1pk AND #gsi1sk = :gsi1sk", ExpressionAttributeNames: { "#gsi1pk": GSI1PK, "#gsi1sk": GSI1SK, }, ExpressionAttributeValues: { ":gsi1pk": `USER#${email}`, ":gsi1sk": `USER#${email}`, }, }) return format.from(data.Items?.[0]) }, async getUserByAccount({ provider, providerAccountId }) { const data = await client.query({ TableName, IndexName, KeyConditionExpression: "#gsi1pk = :gsi1pk AND #gsi1sk = :gsi1sk", ExpressionAttributeNames: { "#gsi1pk": GSI1PK, "#gsi1sk": GSI1SK, }, ExpressionAttributeValues: { ":gsi1pk": `ACCOUNT#${provider}`, ":gsi1sk": `ACCOUNT#${providerAccountId}`, }, }) if (!data.Items?.length) return null const accounts = data.Items[0] as AdapterAccount const res = await client.get({ TableName, Key: { [pk]: `USER#${accounts.userId}`, [sk]: `USER#${accounts.userId}`, }, }) return format.from(res.Item) }, async updateUser(user) { const { UpdateExpression, ExpressionAttributeNames, ExpressionAttributeValues, } = generateUpdateExpression(user) const data = await client.update({ TableName, Key: { // next-auth type is incorrect it should be Partial & {id: string} instead of just Partial [pk]: `USER#${user.id as string}`, [sk]: `USER#${user.id as string}`, }, UpdateExpression, ExpressionAttributeNames, ExpressionAttributeValues, ReturnValues: "ALL_NEW", }) // eslint-disable-next-line @typescript-eslint/no-non-null-assertion return format.from(data.Attributes)! }, async deleteUser(userId) { // query all the items related to the user to delete const res = await client.query({ TableName, KeyConditionExpression: "#pk = :pk", ExpressionAttributeNames: { "#pk": pk }, ExpressionAttributeValues: { ":pk": `USER#${userId}` }, }) if (!res.Items) return null const items = res.Items // find the user we want to delete to return at the end of the function call const user = items.find((item) => item.type === "USER") const itemsToDelete = items.map((item) => { return { DeleteRequest: { Key: { [sk]: item.sk, [pk]: item.pk, }, }, } }) // batch write commands cannot handle more than 25 requests at once const itemsToDeleteMax = itemsToDelete.slice(0, 25) const param: BatchWriteCommandInput = { RequestItems: { [TableName]: itemsToDeleteMax }, } await client.batchWrite(param) return format.from(user) }, async linkAccount(data) { const item = { ...data, id: uuid(), [pk]: `USER#${data.userId}`, [sk]: `ACCOUNT#${data.provider}#${data.providerAccountId}`, [GSI1PK]: `ACCOUNT#${data.provider}`, [GSI1SK]: `ACCOUNT#${data.providerAccountId}`, } await client.put({ TableName, Item: format.to(item) }) return data }, async unlinkAccount({ provider, providerAccountId }) { const data = await client.query({ TableName, IndexName, KeyConditionExpression: "#gsi1pk = :gsi1pk AND #gsi1sk = :gsi1sk", ExpressionAttributeNames: { "#gsi1pk": GSI1PK, "#gsi1sk": GSI1SK, }, ExpressionAttributeValues: { ":gsi1pk": `ACCOUNT#${provider}`, ":gsi1sk": `ACCOUNT#${providerAccountId}`, }, }) const account = format.from(data.Items?.[0]) if (!account) return await client.delete({ TableName, Key: { [pk]: `USER#${account.userId}`, [sk]: `ACCOUNT#${provider}#${providerAccountId}`, }, ReturnValues: "ALL_OLD", }) return account }, async getSessionAndUser(sessionToken) { const data = await client.query({ TableName, IndexName, KeyConditionExpression: "#gsi1pk = :gsi1pk AND #gsi1sk = :gsi1sk", ExpressionAttributeNames: { "#gsi1pk": GSI1PK, "#gsi1sk": GSI1SK, }, ExpressionAttributeValues: { ":gsi1pk": `SESSION#${sessionToken}`, ":gsi1sk": `SESSION#${sessionToken}`, }, }) const session = format.from(data.Items?.[0]) if (!session) return null const res = await client.get({ TableName, Key: { [pk]: `USER#${session.userId}`, [sk]: `USER#${session.userId}`, }, }) const user = format.from(res.Item) if (!user) return null return { user, session } }, async createSession(data) { const session = { id: uuid(), ...data, } await client.put({ TableName, Item: format.to({ [pk]: `USER#${data.userId}`, [sk]: `SESSION#${data.sessionToken}`, [GSI1SK]: `SESSION#${data.sessionToken}`, [GSI1PK]: `SESSION#${data.sessionToken}`, type: "SESSION", ...data, }), }) return session }, async updateSession(session) { const { sessionToken } = session const data = await client.query({ TableName, IndexName, KeyConditionExpression: "#gsi1pk = :gsi1pk AND #gsi1sk = :gsi1sk", ExpressionAttributeNames: { "#gsi1pk": GSI1PK, "#gsi1sk": GSI1SK, }, ExpressionAttributeValues: { ":gsi1pk": `SESSION#${sessionToken}`, ":gsi1sk": `SESSION#${sessionToken}`, }, }) if (!data.Items?.length) return null const { pk, sk } = data.Items[0] as any const { UpdateExpression, ExpressionAttributeNames, ExpressionAttributeValues, } = generateUpdateExpression(session) const res = await client.update({ TableName, Key: { pk, sk }, UpdateExpression, ExpressionAttributeNames, ExpressionAttributeValues, ReturnValues: "ALL_NEW", }) return format.from(res.Attributes) }, async deleteSession(sessionToken) { const data = await client.query({ TableName, IndexName, KeyConditionExpression: "#gsi1pk = :gsi1pk AND #gsi1sk = :gsi1sk", ExpressionAttributeNames: { "#gsi1pk": GSI1PK, "#gsi1sk": GSI1SK, }, ExpressionAttributeValues: { ":gsi1pk": `SESSION#${sessionToken}`, ":gsi1sk": `SESSION#${sessionToken}`, }, }) if (!data?.Items?.length) return null const { pk, sk } = data.Items[0] const res = await client.delete({ TableName, Key: { pk, sk }, ReturnValues: "ALL_OLD", }) return format.from(res.Attributes) }, async createVerificationToken(data) { await client.put({ TableName, Item: format.to({ [pk]: `VT#${data.identifier}`, [sk]: `VT#${data.token}`, type: "VT", ...data, }), }) return data }, async useVerificationToken({ identifier, token }) { const data = await client.delete({ TableName, Key: { [pk]: `VT#${identifier}`, [sk]: `VT#${token}`, }, ReturnValues: "ALL_OLD", }) return format.from(data.Attributes) }, } } // https://github.com/honeinc/is-iso-date/blob/master/index.js const isoDateRE = /(\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d\.\d+([+-][0-2]\d:[0-5]\d|Z))|(\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d([+-][0-2]\d:[0-5]\d|Z))|(\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d([+-][0-2]\d:[0-5]\d|Z))/ function isDate(value: any) { return value && isoDateRE.test(value) && !isNaN(Date.parse(value)) } const format = { /** Takes a plain old JavaScript object and turns it into a Dynamodb object */ to(object: Record) { const newObject: Record = {} for (const key in object) { const value = object[key] if (value instanceof Date) { // DynamoDB requires the TTL attribute be a UNIX timestamp (in secs). if (key === "expires") newObject[key] = value.getTime() / 1000 else newObject[key] = value.toISOString() } else newObject[key] = value } return newObject }, /** Takes a Dynamo object and returns a plain old JavaScript object */ from>(object?: Record): T | null { if (!object) return null const newObject: Record = {} for (const key in object) { // Filter DynamoDB specific attributes so it doesn't get passed to core, // to avoid revealing the type of database if (["pk", "sk", "GSI1PK", "GSI1SK"].includes(key)) continue const value = object[key] if (isDate(value)) newObject[key] = new Date(value) // hack to keep type property in account else if (key === "type" && ["SESSION", "VT", "USER"].includes(value)) continue // The expires property is stored as a UNIX timestamp in seconds, but // JavaScript needs it in milliseconds, so multiply by 1000. else if (key === "expires" && typeof value === "number") newObject[key] = new Date(value * 1000) else newObject[key] = value } return newObject as T }, } function generateUpdateExpression(object: Record): { UpdateExpression: string ExpressionAttributeNames: Record ExpressionAttributeValues: Record } { const formattedSession = format.to(object) let UpdateExpression = "set" const ExpressionAttributeNames: Record = {} const ExpressionAttributeValues: Record = {} for (const property in formattedSession) { UpdateExpression += ` #${property} = :${property},` ExpressionAttributeNames["#" + property] = property ExpressionAttributeValues[":" + property] = formattedSession[property] } UpdateExpression = UpdateExpression.slice(0, -1) return { UpdateExpression, ExpressionAttributeNames, ExpressionAttributeValues, } } export { format, generateUpdateExpression }