Lucia 3.0

[pilcrowonpaper]

I'm excited to announce Lucia 3.0!

We've been working on this for a few months now and it's finally out of beta! I was originally planning to release it this spring. But with Lucia starting to get more attention and usage, I have pushed the date earlier to avoid situations where new users are forced to migrate immediately. Don't worry - v2 will be maintained until the end of the year so you have more than enough time to migrate.

With this update, we have greatly simplified the library. All the annoying bits have been stripped out, and everything else we kept has been refined even more. It's just all around easier to understand and work with. One major component we removed are keys. You're now responsible for creating users and managing authentication. Keys were an awkward concept that confused beginners and made simple projects more complicated, but at the same time, didn't work for more complicated use cases. For a simple username and password implementation, you can just store the hashed password to the user table.

import { generateId } from "lucia";
import { Argon2id } from "oslo/password";

const hashedPassword = await new Argon2id().hash(password);
const userId = generateId(15);

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

const session = await lucia.createSession(userId, {});
headers.set("Set-Cookie", lucia.createSessionCookie(session.id).serialize());

Another major change is that the OAuth integration has been replaced with a separate package, Arctic. With the removal of keys, we were able to convert it into an agnostic OAuth package. Arctic supports all providers that were available in the OAuth integration and more.

import { GitHub, generateState } from "arctic";

const github = new GitHub(GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET);

const state = generateState();

const authorizationURL = await github.createAuthorizationURL(state, {
	scopes: ["email"]
});

We have also removed framework specific middleware. This was a tough decision but we believe maintaining APIs for numerous frameworks across multiple major versions wasn't a viable option moving forward. We still maintain guides and examples for popular frameworks and you just have to copy-paste few lines of code when starting your project.

Finally, Lucia is now built with Oslo. This is a package provides a bunch of auth related utilities. We also recommended using it alongside Lucia as it includes APIs for hashing passwords, two-factor authorization, passkeys, and more.

We'd like to thank everyone who has contributed to Lucia, Oslo, and Arctic!

Ready to upgrade your project? Read the migration guide!

Have any questions? Join our Discord server!

[awbx]

Thanks, @pilcrowonpaper, for simplifying and streamlining the authentication process. Your efforts are much appreciated!

[rohanrehman]

@pilcrowonpaper big fan of you' re approach! moving to v3, the v2 redis adapter is deprecated are you aware if anyone is working on one for V3? or for uspstash-redis?

[michnak]

[rdmchr]

They released v1 just a few days ago (https://twitter.com/pilcrowonpaper/status/1750484300565451261). I think the notice hasn't been updated to reflect that yet.

[michnak]

Oh, I haven't noticed the author is the same person. Thank you!

[pilcrowonpaper]

thanks, fixed

[SrBrahma]

Congratulations and thanks for your work! NextAuth doesn't feel like the best tool and I hope Lucia can take this vacuum for authing.

[ekimia]

Any plans to support access/refresh tokens? It's a total nightmare with nextauth

[sunneydev]

Why?

[naourass]

Just to confirm, so each incoming request is checked against the database since there's no jwt right?

[naourass]

And if it's the case, is it possible to use Oslo package with Lucia currently to serve/verify jwt tokens?

[pilcrowonpaper]

We used to support JWT and it was a broken mess. Token rotation requires additional complexity, you need to sync state in the client, and the added security risks requires you to just do more. Even if it was simple, sessions and JWTs are 2 totally different things and require different db tables. Supporting both with a single library doesn't make any sense.

[jasongitmail]

Hybrid JWT + session strategy detailed in Lucia discussions.

I'm of the opinion that the antagonism toward JWTs is overstated. Security-critical applications (like banking) require database sessions for immediate session revocation, but many consumer apps could benefit from the performance benefits (reduced latency) and reduced database usage costs from a hybrid JWT + session strategy.

Lucia would be well positioned for offering this.

[rodolphoasb]

Does it work with Remix?

[pilcrowonpaper]

It "works" but auth in general is always in remix right now so I'm waiting for them to implement middleware before we add docs for it

[boptom]

@pilcrowonpaper Do you mean we need to check auth in all loaders/actions since there is no middleware concept in Remix?

[danestves]

Tbh I don't have any problems and call auth on every loader/action 👀 but I want to know how to make it work on Remix

[pilcrowonpaper]

There are 2 problems - one more severe

1. The cookie API is awkward
2. Each validateSession() call does a db call. Since loaders run in parallel, you're making multiple unnecessary db calls just to validate a single request.

Both of these should be fixed once they implement middleware

[constantgillet]

Hey, yes it's possible to use Lucia in Remix. Cookie validation should not be done in the loaders, but by creating a custom context middleware in the adaptor. It prevents doing multiple unnecessary db calls.

For example bellow I have used an express middleware and I recover the user data in the context loader, actions.
It works but right know I haven't finished implementing it.

export async function setupRemixContext(
  req: Request,
  res: Response,
  next: NextFunction
) {

  const auth = await validateAuth(req, res);
 res.locals.user = auth.user

  next();
}

//validate auth
const validateAuth = async (req: Request, res: Response) => {
  const sessionId = req.cookies[lucia.sessionCookieName];

  if (!sessionId) {
    console.log("no session id");

    return { session: null, user: null };
  }

  const result = await lucia.validateSession(sessionId);

  try {
    console.log("result", result);

    if (result.session && result.session.fresh) {
      const sessionCookie = lucia.createSessionCookie(result.session.id);
      res.cookie(
        sessionCookie.name,
        sessionCookie.value,
        sessionCookie.attributes
      );
    }
    if (!result.session) {
      const sessionCookie = lucia.createBlankSessionCookie();
      res.cookie(
        sessionCookie.name,
        sessionCookie.value,
        sessionCookie.attributes
      );
    }

    return result;
  } catch (e) {
    console.error(e);
  }
};

[directormac]

Thank you! Time to migrate.

[msbeeman]

Congratulations, and thanks for all the work you put into it!

[KleKlai]

thank you for making developer life easier.

[danilo1105]

First of all, thanks @pilcrowonpaper for your work!

If someone can help me, I'm facing a problem with my implementation.

I'm using Drizzle with "NodePostgresAdapter" and if I try to set the expires_at column as an integer ...

CREATE TABLE IF NOT EXISTS "boilerplate_user_session" (
	"id" varchar(128) PRIMARY KEY NOT NULL,
	"user_id" varchar(15) NOT NULL,
	"expires_at" integer NOT NULL
);
...

...I get following error when running the const session = await lucia.createSession(userId, {}); command:
invalid input syntax for type integer: "2024-02-28T17:07:32.380-03:00"

And If I try to set the expires_at as a timestamp...

CREATE TABLE IF NOT EXISTS "boilerplate_user_session" (
	"id" varchar(128) PRIMARY KEY NOT NULL,
	"user_id" varchar(15) NOT NULL,
	"expires_at" timestamp NOT NULL,
);

... I get the error:
TypeError: date.getTime is not a function at the const result = await lucia.validateSession(sessionId); command.

node_modules/.pnpm/[email protected]/node_modules/oslo/dist/index.js (34:29) @ getTime
 ⨯ TypeError: date.getTime is not a function
    at async eval (./src/server/auth/lucia.ts:53:20)
    at async Page (signup/page.tsx:19:25)
null

Does anyone has an suggestion to what am I doing wrong?

[deadcoder0904]

@danilo1105 you can see how i did it here -> https://github.com/deadcoder0904/next-14-lucia-v3-sqlite-drizzle-conform-zod-email-verification-otp-server-actions/blob/e132a270a2564831c88c73146ffb574fe9beb8ba/src/app/lib/emailVerificationCode.ts#L20

[danilo1105]

Hey @deadcoder0904! Thanks for your help.

In fact my problem was that I was using import { NodePostgresAdapter } from '@lucia-auth/adapter-postgresql'; instead of import { DrizzlePostgreSQLAdapter } from '@lucia-auth/adapter-drizzle';. Rookie mistake. But I only realized it after seeing your code so a big thanks to you!

[stabildev]

How to avoid every request hitting the db?

[deadcoder0904]

React.cache() (see validateRequest) & rate-limit for bad actors.

[sasatatar]

Consider using Redis for storing session info.

[deadcoder0904]

yes, redis example -> https://github.com/deadcoder0904/nextjs-rate-limit

redis example with lucia -> https://github.com/deadcoder0904/next-14-lucia-v3-sqlite-drizzle-conform-zod-email-verification-otp-server-actions

[stabildev]

I would prefer a jwt session. Is it possible with Lucia? Any reason why a db approach is used instead?

[sasatatar]

There was a discussion where pilcrowOnPaper talked about it. Essentially, it's beyond the scope of what lucia was initially designed to do (manage sessions), and maintaining the implementation was a mess.
Refresh token rotation is really tricky to abstract away in a flexible manner. And on the other hand, in-memory DB nicely pollyfills all of the benefits of JWT, so it might actually not make a lot of sense to maintain that solution.