V3 proposal: Rethinking Lucia once more

[pilcrowonpaper]

V3 proposal: Rethinking Lucia once more

Based on the relatively positive feedback on #1231, I thought I'd write a more comprehensive proposal/RFC. I have not decided on anything and this is just a concept. Here's the overview:

• Remove keys
• Remove APIs for handling users
• Rework the OAuth integration

This will be one of the biggest changes to the project.

Redefining Lucia

Lucia will only handle sessions and related database queries. That's it. It will no longer handle the authentication step (OAuth and password check) and users. For an in depth explanation, see #1231. However, in short, the database adapter model and keys are too limiting for handling various auth methods, especially as each project has different requirements. Removing keys allow simple projects to use a more simple mode, and complex projects to not worry about limitations set by Lucia. I'm also thinking of removing APIs like createUser() because they're just redundant considering you're likely using an ORM or query builder.

We will still provide APIs for implementing OAuth, specifically creating authorization URLs, validating authorization codes, and getting the provider user. We will also provide APIs to hash passwords using recommended algorithms/settings. We will also provide guides/docs on it.

Updated API

Overall, the API will be dramatically simplified:

interface Auth {
  createSession(
    userId: string,
    attributes: DatabaseSessionAttributes
  ): Promise<string>;
  invalidateSession(sessionId: string): Promise<void>;
  invalidateAllUserSessions(userId: string): Promise<void>;
  validateSession(
    sessionId: string
  ): Promise<[session: Session, user: User] | [session: null, user: null]>;
  getAllUserSessions(userId: string): Promise<Session[]>;
  updateSessionAttributes(
    sessionId: string,
    attributes: Partial<DatabaseSessionAttributes>
  ): Promise<void>;

  createSessionCookie(sessionId: string): SessionCookie;
  createBlankSessionCookie(): SessionCookie;

  handleRequest(...args: any[]): AuthRequest;
  readBearerToken(
    authorizationHeader: string | null | undefined
  ): string | null;
  readSessionCookie(cookieHeader: string | null | undefined): string | null;
}

interface Session extends SessionAttributes {
  sessionId: string;
  expiresAt: Date;
  fresh: boolean;
}

interface User extends UserAttributes {
  userId: string;
}

Adapter API

The adapter API also gets dramatically simplified:

interface Adapter {
  getSessionAndUser(
    sessionId: string
  ): Promise<[session: Session, user: User] | [session: null, user: null]>;
  deleteSession(sessionId: string): Promise<void>;
  getAllUserSessions(userId: string): Promise<Session[]>;
  setSession(data: SessionSchema): Promise<void>;
  updateSession(sessionId: string, data: Partial<SessionSchema>): Promise<void>;
}

For adapters for session/memory storage, I'm thinking something like this could work:

lucia({
  adapter: useSessionAdapter(redis(redisClient), (userId) => {
    return await db.table("user").where("id", "=", userId).get();
  }),
  // ...
});

Using Oslo

Oslo should be the best companion package for Lucia since it provides APIs for:

• sessions (of course)
• generating random values
• OTP (HOTP, TOTP)
• OAuth
• hashing passwords (limited to Node.js)
• cookies
• passkeys
• JWT
• base64, base64url, hex

This does bring a slight change to the session table: idle_expires and active_expires will be replaced by a single expires column.

name	type	attributes
id	string	primary key
user_id	string
expires	number

OAuth package

The new OAuth package will not be an integration. It will just provide APIs for creating authorization URLs, validating codes, and fetching the provider user:

const github = new Github(clientId, clientSecret, {
  scope: ["user:email"],
});

const [authorizationURL, state] = await github.createAuthorizationURL();
const tokens = await github.validateAuthorizationCode(code);
const githubUser = await github.getGithubUser(tokens.accessToken);

Maybe a shadcn-like copy-paste approach might be better though.

Migration

See #1231 (comment) for a what possible migration may look like.

Code examples

OAuth (basic)

const tokens = await github.validateAuthorizationCode(code);
const githubUser = await github.getGithubUser(tokens.accessToken);

const existingUser = await db
  .table("user")
  .where("github_user_id", "=", githubUser.id)
  .get();

if (existingUser) {
  const session = await auth.createSession(existingUser.id);
  locals.auth.setSession(session);
}

const userId = auth.generateUserId();

await db.table("user").insert({
  id: generateUserId(),
  username: githubUser.login,
  github_user_id: githubUser.login,
});

const session = await auth.createSession(userId);
locals.auth.setSession(session);

Multiple OAuth providers

const github = new Github(clientId, clientSecret);

const tokens = await github.validateCallback(code);
const githubUser = await github.getGithubUser(tokens.accessToken);

const existingAccount = await db
  .table("account")
  .where("user_id", "=", githubUser.id)
  .get();
if (existingAccount) {
  const session = await auth.createSession(existingAccount.user_id);
  locals.auth.setSession(session);
}

const userId = auth.generateUserId();

await db.transaction(
  db.table("user").insert({
    id: userId,
    username: githubUser.login,
  }),
  db.table("oauth_account").insert({
    provider: "github",
    provider_user_id: githubUser.id,
    user_id: userId,
  })
);

const session = await auth.createSession(userId);
locals.auth.setSession(session);

Username & password

import { Argon2id } from "oslo/password";

const argon2id = new Argon2id();
const hashedPassword = await argon2id.hash(password);

const userId = auth.generateUserId();

await db.table("user").insert({
  id: userId,
  username,
  hashed_password: hashedPassword,
});

const user = await db.table("user").where("username", "=", username).get();
if (!user) {
  throw new Error("Invalid username or password");
}
const validPassword = await argon2id.verify(user.hashed_password, password);
if (!validPassword) {
  throw new Error("Invalid username or password");
}