Auth Libraries skill for Codex

Done well means: the choice matches the product’s real needs (B2B orgs, SSO, compliance, budget, data residency), authorization is checked on the server at every data access, not only in middleware, and the setup is reproducible from env vars and migrations.

Choose

Ask the user, or infer from the repo: framework, database, B2C or B2B, need for SAML/SCIM, MFA, passkeys, user count and budget, and whether user data may live with a third party.

Need	Default	Why
TypeScript app, own database, full control	Better Auth	Self-hosted, DB-backed sessions, plugins for orgs, 2FA, passkeys, admin
Existing Next.js app already on NextAuth/Auth.js	Stay on Auth.js v5, plan a move later	Maintained for security fixes; the maintainers recommend Better Auth for new projects
Fastest path to polished UI, MFA, orgs, low ops	Hosted: Clerk	Prebuilt components, user management, per-MAU pricing
B2B with enterprise SSO (SAML) and SCIM	Hosted: WorkOS, Auth0, or Clerk’s enterprise features	SAML and directory sync are expensive to build
Django	django-allauth	Mature, social and MFA built in
Rails 8	bin/rails generate authentication, add OmniAuth for social	Session-based, code lives in your app
Laravel	Starter kit (Fortify-based) + Socialite; Sanctum for API tokens	First-party
Spring Boot	Spring Security with oauth2Login()	Native

Lucia is no longer maintained as a library (it became a learning resource in 2025). Treat it as a migration source, not a choice. Hand-rolled auth is justified only when no option fits; then follow session-auth, password-storage and oauth2-oidc closely.

Before changing anything

1. Read AGENTS.md for package manager, framework version and test commands.
2. rg -n "next-auth|@auth/|better-auth|@clerk|lucia|passport|devise|allauth" package.json */package.json pyproject.toml Gemfile
3. Check the Next.js major: Next.js 16 renamed middleware.ts to proxy.ts. Use whichever the project’s version expects.
4. Installing packages needs network; in a sandbox without it, ask for approval.

Better Auth (Next.js App Router)

// lib/auth.ts
import { betterAuth } from "better-auth";
import { Pool } from "pg";

export const auth = betterAuth({
  database: new Pool({ connectionString: process.env.DATABASE_URL }),
  emailAndPassword: { enabled: true, requireEmailVerification: true },
  socialProviders: {
    github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET! },
  },
  // plugins: [organization(), twoFactor(), passkey()]  -- add only what the product needs
});

// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";
export const { GET, POST } = toNextJsHandler(auth);

// lib/auth-client.ts
import { createAuthClient } from "better-auth/react";
export const authClient = createAuthClient();

// Server component or route handler: the real authorization point
import { headers } from "next/headers";
const session = await auth.api.getSession({ headers: await headers() });
if (!session) redirect("/sign-in");

Env: BETTER_AUTH_SECRET (32+ random bytes) and BETTER_AUTH_URL. Generate or apply the schema with the Better Auth CLI (npx @better-auth/cli generate for ORM schema files, migrate for the built-in Kysely adapter), and commit the resulting migration. With Drizzle or Prisma, use their adapters and the project’s normal migration flow.

Auth.js v5 (existing projects)

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import { PrismaAdapter } from "@auth/prisma-adapter";
import { prisma } from "@/lib/prisma";

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [GitHub],               // reads AUTH_GITHUB_ID / AUTH_GITHUB_SECRET
  session: { strategy: "database" },
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

Requires AUTH_SECRET. The default session strategy without an adapter is an encrypted JWT cookie; it cannot be revoked server-side. Use strategy: "database" when revocation matters.

Clerk (hosted)

// middleware.ts (proxy.ts on Next.js 16)
import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";
const isProtected = createRouteMatcher(["/dashboard(.*)", "/api/private(.*)"]);
export default clerkMiddleware(async (auth, req) => { if (isProtected(req)) await auth.protect(); });
export const config = { matcher: ["/((?!_next|.*\\..*).*)", "/(api|trpc)(.*)"] };

import { auth } from "@clerk/nextjs/server";
const { userId, orgId } = await auth();

Wrap the root layout in <ClerkProvider>. Keys: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY. Mirror users into your database through Clerk webhooks (verify the signature; see webhook-receivers) and key rows by Clerk user ID. For deeper Clerk work, use clerk-auth.

Authorization: the part libraries do not do for you

• Middleware/proxy is a coarse gate for redirects. Re-check the session in every server action, route handler and data-access function; matchers miss routes and Next.js has had middleware bypass CVEs.
• Put ownership and role checks next to the query: where: { id, orgId: session.orgId }.
• Never trust a user ID or org ID sent from the client.

Migrating between libraries

1. Inventory: user table shape, password hash algorithm, linked OAuth accounts, sessions.
2. Map users and accounts into the new schema keeping provider (provider, providerAccountId) pairs, so social logins keep matching.
3. Passwords: if the new library cannot verify the old hash format, verify with the old algorithm on next login and rehash (password-storage). Never ask users to reset en masse unless the old hashes were weak.
4. Sessions: accept a forced re-login unless the user insists; dual-reading two session formats is rarely worth it.
5. Rehearse on a copy of production data. Running the migration against production needs explicit user confirmation and a backup.

Workflow checklist

• Gather requirements and choose with the table; state the trade-off to the user
• Install, set env vars (document them in .env.example, never commit real secrets)
• Generate and review the schema migration
• Wire route handler, client, and server-side session helper
• Protect routes coarsely, then add server-side checks at each data access
• Register OAuth redirect URIs per environment (oauth2-oidc for provider details)
• Test sign-up, sign-in, sign-out, a protected API call without a session, and a cross-org access attempt

Verification

• curl -si https://localhost:3000/api/private without a cookie returns 401 or a redirect.
• A logged-in user from org A requesting org B’s resource ID gets 404 or 403.
• Session cookie flags: HttpOnly, Secure in production, SameSite=Lax.
• Signing out invalidates the session server-side (database strategy) rather than only deleting the cookie.

Gotchas

• AUTH_SECRET or BETTER_AUTH_SECRET differing between instances logs users out randomly.
• OAuth callbacks fail behind proxies when the base URL env var is missing or wrong.
• Account linking by email across providers without verified email enables takeover.
• Edge runtimes cannot use some database drivers; keep session lookups in Node runtime routes or use an edge-compatible driver.
• Hosted providers rate-limit their backend APIs; do not call them on every request when a verified session token already carries the user ID.