Implementing 2FA without the tokens integration (v1/v2)

[pilcrowOnPaper]

With Lucia v2, we are planning to deprecate single use keys, and as such, the tokens integration (@lucia-auth/oauth). This is due to several factors:

• Single use keys are severely limiting
• Security is fine but not the best
• Likely will be a pain to maintain long term
• Using the same API/table for accounts and tokens felt wrong

This post details simple alternatives (not 100% a drop in replacement however) that is easy to extend and is secure. See the examples dir in the repo for examples.

Id tokens (Verification tokens)

Database

column	type	primary key	references
id	TEXT	✓
expires	BIGINT
user_id	TEXT		user(id)

Code

import { db } from "./db.js";
import { generateRandomString } from "lucia"; // v1
import { generateRandomString, isWithinExpiration } from "lucia/utils"; // v2 beta.0

const isWithinExpiration = (expiresIn: number) => {
	const currentTime = new Date().getTime();
	return currentTime < expiresIn;
};

const EXPIRES_IN = 1000 * 60 * 60 * 2; // 2 hours

// generates new token
const generateToken = async (userId: string) => {
	const token = generateRandomString(64); // github uses 128+ for password reset tokens

	// you can optionally invalidate all user tokens
	// so only a single valid token exists per user
	// for high security apps

	await db.setToken({
		id: token,
		expires: new Date().getTime() + EXPIRES_IN,
		user_id: userId
	});
	return token;
};

// validates token and returns user id if valid
const validateToken = async (token: string) => {
	const storedToken = await db.getToken(token);
	if (!storedToken) throw new Error("Invalid token");
	await db.deleteToken(token);
	const tokenExpires = Number(storedToken.expires); // bigint => number conversion
	if (!isWithinExpiration(tokenExpires)) {
		// should throw a vague error to user (expired *or* invalid token)
		throw new Error("Expired token");
	}
	return storedToken.user_id;
};

You can of course use transactions, which is going to be safer.

const queries = [db.getToken(token), db.deleteToken(token)];

const [storedToken] = await transaction(queries);
const [storedToken] = await batch(queries);

Password tokens (one time passwords)

In general, only a single valid password should exist for each user (per use case).

Database

This uses a compound/composite key where the combination of password and user_id makes a unique key. You can alternatively use <user_id>:<password> as the id.

column	type	primary key	references
password	TEXT	✓
user_id	TEXT	✓	user(id)
expires	TEXT

Code

import { db } from "./db.js";
import { generateRandomString } from "lucia"; // v1
import { generateRandomString, isWithinExpiration } from "lucia/utils"; // v2 beta.0

const isWithinExpiration = (expiresIn: number) => {
	const currentTime = new Date().getTime();
	return currentTime < expiresIn;
};

const EXPIRES_IN = 1000 * 60 * 10; // 10 minutes

// generates new password
const generateOneTimePassword = async (userId: string) => {
	// invalidate previous passwords
	await db.deleteTokensByUserId(userId);

	const token = generateRandomString(8);
	await db.setOneTimePassword({
		password: token, // optionally hash it for added security
		expires: new Date().getTime() + EXPIRES_IN,
		user_id: userId
	});
	return token;
};

// validates password and returns user id if valid
const validateOneTimePassword = async (userId: string, password: string) => {
	const storedPassword = await db.getOneTimePassword({
		password: token,
		user_id: userId
	});
	if (!storedPassword) throw new Error("Invalid password");
	await db.deleteOneTimePassword({ password: token, user_id: userId });
	const passwordExpires = Number(storedPassword.expires); // bigint => number conversion
	if (!isWithinExpiration(passwordExpires)) {
		// fine to share its expired
		// since the userId is from the session
		throw new Error("Expired password");
	}
	return storedToken.user_id;
};

You can of course use transactions, which is going to be safer.

const queries = [
	db.getOneTimePassword({
		password: token,
		user_id: userId
	}),
	deleteOneTimePassword.deleteToken(token)
];

const [storedToken] = await transaction(queries);
const [storedToken] = await batch(queries);
if (storedToken) {
	// don't forget to invalidate all other passwords if valid
	// we don't add this in the transaction
	// since it shouldn't the correct token
	// on a single failed attempt
	await db.deleteTokensByUserId(userId);
}

Verification links

