first commit

.codex/plans/IMPLEMENTACAO_INICIAL.md

@@ -0,0 +1,187 @@
+# Plano minimo de implementacao — comunicacao entre servicos com JWT
+
+## Objetivo
+
+Implementar comunicacao minima entre servicos distribuidos onde:
+
+- o **Auth Service** autentica o usuario
+- o **Auth Service** emite o **JWT**
+- os outros servicos **validam o JWT localmente**
+- um servico pode chamar outro **em nome do usuario**, repassando o mesmo token
+- cada servico identifica o usuario autenticado pelo `sub`
+
+---
+
+## Arquitetura minima
+
+### Auth Service
+Responsavel por:
+
+- login
+- refresh token
+- emissao do JWT
+- distribuicao da chave publica para validacao nos demais servicos
+
+### Outros servicos
+Responsaveis por:
+
+- receber `Authorization: Bearer <token>`
+- validar JWT localmente
+- extrair claims
+- montar contexto do usuario autenticado
+
+### Comunicacao entre servicos
+Quando um servico chamar outro em nome do usuario:
+
+- repassar o mesmo header `Authorization`
+
+---
+
+## Contrato minimo do JWT
+
+Exemplo:
+
+```json
+{
+  "sub": "uuid-do-usuario",
+  "iss": "https://auth.seusistema.com",
+  "aud": "internal-apis",
+  "iat": 1776110000,
+  "exp": 1776110900
+}
+```
+
+### Claims minimas
+
+- `sub`: identificador do usuario
+- `iss`: emissor
+- `aud`: audiencia
+- `iat`: emissao
+- `exp`: expiracao
+
+### Regra importante
+
+O identificador confiavel do usuario deve ser sempre o **`sub`**.
+
+Nao confiar em:
+
+- `user_id` no body
+- `x-user-id` em header customizado
+- qualquer identificador separado do token
+
+---
+
+## Escolhas tecnicas minimas
+
+### Algoritmo
+- `RS256`
+
+### Assinatura
+- Auth assina com chave privada
+- demais servicos validam com chave publica
+
+### Tempo de vida (MVP)
+- access token: 15 minutos
+- refresh token: 7 dias
+
+---
+
+## Endpoints minimos do Auth
+
+```http
+POST /auth/login
+POST /auth/refresh
+```
+
+### Login
+Retorna:
+
+```json
+{
+  "access_token": "jwt_aqui",
+  "refresh_token": "refresh_aqui",
+  "token_type": "Bearer",
+  "expires_in": 900
+}
+```
+
+### Refresh
+Recebe refresh token e retorna novo access token + novo refresh token.
+
+## Middleware minimo em cada servico
+
+Passos:
+
+1. ler `Authorization`
+2. extrair bearer token
+3. validar assinatura
+4. validar `exp`
+5. validar `iss`
+6. validar `aud`
+7. extrair claims
+8. montar usuario autenticado no contexto da requisicao
+
+Resultado esperado no contexto:
+
+```json
+{
+  "id": "uuid-do-usuario"
+}
+```
+
+---
+
+## Rotas protegidas minimas para teste
+
+- `GET /profile/me`
+- `GET /dashboard`
+
+Cada rota deve:
+
+- exigir token valido
+- extrair `sub`
+- retornar dados do usuario autenticado
+
+---
+
+## Ordem minima de implementacao
+
+1. definir contrato do token
+2. gerar chaves
+3. implementar `login`, `refresh`
+4. emitir JWT corretamente
+5. implementar middleware JWT em 1 servico consumidor
+6. proteger 1 rota simples
+7. replicar middleware nos demais servicos
+8. implementar propagacao de `Authorization` entre servicos
+
+---
+
+## Criterios de sucesso do MVP
+
+1. login retorna `access_token`
+2. acesso direto a rota protegida funciona
+3. token invalido retorna `401`
+4. token expirado retorna `401`
+5. chamada A -> B preserva o mesmo `sub`
+
+---
+
+## Fora de escopo agora
+
+- blacklist de tokens
+- revogacao imediata global
+- introspection por request
+- machine-to-machine token
+- gateway avancado
+
+---
+
+## Resumo executivo
+
+O minimo para funcionar:
+
+1. Auth emitir JWT assinado
+2. servicos validarem localmente
+3. `sub` como identificador confiavel
+4. propagacao do mesmo bearer token entre servicos