Ryanzucchi/Eldritch_Lich / .agents/skills/autenticacao-jwt-e-refresh-token
autenticacao-jwt-e-refresh-token
VerifiedImplementa autenticação stateless com JWT de curta duração e refresh token rotativo em HTTPOnly cookie. Ativar ao implementar ou auditar o sistema de login, registro, logout e proteção de rotas da plataforma SaaS.
autenticacao-jwt-e-refresh-token
Descrição
A skill autenticacao-jwt-e-refresh-token especifica o fluxo completo de autenticação stateless para a plataforma SaaS de escrita criativa. Ela define a geração de Access Tokens JWT (15 minutos de validade) e Refresh Tokens rotativos (30 dias, armazenados em HTTPOnly cookie), a estratégia de revogação de sessões e a proteção contra roubo de token via rotação obrigatória.
Quando usar
Gatilhos concretos e observáveis:
- Implementação do módulo
autenticacao_perfil(UC-129, UC-130, UC-214). - Revisão de segurança do fluxo de login/logout.
- Implementação do login social (Google, GitHub) via OAuth 2.0 (UC-237).
Quando NÃO usar:
- Para controle de permissões por recurso (usar skill
autorizacao-rbac-por-recurso). - Para criptografia de dados em repouso no banco (escopo de infraestrutura, não de autenticação).
Pré-requisitos
- Biblioteca JWT:
jsonwebtoken(Node.js) oupython-jose(FastAPI). - Banco de dados com tabela
refresh_tokens(campos:token_hash,user_id,expires_at,revoked,family_id). - HTTPS obrigatório em produção (Refresh Token em HTTPOnly cookie é inútil sem TLS).
Processo (passo a passo executável)
-
Login (Geração de Par de Tokens):
- Validar credenciais do usuário (email/senha com bcrypt).
- Gerar Access Token JWT:
{ sub: user_id, role, tenant_id, exp: now+15min }assinado comRS256(chave privada). - Gerar Refresh Token: UUID aleatório criptograficamente seguro (
crypto.randomUUID()). - Persistir o hash SHA-256 do Refresh Token na tabela
refresh_tokenscomfamily_id(UUID único por família de sessão). - Retornar o Access Token no corpo da resposta JSON e o Refresh Token em cookie
Set-Cookie: refreshToken=<value>; HttpOnly; Secure; SameSite=Strict; Path=/api/auth/refresh; Max-Age=2592000.
-
Uso do Access Token (Rotas Protegidas):
- Middleware de autenticação extrai o Bearer token do header
Authorization. - Verificar a assinatura com a chave pública RS256 e a expiração.
- Injetar
{ user_id, role, tenant_id }no contexto da requisição.
- Middleware de autenticação extrai o Bearer token do header
-
Renovação (Refresh Token Rotation):
- Endpoint
POST /api/auth/refreshlê o cookierefreshToken. - Buscar o hash do token na tabela
refresh_tokens. Se não encontrado ou revogado → retornar 401. - Rotação: Revogar o Refresh Token usado e gerar um novo par (Access + Refresh) com o mesmo
family_id. - Se o mesmo Refresh Token for usado duas vezes (roubo detectado): revogar toda a família de tokens (todos os registros com o mesmo
family_id).
- Endpoint
-
Logout:
- Revogar o Refresh Token atual (
revoked = true) na tabela. - Limpar o cookie
refreshTokencomSet-Cookie: refreshToken=; Max-Age=0.
- Revogar o Refresh Token atual (
Parâmetros e configuração
| Parâmetro | Descrição | Padrão |
|---|---|---|
ACCESS_TOKEN_TTL | Duração do Access Token JWT | 15min |
REFRESH_TOKEN_TTL | Duração do Refresh Token | 30d |
JWT_ALGORITHM | Algoritmo de assinatura JWT | RS256 |
COOKIE_SAMESITE | Política SameSite do cookie de refresh | Strict |
Armadilhas e como evitá-las
-
Armadilha: Armazenar o Refresh Token no
localStoragedo navegador, expondo-o a ataques XSS que podem roubar e usar o token indefinidamente. Mitigação: Armazenar o Refresh Token exclusivamente em cookieHttpOnly; Secure; SameSite=Strict. O JavaScript da página nunca terá acesso ao valor. O Access Token (de curta duração) pode ficar em memória (variável JavaScript) sem persistência em storage. -
Armadilha: Não implementar a detecção de roubo por reuso de Refresh Token. Se um token for comprometido, o atacante consegue renovar sessões indefinidamente sem ser detectado. Mitigação: Implementar a revogação de família completa: ao detectar o reuso de um Refresh Token já rotacionado, revogar todos os tokens da família (
family_id) imediatamente, forçando o usuário legítimo a fazer login novamente.
Critérios de validação (Definition of Done)
- O Access Token expira em 15 minutos e não pode ser renovado sem um Refresh Token válido.
- O reuso de um Refresh Token rotacionado revoga toda a sessão da família em 100% dos testes de detecção de roubo.
- O cookie de Refresh Token possui os atributos
HttpOnly,SecureeSameSite=Strictem produção.
Exemplos
Login bem-sucedido:
Response body: { "accessToken": "eyJhbGci..." }
Set-Cookie: refreshToken=<uuid>; HttpOnly; Secure; SameSite=Strict; Path=/api/auth/refresh; Max-Age=2592000
Detecção de roubo: Token da família F-001 já foi rotacionado (B → C). Atacante envia token B novamente. Sistema revoga tokens B, C e quaisquer outros da família F-001. Usuário legítimo é desconectado na próxima requisição.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |