Pushing the project forward

[pilcrowonpaper]

Hi, sorry for the lack of activity recently! I've been thinking about how I want to move Lucia forward and looking to hear your opinions.

I think the bitter truth about auth is that it's not something that can be easily encapsulated. But that feels wrong, right? If you look at various different applications with auth, you're going to find a lot of similarities. So as devs, we want to encapsulate and abstract - something we love to do. But how is that any different from thinking we can make any app feature a library? All social medias have a post that users create and like - so we should have a "post" library that all social media apps can use. That would be insane! Why would you ever do that? And auth encompasses so much more of your application.

Of course, having libraries, microservices, hosted solutions, and a billion industry just for auth isn't insane because it's hard. Yet not being socially insane doesn't make it any easier to abstract or make the abstraction customizable. If you want something that is fully customizable and feels naturally part of your codebase, you need to write it yourself. No different than trying to implement the post/like feature from scratch.

I've always wanted Lucia to be the cleanest way to implement auth. Not the fastest - that's for the VC-backed companies to solve. The cleanest. The repository's description is "Auth, simple and clean" after all. Abstractions often is the answer to that but not this time.

Lucia should be a solid foundation for implementing auth from scratch. The Copenhagen Book, my other project, is about the theory and concepts. So naturally Lucia should be about the implementation.

We do have a tutorial on implementing OAuth-based logins. Great. But it's missing the most important resource - a fully fledged guide on implementing password-based authentication. Something that covers everything from email verification to brute force protection. I've been planning to start building that for a while. But, I don't want to create a guide/example for every single JavaScript framework. It's monotonous, and more importantly, I don't feel like I'm providing anything of value. How exactly you set the cookie using your library's specific API isn't important - it's that the cookie itself is set with the necessary flags. You should already know what about cookies and how to set them in your framework.

So, I'm going to pick a single framework or library with an API that anyone can read - probably either Express, Hono, Astro, or just even Node.js 'http' module. All tutorials and examples will use a simple HTTP server with basic HTML templating, SQLite, and Redis. No more tutorials or examples for Next.js. I handle all the auth stuff so you translate that into whatever framework and database you use. This significantly reduces the burden for me and allows me to create a wider variety of resources (2FA, OAuth, etc). I'll first start by building a tutorial and example for OAuth-based auth and email/password auth, and expanding onto 2FA later on. The basic email/password example will cover passwords, email verification, password resets/updates, and brute-force attack prevention.

While I'll be putting less focus on individual frameworks and databases, I'll still have framework-specific guides when appropriate. These will mainly be for session management, like something we have right now, as well as client-side session management in SPAs.

It's possible that I'll bring back Next.js etc examples in the future, but for now, I want to narrow the scope a bit.

I'm still looking for the framework or router library to use so let me know if you any recommendations! Has to be Node.js since I don't want to make people install a whole new runtime just to run examples.

---

• Why not rely on community contribution for maintaining examples for Next.js etc?: I still have to review PRs. But the bigger issue is that community contributions aren't a good fit for something that requires constant maintenance. All the example needs to be updated whenever the "main" example is updated.

[Blackwidow-sudo]

First: Thank you for your work! I really appreciate the well written guides.
Second: Will the email/password auth include both typical sessions and via JWT?

[pilcrowonpaper]

No, it'll use typical db sessions. But I'll probably have a separate guide/tutorial on JWT sessions so you can "upgrade" the example if you want to.

[rynzuki]

Good point, creating examples for every major framework would be a pain. I would also recommend using just Node.js not any fancy framework only because it is the most used.

Also you should maybe consider that the community could provide framework specific implementations as well, if you spot any good examples you could just add them to the Docs. I personally love using svelte for my web projects and would really like to see an example implemention, as i am not sure if my own is any good xD.

Anyways amazing work wish you the best.

[pilcrowonpaper]

You shouldn't rely on community contributions for something that requires constant upkeep. It's just too inconsistent unfortunately (esp. for small-medium projects).

[productdevbook]

Thank you for this beautiful article. here is what I recommend to you and I have started to use these structures in many places.

h3
srvx
rou3
crossws

[salieflewis]

Hono.

[nawok]

HTTP server with basic HTML templating, SQLite, and Redis

And Bun can provide SQLite and Redis clients.

[SkyfallWasTaken]

I think Express would be a good fit, simply because more people are going to be familiar with it than with e.g. Hono

[binarykitchen]

Aye. Thanks to your excellent guidance from https://lucia-auth.com/ I've successfully managed a complete authentication under Express.js within 4 days while having children. Examples were without Express.js, but that's not a problem if you're smart enough ;)

[Fractal-Tess]

For me, I would be so glad if you could try incorporating diagrams and flow charts. I feel like that would paint a better picture for the user - silly ones should work just fine, so nothing fancy needed; smth like excalidraw for example

[ghostdevv]

I think leaning into the web standards of Request and Response would be ideal. This means that users of any modern framework can easily adapt the code to their framework. While I agree with others that express is still popular I think it's important to go with standards for longevity and maximum compatibility.

You can expand on this and have a community-led "boilerplate" page for adapting to framework/runtime specific APIs that support request/response.

Examples

node:

import { createServerAdapter } from '@whatwg-node/server'
import { createServer } from 'node:http'

const adapter = createServerAdapter(request => {
	return new Response(...)
})

createServer(adapter).listen(...)

hono:

app.get('/', (c) => {
	const request = c.req.raw;
	return new Response(...)
})

deno:

Deno.serve(request => {
	return new Response(...)
})

bun:

Bun.serve({
	fetch(request) {
		return new Response(...)
	}
})

