How do you enforce type safety for custom user fields in Auth.js using TypeScript?

Through Module Augmentation. In a types/next-auth.d.ts file, declare the 'next-auth' module and extend the Session and User interfaces, along with the JWT interface from 'next-auth/jwt', with custom fields like role or permissions. This eliminates risky manual type assertions (as UserRole) across the codebase.

Why is storing authentication session tokens in localStorage considered a critical vulnerability?

Any JavaScript executing within the browser origin (including compromised npm packages, analytics trackers, or XSS payloads) has unfettered read access to localStorage. In contrast, HttpOnly cookies cannot be accessed via document.cookie, neutralizing token exfiltration through XSS.

What are the engineering trade-offs between Stateless JWT and Stateful Database sessions in Next.js?

Stateless JWT sessions store signed or encrypted claims inside an HttpOnly cookie. They require zero database I/O, execute rapidly inside Edge Middleware, and scale seamlessly in serverless setups, but revoking an individual token prior to TTL expiration is complex. Stateful database sessions store an opaque session ID in the cookie and look up user state in Postgres/Redis on every request, providing instant revocation at the cost of database connection pool overhead and network latency.

What security guarantees do __Host- and __Secure- cookie prefixes enforce?

__Secure- enforces that the cookie is transmitted only over encrypted HTTPS connections. __Host- imposes even stricter guarantees: it requires HTTPS, forbids the Domain attribute (preventing subdomain inheritance and poisoning, such as from sub.domain.com), and mandates Path=/.

How does Next.js protect Server Actions against Cross-Site Request Forgery (CSRF)?

Next.js verifies the Origin and Host headers for all incoming POST action requests out of the box, rejecting mismatches to prevent cross-origin invocation. Combining this with HttpOnly cookies configured with SameSite=Lax or Strict provides robust protection against CSRF exploits.

Why does protecting routes in middleware.ts fail to secure Server Actions against unauthorized execution?

Middleware intercepts incoming requests based on requested URL paths (e.g., /admin). Server Actions operate as independent RPC endpoints triggered via HTTP POST requests carrying the Next-Action header. Any authenticated user or external script can submit POST requests directly to that action ID, bypassing route-level page middleware. Defense in Depth mandates that every Server Action independently validates user session and permissions.

Why must Auth.js v5 configurations be split into auth.config.ts and auth.ts?

Next.js Middleware runs in the Edge Runtime (V8 isolates), which does not support Node.js native modules (net, tls) or raw TCP sockets needed by database ORMs like Prisma. auth.config.ts contains Edge-safe configuration (providers, JWT callbacks) for Middleware, while auth.ts imports PrismaAdapter and password hashing modules to run inside the Node.js runtime for Route Handlers and Server Actions.

How does Refresh Token Rotation work and how do you prevent race condition failures?

When an access token expires, the client uses a single-use refresh token to acquire a fresh access/refresh token pair. If multiple concurrent requests trigger this exchange simultaneously, the provider may reject the second request as a replay attack. Mitigations include enabling a 15-30 second grace period on the OAuth provider or coordinating token renewal via a distributed mutex in Redis.

Authentication and Authorization Patterns in Next.js — Next.js 16 App Router

Why This Matters#

Authentication (verifying entity identity) and authorization (enforcing granular resource access) form the bedrock of corporate enterprise web security. In legacy client-side Single Page Application (SPA) architectures (such as React with Vite), session tokens were frequently stored in browser localStorage, and private route security was relegated to client-side lifecycle hooks within useEffect.

In the Next.js App Router architecture, this pattern is classified as a critical vulnerability. Because page rendering initiates on the server, client-side guards guarantee a data leak: the server will generate and transmit confidential server-rendered HTML across the public network first, only for the browser to execute client JavaScript and perform an unacceptably delayed redirect afterwards.

Modern architecture relies on a rigorous Defense in Depth strategy:

Session identifiers reside strictly inside encrypted HttpOnly Cookies equipped with security Cookie Prefixes (__Host-).
The initial perimeter filter is established at the Next.js Middleware tier inside the Edge Runtime Boundary.
The secondary perimeter is enforced inside Server Components (RSC) and layouts.
The tertiary, non-negotiable perimeter is the Server Action Authorization Guard, as data mutations in App Router are directly accessible public RPC endpoints.

Mental Model#

Application security is constructed as a multi-tiered defense perimeter:

text

Incoming Client HTTP Request
         │
         ▼
[Tier 1: Edge Middleware] ──────────────────────► Reject: HTTP 307 Redirect (/login)
(Rapid cryptographic JWT-cookie verification)
         │ Session valid
         ▼
[Tier 2: Server Layout / Page] ─────────────────► Reject: redirect('/unauthorized')
(Enforce role permissions: session.user.role)
         │ Render protected UI
         ▼
[Tier 3: Server Action Guard] ──────────────────► Reject: throw new Error('Forbidden')
(Isolated session verification inside mutation)
         │ Access granted
         ▼
Execute Database Mutation / Transaction

Comparison of Session Management Strategies in Next.js

Критерий	Stateless JWT Session	Stateful Database Session
Data Storage	Encrypted JWE token stored inside an HttpOnly cookie	Opaque Session ID in cookie; state stored in PostgreSQL or Redis
Validation Speed	Instant cryptographic signature check with zero database I/O	Requires a database query on every incoming HTTP request
Edge Middleware	100% compatible with lightweight Edge Runtime	Requires Node.js runtime or HTTP-based drivers (Neon/Supabase)
Scalability	Ideal for serverless architectures (no connection pooling issues)	Can exhaust database connection pools under intense traffic spikes
Revocation	Difficult to revoke an individual token before TTL expiration	Instant revocation of any session ('Log out from all devices')

OAuth 2.0 / OIDC Authentication Flow in Auth.js

1. Initiate Sign-inClient

The user submits credentials or clicks a third-party OAuth provider button.

2. Redirect to IdPSecurity

Auth.js generates PKCE challenges, state parameters, and redirects to the identity provider (Google/GitHub).

3. Callback & Code ExchangeServer

The provider redirects back to /api/auth/callback/[provider]. The server securely exchanges the auth code for tokens.

4. Generate JWE SessionSession

Auth.js bundles identity claims and user roles into an encrypted HttpOnly cookie with the __Secure- prefix.

5. Authorized AccessReady

The browser sends the cookie automatically on each request; Edge Middleware and RSC verify permissions.

CHECKPOINT

Knowledge Check: Auth.js v5 Architecture and Edge Runtime Isolation

+15 XP

A developer integrates authentication in Next.js 15 by creating a unified auth.ts file with PrismaAdapter and importing auth() into middleware.ts. During deployment to Vercel, the build fails with 'The edge runtime does not support Node.js net module'. What is the root cause and the correct architectural solution?

Syntax and API#

1. TypeScript Module Augmentation for Auth.js#

In strict TypeScript setups, manually casting session fields using as string introduces type degradation. Create a dedicated ambient type definition file:

typescripttypes/next-auth.d.ts (Strict Session Augmentation)

import { type DefaultSession } from 'next-auth';
import { type JWT } from 'next-auth/jwt';

export type UserRole = 'USER' | 'ADMIN' | 'EDITOR';

declare module 'next-auth' {
  interface Session {
    user: {
      id: string;
      role: UserRole;
    } & DefaultSession['user'];
  }

  interface User {
    role?: UserRole;
  }
}

declare module 'next-auth/jwt' {
  interface JWT {
    id?: string;
    role?: UserRole;
  }
}

2. Route Handlers Setup#

To service OAuth callback redirects and session verification endpoints, Auth.js provides dynamic HTTP handlers:

typescriptsrc/app/api/auth/[...nextauth]/route.ts (Dynamic Auth Route Handlers)

import { handlers } from '@/auth';

export const { GET, POST } = handlers;

Practical Patterns#

1. Route Protection via Edge Middleware#

Middleware filters out unauthorized requests before any server rendering begins, ensuring zero CPU and memory load on backend services:

typescriptsrc/middleware.ts (Edge Perimeter Guard)

import NextAuth from 'next-auth';
import { authConfig } from '@/auth.config';
import { NextResponse } from 'next/server';

const { auth } = NextAuth(authConfig);

export default auth((req) => {
  const { nextUrl } = req;
  const isLoggedIn = !!req.auth;
  const isDashboardRoute = nextUrl.pathname.startsWith('/dashboard');
  const isAuthRoute = nextUrl.pathname.startsWith('/login') || nextUrl.pathname.startsWith('/register');

  if (isAuthRoute && isLoggedIn) {
    return NextResponse.redirect(new URL('/dashboard', nextUrl));
  }

  if (isDashboardRoute && !isLoggedIn) {
    let callbackUrl = nextUrl.pathname;
    if (nextUrl.search) {
      callbackUrl += nextUrl.search;
    }
    const encodedCallbackUrl = encodeURIComponent(callbackUrl);

    return NextResponse.redirect(
      new URL(`/login?callbackUrl=${encodedCallbackUrl}`, nextUrl)
    );
  }

  return NextResponse.next();
});

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};

2. Role-Based Access Control (RBAC) in Server Components#

Inside Server Components, resolve the session asynchronously via direct invocation of auth():

tsxsrc/app/(dashboard)/admin/page.tsx (RBAC Server Component)

import { auth } from '@/auth';
import { redirect } from 'next/navigation';

export default async function AdminManagementPage() {
  const session = await auth();

  if (!session?.user) {
    redirect('/login?callbackUrl=/admin');
  }

  if (session.user.role !== 'ADMIN') {
    // Authenticated user lacks required elevated privileges
    redirect('/unauthorized');
  }

  return (
    <main className="p-8 max-w-6xl mx-auto">
      <h1 className="text-3xl font-bold tracking-tight text-text-primary mb-4">
        System Administration Console
      </h1>
      <p className="text-text-secondary">
        Welcome, {session.user.name} ({session.user.email}). Access authorized.
      </p>
    </main>
  );
}

3. Securing Server Actions: Mandatory Internal Guards#

Every Server Action functions as an independently reachable network RPC endpoint. Middleware alone does not guarantee security for direct action invocations:

