# Auth Configuration & Providers

> Complete code examples for Auth.js configuration, providers, and callbacks. See [SKILL.md](../SKILL.md) for core concepts.

---

## Pattern 1: Basic OAuth Configuration

### Good Example - Multi-Provider Setup

```typescript
// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";
import Discord from "next-auth/providers/discord";

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [
    GitHub, // Auto-detects AUTH_GITHUB_ID, AUTH_GITHUB_SECRET
    Google, // Auto-detects AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET
    Discord, // Auto-detects AUTH_DISCORD_ID, AUTH_DISCORD_SECRET
  ],
  pages: {
    signIn: "/login", // Custom sign-in page
    error: "/auth/error", // Custom error page
  },
});
```

```typescript
// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";

export const { GET, POST } = handlers;
```

```bash
# .env.local
AUTH_SECRET="npx auth secret"
AUTH_GITHUB_ID="..."
AUTH_GITHUB_SECRET="..."
AUTH_GOOGLE_ID="..."
AUTH_GOOGLE_SECRET="..."
AUTH_DISCORD_ID="..."
AUTH_DISCORD_SECRET="..."
```

**Why good:** Providers auto-detect env vars (zero config), custom pages override defaults, single route file handles all auth endpoints

### Bad Example - v4 Style Configuration

```typescript
// BAD: v4 pattern - authOptions export in API route
// pages/api/auth/[...nextauth].ts
import NextAuth from "next-auth";

export const authOptions = {
  providers: [
    // ...
  ],
  secret: process.env.NEXTAUTH_SECRET, // BAD: deprecated env var
};

export default NextAuth(authOptions);
```

**Why bad:** v4 pattern (authOptions export), deprecated `NEXTAUTH_SECRET`, Pages Router API route, no typed exports

---

## Pattern 2: Credentials Provider

### Good Example - Email/Password with Validation

```typescript
// auth.ts
import NextAuth from "next-auth";
import Credentials from "next-auth/providers/credentials";
import bcrypt from "bcryptjs";
import { z } from "zod";

const LoginSchema = z.object({
  email: z.string().email("Invalid email address"),
  password: z.string().min(8, "Password must be at least 8 characters"),
});

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [
    Credentials({
      credentials: {
        email: { label: "Email", type: "email" },
        password: { label: "Password", type: "password" },
      },
      async authorize(credentials) {
        // Validate input
        const parsed = LoginSchema.safeParse(credentials);
        if (!parsed.success) return null;

        // Look up user
        const user = await db.user.findUnique({
          where: { email: parsed.data.email },
        });
        if (!user?.hashedPassword) return null;

        // Verify password
        const isValid = await bcrypt.compare(
          parsed.data.password,
          user.hashedPassword,
        );
        if (!isValid) return null;

        // Return user object (becomes `user` in jwt callback)
        return {
          id: user.id,
          name: user.name,
          email: user.email,
          role: user.role,
        };
      },
    }),
  ],
  session: { strategy: "jwt" }, // Credentials requires JWT strategy
});
```

