Imported from terminalskills/skills (skills/lucia-auth/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill lucia-auth. Copyright stays with the author (Apache-2.0).

Lucia Auth — Simple Authentication

You are an expert in Lucia, the lightweight authentication library for TypeScript. You help developers implement session-based authentication with email/password, OAuth (Google, GitHub, Discord), magic links, and two-factor authentication — providing a simple, database-agnostic auth layer that you understand and control, without the complexity of full auth platforms.

Core Capabilities

Session Management

// lib/auth.ts
import { Lucia } from "lucia";
import { DrizzlePostgreSQLAdapter } from "@lucia-auth/adapter-drizzle";
import { db } from "./db";
import { users, sessions } from "./db/schema";

const adapter = new DrizzlePostgreSQLAdapter(db, sessions, users);

export const lucia = new Lucia(adapter, {
  sessionCookie: {
    expires: false,                        // Session cookie (cleared on browser close)
    attributes: { secure: process.env.NODE_ENV === "production" },
  },
  getUserAttributes: (attributes) => ({
    email: attributes.email,
    name: attributes.name,
    avatarUrl: attributes.avatar_url,
  }),
});

// Email/password signup
async function signup(email: string, password: string, name: string) {
  const hashedPassword = await new Argon2id().hash(password);
  const userId = generateIdFromEntropySize(10);

  await db.insert(users).values({
    id: userId,
    email,
    name,
    hashedPassword,
  });

  const session = await lucia.createSession(userId, {});
  const sessionCookie = lucia.createSessionCookie(session.id);
  return sessionCookie;                    // Set as response cookie
}

// Login
async function login(email: string, password: string) {
  const user = await db.query.users.findFirst({ where: eq(users.email, email) });
  if (!user) throw new Error("Invalid credentials");

  const valid = await new Argon2id().verify(user.hashedPassword, password);
  if (!valid) throw new Error("Invalid credentials");

  const session = await lucia.createSession(user.id, {});
  return lucia.createSessionCookie(session.id);
}

// Validate session (middleware)
async function validateRequest(request: Request) {
  const cookieHeader = request.headers.get("Cookie");
  const sessionId = lucia.readSessionCookie(cookieHeader ?? "");
  if (!sessionId) return { user: null, session: null };

  const result = await lucia.validateSession(sessionId);
  return result;                           // { user, session } or { user: null, session: null }
}

// Logout
async function logout(sessionId: string) {
  await lucia.invalidateSession(sessionId);
  return lucia.createBlankSessionCookie();
}

OAuth (Google)

import { Google } from "arctic";

const google = new Google(
  process.env.GOOGLE_CLIENT_ID!,
  process.env.GOOGLE_CLIENT_SECRET!,
  "https://myapp.com/auth/google/callback",
);

// Redirect to Google
app.get("/auth/google", async (c) => {
  const [url, codeVerifier, state] = await google.createAuthorizationURL();
  // Store codeVerifier and state in cookie
  return c.redirect(url.toString());
});

// Handle callback
app.get("/auth/google/callback", async (c) => {
  const { code, state } = c.req.query();
  const tokens = await google.validateAuthorizationCode(code, codeVerifier);
  const googleUser = await fetch("https://www.googleapis.com/oauth2/v3/userinfo", {
    headers: { Authorization: `Bearer ${tokens.accessToken()}` },
  }).then(r => r.json());

  // Find or create user
  let user = await db.query.users.findFirst({ where: eq(users.email, googleUser.email) });
  if (!user) {
    const userId = generateIdFromEntropySize(10);
    [user] = await db.insert(users).values({
      id: userId, email: googleUser.email, name: googleUser.name, avatar_url: googleUser.picture,
    }).returning();
  }

  const session = await lucia.createSession(user.id, {});
  const cookie = lucia.createSessionCookie(session.id);
  return c.redirect("/dashboard", { headers: { "Set-Cookie": cookie.serialize() } });
});

Installation

npm install lucia arctic                   # Lucia + OAuth helpers
npm install @lucia-auth/adapter-drizzle    # Or adapter-prisma, adapter-mongoose, etc.
npm install @node-rs/argon2                # Password hashing

Best Practices

1. Session-based — Lucia uses server-side sessions + cookies; more secure than JWT for web apps
2. Database-agnostic — Adapters for Drizzle, Prisma, Mongoose, better-sqlite3, Turso, etc.
3. Arctic for OAuth — Use arctic library for OAuth providers; handles PKCE, state, tokens
4. Argon2 for passwords — Use @node-rs/argon2 for hashing; industry standard, timing-safe
5. Cookie security — Set secure: true in production; httpOnly is automatic
6. Session validation — Call validateSession() on every request; auto-extends session expiry
7. Invalidation — invalidateSession for logout; invalidateUserSessions for security reset
8. No magic — Lucia is explicit; you write the signup/login/oauth flows; you understand every line