typescriptsrc/features/users/server/actions.ts (Hardened Server Action Guard)

'use server';

import { auth } from '@/auth';
import { db } from '@/shared/lib/db';
import { revalidatePath } from 'next/cache';
import { z } from 'zod';

const DeleteUserSchema = z.object({
  userId: z.string().uuid(),
});

export type DeleteUserState =
  | { status: 'idle' }
  | { status: 'success'; message: string }
  | { status: 'error'; message: string };

export async function deleteUserAction(
  _prevState: DeleteUserState,
  formData: FormData
): Promise<DeleteUserState> {
  // 1. Mandatory identity verification of caller
  const session = await auth();

  if (!session?.user) {
    return { status: 'error', message: 'Authentication required. Please log in.' };
  }

  // 2. Strict Role-Based Access Control (RBAC)
  if (session.user.role !== 'ADMIN') {
    return { status: 'error', message: 'Access denied: Administrator privileges required.' };
  }

  // 3. Schema validation
  const parsed = DeleteUserSchema.safeParse({
    userId: formData.get('userId'),
  });

  if (!parsed.success) {
    return { status: 'error', message: 'Invalid target user identifier.' };
  }

  try {
    await db.user.delete({
      where: { id: parsed.data.userId },
    });

    revalidatePath('/admin/users');
    return { status: 'success', message: 'User record deleted successfully.' };
  } catch (err: unknown) {
    const errorMsg = err instanceof Error ? err.message : 'Database mutation error';
    console.error('[DeleteUserAction Failed]:', errorMsg);
    return { status: 'error', message: 'Failed to complete user deletion.' };
  }
}

4. Client Session Access in Interactive Components#

For client-side interactive widgets (such as responsive profile dropdowns and avatar controls), leverage SessionProvider and the useSession() hook:

tsxsrc/widgets/Navbar/ui/UserMenu.tsx (Client Session Consumer)

'use client';

import { useSession, signOut } from 'next-auth/react';

export function UserMenu() {
  const { data: session, status } = useSession();

  if (status === 'loading') {
    return <div className="h-9 w-9 rounded-full bg-bg-surface animate-pulse" />;
  }

  if (!session?.user) {
    return (
      <a href="/login" className="text-sm font-medium text-text-primary hover:text-accent-violet">
        Sign In
      </a>
    );
  }

  return (
    <div className="flex items-center gap-3">
      <span className="text-sm text-text-secondary">{session.user.name}</span>
      <button
        onClick={() => signOut({ callbackUrl: '/' })}
        className="px-3 py-1.5 text-xs font-medium rounded-lg bg-bg-surface border border-border hover:bg-bg-subtle transition-colors"
      >
        Sign Out
      </button>
    </div>
  );
}

CHECKPOINT

Knowledge Check: Defense in Depth and Server Action Vulnerabilities

+15 XP

A developer builds a protected route at /admin/users with administrator role verification in middleware.ts. The page contains a user deletion form calling the deleteUserAction Server Action. Inside the action itself, no authorization checks are performed because 'users without admin rights cannot navigate to this page'. What critical security vulnerability exists in this implementation?

Common Pitfalls#

Ошибка: The False Sense of Security: Omitting Authorization in Server Actions

A pervasive mistake is assuming that because a route /admin is guarded in middleware.ts, all Server Actions called from within that page are protected automatically.

This is a critical security vulnerability. Next.js compiles every Server Action into an autonomous public HTTP POST endpoint designated by a unique Next-Action ID header. Any caller can fire a POST payload directly at the action using fetch or curl, completely bypassing the page and layout.

Solution: Every Server Action must independently execute const session = await auth() and verify permissions before executing mutations.

Ошибка: Edge Runtime Crash: Importing Heavy ORMs or Prisma in Middleware

Next.js Middleware runs exclusively within the lightweight Edge Runtime, which does not support Node.js core modules (net, tls, child_process) or standard TCP database sockets. Importing a NextAuth instance bundled with PrismaAdapter directly into middleware.ts will trigger fatal build or runtime errors.

Solution: Split your auth configuration into auth.config.ts (Edge-compatible JWT checks) and auth.ts (Node.js runtime with PrismaAdapter).

Ошибка: Refresh Token Race Condition During Concurrent Requests

When an access token expires, multiple parallel requests initiated by the same page can simultaneously trigger Refresh Token Rotation within the jwt callback. If the OAuth provider invalidates single-use refresh tokens immediately upon exchange, the second parallel request fails and logs the user out unexpectedly.

Solution: Implement a grace period (15–30 seconds) on your identity provider or serialize token exchanges via a Redis-backed distributed lock/mutex.

Ошибка: Client-Side Route Protection via useSession and useRouter

Enforcing page protection inside client-side useEffect hooks allows the server to render and transmit confidential HTML across the network during SSR before the browser JavaScript executes and calls router.push('/login'). Attackers inspecting raw network responses will view the private content.

Solution: Enforce authentication server-side in middleware.ts and root layout.tsx / page.tsx via await auth().

Interview Questions#

Interview Questions8 questions