This implementation sends the same email verification link if an hour (expiration / 2) hasn't passed since token generation. Can be used for email verification and password reset links. You should implement rate-limiting but this reduces the number of tokens stored.

const EXPIRES_IN = 1000 * 60 * 60 * 2; // 2 hours

const generateVerificationToken = async (userId: string) => {
	const storedUserTokens = await db.getTokensByUserId(userId); // github uses 128+ for password reset tokens
	if (storedUserTokens.length > 0) {
		const reusableStoredToken = storedUserTokens.find((token) => {
			// check if expiration is within 1 hour
			// and reuse the token if true
			return isWithinExpiration(
				Number(token.expires) - EXPIRES_IN / 2
			);
		});
		if (reusableStoredToken) return reusableStoredToken.id;
	}

	// you can optionally invalidate all user tokens
	// so only a single valid token exists per user
	// for high security apps

	const token = generateRandomString(64);
	await prismaClient.setToken({
		id: token,
		expires: new Date().getTime() + EXPIRES_IN,
		user_id: userId
	});
	return token;
};

Email verification

// user registration flow
// route: POST /signup

const user = await auth.createUser({
	key: {
		providerId: "email",
		providerUserId: email,
		password
	},
	attributes: {
		email,
		email_verified: false
	}
});
const session = await auth.createSession(user.userId);
authRequest.setSession(session);
const token = await generateVerificationToken(session.user.userId);
await sendVerificationEmail(email, token);

// resend email
// route: POST /email-verification

const session = await authRequest.validate();
if (!session) {
	// unauthorized
}
if (session.user.emailVerified) {
	// already verified!
}
const token = await generateVerificationToken(session.user.userid);
await sendVerificationEmail(email, token);

// validate verification links
// route: GET /email-verification/<verification_token>

const token = readTokenFromUrl(url);
const userId = await validateEmailVerificationToken(token);
if (!userId) {
	// "invalid or expired token"
}

// we can invalidate all tokens belonging to a user
// since a user only verifies their email once
await db.deleteTokensByUserId(userid);
await auth.invalidateAllUserSessions(userId);
await auth.updateUserAttributes(userId, {
	email_verified: true
});
authRequest.setSession(session);

// protect pages

const session = await authRequest.validate();
if (!session) {
	// redirect to /login
}
if (!session.user.emailVerified) {
	// redirect to "please check your inbox" page (e.g. /email/verification)
}

Password reset

// send reset link
// route: POST /reset-password

const email = getEmailFromFormData(formData);
const token = await generateVerificationToken(session.user.userId);
await sendVerificationEmail(email, token);

// validate verification links
// route: POST /password-reset/<verification_token>

const token = readTokenFromUrl(url);
const userId = await validateEmailVerificationToken(token);
const newPassword = getNewPasswordFromFormData(formData);
const user = await auth.getUser(userId);
await auth.invalidateAllUserSessions(userId); // IMPORTANT!!!
await auth.updateKeyPassword("email", user.email, newPassword);
const session = await auth.createSession(user.userId);
authRequest.setSession(session);

One time passwords

// user registration flow
// route: POST /signup

const user = await auth.createUser({
	key: {
		providerId: "email",
		providerUserId: email,
		password
	},
	attributes: {
		email,
		email_verified: false
	}
});
const session = await auth.createSession(user.userId);
authRequest.setSession(session);
const token = await generateOneTimePassword(session.user.userId);
await sendVerificationEmail(email, token);

// resend email
// route: POST /email-verification/resend

const session = await authRequest.validate();
if (!session) {
	// unauthorized
}
if (session.user.emailVerified) {
	// already verified!
}

const token = await generateOneTimePassword(session.user.userid);
await sendVerificationEmail(email, token);

// validate verification links
// route: POST /email-verification/

const session = await authRequest.validate();
if (!session) {
	// unauthorized
}
if (session.user.emailVerified) {
	// already verified!
}
const token = getTokenFromUrl(url);
const userId = await validateOneTimePassword(session.user.userId, token);
await auth.invalidateAllUserSessions(userId);
await auth.updateUserAttributes(userId, {
	email_verified: true
});
authRequest.setSession(session);

// protect pages

const session = await authRequest.validate();
if (!session) {
	// redirect to /login
}
if (!session.user.emailVerified) {
	// redirect to "please check your inbox" page (e.g. /email/verification)
}