P-4 — Authentication with Auth.js (NextAuth v5)

One function, same interface everywhere. No passing config objects, no getServerSession(authOptions) calls.

---

Session Strategies: JWT vs Database

Auth.js supports two session storage strategies:

JWT (default): Session data is stored in an encrypted cookie. No database reads on every request — the session is decoded from the cookie. Fast, works at the edge, stateless.

Database sessions: Session data is stored in a database. The cookie contains only a session ID. Every auth() call queries the database. Supports instant session revocation (delete the row, user is logged out immediately). Requires an Auth.js database adapter.

// JWT strategy (default) — no additional config needed
 
// Database strategy
export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(db),  // from @auth/prisma-adapter
  session: { strategy: 'database' },
  providers: [...],
});

When to use JWT: Personal projects, most SaaS applications, applications where session invalidation latency is acceptable (the JWT expires naturally).

When to use database sessions: Applications with strict security requirements (banking, healthcare), when you need instant logout across all devices, when you need to store large amounts of session data that would exceed cookie size limits.

For most applications, JWT is the right choice.

---

Extending the Session Type

TypeScript will complain that session.user.role doesn't exist on the default Session type. Fix this by extending the Auth.js types:

// types/next-auth.d.ts
 
import { DefaultSession } from 'next-auth';
 
declare module 'next-auth' {
  interface Session {
    user: {
      id: string;
      role: string;
    } & DefaultSession['user'];
  }
}

This augments the Auth.js types globally so session.user.id and session.user.role are typed correctly throughout the application.

---

Middleware Route Protection — The Edge Layer

Middleware runs at the CDN edge before every request — before the page renders, before Server Components execute, before any Route Handlers run. This makes it the right place for session-based redirects: the check is cheap (JWT decryption, no database), happens as early as possible, and never renders a page that the user shouldn't see.

// middleware.ts (at the project root)
 
import { auth } from '@/auth';
import { NextResponse } from 'next/server';
 
export default auth((request) => {
  const { nextUrl, auth: session } = request;
  const isLoggedIn = !!session;
  const isAuthPage = nextUrl.pathname.startsWith('/auth');
  const isDashboard = nextUrl.pathname.startsWith('/dashboard');
  const isAdmin = nextUrl.pathname.startsWith('/admin');
 
  // Redirect unauthenticated users away from protected routes
  if (isDashboard && !isLoggedIn) {
    return NextResponse.redirect(new URL('/auth/login', nextUrl));
  }
 
  // Redirect authenticated users away from auth pages
  if (isAuthPage && isLoggedIn) {
    return NextResponse.redirect(new URL('/dashboard', nextUrl));
  }
 
  // Role-based access: admin routes require admin role
  if (isAdmin && session?.user?.role !== 'admin') {
    return NextResponse.redirect(new URL('/unauthorized', nextUrl));
  }
 
  return NextResponse.next();
});
 
export const config = {
  matcher: [
    '/((?!api/auth|_next/static|_next/image|favicon.ico).*)',
  ],
};

Auth.js v5 wraps your middleware function with session decoding — request.auth contains the session (or null) without you writing any JWT decryption code.

The matcher controls which routes trigger the middleware. The pattern above skips static files, images, and the auth API routes themselves (which must be accessible without a session). Always be specific with matchers — running auth middleware on every static file request wastes compute.

---

forbidden() and unauthorized() — Auth Interrupts (Next.js 15)

Next.js 15 introduced two new control-flow functions specifically for auth scenarios:

• unauthorized() — the user is not authenticated (401). Renders the nearest unauthorized.tsx.
• forbidden() — the user is authenticated but lacks permission (403). Renders the nearest forbidden.tsx.

// app/admin/page.tsx
 
import { auth } from '@/auth';
import { unauthorized, forbidden } from 'next/navigation';
 
export default async function AdminPage() {
  const session = await auth();
 
  if (!session) unauthorized();          // → renders app/unauthorized.tsx
  if (session.user.role !== 'admin') forbidden(); // → renders app/forbidden.tsx
 
  return <AdminDashboard />;
}

// app/unauthorized.tsx
 
import Link from 'next/link';
 
export default function UnauthorizedPage() {
  return (
    <div className="text-center py-24">
      <h1 className="text-2xl font-semibold mb-2">Sign in required</h1>
      <p className="text-zinc-400 mb-6">You need to be signed in to access this page.</p>
      <Link href="/auth/login" className="bg-white text-black px-4 py-2 rounded">
        Sign In
      </Link>
    </div>
  );
}

// app/forbidden.tsx
 
export default function ForbiddenPage() {
  return (
    <div className="text-center py-24">
      <h1 className="text-2xl font-semibold mb-2">Access Denied</h1>
      <p className="text-zinc-400">You don't have permission to access this page.</p>
    </div>
  );
}

Before unauthorized() and forbidden(), the pattern was redirect('/login') for both cases. The new functions are semantically correct (401 vs 403 status codes), and they render dedicated pages rather than redirecting — which means the user sees the right message rather than landing on a generic login page when they're already logged in but lack permission.

---

Sign-In and Sign-Out

Sign-in page:

// app/auth/login/page.tsx
 
import { signIn } from '@/auth';
 
export default function LoginPage() {
  return (
    <div className="max-w-sm mx-auto mt-24 space-y-4">
      {/* OAuth providers */}
      <form
        action={async () => {
          'use server';
          await signIn('github', { redirectTo: '/dashboard' });
        }}
      >
        <button type="submit" className="w-full bg-zinc-800 py-2 rounded">
          Sign in with GitHub
        </button>
      </form>
 
      {/* Credentials */}
      <form
        action={async (formData) => {
          'use server';
          await signIn('credentials', {
            email: formData.get('email'),
            password: formData.get('password'),
            redirectTo: '/dashboard',
          });
        }}
      >
        <input name="email" type="email" placeholder="Email" className="w-full border rounded px-3 py-2" />
        <input name="password" type="password" placeholder="Password" className="w-full border rounded px-3 py-2" />
        <button type="submit" className="w-full bg-white text-black py-2 rounded">
          Sign in
        </button>
      </form>
    </div>
  );
}

Sign-out:

// components/SignOutButton.tsx
 
import { signOut } from '@/auth';
 
export default function SignOutButton() {
  return (
    <form
      action={async () => {
        'use server';
        await signOut({ redirectTo: '/' });
      }}
    >
      <button type="submit">Sign out</button>
    </form>
  );
}

Both signIn and signOut are Server Actions — they handle the redirect internally. No router.push(), no manual cookie clearing.

---

RBAC — Role-Based Access Control

With role in the JWT (set up in the callbacks above), RBAC flows naturally:

// Middleware: protect entire routes by role
if (isAdmin && session?.user?.role !== 'admin') {
  return NextResponse.redirect(new URL('/forbidden', nextUrl));
}
 
// Server Component: conditional rendering based on role
const session = await auth();
if (session?.user?.role === 'admin') {
  return <AdminControls />;
}
 
// Server Action: verify role before executing
const session = await auth();
if (session?.user?.role !== 'editor' && session?.user?.role !== 'admin') {
  throw new Error('Forbidden');
}

For more sophisticated RBAC (hierarchical roles, permission sets, resource-level access), consider abstracting the checks:

// lib/permissions.ts
 
type Role = 'admin' | 'editor' | 'viewer';
type Resource = 'posts' | 'users' | 'settings';
type Action = 'create' | 'read' | 'update' | 'delete';
 
const permissions: Record<Role, Record<Resource, Action[]>> = {
  admin: {
    posts: ['create', 'read', 'update', 'delete'],
    users: ['create', 'read', 'update', 'delete'],
    settings: ['read', 'update'],
  },
  editor: {
    posts: ['create', 'read', 'update'],
    users: ['read'],
    settings: ['read'],
  },
  viewer: {
    posts: ['read'],
    users: [],
    settings: [],
  },
};
 
export function can(role: Role, resource: Resource, action: Action): boolean {
  return permissions[role]?.[resource]?.includes(action) ?? false;
}

// In a Server Action
const session = await auth();
const role = session?.user?.role as Role;
if (!can(role, 'posts', 'delete')) throw new Error('Forbidden');

---

Environment Variables

Auth.js requires specific environment variables:

# .env.local
 
# Required: secret for JWT/cookie encryption
AUTH_SECRET=your-random-secret-here  # openssl rand -base64 32
 
# OAuth providers (if used)
AUTH_GITHUB_ID=your-github-client-id
AUTH_GITHUB_SECRET=your-github-client-secret
 
# Auth.js v5 automatically uses AUTH_* prefix for providers
# No AUTH_URL needed in most deployments (auto-detected from request headers)

AUTH_SECRET is the only hard requirement. Generate it with openssl rand -base64 32 and never commit it. On Vercel and most deployment platforms, set it in the environment variables dashboard, not in .env files.

---

Where We Go From Here

P-5 covers database integration with Prisma — setting up the schema for the user/session tables Auth.js needs (if using database sessions), the critical connection pooling issue that kills serverless applications at scale, and the full mutation pattern that connects Prisma to Server Actions.

The auth patterns from this module are the prerequisite for everything in the Architect phase that involves user-specific data — personalised pages, user-scoped caching, tenant isolation in multi-zone architectures.

---