Auth.js (NextAuth v5) Padrões

Padrões Auth.js (NextAuth v5)

Guia Rápido: Configure o Auth.js em um arquivo raiz auth.ts exportando { auth, handlers, signIn, signOut } do NextAuth(). Use a função unificada auth() em todos os lugares (Server Components, Route Handlers, middleware). A estratégia de sessão padrão é JWT (baseada em cookies); adicione um adaptador de banco de dados para sessões persistentes. Proteja rotas via middleware ou verificações com auth() por página.

---

<critical_requirements>

CRÍTICO: Antes de Usar Este Skill

Todo o código deve seguir as convenções do projeto em CLAUDE.md (kebab-case, named exports, ordenação de imports, import type, constantes nomeadas)

**(Você DEVE configurar o Auth.js em um arquivo raiz auth.ts e exportar { auth, handlers, signIn, signOut } do NextAuth()) **

**(Você DEVE usar a função unificada auth() para acesso à sessão no lado do servidor - NÃO use as funções obsoletas getServerSession(), getSession() ou getToken()) **

(Você DEVE usar a variável de ambiente AUTH_SECRET - NEXTAUTH_SECRET está obsoleto no v5)

(Você DEVE usar variáveis de ambiente com prefixo AUTH_ para as credenciais dos provedores (ex.: AUTH_GITHUB_ID, AUTH_GITHUB_SECRET) - elas são auto-detectadas)

(Você DEVE dividir a configuração de auth em auth.config.ts (compatível com Edge) e auth.ts (com adaptador) ao usar sessões de banco de dados com middleware)

(Você DEVE verificar a sessão dentro de Server Actions e rotas de API - o middleware sozinho NÃO é suficiente para autorização)

</critical_requirements>

---

Auto-detecção: Auth.js, NextAuth, next-auth, authjs, auth.ts, auth.config.ts, NextAuth(), signIn, signOut, auth(), handlers, SessionProvider, useSession, AUTH_SECRET, provedor OAuth, provedor credentials, adaptador de banco de dados, @auth/prisma-adapter, @auth/drizzle-adapter, callback authorized, callback jwt, callback session, proxy auth, middleware auth

Quando usar:

• Adicionar autenticação a aplicações Next.js, SvelteKit, Express ou Qwik
• Implementar login OAuth (GitHub, Google, Discord, etc.) com mais de 80 provedores integrados
• Construir fluxos de autenticação por email/link mágico
• Precisar de gerenciamento de sessão baseado em JWT ou banco de dados
• Projetos que exigem autenticação de middleware compatível com Edge

Quando NÃO usar:

• Construir um sistema de autenticação personalizado do zero (Auth.js é opinativo)
• Precisar de gerenciamento detalhado de organização/equipe pronto para uso
• Aplicativos exclusivamente mobile sem frontend web
• Precisar de autenticação auto-hospedada com arquitetura de plugins

Principais padrões abordados:

• Configuração de Auth (auth.ts, auth.config.ts)
• Provedores OAuth (GitHub, Google, Credentials, Email)
• Estratégias de sessão (JWT vs banco de dados)
• Acesso à sessão (Server Components, Route Handlers, Client Components)
• Proteção de rotas via middleware/proxy
• Adaptadores de banco de dados (Prisma, Drizzle)
• Callbacks (jwt, session, signIn, redirect)
• Controle de acesso baseado em funções
• Configuração dividida para compatibilidade com Edge

Recursos Detalhados:

• Para frameworks de decisão e antipadrões, consulte reference.md

Padrões principais:

• examples/core.md - Configuração de auth, provedores, callbacks
• examples/session.md - Estratégias de sessão, padrões de acesso à sessão
• examples/middleware.md - Proteção de rotas, middleware, compatibilidade com Edge
• examples/database.md - Adaptadores de banco de dados, Prisma, Drizzle
• examples/patterns.md - Acesso baseado em funções, links mágicos, vinculação de contas

---

Filosofia

Auth.js (v5) consolida a autenticação em uma API única e unificada. A função auth() substitui getServerSession, getSession, withAuth e getToken do v4 para uso no lado do servidor. useSession() permanece a API correta para o lado do cliente. A configuração reside em um arquivo raiz, não em rotas de API.

Princípios fundamentais:

