Authentication & Authorization

openssl rand -base64 32      # a 32-byte random secret; paste it into .env.local
# .env.local (never committed)
# SESSION_SECRET=<the generated value>

import * as z from "zod";

export type Role = "admin" | "user";

export type SessionPayload = {
  userId: string;
  role: Role; // a hint for optimistic checks only
  expiresAt: Date;
};

export const LoginSchema = z.object({
  email: z.email({ error: "Please enter a valid email." }).trim(),
  password: z.string().min(1, { error: "Password is required." }),
});

export type FormState =
  | { errors?: { email?: string[]; password?: string[] }; message?: string }
  | undefined;

import "server-only";
import { SignJWT, jwtVerify } from "jose";
import { cookies } from "next/headers";
import type { SessionPayload } from "@/lib/definitions";

const encodedKey = new TextEncoder().encode(process.env.SESSION_SECRET);
export const COOKIE_NAME = "session";

export async function encrypt(payload: SessionPayload) {
  return new SignJWT({ ...payload })
    .setProtectedHeader({ alg: "HS256" })
    .setIssuedAt()
    .setExpirationTime("7d")
    .sign(encodedKey);
}

export async function decrypt(session: string | undefined = "") {
  try {
    const { payload } = await jwtVerify(session, encodedKey, { algorithms: ["HS256"] });
    return payload as unknown as SessionPayload;
  } catch {
    return undefined; // tampered, expired or missing: never throw to the user
  }
}

export async function createSession(userId: string, role: SessionPayload["role"]) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
  const session = await encrypt({ userId, role, expiresAt });
  const cookieStore = await cookies();
  cookieStore.set(COOKIE_NAME, session, {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    expires: expiresAt,
    sameSite: "lax",
    path: "/",
  });
}

export async function deleteSession() {
  (await cookies()).delete(COOKIE_NAME);
}

"use server";

import * as z from "zod";
import { redirect } from "next/navigation";
import { LoginSchema, type FormState } from "@/lib/definitions";
import { createSession, deleteSession } from "@/lib/session";
import { findUserByEmail, verifyPassword } from "@/lib/users";

export async function login(state: FormState, formData: FormData): Promise<FormState> {
  const parsed = LoginSchema.safeParse({
    email: formData.get("email"),
    password: formData.get("password"),
  });
  if (!parsed.success) {
    return { errors: z.flattenError(parsed.error).fieldErrors };
  }

  const user = await findUserByEmail(parsed.data.email);
  // Same message for "no such user" and "wrong password"
  if (!user || !verifyPassword(parsed.data.password, user.passwordHash)) {
    return { message: "Invalid email or password." };
  }

  await createSession(user.id, user.role);
  redirect("/dashboard");
}

export async function logout() {
  await deleteSession();
  redirect("/login");
}

"use client";

import { useActionState } from "react";
import { login } from "@/app/actions/auth";

export function LoginForm() {
  const [state, action, pending] = useActionState(login, undefined);
  return (
    <form action={action}>
      <label htmlFor="email">Email</label>
      <input id="email" name="email" type="email" autoComplete="username" />
      {state?.errors?.email && <p>{state.errors.email}</p>}

      <label htmlFor="password">Password</label>
      <input id="password" name="password" type="password" autoComplete="current-password" />
      {state?.errors?.password && <p>{state.errors.password}</p>}

      {state?.message && <p role="alert">{state.message}</p>}
      <button disabled={pending} type="submit">Log in</button>
    </form>
  );
}

import "server-only";
import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
import type { Role } from "@/lib/definitions";

export type UserRow = {
  id: string;
  name: string;
  email: string;
  role: Role;
  passwordHash: string;
};

function hashPassword(password: string): string {
  const salt = randomBytes(16);
  return `${salt.toString("hex")}:${scryptSync(password, salt, 32).toString("hex")}`;
}

