v3 RFC: Remove request handling APIs

[pilcrowonpaper]

Supersedes #1284.

I'm considering removing middleware and AuthRequest as a whole. The big issue is dependencies. If one of the frameworks has a breaking change that breaks existing Lucia API, we would have to introduce a new major version, even if 99% of the code stays the same. We can separate them into their own packages, but it's at most 50 lines of code. And most of them are just simple if checks. Is it really worth it to maintain 10 more packages? Wouldn't it be easier to just let people copy-paste what's in the docs?

If we go with this change, you'd have to copy-paste < 50 lines of boilerplate code from the getting started guide. For example, Astro users would have to just add the middleware below. It's just some CSRF checks and validating cookies. It's really hard for me to justify building a separate package just for this.

I am very torn on this so I'd love to hear your thoughts.

// src/middleware.ts
import { lucia } from "./auth";
import { verifyRequestOrigin } from "oslo/request";
import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware(async (context, next) => {
	if (context.request.method !== "GET") {
		const originHeader = request.headers.get("Origin");
		const hostHeader = request.headers.get("Header");
		if (!originHeader || !hostHeader || !verifyRequestOrigin(originHeader, [hostHeader])) {
			return new Response(null, {
				status: 403
			});
		}
	}

	const sessionId = context.cookies.get(lucia.sessionCookieName)?.value ?? null;
	if (!sessionId) {
		context.locals.user = null;
		return next();
	}
	const { session, user } = await lucia.validateSession(sessionId);
	if (session && session.fresh) {
		const sessionCookie = lucia.createSessionCookie(session.id);
		context.cookies.set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
	}
	if (!session) {
		const sessionCookie = lucia.createBlankSessionCookie();
		context.cookies.set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
	}
	context.locals.user = user;
	return next();
});

Examples

SvelteKit

import { lucia } from "$lib/server/auth";
import type { Handle } from "@sveltejs/kit";

export const handle: Handle = async ({ event, resolve }) => {
	const sessionId = event.cookies.get(lucia.sessionCookieName);
	if (!sessionId) {
		event.locals.user = null;
		return resolve(event);
	}
	const { session, user } = await lucia.validateSession(sessionId);
	if (session && session.fresh) {
		const sessionCookie = lucia.createSessionCookie(session.id);
		event.cookies.set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
	}
	if (!session) {
		const sessionCookie = lucia.createBlankSessionCookie();
		event.cookies.set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
	}
	event.locals.user = user;
	return resolve(event);
};

Nuxt

// server/middleware/auth.ts
import { verifyRequestOrigin } from "oslo/request";

import type { H3Event } from "h3";
import type { User } from "lucia";

export default defineEventHandler((event) => {
	if (context.request.method !== "GET") {
		const originHeader = getHeader(event, "Origin") ?? null;
		const hostHeader = getHeader(event, "Host") ?? null;
		if (!originHeader || !hostHeader || !verifyRequestOrigin(originHeader, [hostHeader])) {
			return event.node.res.writeHead(403).end();
		}
	}

	const sessionId = getCookie(event, lucia.sessionCookieName) ?? null;
	if (!sessionId) {
		event.context.user = null;
		return;
	}
	const { session, user } = await lucia.validateSession(sessionId);
	if (session && session.fresh) {
		appendResponseHeader(event, "Set-Cookie", lucia.createSessionCookie(session.id).serialize());
	}
	if (!session) {
		appendResponseHeader(event, "Set-Cookie", lucia.createBlankSessionCookie().serialize());
	}
	event.context.user = user;
});

declare module "h3" {
	interface H3EventContext {
		user: User | null;
	}
}

Next.js Pages router

import { verifyRequestOrigin } from "oslo/request";

import type { NextApiRequest, NextApiResponse } from "next";

async function validateRequest(req: NextApiRequest, res: NextApiResponse): Promise<User | null> {
	if (req.method !== "GET") {
		const originHeader = request.headers.origin;
		const hostHeader = request.headers.host;
		if (!originHeader || !hostHeader || !verifyRequestOrigin(originHeader, [hostHeader])) {
			return null;
		}
	}

	const sessionId = req.cookies.get(lucia.sessionCookieName);
	if (!sessionId) {
		return null;
	}
	const { session, user } = await lucia.validateSession(sessionId);
	if (!session) {
		res.setHeader("Set-Cookie", lucia.createBlankSessionCookie().serialize());
	}
	if (session && session.fresh) {
		res.setHeader("Set-Cookie", lucia.createSessionCookie(session.id).serialize());
	}
	return user;
}

Next.js App Router

import { lucia } from "@/utils/auth";
import { cookies, headers } from "next/headers";

import type { User } from "lucia";

async function validateRequest(): Promise<User | null> {
	const sessionId = cookies().get(lucia.sessionCookieName);
	if (!sessionId) return null;
	const { session, user } = await lucia.validateSession(sessionId);
	if (session && session.fresh) {
		const sessionCookie = lucia.createSessionCookie(session.id);
		cookies().set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
	}
	if (!session) {
		const sessionCookie = lucia.createBlankSessionCookie();
		cookies().set(sessionCookie.name, sessionCookie.value, sessionCookie.attributes);
	}
	return user;
}

[ollema]

Say that one of frameworks has a breaking change that breaks existing Lucia API...

How would the users know that they need to update their Lucia code (which they copy pasted)? Normally, you would notice this when updating to a new major release of Lucia in the release notes. Should they regularly try to skim through the code in the docs (which they initially copy pasted) and compare with their actual code to see if there are any differences? This feels brittle!

