RFC: Lucia v3

[pilcrowonpaper]

Based on the relatively positive feedback on #1231, I thought I'd write a more comprehensive proposal.

You can find the work-in-progress source code in the v3 branch.

Redefining Lucia

Lucia will 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 model, and complex projects to not worry about limitations set by Lucia. I also think there's more value for Lucia to focus on the docs than to provide wrappers around database queries.

There will be an even more heavy focus on the docs. While we are removing APIs for checking passwords etc, there will be proper guides on implementing OAuth, email/password, passkeys, and more.

Oslo

Lucia will be built on oslo. 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 encoding

Guides for OTP, custom OAuth providers, passkeys, etc will use Oslo.

New API

Lucia will be initialized with Lucia() instead of a function lucia(). See Embracing classes for details.

import { Lucia } from "lucia";

const auth = new Lucia(adapter, options);

Here's the entire core API:

interface Lucia {
  createSession(
    userId: string,
    attributes: DatabaseSessionAttributes
  ): Promise<Session>;
  validateSession(
    sessionId: string
  ): Promise<{ user: User; session: Session } | { user: null; session: null }>;
  invalidateSession(sessionId: string): Promise<void>;
  invalidateUserSessions(userId: string): Promise<void>;
  getUserSessions(userId: string): Promise<Session[]>;

  readSessionCookie(cookieHeader: string): string | null;
  readBearerToken(authorizationHeader: string): string | null;

  handleRequest(...args: any[]): AuthRequest;

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

That's it. No more extra bloat that you can just use your ORM/query-builder for. I'm still considering whether to add an updateSessionAttributes() however. AuthRequest will be mostly the same, except for AuthRequest.setSession(), which will be replaced by AuthRequest.setSessionCookie() and AuthRequest.deleteSessionCookie().

interface AuthRequest {
  validate(): Promise<
    { user: User; session: Session } | { user: null; session: null }
  >;
  validateBearerToken(): Promise<
    { user: User; session: Session } | { user: null; session: null }
  >;
  invalidate(): void;
  setSessionCookie(sessionId: string): void;
  deleteSessionCookie(): void;
}

Updated configuration

getSessionAttributes() and getUserAttributes() will only be provided DatabaseSessionAttributes and DatabaseUserAttributes

I have removed the env config. I have moved it to sessionCookie.attributes.secure to make the relation more clear.

import { Lucia, TimeSpan } from "lucia";

const auth = new Lucia(adapter, {
  // these are all optional
  middleware: sveltekit(),
  csrfProtection: {
    hostHeader: "Host",
    allowedDomains: ["api.example.com"],
  },
  sessionExpiresIn: new TimeSpan(30, "d"),
  sessionCookie: {
    name: "session",
    expires: true,
    attributes: {
      secure: env === "PROD",
      sameSite: "lax",
      domain,
    },
  },
  getSessionAttributes: (databaseSessionAttributes) => {
    return {
      ipOrigin: databaseSessionAttributes.ip,
    };
  },
  getUserAttributes: (databaseUserAttributes) => {
    return {
      username: databaseSessionAttributes.username,
    };
  },
});

Error handling

v3 will no longer throw errors and thus LuciaError is removed. This is huge in terms of usability and maintainability. That said, all APIs will still throw a database error (connection error, etc).

Embracing classes

lucia() will be changed to new Lucia(), prisma() adapter to new PrismaAdapter(), etc. This change will make extending existing adapters much easier:

class CustomAdapter extends BetterSQLite3Adapter {
  constructor(db: Database) {
    super(db, tableNames);
  }