export function verifyPassword(password: string, stored: string): boolean {
  const [salt, hash] = stored.split(":");
  const candidate = scryptSync(password, Buffer.from(salt, "hex"), 32);
  return timingSafeEqual(candidate, Buffer.from(hash, "hex"));
}

// Stands in for a database table. Seeded from an env var, never a literal.
const seed = process.env.SEED_PASSWORD ?? "";
const table: UserRow[] = [
  { id: "u1", name: "Ada", email: "ada@example.com", role: "admin", passwordHash: hashPassword(seed) },
  { id: "u2", name: "Bob", email: "bob@example.com", role: "user", passwordHash: hashPassword(seed) },
];

export async function findUserByEmail(email: string) {
  return table.find((u) => u.email === email);
}
export async function findUserById(id: string) {
  return table.find((u) => u.id === id);
}
export async function demoteToUser(id: string) {
  const u = table.find((x) => x.id === id);
  if (u) u.role = "user";
}

import "server-only";
import { randomUUID } from "node:crypto";
import { cookies } from "next/headers";
import { SignJWT, jwtVerify } from "jose";

const key = new TextEncoder().encode(process.env.SESSION_SECRET);
const COOKIE = "sid";

type SessionRow = { id: string; userId: string; expiresAt: number };
const sessions = new Map<string, SessionRow>(); // stands in for a "sessions" table

export async function createDbSession(userId: string) {
  const expiresAt = Date.now() + 7 * 24 * 60 * 60 * 1000;
  const row: SessionRow = { id: randomUUID(), userId, expiresAt };
  sessions.set(row.id, row); // 1. persist the session

  const sealed = await new SignJWT({ sid: row.id }) // 2. the cookie only carries the id
    .setProtectedHeader({ alg: "HS256" })
    .setExpirationTime("7d")
    .sign(key);
  (await cookies()).set(COOKIE, sealed, {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    expires: expiresAt,
    path: "/",
  });
}

export async function readDbSession() {
  const sealed = (await cookies()).get(COOKIE)?.value;
  if (!sealed) return null;
  try {
    const { payload } = await jwtVerify(sealed, key, { algorithms: ["HS256"] });
    const row = sessions.get(String(payload.sid));
    if (!row || row.expiresAt < Date.now()) return null; // revoked or expired
    return row;
  } catch {
    return null;
  }
}

// "Sign out everywhere": impossible with a pure stateless cookie.
export function revokeAllSessions(userId: string) {
  for (const [id, row] of sessions) if (row.userId === userId) sessions.delete(id);
}

import { getUser } from "@/lib/dal";
import { logout } from "@/app/actions/auth";

export default async function DashboardPage() {
  const user = await getUser(); // verifySession() runs inside
  return (
    <main>
      <h1>Welcome, {user?.name}</h1>
      <p>Role: {user?.role}</p>
      <form action={logout}>
        <button type="submit">Log out</button>
      </form>
    </main>
  );
}

import type { ReactNode } from "react";
import { verifySession } from "@/lib/dal";

// Anti-pattern: the only check lives in the layout.
export default async function MembersLayout({ children }: { children: ReactNode }) {
  await verifySession();
  return <section>{children}</section>;
}

import Link from "next/link";
import { deleteNoteSafe, deleteNoteUnsafe } from "./actions";

// Anti-pattern: no check here, the page trusts its layout.
export default async function MemberPage({ params }: PageProps<"/members/[slug]">) {
  const { slug } = await params;
  return (
    <>
      <p>Members-only content for {slug}</p>
      <Link href={slug === "a" ? "/members/b" : "/members/a"} prefetch={false}>Next member</Link>
      <form action={deleteNoteUnsafe}><button>Delete (unsafe)</button></form>
      <form action={deleteNoteSafe}><button>Delete (safe)</button></form>
    </>
  );
}

"use server";

import { verifySession } from "@/lib/dal";

// Anti-pattern: reachable by POST even though the layout above redirects.
export async function deleteNoteUnsafe() {
  console.log("deleteNoteUnsafe executed");
}