**Why good:** Zod validates input before DB query, bcrypt for password verification, null return on any failure (doesn't reveal which step failed), explicit JWT strategy

### Bad Example - Insecure Credentials

```typescript
// BAD: No validation, plain text comparison
Credentials({
  async authorize(credentials) {
    const user = await db.user.findUnique({
      where: { email: credentials.email as string },
    });
    if (user?.password === credentials.password) {
      // BAD: plain text compare
      return user;
    }
    throw new Error("Invalid credentials"); // BAD: throws instead of returning null
  },
});
```

**Why bad:** No input validation, plain text password comparison, throwing error leaks information to client (return null instead)

---

## Pattern 3: Callbacks

### Good Example - JWT and Session Callbacks with Custom Data

```typescript
// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [GitHub],
  callbacks: {
    async jwt({ token, user, account }) {
      // `user` is only available on first sign-in
      if (user) {
        token.id = user.id;
        token.role = user.role ?? "user";
      }
      // `account` has OAuth tokens on first sign-in
      if (account) {
        token.accessToken = account.access_token;
      }
      return token;
    },

    async session({ session, token }) {
      // Expose only what the client needs
      session.user.id = token.id as string;
      session.user.role = token.role as string;
      // Do NOT expose accessToken to client
      return session;
    },

    async signIn({ user, account, profile }) {
      // Restrict to specific email domains
      if (account?.provider === "google") {
        return user.email?.endsWith("@company.com") ?? false;
      }
      return true;
    },

    async redirect({ url, baseUrl }) {
      // Prevent open redirect attacks
      if (url.startsWith("/")) return `${baseUrl}${url}`;
      if (new URL(url).origin === baseUrl) return url;
      return baseUrl;
    },
  },
});
```

**Why good:** Custom data flows from jwt -> session callback, sensitive tokens kept server-side, email domain restriction for corporate SSO, redirect validation prevents open redirects

### Bad Example - Leaking Tokens to Client

```typescript
// BAD: Exposing OAuth access token to client
callbacks: {
  async session({ session, token }) {
    session.accessToken = token.accessToken; // BAD: exposed to client
    session.refreshToken = token.refreshToken; // BAD: exposed to client
    return session;
  },
}
```

**Why bad:** Access and refresh tokens exposed to browser, allows token theft via XSS, should stay server-side only

---

## Pattern 4: Sign In / Sign Out

### Good Example - Server Actions for Auth

```typescript
// components/auth-buttons.tsx
import { signIn, signOut } from "@/auth";

export function SignInButton({ provider = "github" }: { provider?: string }) {
  return (
    <form
      action={async () => {
        "use server";
        await signIn(provider, { redirectTo: "/dashboard" });
      }}
    >
      <button type="submit">Sign in with {provider}</button>
    </form>
  );
}

export function SignOutButton() {
  return (
    <form
      action={async () => {
        "use server";
        await signOut({ redirectTo: "/" });
      }}
    >
      <button type="submit">Sign out</button>
    </form>
  );
}
```

**Why good:** Server Actions for progressive enhancement (works without JS), `redirectTo` controls destination, imported from server-side `@/auth`

### Good Example - Client-Side Sign In

```typescript
// components/client-auth.tsx
"use client";

import { signIn, signOut } from "next-auth/react";

export function ClientSignIn() {
  return (
    <button onClick={() => signIn("github", { callbackUrl: "/dashboard" })}>
      Sign in
    </button>
  );
}

export function ClientSignOut() {
  return (
    <button onClick={() => signOut({ callbackUrl: "/" })}>
      Sign out
    </button>
  );
}
```

**Why good:** Client-side import from `next-auth/react` (not `@/auth`), `callbackUrl` for client-side redirect

---

## Pattern 5: TypeScript Type Extensions

### Good Example - Extending Session Types

```typescript
// types/next-auth.d.ts
import type { DefaultSession, DefaultJWT } from "next-auth";

declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      role: "admin" | "editor" | "user";
    } & DefaultSession["user"];
  }

  interface User {
    role?: "admin" | "editor" | "user";
  }
}

declare module "next-auth/jwt" {
  interface JWT extends DefaultJWT {
    id?: string;
    role?: "admin" | "editor" | "user";
    accessToken?: string;
  }
}
```

**Why good:** Type-safe custom fields on session and JWT, extends defaults rather than replacing, union type for role values

---

_See [session.md](session.md) for session strategies and [middleware.md](middleware.md) for route protection._

# Database Adapters

> Code examples for Auth.js database adapters - Prisma, Drizzle, session storage. See [SKILL.md](../SKILL.md) for core concepts.

---

## Pattern 1: Prisma Adapter

### Good Example - Full Prisma Setup

```typescript
// 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 { auth, handlers, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [GitHub],
  session: { strategy: "database" },
  callbacks: {
    async session({ session, user }) {
      // With database sessions, `user` (not `token`) is available
      session.user.id = user.id;
      session.user.role = user.role;
      return session;
    },
  },
});
```

Auth.js requires four models in your schema: **User**, **Account**, **Session**, **VerificationToken**. See the [official Prisma adapter docs](https://authjs.dev/getting-started/adapters/prisma) for the complete schema. Key points:

- `Account` has `@@unique([provider, providerAccountId])` composite key
- `Session` has `sessionToken @unique` and `expires` field
- `VerificationToken` has `@@unique([identifier, token])` composite key
- All relations should use `onDelete: Cascade`
- Add custom fields (e.g., `role`) to User model, then expose via session callback

**Why good:** Session callback uses `user` (not `token`) for database strategy, cascade deletes clean up related records

---

## Pattern 2: Drizzle Adapter

### Good Example - Drizzle ORM with PostgreSQL

```typescript
// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import { DrizzleAdapter } from "@auth/drizzle-adapter";
import { db } from "@/lib/db";

export const { auth, handlers, signIn, signOut } = NextAuth({
  adapter: DrizzleAdapter(db),
  providers: [GitHub],
  session: { strategy: "database" },
});
```

The same four models (users, accounts, sessions, verificationTokens) are required. See the [official Drizzle adapter docs](https://authjs.dev/getting-started/adapters/drizzle) for the complete schema. Key points:

- Import `AdapterAccountType` from `next-auth/adapters` for typed `account.type` field
- Use `primaryKey({ columns: [account.provider, account.providerAccountId] })` composite key
- Use `onDelete: "cascade"` on all foreign key references
- Use `timestamp("emailVerified", { mode: "date" })` for proper Date handling

**Why good:** Drizzle schema matches Auth.js model requirements, cascade deletes for data integrity, typed account type from Auth.js adapters

---

## Pattern 3: Email Provider with Database

### Good Example - Magic Link Authentication

```typescript
// auth.ts
import NextAuth from "next-auth";
import Resend from "next-auth/providers/resend";
import { PrismaAdapter } from "@auth/prisma-adapter";
import { prisma } from "@/lib/prisma";

export const { auth, handlers, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma), // Required for email provider
  providers: [
    Resend({
      // Auto-detects AUTH_RESEND_KEY
      from: "noreply@example.com",
    }),
  ],
});
```

**Why good:** Email provider requires database adapter (stores verification tokens), Resend auto-detects API key, minimal configuration needed

### Bad Example - Email Provider Without Adapter

```typescript
// BAD: Email provider needs a database adapter
export const { auth } = NextAuth({
  providers: [Resend({ from: "noreply@example.com" })],
  // Missing adapter - verification tokens can't be stored
});
```

**Why bad:** Email provider stores verification tokens in database; without adapter, magic links can't be verified

---

## Pattern 4: Custom User Fields

### Good Example - Extending User Model

Add custom fields directly to your User model (e.g., `role`, `bio`, `onboardingComplete`), then expose them via the session callback:

```typescript
// auth.ts - Expose custom fields in session
export const { auth, handlers, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [GitHub],
  session: { strategy: "database" },
  callbacks: {
    async session({ session, user }) {
      // `user` is the full database User object
      session.user.id = user.id;
      session.user.role = user.role;
      session.user.onboardingComplete = user.onboardingComplete;
      return session;
    },
  },
});
```

```typescript
// types/next-auth.d.ts
import type { DefaultSession } from "next-auth";

declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      role: string;
      onboardingComplete: boolean;
    } & DefaultSession["user"];
  }
}
```

**Why good:** Custom fields on User model, exposed via session callback, TypeScript types updated for type safety, database strategy gives access to full `user` object

---

_See [patterns.md](patterns.md) for role-based access and account linking patterns._

# Route Protection & Middleware

> Code examples for Auth.js route protection - middleware patterns, Edge compatibility, per-page checks. See [SKILL.md](../SKILL.md) for core concepts.

> **Next.js 16 note:** `middleware.ts` is renamed to `proxy.ts` and the export is renamed to `proxy` in Next.js 16+. In Next.js 16, `proxy.ts` runs on **Node.js runtime** (not Edge), so the split config pattern is no longer required. Examples below use `middleware.ts` (Next.js 14/15). For Next.js 16+, rename to `proxy.ts` and export as `proxy`.

---

## Pattern 1: Basic Middleware Protection

### Good Example - Protect All Routes with Exceptions

```typescript
// middleware.ts (Next.js 14/15) or proxy.ts (Next.js 16+)
export { auth as middleware } from "@/auth";
// Next.js 16+: export { auth as proxy } from "@/auth";

export const config = {
  matcher: [
    // Match all routes except static files and public paths
    "/((?!api/auth|_next/static|_next/image|favicon.ico|public).*)",
  ],
};
```

```typescript
// auth.ts - with authorized callback
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [GitHub],
  callbacks: {
    authorized({ auth, request }) {
      const isLoggedIn = !!auth?.user;
      const isPublicRoute = ["/", "/about", "/pricing"].includes(
        request.nextUrl.pathname,
      );

      if (isPublicRoute) return true;
      return isLoggedIn; // false redirects to sign-in
    },
  },
});
```

**Why good:** Centralized auth check for all routes, public routes explicitly allowed, `authorized` callback returns boolean (false = redirect to sign-in)

---

## Pattern 2: Custom Middleware with Redirect Logic

### Good Example - Role-Based Redirect

```typescript
// middleware.ts (Next.js 14/15) or proxy.ts (Next.js 16+)
import { auth } from "@/auth";
import { NextResponse } from "next/server";

const PUBLIC_ROUTES = ["/", "/about", "/pricing", "/login"];
const ADMIN_ROUTES = ["/admin"];

export default auth((req) => {
  const { nextUrl } = req;
  const isLoggedIn = !!req.auth;
  const isPublicRoute = PUBLIC_ROUTES.some((route) =>
    nextUrl.pathname.startsWith(route),
  );
  const isAdminRoute = ADMIN_ROUTES.some((route) =>
    nextUrl.pathname.startsWith(route),
  );

  // Public routes: always accessible
  if (isPublicRoute) return NextResponse.next();

  // Not logged in: redirect to login
  if (!isLoggedIn) {
    const loginUrl = new URL("/login", nextUrl.origin);
    loginUrl.searchParams.set("callbackUrl", nextUrl.pathname);
    return NextResponse.redirect(loginUrl);
  }

  // Admin routes: check role (available in JWT)
  if (isAdminRoute && req.auth?.user?.role !== "admin") {
    return NextResponse.redirect(new URL("/unauthorized", nextUrl.origin));
  }

  return NextResponse.next();
});

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

**Why good:** Named route arrays for maintainability, preserves callback URL for post-login redirect, role check in middleware for admin routes

### Bad Example - No Public Route Handling

```typescript
// BAD: All routes require auth including landing page
export { auth as middleware } from "@/auth";

// No matcher config - catches everything
// No authorized callback - defaults to requiring auth
```

**Why bad:** Blocks public pages (landing, pricing, about), no matcher excludes static assets, forces login on every route

---

## Pattern 3: Edge-Compatible Split Configuration

### Good Example - Split Config for Database Sessions + Middleware

```typescript
// auth.config.ts - Edge-compatible (NO database imports)
import GitHub from "next-auth/providers/github";
import type { NextAuthConfig } from "next-auth";

const PUBLIC_ROUTES = ["/", "/about", "/login"];

export const authConfig = {
  providers: [GitHub],
  pages: {
    signIn: "/login",
  },
  callbacks: {
    authorized({ auth, request }) {
      const isLoggedIn = !!auth?.user;
      const isPublic = PUBLIC_ROUTES.some((route) =>
        request.nextUrl.pathname.startsWith(route),
      );
      if (isPublic) return true;
      return isLoggedIn;
    },
  },
} satisfies NextAuthConfig;
```

```typescript
// auth.ts - Full config with database adapter (Node.js only)
import NextAuth from "next-auth";
import { PrismaAdapter } from "@auth/prisma-adapter";
import { prisma } from "@/lib/prisma";
import { authConfig } from "./auth.config";

export const { auth, handlers, signIn, signOut } = NextAuth({
  ...authConfig,
  adapter: PrismaAdapter(prisma),
  session: { strategy: "database" },
});
```

```typescript
// middleware.ts (Next.js 14/15) - Uses Edge-compatible config
import NextAuth from "next-auth";
import { authConfig } from "./auth.config";

export const { auth: middleware } = NextAuth(authConfig);
// Next.js 16+: export const { auth: proxy } = NextAuth(authConfig);
// Note: In Next.js 16, proxy.ts runs on Node.js, so split config is optional

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

**Why good:** `auth.config.ts` has no database imports (Edge-safe), `auth.ts` adds adapter for full Node.js runtime, middleware uses the slim Edge config. In Next.js 16+, `proxy.ts` runs on Node.js so you can use the full `auth.ts` directly.

### Bad Example - Database Adapter in Middleware (Next.js 14/15)

```typescript
// BAD: Importing Prisma in middleware breaks Edge runtime (Next.js 14/15)
// middleware.ts
import { auth } from "@/auth"; // auth.ts imports PrismaAdapter

export { auth as middleware };
// ERROR: PrismaClient cannot run on Edge runtime
// Note: This is NOT an issue in Next.js 16+ proxy.ts (runs on Node.js)
```

**Why bad:** Prisma/Drizzle can't run on Edge runtime, middleware crashes at deploy time, must split config. In Next.js 16+, `proxy.ts` runs on Node.js so this limitation no longer applies.

---

## Pattern 4: Per-Page Protection

### Good Example - Authorization in Server Components

```typescript
// app/admin/page.tsx
import { auth } from "@/auth";
import { redirect } from "next/navigation";

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

  if (!session?.user) {
    redirect("/login");
  }

  if (session.user.role !== "admin") {
    redirect("/unauthorized");
  }

  // Only admins reach here
  return (
    <div>
      <h1>Admin Dashboard</h1>
      <p>Welcome, {session.user.name}</p>
    </div>
  );
}
```

### Good Example - Protected Server Action

```typescript
// app/actions/admin-actions.ts
"use server";

import { auth } from "@/auth";

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

  if (!session?.user) {
    throw new Error("Authentication required");
  }

  if (session.user.role !== "admin") {
    throw new Error("Admin access required");
  }

  // Proceed with deletion
  await db.user.delete({ where: { id: userId } });

  return { success: true };
}
```

**Why good:** Defense in depth - middleware provides first check, Server Component/Action provides authorization check, both session and role verified

---

## Pattern 5: Protecting API Routes

### Good Example - Authenticated API Endpoint

```typescript
// app/api/users/route.ts
import { auth } from "@/auth";
import { NextResponse } from "next/server";

export const GET = auth(async function GET(req) {
  if (!req.auth?.user) {
    return NextResponse.json(
      { error: "Authentication required" },
      { status: 401 },
    );
  }

  if (req.auth.user.role !== "admin") {
    return NextResponse.json(
      { error: "Admin access required" },
      { status: 403 },
    );
  }

  const users = await db.user.findMany({
    select: { id: true, name: true, email: true, role: true },
  });

  return NextResponse.json(users);
});
```

**Why good:** Wrapped with `auth()` for automatic session injection, 401 for unauthenticated, 403 for unauthorized, proper HTTP status codes

---

_See [database.md](database.md) for adapter setup and [patterns.md](patterns.md) for advanced auth patterns._

# Advanced Auth Patterns

> Code examples for role-based access, magic links, account linking, and custom sign-in pages. See [SKILL.md](../SKILL.md) for core concepts.

---

## Pattern 1: Role-Based Access Control

### Good Example - RBAC with Auth.js

```typescript
// lib/auth-utils.ts
import { auth } from "@/auth";
import { redirect } from "next/navigation";

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

export async function requireAuth() {
  const session = await auth();
  if (!session?.user) {
    redirect("/login");
  }
  return session;
}

export async function requireRole(requiredRole: Role) {
  const session = await requireAuth();

  const ROLE_HIERARCHY: Record<Role, number> = {
    admin: 3,
    editor: 2,
    user: 1,
  };

  const userLevel = ROLE_HIERARCHY[session.user.role as Role] ?? 0;
  const requiredLevel = ROLE_HIERARCHY[requiredRole];

  if (userLevel < requiredLevel) {
    redirect("/unauthorized");
  }

  return session;
}
```

```typescript
// app/admin/users/page.tsx
import { requireRole } from "@/lib/auth-utils";

export default async function AdminUsersPage() {
  const session = await requireRole("admin");

  const users = await db.user.findMany({
    select: { id: true, name: true, email: true, role: true },
  });

  return (
    <div>
      <h1>User Management</h1>
      <p>Logged in as: {session.user.name} ({session.user.role})</p>
      <table>
        <thead>
          <tr><th>Name</th><th>Email</th><th>Role</th></tr>
        </thead>
        <tbody>
          {users.map((user) => (
            <tr key={user.id}>
              <td>{user.name}</td>
              <td>{user.email}</td>
              <td>{user.role}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}
```

**Why good:** Reusable auth helpers, role hierarchy allows admins to access editor pages too, named constant for hierarchy, redirect on insufficient permissions

---

## Pattern 2: Custom Sign-In Page

### Good Example - Branded Login Page

```typescript
// auth.ts
export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [
    GitHub,
    Google,
    Credentials({
      /* ... */
    }),
  ],
  pages: {
    signIn: "/login", // Custom login page
    error: "/login/error", // Custom error page
  },
});
```

```typescript
// app/login/page.tsx
import { auth, signIn } from "@/auth";
import { redirect } from "next/navigation";

export default async function LoginPage({
  searchParams,
}: {
  searchParams: Promise<{ callbackUrl?: string; error?: string }>;
}) {
  const session = await auth();
  const { callbackUrl, error } = await searchParams;

  // Already logged in - redirect to callback or dashboard
  if (session?.user) {
    redirect(callbackUrl ?? "/dashboard");
  }

  return (
    <div className="login-container">
      <h1>Sign In</h1>

      {error && (
        <div className="error-banner" role="alert">
          {error === "OAuthAccountNotLinked"
            ? "This email is already associated with another provider."
            : "An error occurred during sign in."}
        </div>
      )}

      {/* OAuth providers */}
      <form
        action={async () => {
          "use server";
          await signIn("github", { redirectTo: callbackUrl ?? "/dashboard" });
        }}
      >
        <button type="submit">Continue with GitHub</button>
      </form>

      <form
        action={async () => {
          "use server";
          await signIn("google", { redirectTo: callbackUrl ?? "/dashboard" });
        }}
      >
        <button type="submit">Continue with Google</button>
      </form>

      {/* Credentials form */}
      <form
        action={async (formData: FormData) => {
          "use server";
          await signIn("credentials", {
            email: formData.get("email"),
            password: formData.get("password"),
            redirectTo: callbackUrl ?? "/dashboard",
          });
        }}
      >
        <input type="email" name="email" placeholder="Email" required />
        <input type="password" name="password" placeholder="Password" required />
        <button type="submit">Sign in with Email</button>
      </form>
    </div>
  );
}
```

**Why good:** Redirects already-authenticated users, preserves callback URL, handles OAuth error codes, Server Actions for each provider, progressive enhancement

---

## Pattern 3: Account Linking

### Good Example - Controlled Account Linking

```typescript
// auth.ts
export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [GitHub, Google],
  callbacks: {
    async signIn({ user, account, profile }) {
      // Check if email already exists with a different provider
      if (account?.provider && user.email) {
        const existingUser = await db.user.findUnique({
          where: { email: user.email },
          include: { accounts: true },
        });

        if (existingUser) {
          const hasProvider = existingUser.accounts.some(
            (a) => a.provider === account.provider,
          );

          if (!hasProvider) {
            // Link the new provider to existing account
            // Auth.js handles this automatically with allowDangerousEmailAccountLinking
            // But you may want custom logic here
          }
        }
      }
      return true;
    },
  },
  // Enable automatic linking for same-email accounts
  // WARNING: Only enable if you trust ALL your OAuth providers to verify emails
  // allowDangerousEmailAccountLinking: true,
});
```

**Why good:** Explicit check for existing accounts, documented security implications, automatic linking commented out with warning

---

## Pattern 4: Session-Based Guards for Components

### Good Example - Conditional UI Based on Auth Status

```typescript
// components/auth-guard.tsx
import { auth } from "@/auth";

interface AuthGuardProps {
  children: React.ReactNode;
  fallback?: React.ReactNode;
  requiredRole?: string;
}

export async function AuthGuard({
  children,
  fallback = null,
  requiredRole,
}: AuthGuardProps) {
  const session = await auth();

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

  if (requiredRole && session.user.role !== requiredRole) {
    return <>{fallback}</>;
  }

  return <>{children}</>;
}
```

```typescript
// app/page.tsx
import { AuthGuard } from "@/components/auth-guard";

export default function HomePage() {
  return (
    <div>
      <h1>Welcome</h1>

      <AuthGuard fallback={<p>Sign in to see your dashboard</p>}>
        <DashboardWidget />
      </AuthGuard>

      <AuthGuard requiredRole="admin">
        <AdminPanel />
      </AuthGuard>
    </div>
  );
}
```

**Why good:** Reusable Server Component guard, optional role check, fallback content for unauthenticated users, composable

---

## Pattern 5: Rate Limiting Sign-In

### Good Example - Rate Limiting Credentials Provider

```typescript
// lib/rate-limit.ts
const WINDOW_MS = 15 * 60 * 1000; // 15 minutes
const MAX_ATTEMPTS = 5;

const attempts = new Map<string, { count: number; resetTime: number }>();

export function checkRateLimit(identifier: string): boolean {
  const now = Date.now();
  const entry = attempts.get(identifier);

  if (!entry || now > entry.resetTime) {
    attempts.set(identifier, { count: 1, resetTime: now + WINDOW_MS });
    return true; // Allowed
  }

  if (entry.count >= MAX_ATTEMPTS) {
    return false; // Rate limited
  }

  entry.count++;
  return true; // Allowed
}
```

```typescript
// auth.ts
import { checkRateLimit } from "@/lib/rate-limit";

Credentials({
  async authorize(credentials) {
    const email = credentials.email as string;

    // Rate limit by email address
    if (!checkRateLimit(email)) {
      return null; // Silently reject (don't reveal rate limiting)
    }

    // ... normal auth logic
  },
});
```

**Why good:** Named constants for window and max attempts, per-email rate limiting, silent rejection (doesn't tell attacker they're rate limited), simple in-memory store (use Redis in production)

---

_See [core.md](core.md) for basic configuration and [session.md](session.md) for session strategies._

# Session Strategies & Access

> Code examples for Auth.js session management - JWT vs database sessions, accessing sessions in different contexts. See [SKILL.md](../SKILL.md) for core concepts.

---

## Pattern 1: JWT Sessions (Default)

### Good Example - JWT Configuration

```typescript
// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

const MAX_AGE_SECONDS = 30 * 24 * 60 * 60; // 30 days
const UPDATE_AGE_SECONDS = 24 * 60 * 60; // 24 hours

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [GitHub],
  session: {
    strategy: "jwt",
    maxAge: MAX_AGE_SECONDS,
    updateAge: UPDATE_AGE_SECONDS, // How often to refresh the JWT
  },
});
```

**Why good:** Named constants for time values, explicit strategy declaration, `updateAge` prevents unnecessary JWT refreshes

---

## Pattern 2: Database Sessions

### Good Example - Database Session with Prisma

```typescript
// 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 { auth, handlers, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [GitHub],
  session: {
    strategy: "database", // Explicit (default when adapter is present)
  },
});
```

See [database.md](database.md) for the required Prisma/Drizzle schema models (User, Account, Session, VerificationToken).

**Why good:** PrismaAdapter handles session CRUD, database sessions support immediate revocation, explicit `strategy: "database"` when adapter is present

### Bad Example - Database Strategy Without Adapter

```typescript
// BAD: Database strategy requires an adapter
export const { auth } = NextAuth({
  providers: [GitHub],
  session: {
    strategy: "database", // Will fail - no adapter configured
  },
});
```

**Why bad:** Database strategy requires a database adapter; will throw runtime error

---

## Pattern 3: Accessing Sessions in Different Contexts

### Good Example - Server Component

```typescript
// app/profile/page.tsx
import { auth } from "@/auth";
import { redirect } from "next/navigation";

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

  if (!session?.user) {
    redirect("/login");
  }

  return (
    <div>
      <h1>Profile</h1>
      <p>Name: {session.user.name}</p>
      <p>Email: {session.user.email}</p>
      <p>Role: {session.user.role}</p>
    </div>
  );
}
```

### Good Example - Route Handler

```typescript
// app/api/profile/route.ts
import { auth } from "@/auth";
import { NextResponse } from "next/server";

export const GET = auth(function GET(req) {
  if (!req.auth?.user) {
    return NextResponse.json(
      { error: "Authentication required" },
      { status: 401 },
    );
  }

  return NextResponse.json({
    id: req.auth.user.id,
    name: req.auth.user.name,
    role: req.auth.user.role,
  });
});
```

### Good Example - Server Action

```typescript
// app/actions.ts
"use server";

import { auth } from "@/auth";

export async function updateProfile(formData: FormData) {
  const session = await auth();

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

  const name = formData.get("name") as string;

  await db.user.update({
    where: { id: session.user.id },
    data: { name },
  });

  return { success: true };
}
```

### Good Example - Client Component with SessionProvider

```typescript
// components/session-info.tsx
"use client";

import { useSession } from "next-auth/react";

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

  if (status === "loading") {
    return <p>Loading session...</p>;
  }

  if (status === "unauthenticated") {
    return <p>Not signed in</p>;
  }

  return (
    <div>
      <p>Signed in as {session?.user?.name}</p>
      <p>Role: {session?.user?.role}</p>
    </div>
  );
}
```

**Why good:** Each context uses the appropriate method, server-side uses `auth()` directly, client-side uses `useSession()` with loading states

### Bad Example - Using Deprecated Functions

```typescript
// BAD: v4 patterns
import { getServerSession } from "next-auth"; // Deprecated
import { authOptions } from "@/app/api/auth/[...nextauth]/route"; // Deprecated pattern

export default async function Page() {
  const session = await getServerSession(authOptions); // BAD
  // ...
}
```

**Why bad:** `getServerSession` is deprecated in v5, `authOptions` export pattern is v4, should use `auth()` from `@/auth`

---

## Pattern 4: Session Update (Refreshing Client Session)

### Good Example - Updating Session After Profile Change

```typescript
// components/profile-form.tsx
"use client";

import { useSession } from "next-auth/react";
import { useState } from "react";

export function ProfileForm() {
  const { data: session, update } = useSession();
  const [name, setName] = useState(session?.user?.name ?? "");

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    // Update in database via Server Action
    await updateProfile(new FormData(e.target as HTMLFormElement));

    // Refresh the client session to reflect changes
    await update({ name });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        name="name"
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <button type="submit">Save</button>
    </form>
  );
}
```

**Why good:** `update()` refreshes client session after server-side change, no full page reload needed, optimistic UI with local state

---

_See [middleware.md](middleware.md) for route protection patterns and [database.md](database.md) for adapter setup._