Planning for 1.0: Tokens

[pilcrowonpaper]

This feature will make it much easier to implement email verification, 2FA, and OTPs.

Summary

Provide APIs for generating and validating tokens. Tokens can be stored in any number of database tables. Tokens can hold any number of data, similar to User.

(Please help me with the names).

type Token {
  tokenId: string,
  userId: string,
  attributes: Record<any, any>
}

Token types

Tokens can be either one time tokens or multi-use.

Access tokens

These token are user-context independent. Useful when you don't have the current session, like forgot-password email links.

const tokenId = await auth.generateToken(tokenName, userId, attributes);
const token = await auth.validateToken(tokenName, tokenId);

Context tokens

These tokens use the user-context. Useful when you have the current session, like one time passwords.

const tokenId = await auth.generateContextToken(tokenName, userId, attributes);
const token = await auth.validateContextToken(tokenName, tokenId, userId);

Token validation

The validation process is:

1. Check expiry time
2. If one_time is enabled, delete token
3. Return user

Configs

Tokens can be declared and configured inside lucia().

lucia({
  tokens: [{
    type: "context",
    generate: () => generateRandomString(6),
    databaseTable: "one_time_password", // table name
    duration: 60 * 60,
    oneTime: true, // delete token on validation?,
    transform: () = {} // transform attributes, return type as Token.attributes
  }]
})

Database model

You can have any number of tables.

[token]

name	type	reference	unique
id	string		true
user_id	string	user(id)
expires	number
[any]

[v-rogg]

I really like the proposal. I thought about the same thing the last few days. We could also think about adding an interface to implement a verification service easily or adding an example of how to build one (e.g., email verification with nodemailer similar to how auth.js does it) to the docs/repo.

[pilcrowonpaper]

That’s the plan!