// Fixed: the action authorises itself.
export async function deleteNoteSafe() {
  const session = await verifySession();
  console.log(`deleteNoteSafe executed for ${session.userId}`);
}

import { cookies } from "next/headers";
import { COOKIE_NAME, decrypt } from "@/lib/session";
import { findUserById } from "@/lib/users";

export async function GET() {
  const session = await decrypt((await cookies()).get(COOKIE_NAME)?.value);
  const user = session && (await findUserById(session.userId));
  if (!user) {
    return Response.json({ error: "Not authenticated" }, { status: 401 });
  }
  if (user.role !== "admin") {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  }
  return Response.json({ report: "admin-only data" });
}

npm install next-auth@beta
npx auth secret        # writes AUTH_SECRET to .env.local

import NextAuth, { type DefaultSession } from "next-auth";
import GitHub from "next-auth/providers/github";
import Credentials from "next-auth/providers/credentials";
import "next-auth/jwt"; // makes the declare module below an augmentation
import { findUserByEmail, verifyPassword, type Role } from "@/lib/users";

declare module "next-auth" {
  interface Session {
    user: { id: string; role: Role } & DefaultSession["user"];
  }
  interface User {
    role?: Role;
  }
}
declare module "next-auth/jwt" {
  interface JWT {
    uid?: string;
    role?: Role;
  }
}

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    // Reads AUTH_GITHUB_ID and AUTH_GITHUB_SECRET from the environment
    GitHub,
    Credentials({
      credentials: { email: {}, password: {} },
      authorize: async (credentials) => {
        const user = await findUserByEmail(String(credentials?.email ?? ""));
        if (!user || !verifyPassword(String(credentials?.password ?? ""), user.passwordHash)) {
          return null; // Auth.js turns this into a CredentialsSignin error
        }
        return { id: user.id, name: user.name, email: user.email, role: user.role };
      },
    }),
  ],
  session: { strategy: "jwt", maxAge: 60 * 60 * 24 * 7 },
  pages: { signIn: "/login" },
  callbacks: {
    // Runs in Proxy when auth is exported as proxy: an optimistic check
    authorized({ auth, request: { nextUrl } }) {
      const protectedPath = ["/dashboard", "/admin"].some((p) => nextUrl.pathname.startsWith(p));
      return protectedPath ? !!auth?.user : true;
    },
    jwt({ token, user }) {
      if (user) {
        token.uid = user.id;
        token.role = user.role ?? "user";
      }
      return token;
    },
    session({ session, token }) {
      session.user.id = token.uid ?? "";
      session.user.role = token.role ?? "user";
      return session;
    },
  },
});

import { handlers } from "@/auth";
export const { GET, POST } = handlers;

export { auth as proxy } from "@/auth";

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|.*\\.png$).*)"],
};

import { signIn } from "@/auth";

export default function LoginPage() {
  return (
    <main>
      <h1>Log in</h1>
      <form
        action={async () => {
          "use server";
          await signIn("github", { redirectTo: "/dashboard" });
        }}
      >
        <button type="submit">Continue with GitHub</button>
      </form>
      <form
        action={async (formData: FormData) => {
          "use server";
          await signIn("credentials", formData, { redirectTo: "/dashboard" });
        }}
      >
        <input name="email" type="email" autoComplete="username" />
        <input name="password" type="password" autoComplete="current-password" />
        <button type="submit">Log in</button>
      </form>
    </main>
  );
}

import { redirect } from "next/navigation";
import { auth, signOut } from "@/auth";

export default async function DashboardPage() {
  const session = await auth();
  if (!session?.user) redirect("/login"); // authoritative check, next to the data
  return (
    <main>
      <h1>Welcome, {session.user.name}</h1>
      <p>Role: {session.user.role}</p>
      <form
        action={async () => {
          "use server";
          await signOut({ redirectTo: "/login" });
        }}
      >
        <button type="submit">Log out</button>
      </form>
    </main>
  );
}

