Next.js 16 Auth.js — getSession() Returned Stale Data for 2 Hours During Peak Traffic

// ============================================
// CORRECT: Use auth() in Server Components
// ============================================

// src/auth.ts — Auth.js v5 configuration
import NextAuth from 'next-auth'
import GitHub from 'next-auth/providers/github'
import Credentials from 'next-auth/providers/credentials'

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    GitHub,
    Credentials({
      credentials: {
        email: {},
        password: {},
      },
      async authorize(credentials) {
        const user = await authenticateUser(
          credentials.email as string,
          credentials.password as string
        )
        return user
      },
    }),
  ],
  session: {
    strategy: 'jwt', // Or 'database'
    maxAge: 30 * 24 * 60 * 60, // 30 days
  },
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.id = user.id
        token.role = user.role
      }
      return token
    },
    async session({ session, token }) {
      session.user.id = token.id as string
      session.user.role = token.role as string
      return session
    },
  },
})

// app/dashboard/page.tsx
// ✅ CORRECT: use auth() — no HTTP call, always fresh
export default async function DashboardPage() {
  const session = await auth()

  if (!session?.user) {
    return <RedirectToLogin />
  }

  return (
    <div>
      <h1>Welcome, {session.user.name}</h1>
      <p>Role: {session.user.role}</p>
    </div>
  )
}

// app/api/user/profile/route.ts
// ✅ CORRECT: use auth() in route handlers too
export async function GET() {
  const session = await auth()

  if (!session?.user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const profile = await getUserProfile(session.user.id)
  return Response.json(profile)
}

// ============================================
// Auth route handler — MUST be force-dynamic
// ============================================

// app/api/auth/[...nextauth]/route.ts
import { handlers } from '@/src/auth'

// ❌ WITHOUT this, the Data Cache caches auth responses
// The first user's session is cached and returned to everyone

// ✅ REQUIRED: prevent Data Cache from caching auth responses
export const dynamic = 'force-dynamic'

// Optional: set explicit revalidation to 0
// export const revalidate = 0

// Export the Auth.js handlers for GET and POST
export const { GET, POST } = handlers

// ============================================
// Alternative: Full manual handler with cache control
// ============================================

// app/api/auth/[...nextauth]/route.ts (manual version)
// import { handlers } from '@/src/auth'
// import { NextResponse } from 'next/server'
//
// export const dynamic = 'force-dynamic'
//
// export async function GET(request: Request) {
//   const response = await handlers.GET(request)
//
//   // Add cache-prevention headers
//   response.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate')
//   response.headers.set('Pragma', 'no-cache')
//   response.headers.set('Expires', '0')
//
//   return response
// }
//
// export const POST = handlers.POST

// ============================================
// CI check: ensure auth routes are force-dynamic
// ============================================

// In CI pipeline:
// grep -r 'force-dynamic' app/api/auth/ && echo 'AUTH ROUTE IS DYNAMIC' || echo 'WARNING: Auth route may be cached!'
//
// If the check fails, fail the CI build.
// One line of config prevents a P0 security incident.

// ============================================
// Auth.js Middleware — ALWAYS with matcher
// ============================================

// middleware.ts
import { auth } from '@/src/auth'
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

// Option 1: Simple export (if using default export from Auth.js)
// export { default } from 'next-auth/middleware'
// But you MUST still add matcher config below this line

// Option 2: Custom middleware with auth()
export default auth(async function middleware(request: NextRequest) {
  const session = await auth()
  const { nextUrl } = request

  // Define protected paths
  const isProtectedPath = [
    '/dashboard',
    '/account',
    '/admin',
    '/orders',
  ].some(path => nextUrl.pathname.startsWith(path))

  if (isProtectedPath && !session?.user) {
    // Redirect to login with return URL
    const loginUrl = new URL('/login', nextUrl.origin)
    loginUrl.searchParams.set('callbackUrl', nextUrl.pathname)
    return NextResponse.redirect(loginUrl)
  }

  // Redirect logged-in users away from login page
  if (nextUrl.pathname === '/login' && session?.user) {
    return NextResponse.redirect(new URL('/dashboard', nextUrl.origin))
  }

  return NextResponse.next()
})

// CRITICAL: Restrict middleware to specific paths
export const config = {
  matcher: [
    // Protected routes — only these run through auth middleware
    '/dashboard/:path*',
    '/account/:path*',
    '/admin/:path*',
    '/orders/:path*',
    // Also include login to handle redirect for already-authenticated users
    '/login',
  ]
}

// Without matcher, this middleware runs on:
// - Every page load (/_next/static/*.css, *.js, *.png)
// - API calls (/api/auth/*, /api/*)
// - Static files (/favicon.ico, /robots.txt)
// - Images, fonts, everything
//
// With matcher, it runs ONLY on the paths listed above.
// 50-100x fewer executions per page view.

// ============================================
// JWT Session Strategy (Default)
// ============================================

// src/auth.ts
import NextAuth from 'next-auth'
import GitHub from 'next-auth/providers/github'

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [GitHub],
  session: {
    strategy: 'jwt', // Default — no database needed
    maxAge: 30 * 24 * 60 * 60, // 30 days
  },
  callbacks: {
    async jwt({ token, account, profile }) {
      // First login: add user info to JWT
      if (account) {
        token.accessToken = account.access_token
        token.id = profile?.id
      }
      return token
    },
    async session({ session, token }) {
      // Pass JWT data to session object
      session.user.id = token.id as string
      session.accessToken = token.accessToken
      return session
    },
  },
})

