Lucia Auth v3: English for Session-Based Authentication

Lucia Auth v3 is a minimal, framework-agnostic authentication library for TypeScript. Unlike managed auth services, Lucia gives you full control over your session logic and database schema. Version 3 simplified the API significantly, removing the adapter abstraction in favour of a small set of functions you call directly. The vocabulary in this post will help ESL developers read authentication documentation, discuss security decisions in English, and implement robust session handling with confidence.

Sessions and Tokens

session — a server-side record that represents an authenticated user at a specific point in time; Lucia stores sessions in your database and links them to users by ID.

“After the user logs in successfully, we create a session in the database and send the session token to the browser as a cookie.”

session token — a random, unpredictable string that identifies a session; the client stores this token in a cookie and sends it with every request so the server can look up the corresponding session record.

“We generate a 40-character session token using Lucia’s generateSessionToken helper, which uses a cryptographically secure source of randomness.”

session expiry — the point in time after which a session is considered invalid; Lucia extends the expiry on each request if the session is near its deadline, keeping active users logged in.

“We set the session expiry to 30 days and enabled rolling expiration so users who visit the site regularly are never unexpectedly logged out.”

Core API Functions

createSession — the Lucia function that inserts a new session record into the database and returns the session object, typically called right after verifying the user’s password or OAuth token.

“We call createSession immediately after confirming the password hash matches, passing the user’s ID so the session is linked to the correct account.”

validateSessionToken — the Lucia function that looks up a session token in the database, checks whether it has expired, and returns the associated session and user if valid.

“Every API route calls validateSessionToken at the start of the request handler to confirm the caller is authenticated before processing any business logic.”

invalidateSession — the Lucia function that deletes a session record from the database, effectively logging the user out; it is called on logout or when a security event requires terminating all sessions.

“On the account settings page, a Revoke all sessions button calls invalidateSession for every session belonging to the current user.”

Database and Adapters

database adapter — in Lucia v3, a thin set of SQL queries (or ORM calls) you write yourself to read and write session and user records; Lucia v3 removed the built-in adapter interface and instead provides database schema guidance.

“We wrote our database adapter using Drizzle ORM so Lucia’s session functions call our existing database layer rather than making raw SQL calls.”

user model — the table or collection in your database that stores user identity information such as email, hashed password, and account status; Lucia requires you to define this yourself and link sessions to it.

“We extended the user model to include an emailVerified boolean column that our middleware checks before granting access to protected routes.”

Cookies and Security

cookies — the HTTP mechanism used to persist the session token in the user’s browser; Lucia provides helpers to set the correct cookie attributes for security.

“We use Lucia’s cookie helper to set the session cookie with HttpOnly and Secure attributes so client-side JavaScript cannot read or tamper with it.”

HttpOnly flag — a cookie attribute that prevents JavaScript running in the browser from reading the cookie’s value, protecting the session token from cross-site scripting attacks.

“Setting the HttpOnly flag on the session cookie means that even if an XSS vulnerability exists, an attacker’s script cannot steal the token.”

CSRF protection — measures that prevent malicious third-party websites from submitting requests on behalf of an authenticated user; for session-cookie-based auth, checking the Origin or Referer header is a common approach.

“We added CSRF protection to all state-changing API routes by verifying that the request origin matches our application’s domain before processing the session.”

Practice

Implement a minimal login flow using Lucia v3: call createSession after validating a password, set the session token as an HttpOnly cookie, and call validateSessionToken on a protected route. In English, explain to a colleague what happens if you forget the HttpOnly flag and why that is a security risk.