import { NextResponse } from "next/server";
import { auth } from "@/auth";

export const GET = auth(function GET(req) {
  if (!req.auth?.user) {
    return NextResponse.json({ message: "Not authenticated" }, { status: 401 });
  }
  const { id, name, role } = req.auth.user;
  return NextResponse.json({ id, name, role });
});

import type { GetServerSideProps, InferGetServerSidePropsType } from "next";
import { auth } from "@/auth";

export const getServerSideProps = (async (ctx) => {
  const session = await auth(ctx);
  if (!session?.user) {
    return { redirect: { destination: "/login", permanent: false } };
  }
  return { props: { name: session.user.name ?? "" } };
}) satisfies GetServerSideProps<{ name: string }>;

export default function LegacyDashboard({
  name,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  return <h1>Welcome (Pages Router), {name}</h1>;
}

import { Auth0Client } from "@auth0/nextjs-auth0/server";

// Reads AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_SECRET
// and APP_BASE_URL from the environment.
export const auth0 = new Auth0Client();

import { auth0 } from "@/lib/auth0";

export async function proxy(request: Request) {
  // Mounts /auth/login, /auth/logout, /auth/callback and /auth/profile
  // and keeps the rolling session alive.
  return await auth0.middleware(request);
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)"],
};

import { auth0 } from "@/lib/auth0";

export default async function DashboardPage() {
  const session = await auth0.getSession();
  if (!session) {
    return (
      <main>
        <a href="/auth/login">Log in</a>
      </main>
    );
  }
  return (
    <main>
      <h1>Welcome, {session.user.name}</h1>
      <a href="/auth/logout">Log out</a>
    </main>
  );
}

import { clerkMiddleware } from "@clerk/nextjs/server";

// Public by default: clerkMiddleware() protects nothing on its own.
export default clerkMiddleware();

export const config = {
  matcher: [
    // Skip Next.js internals and static files
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
    // Always run for API routes
    "/(api|trpc)(.*)",
  ],
};

import { auth, currentUser } from "@clerk/nextjs/server";

export default async function DashboardPage() {
  // Redirects to sign-in when signed out (document requests)
  await auth.protect();
  const user = await currentUser();
  return <h1>Welcome, {user?.firstName}</h1>;
}

import { auth } from "@clerk/nextjs/server";

export async function GET() {
  const { isAuthenticated, userId } = await auth();
  if (!isAuthenticated) {
    return new Response(null, { status: 401 });
  }
  return Response.json({ userId });
}

import type { ReactNode } from "react";
import { ClerkProvider, Show, SignInButton, SignUpButton, UserButton } from "@clerk/nextjs";

export function Shell({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClerkProvider>
          <header>
            <Show when="signed-out">
              <SignInButton />
              <SignUpButton />
            </Show>
            <Show when="signed-in">
              <UserButton />
            </Show>
          </header>
          {children}
        </ClerkProvider>
      </body>
    </html>
  );
}

npm install better-auth
# .env.local (never committed): BETTER_AUTH_SECRET (generate with: openssl rand -base64 32),
# BETTER_AUTH_URL, and the GitHub credentials named in lib/auth.ts
npx auth@latest migrate        # creates the user, session, account and verification tables

import { betterAuth } from "better-auth";
import { nextCookies } from "better-auth/next-js";
import Database from "better-sqlite3";

export const auth = betterAuth({
  database: new Database("./sqlite.db"),
  emailAndPassword: { enabled: true },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID as string,
      clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
    },
  },
  plugins: [nextCookies()], // keep this the last plugin
});

import { toNextJsHandler } from "better-auth/next-js";
import { auth } from "@/lib/auth";

export const { GET, POST } = toNextJsHandler(auth);

import { NextResponse, type NextRequest } from "next/server";
import { getSessionCookie } from "better-auth/cookies";