Cloudflare Workers:

export default {
	fetch(request) {
		return new Response(...)
	}
}

etc

[florian-lefebvre]

Yeah I think using a simple framework based on Request/Response would be the best since it's the standard these days. I think Hono would be a good choice since it's pretty minimal and have a convenient way to define routes

[ThimoDEV]

I do agree with your story about auth. I tried implementing your guides in my Nuxt app and it became a lot of code which would be Nuxt only. Over time I did switch to better-auth. I haven't had in depth use cases where I would encounter limitations but I do really like that its framework agnostic and that it has a plugin system to extend or change how it works. Since the basic concepts are always the same and they wrote the most minimal helpers to make it work per framework.

How do you view that approach for auth?

[proof-llc]

I highly recommend you to avoid passwords and focus on webauthn. all browsers support it now. I would love for Lucia to be a guide to perfect auth - which deals with tech of today, not yesterday. I think Lucia should be webauthn exclusive with a path to add OAuth. That's it. If you include passwords in the mix, it will greatly complicate your code and DB and I think Lucia should not be focused on the status quo - but on what auth ought to be.

[proof-llc]

Whatever you decide, less is more. The less code you write and less tables you have, the better. Simplicity is key as Lucia is no longer a library where someone imports it and doesn't care about implementation.

[humemm]

I've spent the past three weeks diving into your documentation to build a new system. I took my time, exploring every example and following every rabbit hole—it was a rewarding experience. I really appreciate your approach of keeping things simple and leaving implementation details to the user; it's the right choice.

I do have a few suggestions that might enhance the experience:

1. Structure of Content:
   The Copenhagen book is an excellent resource, offering rich context. However, I often found myself flipping between it and the documentation to connect the dots. It might be helpful if each section began with the theory (the "why") and concluded with the implementation (the "how").

2. Simplify with Pseudocode:
   I agree with your minimalist approach regarding frameworks and databases. To take it a step further, consider using pseudocode to focus on function signatures and data structures. This way, the guides can emphasize core concepts, while the repository can provide full implementations for reference.

3. Enhance Continuity:
   Consistency across examples is crucial. Implementing navigation similar to VitePress, with "Next" and "Previous" steps at the bottom of each page, could greatly improve the learning flow.

I'm happy to help further and look forward to seeing how the documentation evolves.

[binarykitchen]

Simplify with Pseudocode

Oh yes, exactly 👍

[arorajatin]

Thank you for the great work you've done here @pilcrowonpaper! I have used lucia's documentation to implement my own auth and arctic to support OAuth. However, I find SAML implementation/documentation missing. Is this something you plan to add at some point of time?

[margusliinev]

I think Hono is a clear winner here for this use case:

• Supports all javascript runtimes
• Simple and Minimal API
• Excellent TypeScript Support
• Built on web standards like many meta frameworks (SvelteKit, Remix) and soon (Nuxt, SolidStart, TanStackStart) once H3 and Nitro make the changes.
• Hono can be easily mounted inside other meta-frameworks if needed, and many people already use it that way

[revskill10]

An example to use with Express and NestJS is enough for large scale adoption.

[binarykitchen]

Well no, I think pseudocode and have it neutral from any frameworks is better.

Real examples are dangerous, especially when it comes to authentication. You need to learn and to understand it properly instead of copying and pasting the examples.

[revskill10]

@binarykitchen Opinions are yours, but it's fine to underestimate the power of marketing until the project is dead even it's the best library. Who cares to use a library without native integration with their daily framework ?

[Fractal-Tess]

Personally, I think that express is a thing of the past. Although widespread, I think absolutely no one should start a projet using express and it should be generally avoided to promote express.

Something like hono is miles ahead in its simplicity and adaptability to different runtimes, not to mention speed and the following of standards.

[Fractal-Tess]

On a side note, I would also love to see more examples and clear explanations of how to work with jwt, be it how to store them server side or client side, refresh them, use them on the client, hit oauth providers for data with the jwt, revoke them, roll out your own jwt service, and much much more.

If the goal of Lucia is to provide education for people about authentication, I feel like adding jwt to the scope of the documentation is a must.

But it should not be limited to jwt, maybe provide some examples of how to work with webauthn and best patterns, biometrics, passkeys, etc.

I'm open to landing a hand in that aspect.

[doroved]

@pilcrowonpaper Use Bun + Hono - it's the real future.

[AlexanderHott]

I would really like to see an example of how JWTs can be used securely without having to store an expired/revoked session table in the database. Something like how clerk handles it with two JWTs, a short lived one and a long lived one, could work, but that's pretty complex.

[doroved]

Why use the complicated option?

[AlexanderHott]

Why use the complicated option?

Using JWTs opens the door for attackers to use a session until it expires without a way for the user to revoke it. If you do make a way for users to revoke sessions, you have to store it somewhere, presumably in the database, and then check every time someone sends a JWT that it isn't revoked by querying the database. The whole point of JWTs is that you can have stateless auth, so bringing the DB back in the mix counteracts the benefits of using them in the first place.

The more complicated pattern uses JWTs without the security flaw, but I'm still not entirely sure that it's better than just using sessions.

Showcasing JWTs without a way for users to revoke sessions would be irresponsible imo.

[Fractal-Tess]

Jwts are the main mechanism behind oauth and sso - knowing how to work with them, their draw backs, advantages and edge cases is crucial in the modern web.

Since Lucia aims to be learning resource on best practices on all things Auth related, then I think it's a no brainer that jwts should be covered.

[benjick]

Someone will create implementations of it for different frameworks and then someone will create an "awesome lucia auth" which links them all