To clarify, reducing the scope of Lucia to not cover request handling at all is one thing and that might be good (I don't think so) but that is a separate discussion. But personally, I think moving request handling APIs from semantically versioned code - to code that just lives as snippets that you should copy paste in the docs is not a good idea.

I would rather migrate to new major versions of Lucia (especially if the migration is easy, compare svelte 3 to svelte 4) more often than instead staying on the same major version of Lucia but having to deal with and keep track of breaking changes manually.

Also - releasing major versions often is not inherently a bad thing I think? How often have breaking changes in frameworks forced Lucia to update in the past? Is this a big problem?

[pilcrowonpaper]

I really doubt that the code snippet would become outdated in a way that TS won't catch it. It's just basic CSRF protection and session validation. It's not going to become insecure because of one update.

[ollema]

Relying on TypeScript to catch breaking changes also seems brittle according to me 🙂 Is Lucia aimed towards TypeScript users only?

[pilcrowonpaper]

I mean like runtimes errors like X is not a function etc that TS would tell you ahead of time. If you don't use TS or some other way to detect those kind of errors, that's not a Lucia problem

[ollema]

If we are relying on users detecting runtime errors to communicate breaking changes then why even bother with semver semantics in the first place?

I think for me this boils down to: if there is a breaking change in a framework that breaks lucia request handling for Lucia users - how should Lucia users be notified that they need to change their code?

1. Should they:

• see that a new (major? minor?) version of lucia (or maybe lucia-requests or lucia-middleware) is released on npm?
• update their version and more often than not they don't need to change anything since the change was covered in the release

2. Or should they:

• detect random X is not a function in their (production 😲) logs
• figure out that this was due to Lucia
• go to the Lucia docs (maybe they are using an older version as you pointed our earlier, the docs might be out of date) and try to cross-reference what they need to update?

The first option is superior DX according to me.

Anyways, this was my comment on your RFC, follow what you think will be best ofc

[pilcrowonpaper]

If Lucia changes how session works, regardless of the type declaration, that's a breaking change and a new major version

[shreyassanthu77]

We need a CLI similar to shadcn/ui

[StevenStavrakis]

The middlewares should be split into separate packages and maintained by Lucia.

Consider the following:

1. Since the code per framework is fairly small, it shouldn't be too difficult to maintain.
2. Would maintaining the per-framework middlewares be that much more work than maintaining their documentation? I'd suggest not.
3. Having to reference documentation makes it difficult to identify breaking changes. An out of date version is relatively easy to learn about, track, and fix.

If the issue being addressed is that any breaking changes will require a major version update, I think that breaking everything into packages that can be updated granularly is the way to go. AuthRequest hasn't caused me any DX headaches yet, and if the DX is good, then it should probably remain. I use Lucia because it makes auth easy.

[pilcrowonpaper]

I think that breaking everything into packages that can be updated granularly is the way to go

I really do not want to maintain a package that consists of just 20~50 lines of code.

[pilcrowonpaper]

In general, I don't think it's a big ask to users to learn what CSRF is and how you validate requests with Lucia

[StevenStavrakis]

I really do not want to maintain a package that consists of just 20~50 lines of code.

I felt that this was the case.

With all due respect, why are you asking us then? I'm not sure there is anything I can say that would make you want to do this.

In general, I don't think it's a big ask to users to learn what CSRF is and how you validate requests with Lucia

I would probably agree with you, but you have to wonder how many people won't. I do think that catering to frameworks individually, even in small ways, is key to staying relevant and gaining new users.

My added comment was to address this, being that it can remain maintained by community contributions. Furthermore, does that mean the documentation will be maintained? I legitimately do not know what kind of effort it takes to accomplish one over the other.

Do I think Lucia should provide a way to easily interact with a variety of frontend frameworks and reduce boilerplate?

Yes.

Do I know the best way to do this from a maintainer's perspective?

No.

[pilcrowonpaper]

With all due respect, why are you asking us then? I'm not sure there is anything I can say that would make you want to do this.

I want to make sure I didn't miss anything and I also want to check if there'll be significant push back. I don't mind copy pasting some boilerplate code from the docs, but since it's not just a tiny personal project, I try to at least get the community's perspective on it before committing to something

[StevenStavrakis]

I don't mind copying boilerplate from the docs either, its just that docs do not go through testing like packages do. I don't think it's a huge issue overall.

[proof-llc]

I would go with whatever you think is best. I wouldn't assume to be smarter than you. I think you spent a lot more time thinking about it, so I trust your judgement. I don't mind having to copy paste a few lines of code instead of importing from lib. I see the point. I desire to have as much flexibility as possible and so far in line with you with v3 approach.

[ollema]

noone here is claiming to be smarter than @pilcrowonpaper.

this is a RFC - request for comments.

the original post even included:

I am very torn on this so I'd love to hear your thoughts.

so not commenting due to fear of not being smarter than the original author is counterproductive I think

[pilcrowonpaper]

To be honest though, I'm personally fine with this change. What I am torn on is if the wider community will accept it. It's more than just a personal project now, so I'm trying to gather some feedback and thoughts before committing to a change

[proof-llc]

hey @ollema, my intent wasn't to attempt in suppressing speech in any way - just wanted to clarify. I think it's great that we are all voicing our opinions/convictions.

[pilcrowonpaper]

Yeah I'm going with this change. If people really don't like it, we can always create @lucia-auth/nextjs etc packages afterward without any breaking changes.

[gnllucena]

@pilcrowonpaper where exactly should I add the nextjs app route example?

Should I call this function on every server component / api route I use that is protected?

[pilcrowonpaper]

See this guide:
https://v3.lucia-auth.com/guides/validate-session-cookies/nextjs-app/