ADR-0003 · Autenticação por sessão em cookie com Better Auth

Status: aceito · Data: 2025 (substitui a abordagem JWT + refresh token)

Contexto

A primeira versão da V2 usava JWT de acesso (15 min) com refresh token (7 dias). Isso exigia lógica de renovação no front, tokens acessíveis ao JavaScript e revogação difícil.

Decisão

Usar Better Auth dentro do Next.js (/api/auth/*) com sessão persistida no PostgreSQL e cookie moldape.session_token HttpOnly, com validade de 30 dias, compartilhado entre moldape.com e api.moldape.com (crossSubDomainCookies). O Fastify valida o token contra o banco, com cache no Redis. Plugins: admin (papéis, banimento, listagem), jwt e openAPI.

Consequências

• ➕ O token não fica exposto ao JavaScript; revogar é apagar a sessão.
• ➕ O painel de acessos usa a API de admin do Better Auth.
• ➖ API e front precisam estar no mesmo domínio registrável.
• ➖ Restaram dependências e variáveis JWT (jsonwebtoken, jose, JWT_*) que podem ser limpas.