// ============================================
// Database Session Strategy
// ============================================

// src/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],
  session: {
    strategy: 'database', // Requires adapter
    maxAge: 30 * 24 * 60 * 60,
    updateAge: 24 * 60 * 60, // Update session in DB every 24h
  },
})

// With database sessions, auth() does:
// 1. Read session cookie (session ID)
// 2. Query database for session by ID
// 3. Return session data
//
// Performance: -5-20ms per auth() call (database round trip)
// Benefit: Immediate session revocation (delete from database)
//
// Important: database adapter stores sessions in a 'session' table.
// Your database must have the session model defined in your schema.
// Prisma adapter handles this automatically if schema is configured.

// ============================================
// Hybrid: JWT with revocation tracking
// ============================================

// src/auth.ts
import NextAuth from 'next-auth'

// Use JWT strategy (fast) and maintain a 'valid sessions' set
// This is a simplified example — production would use Redis/DB

export const { handlers, auth, signIn, signOut } = NextAuth({
  session: { strategy: 'jwt' },
  callbacks: {
    async jwt({ token }) {
      // On every token refresh, check if session is still valid
      if (token.sessionId) {
        const isValid = await checkSessionValid(token.sessionId)
        if (!isValid) {
          throw new Error('Session revoked')
        }
      }
      return token
    },
  },
})

// ============================================
// Multiple Provider Configuration
// ============================================

// src/auth.ts
import NextAuth from 'next-auth'
import GitHub from 'next-auth/providers/github'
import Google from 'next-auth/providers/google'
import Email from 'next-auth/providers/email'
import Credentials from 'next-auth/providers/credentials'
import { compare } from 'bcrypt' // Node.js only — not Edge-compatible

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [
    // OAuth provider — GitHub
    GitHub({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),

    // OAuth provider — Google
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),

    // Magic link provider — Email
    Email({
      server: process.env.EMAIL_SERVER,
      from: process.env.EMAIL_FROM,
      maxAge: 10 * 60, // Link expires in 10 minutes
    }),

    // Credentials provider — email/password
    Credentials({
      credentials: {
        email: { label: 'Email', type: 'email' },
        password: { label: 'Password', type: 'password' },
      },
      async authorize(credentials) {
        if (!credentials?.email || !credentials?.password) {
          return null
        }

        const user = await findUserByEmail(credentials.email as string)

        if (!user || !user.passwordHash) {
          return null
        }

        const isValid = await compare(
          credentials.password as string,
          user.passwordHash
        )

        if (!isValid) {
          return null
        }

        return {
          id: user.id,
          email: user.email,
          name: user.name,
          image: user.image,
        }
      },
    }),
  ],
  pages: {
    signIn: '/login',
    error: '/login/error',
  },
  callbacks: {
    async signIn({ user, account }) {
      // Allow all authenticated users
      return true
    },
    async redirect({ url, baseUrl }) {
      // Only allow relative URLs or same-origin URLs
      if (url.startsWith('/')) return `${baseUrl}${url}`
      if (new URL(url).origin === baseUrl) return url
      return baseUrl
    },
  },
})

// ============================================
// Custom Session Callbacks
// ============================================

// src/auth.ts
import NextAuth from 'next-auth'
import type { DefaultSession } from 'next-auth'

// Extend the default session type
declare module 'next-auth' {
  interface Session {
    user: {
      id: string
      role: 'admin' | 'user' | 'viewer'
      permissions: string[]
    } & DefaultSession['user']
  }

  interface JWT {
    role?: 'admin' | 'user' | 'viewer'
    permissions?: string[]
  }
}

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [/* ... */],
  callbacks: {
    // Runs on sign in and every session access
    async jwt({ token, user, trigger }) {
      // First login: add user data from database
      if (user) {
        const dbUser = await findUserByEmail(user.email!)
        token.id = dbUser.id
        token.role = dbUser.role
        token.permissions = dbUser.permissions
      }

      // Token refresh: check if data changed
      if (trigger === 'update') {
        const dbUser = await findUserByEmail(token.email!)
        token.role = dbUser.role
        token.permissions = dbUser.permissions
      }

      return token
    },

    // Runs on every auth() call — maps JWT to session
    async session({ session, token }) {
      // Pass JWT data to session object
      session.user.id = token.id as string
      session.user.role = token.role as 'admin' | 'user' | 'viewer'
      session.user.permissions = token.permissions as string[]

      return session
    },
  },
})

// app/admin/page.tsx — role-based access check
export default async function AdminPage() {
  const session = await auth()

  if (!session?.user) {
    return <RedirectToLogin />
  }

  if (session.user.role !== 'admin') {
    return <Unauthorized />
  }

  if (!session.user.permissions.includes('view:admin-panel')) {
    return <Forbidden />
  }

  return <AdminPanel />
}

// app/actions.ts — Server Action with auth check
'use server'

import { auth } from '@/src/auth'

export async function deleteUser(userId: string) {
  const session = await auth()

  if (!session?.user) {
    throw new Error('Unauthorized')
  }

  if (session.user.role !== 'admin') {
    throw new Error('Forbidden: admin only')
  }

  // Perform deletion
  await db.users.delete({ where: { id: userId } })
}

// ============================================
// Sign Out Patterns
// ============================================

// Client component sign out
'use client'

import { signOut } from 'next-auth/react'

export function SignOutButton() {
  return (
    <button onClick={() => signOut({
      callbackUrl: '/', // Redirect to homepage after sign out
    })}>
      Sign Out
    </button>
  )
}

// Server Action sign out
// app/actions.ts
'use server'

import { signOut } from '@/src/auth'

export async function serverSignOut() {
  await signOut({
    redirectTo: '/',
  })
}

// ============================================
// Session Refresh
// ============================================

// Client component — update session
'use client'

import { useSession } from 'next-auth/react'
import { updateProfile } from '@/app/actions'

export function ProfileEditor() {
  const { data: session, update } = useSession()

  async function handleSave(formData: FormData) {
    const result = await updateProfile(formData)

    if (result.success) {
      // Manually trigger session update
      // This calls the /api/auth/session endpoint
      await update({
        name: formData.get('name'),
      })
    }
  }

  return (
    <form action={handleSave}>
      <input
        name="name"
        defaultValue={session?.user?.name ?? ''}
      />
      <button type="submit">Save</button>
    </form>
  )
}

// ============================================
// Token Rotation Pattern (for short-lived access tokens)
// ============================================

// src/auth.ts
export const { handlers, auth, signIn, signOut } = NextAuth({
  session: {
    strategy: 'jwt',
    maxAge: 24 * 60 * 60, // JWT expires in 24 hours
  },
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        // Store refresh token on first sign in
        token.refreshToken = account.refresh_token
        token.accessTokenExpires = Date.now() + 3600 * 1000 // 1 hour
      }

      // Return previous token if not expired
      if (Date.now() < (token.accessTokenExpires as number)) {
        return token
      }

      // Token expired — refresh it
      try {
        const response = await fetch('https://oauth2.googleapis.com/token', {
          method: 'POST',
          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
          body: new URLSearchParams({
            client_id: process.env.GOOGLE_CLIENT_ID!,
            client_secret: process.env.GOOGLE_CLIENT_SECRET!,
            grant_type: 'refresh_token',
            refresh_token: token.refreshToken as string,
          }),
        })

        const tokens = await response.json()

        token.accessToken = tokens.access_token
        token.accessTokenExpires = Date.now() + tokens.expires_in * 1000

        return token
      } catch {
        // Refresh failed — force re-login
        return { ...token, error: 'RefreshAccessTokenError' }
      }
    },
  },
})