  public getSessionAndUser(): Promise<
    [session: DatabaseSession | null, user: DatabaseUser | null]
  > {
    // custom implementation
  }
}

Type declarations

You no longer have to declare types with .d.ts.

const auth = new Lucia();

declare module "lucia" {
  interface Register {
    Lucia: typeof auth;
    DatabaseUserAttributes: {
      username: string;
    };
    DatabaseSessionAttributes: {
      ip: string;
    };
  }
}

Hashing passwords

While we recommend using Argon2id for new projects, for older projects you can use generateLegacyLuciaPasswordHash() and verifyLegacyLuciaPasswordHash() to hash passwords.

import { generateScryptHash, verifyScryptHash } from "lucia";

Deprecating @lucia-auth/oauth

Since we're removing keys, there's no way to provide an OAuth integration specifically for Lucia. However, @lucia-auth/oauth still provides a lot of value by handling all the API requests. So, I'll be extracting part of it into a new package (currently work-in-progress). This package is also built on Oslo. I will make sure it'll have all providers currently provided by @lucia-auth/oauth by the release. This package will also include some improvements over the existing OAuth integration, namely better errors and an API for refreshing access tokens.

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

const state = generateState();

const url = await github.createAuthorizationURL(state);

// store state as cookie
setCookie("state", state, {
  secure: true, // set to false in localhost
  path: "/",
  httpOnly: true,
  maxAge: 60 * 10, // 10 min
});
return redirect(url);

const code = request.url.searchParams.get("code");
const state = request.url.searchParams.get("state");

const storedState = getCookie("state");

if (!code || !storedState || code !== storedState) {
  // 400
  throw new Error("Invalid request");
}

try {
  const tokens = await github.validateAuthorizationCode(code);
  const user = await github.getUser(tokens.accessToken);
} catch (e) {
  if (e instanceof OAuth2RequestError) {
    const { message, description, request } = e;
  }
  // unknown error
}

Database

Database schema

As always, you can add custom columns to both the user and session table. The session table will not support default values.

user table

column	type
id	string

session table

expires_at will replace active_expires and idle_expires.

column	type
id	string
user_id	string
expires_at	Date

Adapter API

The adapter API is significantly simplified. Adapters no longer have to worry about errors as well. This means adapters for ORMs and query builders are now possible.

interface Adapter {
  getSessionAndUser(
    sessionId: string
  ): Promise<[session: DatabaseSession | null, user: DatabaseUser | null]>;
  getUserSessions(userId: string): Promise<DatabaseSession[]>;
  setSession(value: DatabaseSession): Promise<void>;
  updateSessionExpiration(
    sessionId: string,
    expiresAt: Date
  ): Promise<void>;
  deleteSession(sessionId: string): Promise<void>;
  deleteUserSessions(userId: string): Promise<void>;
}

interface DatabaseUser {
  userId: string;
  attributes: DatabaseUserAttributes;
}

interface DatabaseSession {
  sessionId: string;
  expiresAt: Date;
  userId: string;
  attributes: DatabaseSessionAttributes;
}

Session adapters

There's a bit more work to get session adapters working since you can no longer merge it with a regular adapter.

interface SessionAdapter {
  getSession(sessionId: string): Promise<DatabaseSession | null>;
  getUserSessions(userId: string): Promise<DatabaseSession[]>;
  setSession(value: DatabaseSession): Promise<void>;
  updateSessionExpiration(
    sessionId: string,
    expiresAt: Date
  ): Promise<void>;
  deleteSession(sessionId: string): Promise<void>;
  deleteUserSessions(userId: string): Promise<void>;
}

class CustomAdapter extends RedisSessionAdapter implements Adapter {
  private db: Database;

  constructor(db: Database, client: RedisClient) {
    super(client);
    this.db = db;
  }

  public getSessionAndUser(): Promise<
    [session: DatabaseSession, user: DatabaseUser]
  > {
    const databaseSession = await this.getSession();
    if (!databaseSession) return [null, null];
    const result = await this.db
      .prepare("SELECT * FROM user WHERE id = ?")
      .get(session.userId);
    if (!result) return [null, null];
    const databaseUser: DatabaseUser = {
      userId: result.id,
      attributes: {
        username: result.username,
      },
    };
    return [databaseSession, databaseUser];
  }
}

[eagerestwolf]

I mean no disrespect with what I am about to say, but I genuinely believe this is the wrong direction to go. Rule number 1 of authentication, don't roll your own auth and that is exactly what Lucia V3 is going to force everyone to do. When you force users of your library to handle checking and hashing passwords you can recommend Argon2id all day long, but somebody out there is going to use MD5.

Moreover, yes the keys system is limiting and complex, but it's way less complex than trying to manage and link profiles on your own. Auth0 faced a similar problem, and they struggled with it for a long time. Eventually though, people got used to how it works and just rolled with it.

However, I will concede that using the actual 1st party libraries for OAuth is probably a smart idea, but it's not a one size fits all solution. There are cases where having an OAuth library that is tailored to your authorization library makes perfect sense. This is one of those cases in my opinion.

Ultimately, I will keep an eye on this RFC, and the decision ultimately lies with the team behind Lucia; but if this is the direction Lucia intends to go, I'll just migrate all of my projects to Supabase Auth.

[pilcrowonpaper]

don't roll your own auth and that is exactly what Lucia V3 is going to force everyone to do

Aside from password hashing, you still need to do everything else in Lucia v2. Login throttling, email verification, password reset, etc. IMO, password hashing is the last to thing worry about since most people at least know the importance of it. An auth library won't stop devs from leaking credentials either.

[saturnonearth]

Login throttling, email verification, password reset, etc.

Just a note on this - imo, login throttling should be left to other libraries or services such as Upstash, as if you are needing to throttle your login, you are probably going to need to throttle a lot of other features in your app, and will likely need to learn why throttling is important and will end up using different library at that point.

[benjick]

Sorry if it's the wrong place to ask, but with oslo; what will be the role of lucia? Why not keep these the same?

[pilcrowonpaper]

I've thought about this, but database adapters don't fit into the idea behind Oslo, and adding everything Oslo offers into Lucia doesn't feel right either.

[benjick]

Okay, I understand! Is your goal to offer a complete guide on how to use them in tandem eventually?

[pilcrowonpaper]

Yes! We'll be opinionated via the docs

[JeffWScott]

As someone who has followed you on Twitter for a while now I'm a bit disappointed to hear this. I know absolutely nothing about Auth, I want an Auth library with ALL the opinions from someone who understands it completely. I want to not think about anything. Auth is very complex, I assumed Lucia was this library as on Twitter you have lots of great tweets on the topic. It sounds like you're moving away from something that has opinions I would want to something that wants my opinions. My opinions suck.

[pilcrowonpaper]

I want to make it opinionated, but I really don't see how I can make it anymore opinionated than what we have in v2. And that makes Lucia v2 be in an awkward state of being too opinionated for implementing various systems (multiple emails per user, passkeys, etc), while not providing built-in support for everything required for password auth, including login throttling, email verification, and password reset.

Keys just make Lucia opinionated for the sake of being opinionated, while not providing the usual benefits of being opinionated.

[JeffWScott]

As an aside maybe, I've always wanted Auth to be as simple and optomistic as this:

// Give Luica whatever oAuth specific nonsense the auth provider (google, microsoft) gives me.
const auth = Lucia(options)

// wrap my handler in auth to protect it. 
api.post('/userData', {
    handler: () => auth(userDataHandler)
});

Call the handler callback if Auth is good or send a "not authenticated" response back if auth fails.

This all makes sense to me as I don't want to care about all the stuff that makes this happen, I just want to give it to you. I don't know why auth packages make me deal with validating the user manually inside my handlers. Maybe provide me an hook if I need it, but do the happy path for me. Is the user my user or not? That's all I care about.

So, if you're talking about splitting out all the pieces and joining them together with documentation, that's the opposite of what I want. I'm willing to walk out on the limb and be alone here.

In backend I have a million things I need to learn and make work together. Sure, Auth IS one of those things but it's generally the LAST thing I think about. Don't assume my mental model of Auth is anywhere near yours. I don't actually want to think about it and I will believe you if you tell me to do it a certain way; I will even proclaim your way as the best if if just works.

[pilcrowonpaper]

Lucia has never intended to be that kind of auth library from the start. I'd recommend switching libraries if you don't want to care about auth

[JeffWScott]

Will do

[iankettler]

The key to success to many libraries is not to build a complete solution but take away the complexity that comes with a dedicated point of failure, in this case Auth. I think of this proposal as a headless Auth library, which I hope the opensource community will implement to create framework tailored solutions for us to implement. Auth is difficult, and we cannot expect someone to take away all the complexity and still leave many scenarios open. This will just set the stage for focussing on the important parts of Auth and not the framework specific solutions and many possibilities to implement Auth.

[KazuumiN]

Removing keys allow ... complex projects to not worry about limitations set by Lucia.

I very much agree with this part, as I am having trouble implementing with the current Key concept.

[saturnonearth]

After reading some peoples' responses here, I realize Lucia always stood in a weird place because it started out as a Session management library, but sort of evolved into an easy to use and easy to get started auth library.

Auth libraries are hard because, they are never going to compete with a fully fledged service such as Clerk, or Auth0, or even Supabase Auth, as they have complete control over everything and just give you a modal. But that's okay!

You will have a few groups of people...

1. People who want a completely done solution and an can afford a third-party service such as Clerk, Auth0. They want all features for auth at the click of a button.
2. People who just want a user login and and don't want to worry about a lot of fluff, a don't need complexity.
3. People who want full control over their Auth, and want to use a auth library such as Lucia or Auth.js. They are okay with initial limitations as they can always add complexity down the line if they need to, as they may not need it right now.

Unfortunately, you can't please everyone as everyones needs are different. But I can definitely say drastic changes are gonna make a lot of people nervous

[SrGeneroso]

🦊

[danstans]

How limiting is oslo in regards to when ran on node vs bun runtimes?

[pilcrowonpaper]

Oslo is runtime agnostic aside from the password hashing module

[Djboy08]

I hope there would be complete guides for OAuth implementations for various models i.e PKCE.

I switched to lucia specifically for OAuth handling and so I am starting to wonder if this was the right choice as I am not trying to create my entire own oauth system. It seems like Lucia v3 will be primitives to create oauth but I still have to put in the work to make things run.

[pilcrowonpaper]

There will be guides for implementing OAuth, with and without PKCE.

[jasongitmail]

To respond to a specific aspect: Regarding naming, you could consider putting session-related items onto a session property, like below. Cleans it up and provides more helpful Intellisense of method names for developers:

session.create(sessionId: string, attributes: DatabaseSessionAttributes)
session.get(sessionId: string)
session.getAll(userId: string)
session.invalidate(sessionId: string)
session.invalidateAll(userId: string)
session.readCookie(sessionId: string)
session.createCookie(sessionId: string)
...

Similarly, it'd be be nice to see naming where the user's id within the user's object is simply id when it appears within an object representing a user, rather than userId. E.g.

const user = {
   id: 'abc123'
}

not like this:

const user = {
   userId: 'abc123'
}

because it's redundant when used (e.g. user.userId).

Same for sessionId.

[pilcrowonpaper]

I have considered the idea and discussed with the community, but we decided to go with the current approach. As for userId vs id, I don't have a big preference

[jasongitmail]

It's an opportunity to revisit and improve since it's a major version bump

[jasongitmail]

I will add that I think having a separate package named oslo is a net negative for Lucia because it creates an additional mental decision for developers to consider: "should I use Lucia or Oslo vs all the others?". Rather than allowing devs to simply start with Lucia and they can access the methods if they want or need, now or later.

These methods could just as easily be exported from Lucia.

[pilcrowonpaper]

Oslo will complement Lucia. It's not a replacement. Use Lucia for dealing with sessions, and use Oslo for generating random values, encoding strings, generating OTPs, hashing passwords, etc. The only thing Oslo is "taking away" from Lucia is lucia/utils and password hashing.

[productdevbook]

I'm glad to hear that, I was very confused by your posts on twitter. Oslo or Lucia.

Now I know it's Lucia.

[jasongitmail]

[jasongitmail]

You can make the props optional or mimic the structure. I think you might be missing the point if that's the reasoning

[pilcrowonpaper]

I'm not sure what you mean? If it's typed DatabaseUser, the value should match the type. We can't just set DatabaseUser.attributes to an empty object

[jasongitmail]

If the attributes are different values (user vs session, which I just noticed in the types), then it makes sense as is. But if they're the same values, like if they're the same optional attributes specified for that user, then the original structure is semantically unclear and would be more clear inside a user property of the session.

[pilcrowonpaper]

yeah session and user attributes are different things, like in v2

[jasongitmail]

cool, got it. 👍 Will delete this one

[rmarscher]

In lucia v2, it is not easy to swap out scrypt... so this v3 proposal is great to make that more modular. It would be nice if a recommended solution could be provided for non-legacy hashing in a cloudflare worker environment. I tested https://github.com/auth70/argon2-wasi and it works. hash-wasm would probably also work but needs a build step to create wasm binaries. Daninet/hash-wasm#56

Maybe there could be an oslo/password-wasm package. If it's too much to maintain in oslo, a guide for one of these other webassembly solutions would work. Thanks!

[pilcrowonpaper]

There's also @noble/hashes which is pure JS, but it's like 1.5~2x slower than WASM/Node implementation

[msbeeman]

From what I've read/seen, I'm gathering that the folks who are against this change in direction to just session handling are mainly the folks that currently rely on Lucia's authentication implementation because they don't know how to do it themselves safely and securely. I think the change will be less stressful to those folks if meaningful documentation and guides are provided (like in the nicely written guidebooks https://lucia-auth.com/guidebook/) that could show them a good example implementation of the user authentication (securely and properly) alongside with the new library. That way some people don't feel totally lost since they have a starting point to go off of for secure authentication, and that also may help current Lucia users who try to switch not compromise their user data through a poor attempt that results insecure implementation. If Oslo will handle this already then great!

[pilcrowonpaper]

Ok, after testing the beta version (see #1258), I'm happy with the general direction of the proposal. As such, I am going forward with this change. Thanks to everyone who left a comment in the discussion.

The details are still being fleshed out and specific APIs might change. I'll announce it on Twitter and Discord when we've built the basic documentation. In the meantime, if you want to play around, you can install the beta version with npm i lucia@beta.

[Jonatthu]

I think the direction you are taking is the right one, all the helpers and utils are there. The rest is easy to implement thanks to the libs and work you are providing. Looking forward into the new cooking guides for v3. I am looking forward to even help if you need to.