export async function proxy(request: NextRequest) {
  // Optimistic only: checks the cookie exists, not that it is valid
  const sessionCookie = getSessionCookie(request);
  if (!sessionCookie) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
  return NextResponse.next();
}

export const config = { matcher: ["/dashboard"] };

import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { auth } from "@/lib/auth";

export default async function DashboardPage() {
  // Authoritative: validates the session against the database
  const session = await auth.api.getSession({ headers: await headers() });
  if (!session) redirect("/login");
  return <h1>Welcome, {session.user.name}</h1>;
}

import "server-only";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
import { COOKIE_NAME, decrypt } from "@/lib/session";
import { findUserById } from "@/lib/users";

export type CurrentUser = { id: string; name: string; role: "admin" | "user" };

// Reads cookies(), so it must be "use cache: private": the result may be
// kept in the browser's cache, never on the server.
export async function getCurrentUser(): Promise<CurrentUser> {
  "use cache: private";
  const session = await decrypt((await cookies()).get(COOKIE_NAME)?.value);
  if (!session?.userId) redirect("/login");
  const user = await findUserById(session.userId);
  if (!user) redirect("/login");
  return { id: user.id, name: user.name, role: user.role };
}

import { Suspense } from "react";
import { getCurrentUser } from "@/lib/auth";
import { getNotes } from "@/lib/notes";
import { addNote } from "@/app/actions/notes";

export default function DashboardPage() {
  return (
    <main>
      {/* Static: prerendered into the shell */}
      <h1>Bookshelf dashboard</h1>
      <Suspense fallback={<p>Loading your dashboard...</p>}>
        <Greeting />
        <Notes />
      </Suspense>
    </main>
  );
}

async function Greeting() {
  const user = await getCurrentUser();
  return <p>Welcome, {user.name}</p>;
}

async function Notes() {
  const notes = await getNotes();
  return (
    <>
      <ul>
        {notes.map((n) => (
          <li key={n}>{n}</li>
        ))}
      </ul>
      <form action={addNote}>
        <input name="note" />
        <button type="submit">Add note</button>
      </form>
    </>
  );
}

import { Suspense } from "react";
import { forbidden } from "next/navigation";
import { verifySession } from "@/lib/dal";

export default function AdminPage() {
  return (
    <main>
      <h1>Admin</h1>
      <Suspense fallback={<p>Checking access...</p>}>
        <AdminPanel />
      </Suspense>
    </main>
  );
}

async function AdminPanel() {
  const session = await verifySession();
  if (session.role !== "admin") forbidden();
  return <p>Admin-only panel</p>;
}

import "server-only";
import { cacheLife, cacheTag } from "next/cache";
import { getCurrentUser } from "@/lib/auth";

const notes = new Map<string, string[]>();
export let reads = 0; // counts real "database" reads (scratch only)

export async function saveNote(userId: string, note: string) {
  notes.set(userId, [...(notes.get(userId) ?? []), note]);
}

// Exported: resolves the user first, so a caller cannot pick another id.
export async function getNotes() {
  const user = await getCurrentUser();
  return getNotesByUserId(user.id);
}

// Not exported on purpose. The user id becomes part of the cache key.
async function getNotesByUserId(userId: string) {
  "use cache";
  cacheTag(`notes:${userId}`);
  cacheLife("minutes");
  reads++;
  console.log(`db read for ${userId} (#${reads})`);
  return notes.get(userId) ?? [];
}

"use server";

import { updateTag } from "next/cache";
import { redirect } from "next/navigation";
import { COOKIE_NAME, decrypt } from "@/lib/session";
import { cookies } from "next/headers";
import { saveNote } from "@/lib/notes";

export async function addNote(formData: FormData) {
  // Re-read the session: the action authorises itself.
  const session = await decrypt((await cookies()).get(COOKIE_NAME)?.value);
  if (!session?.userId) redirect("/login");

  const note = String(formData.get("note") ?? "").trim();
  if (note) {
    await saveNote(session.userId, note);
    updateTag(`notes:${session.userId}`);
  }
}