1. Independente de framework - Funciona com Next.js, SvelteKit, Express, Qwik
2. API unificada - Função auth() única para todos os contextos do servidor
3. Ecossistema de provedores - Mais de 80 provedores OAuth integrados com auto-detecção de variáveis de ambiente AUTH_*
4. JWT por padrão - Sessões stateless em cookies criptografados, sem necessidade de banco de dados
5. Compatível com Edge - Middleware executa no runtime Edge com configuração dividida (proxy Next.js 16 executa em Node.js)
6. Complexidade progressiva - Comece com OAuth, adicione adaptador de banco de dados e depois personalize callbacks

---

Padrões Principais

Padrão 1: Configuração de Auth

O arquivo de configuração central exporta tudo que você precisa do NextAuth().

Configuração Básica com OAuth

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

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [
    GitHub, // Auto-detecta AUTH_GITHUB_ID e AUTH_GITHUB_SECRET
    Google, // Auto-detecta AUTH_GOOGLE_ID e AUTH_GOOGLE_SECRET
  ],
});

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

export const { GET, POST } = handlers;

Por que é bom: Um único arquivo de configuração exporta todas as utilitárias de auth, provedores auto-detectam variáveis de ambiente AUTH_*, a rota de API é mínima

Variáveis de Ambiente

# .env.local
AUTH_SECRET="gerar-com-npx-auth-secret"  # Obrigatório
AUTH_GITHUB_ID="seu-github-client-id"       # Auto-detectado pelo provedor GitHub
AUTH_GITHUB_SECRET="seu-github-secret"      # Auto-detectado pelo provedor GitHub
AUTH_GOOGLE_ID="seu-google-id"       # Auto-detectado pelo provedor Google
AUTH_GOOGLE_SECRET="seu-google-secret"

Por que é bom: O prefixo AUTH_ é padronizado no v5, AUTH_SECRET substitui o obsoleto NEXTAUTH_SECRET, provedores auto-detectam credenciais

---

Padrão 2: Provedores

Auth.js suporta autenticação OAuth, email/link mágico e credentials. Mais de 80 provedores OAuth integrados auto-detectam variáveis de ambiente AUTH_*.

// OAuth: personalizar mapeamento de perfil
GitHub({
  profile(profile) {
    return {
      id: String(profile.id),
      name: profile.name ?? profile.login,
      role: "user",
    };
  },
});

// Credentials: validar entrada, retornar null em caso de falha
Credentials({
  async authorize(credentials) {
    const parsed = LoginSchema.safeParse(credentials);
    if (!parsed.success) return null;
    const user = await getUserByEmail(parsed.data.email);
    if (
      !user ||
      !(await verifyPassword(parsed.data.password, user.hashedPassword))
    )
      return null;
    return { id: user.id, name: user.name, email: user.email };
  },
});

Regras principais: Valide a entrada antes da consulta ao banco de dados, sempre faça hash de senhas, retorne null em caso de falha (nunca lance exceções - isso vaza informações). Consulte examples/core.md para implementações completas.

---

Padrão 3: Callbacks

Quatro callbacks personalizam o comportamento da autenticação. O fluxo de dados é: callback jwt (enriquecer token) -> callback session (expor ao cliente).

callbacks: {
  jwt({ token, user }) {
    if (user) { token.id = user.id; token.role = user.role ?? "user"; }
    return token;
  },
  session({ session, token }) {
    session.user.id = token.id as string;
    session.user.role = token.role as string;
    return session;
  },
}

Regras principais: O callback jwt é executado em TODA chamada auth() (mantenha leve), o parâmetro user está presente apenas no sign-in, nunca exponha tokens OAuth ao cliente. Consulte examples/core.md para implementações completas de callbacks, incluindo signIn e redirect.

---

Padrão 4: Acesso à Sessão

A função unificada auth() substitui getServerSession, getSession e getToken do v4 para uso no lado do servidor. useSession() permanece para Client Components.

Contexto	Como acessar a sessão
Server Component	const session = await auth()
Route Handler	export const GET = auth(function GET(req) { req.auth })
Server Action	const session = await auth()
Middleware/Proxy	export { auth as middleware } ou callback authorized
Client Component	useSession() (requer SessionProvider no layout)

Regras principais: Imports do lado do servidor vêm de @/auth, imports do lado do cliente vêm de next-auth/react. Nunca chame auth() em Client Components. Consulte examples/session.md para implementações completas.

---

Padrão 5: Ações de Sign In / Sign Out

Duas abordagens: Server Actions (recomendado, melhoria progressiva) ou lado do cliente.

// Lado do servidor (recomendado): importe de @/auth, use Server Actions em formulários
import { signIn, signOut } from "@/auth";
// Na ação do formulário: await signIn("github", { redirectTo: "/dashboard" })
// Na ação do formulário: await signOut({ redirectTo: "/" })

// Lado do cliente: importe de next-auth/react, use handlers onClick
import { signIn, signOut } from "next-auth/react";
// onClick: signIn("github", { callbackUrl: "/dashboard" })

Regras principais: No lado do servidor, use redirectTo; no lado do cliente, use callbackUrl. signIn() lança uma exceção NEXT_REDIRECT internamente -- não envolva em try/catch esperando um valor de retorno. Consulte examples/core.md para implementações completas.

---

Padrão 6: Extensões TypeScript

Estenda os tipos de sessão e JWT via declaração de mesclagem em types/next-auth.d.ts. Declare campos personalizados (ex.: id, role) nas interfaces Session, User e JWT usando & DefaultSession["user"] para preservar os padrões. Consulte examples/core.md para o exemplo completo de declaração de tipos.

---

Guia de Integração

Auth.js é a camada de autenticação. Ele lida com verificação de identidade, gerenciamento de sessão e proteção de rotas. Ele NÃO lida com lógica de autorização (verificações de função, sistemas de permissão) -- isso é código da aplicação.

Suporte a frameworks: Auth.js funciona com vários frameworks web através de pacotes específicos (next-auth, @auth/sveltekit, @auth/express).

Adaptadores de banco de dados: Para sessões em banco de dados, o Auth.js fornece pacotes de adaptadores (@auth/prisma-adapter, @auth/drizzle-adapter, etc.) que se integram ao seu ORM. Consulte examples/database.md.

A estratégia de sessão depende das suas necessidades:

• JWT (padrão) - Sem necessidade de banco de dados, funciona no Edge, stateless
• Banco de dados - Requer adaptador, armazenamento de sessão no servidor, suporta revogação imediata

O Auth.js NÃO lida com: autorização/RBAC detalhado, limitação de taxa ou consultas de banco de dados além da autenticação -- essas são preocupações da aplicação.

---

<red_flags>

SINALIZADORES VERMELHOS

• Usar getServerSession(authOptions) -- obsoleto no v5; use auth() do seu auth.ts
• Usar NEXTAUTH_SECRET ou NEXTAUTH_URL -- obsoleto; use AUTH_SECRET (URL é auto-detectada)
• Provedor Credentials sem limitação de taxa -- vulnerável a ataques de força bruta
• Expor tokens OAuth ao cliente via callback session -- mantenha accessToken/refreshToken apenas no servidor
• Middleware/proxy como única autorização -- executa antes da renderização, mas não substitui verificações por rota em Server Actions/rotas de API
• Adaptador de banco de dados importado no middleware -- ORMs de banco de dados não podem executar no runtime Edge (Next.js 14/15); divida a configuração em auth.config.ts + auth.ts
• Envolver signIn() em try/catch -- ele lança uma exceção NEXT_REDIRECT internamente (isso é intencional)
• Callback jwt consultando banco de dados a cada chamada -- é executado em TODA invocação auth(); mantenha leve

Consulte reference.md para a lista completa de antipadrões, pegadinhas e tabela de migração.

</red_flags>

---

<critical_reminders>

LEMBRETES CRÍTICOS

Todo o código deve seguir as convenções do projeto em CLAUDE.md

**(Você DEVE configurar o Auth.js em um arquivo raiz auth.ts e exportar { auth, handlers, signIn, signOut } do NextAuth()) **

**(Você DEVE usar a função unificada auth() para acesso à sessão no lado do servidor - NÃO use as funções obsoletas getServerSession(), getSession() ou getToken()) **

(Você DEVE usar a variável de ambiente AUTH_SECRET - NEXTAUTH_SECRET está obsoleto no v5)

(Você DEVE usar variáveis de ambiente com prefixo AUTH_ para as credenciais dos provedores (ex.: AUTH_GITHUB_ID, AUTH_GITHUB_SECRET) - elas são auto-detectadas)

(Você DEVE dividir a configuração de auth em auth.config.ts (compatível com Edge) e auth.ts (com adaptador) ao usar sessões de banco de dados com middleware)

(Você DEVE verificar a sessão dentro de Server Actions e APIs - o middleware sozinho NÃO é suficiente para autorização)

A falha em seguir estas regras causará falhas de autenticação, exporá padrões obsoletos ou criará vulnerabilidades de segurança.

</critical_reminders>