saveinmed/docs/PLANO_BACKEND_AUTENTICACAO_ACESSO.md

Plano de Execução Backend (Autenticação + Níveis de Acesso)

Este documento detalha, em ordem de prioridade, o que deve ser implementado no backend para destravar o produto, começando por autenticação e níveis de acesso. A ideia é evoluir sem quebrar o que já existe.

0) Princípios de execução (não quebrar o que já foi feito)

1. Compatibilidade com o fluxo atual: preservar contratos de API existentes (ex.: /auth/login, /auth/refresh, /auth/me).
2. Evolução incremental: cada etapa deve ser entregue com migrações e feature flags quando necessário.
3. Observabilidade mínima: logs estruturados para autenticação e autorização (sucesso/falha).
4. Segurança desde o início: hash de senha, JWT com expiração curta e refresh tokens.

---

1) Autenticação (Prioridade Máxima)

1.1. Modelo de dados base

• Usuário (users)

  • id (UUID)
  • email (unique)
  • password_hash
  • status (active, pending, blocked)
  • created_at, updated_at

• Refresh tokens (refresh_tokens)

  • id (UUID)
  • user_id (FK users)
  • token_hash
  • expires_at
  • created_at, revoked_at

Entrega mínima: tabelas + migrações + seed de admin inicial.

1.2. Endpoints mínimos

1. POST /auth/login
   • Entrada: email, password.
   • Saída: accessToken, refreshToken, expiresIn, user.
   • Opcional recomendado: setar cookie httpOnly com refresh token.
2. POST /auth/refresh
   • Entrada: refreshToken (body) ou cookie httpOnly.
   • Saída: accessToken, refreshToken (rotacionado).
3. POST /auth/logout
   • Entrada: refreshToken (body) ou cookie httpOnly.
   • Saída: 204.
4. GET /auth/me
   • Requer bearer token.
   • Saída: user + roles + permissions.

1.3. Segurança mínima

• Senha: bcrypt (>= 10 rounds).
• JWT: access token curto (15–30min), refresh token longo (7–30 dias).
• Rotação: refresh token rotacionado a cada uso (revoga o anterior).
• Bloqueio: usuário com status=blocked não autentica.
• Cookie: refresh token em cookie httpOnly, sameSite=lax e secure em produção.

1.4. Infra/Configuração

• Variáveis de ambiente:
  • JWT_ACCESS_SECRET, JWT_REFRESH_SECRET.
  • JWT_ACCESS_TTL, JWT_REFRESH_TTL.
  • BCRYPT_ROUNDS.
  • COOKIE_DOMAIN, COOKIE_SECURE (quando aplicável).

---

2) Autorização por níveis de acesso (RBAC)

2.1. Modelo de dados

• Roles (ex.: SUPERADMIN, ADMIN, GERENTE, COMPRADOR)
  • roles: id, name, description
• Permissions (ex.: catalog.read, orders.create)
  • permissions: id, name, description
• Relações
  • user_roles: user_id + role_id
  • role_permissions: role_id + permission_id

2.2. Middleware/Guards

• Guard JWT: valida token.
• Guard Roles: verifica se o usuário possui role necessária.
• Guard Permissions: verifica permissão específica.

2.3. Padrão de uso (contrato)

• Em cada controller/rota protegida:
  • @UseGuards(JwtAuthGuard, RolesGuard)
  • @Roles('ADMIN')
  • @Permissions('orders.create')

---

3) Escopo multi-empresa (tenant/empresa)

3.1. Modelo de dados

• Empresas (companies)
  • id, name, cnpj, status
• Vínculo usuário-empresa
  • company_users: company_id + user_id + role_id

3.2. Guard de empresa ativa

• Todo usuário precisa de uma empresa ativa para acessar recursos de negócio.
• Middleware valida company_id no token ou header, e injeta em contexto.

---

4) Gestão de usuários (Backoffice / Admin)

4.1. Endpoints mínimos

• POST /users (criar usuário)
• GET /users (listar)
• PATCH /users/:id (status/roles)
• POST /users/:id/reset-password

4.2. Fluxo de convite

• Usuário criado com status=pending.
• Envia convite por e-mail para definir senha.
• Após definição de senha → status=active.

---

5) Auditoria e logs

• Tabela de auditoria
  • audit_logs: user_id, action, resource, metadata, created_at.
• Eventos críticos
  • login, refresh, mudança de role, alteração de status.

---

6) Checklist final (destravar)

1. ✅ Auth login/refresh/me funcionando
2. ✅ Token guard aplicado nas rotas críticas
3. ✅ RBAC aplicado nas rotas admin
4. ✅ Vínculo usuário↔empresa definido
5. ✅ Logs de auditoria básicos

---

7) Ordem sugerida de execução (passo a passo)

1. Criar schema de users + refresh_tokens.
2. Implementar /auth/login, /auth/refresh, /auth/me.
3. Adicionar middleware JWT e garantir /auth/me protegido.
4. Criar schema RBAC (roles, permissions, user_roles).
5. Implementar Guards Roles e Permissions.
6. Introduzir companies e company_users.
7. Guard de empresa ativa (multi-tenant).
8. Endpoints de gestão de usuários (admin).
9. Auditoria mínima.

---

8) Notas para manter compatibilidade

• Não renomear endpoints existentes.
• Manter payloads de login/refresh para o front atual.
• Adicionar campos novos sem remover antigos.

---

9) Recomendação — Próximo item prioritário (checklist detalhado)

Baseado no plano de autenticação do backend, o próximo passo é solidificar o core de autenticação e preparar a base de RBAC.

Backend: core de autenticação

• Criar/validar schema de users e refresh_tokens (incluindo UUIDs e hash do token).
• Implementar/validar POST /auth/login com retorno de accessToken + refreshToken.
• Implementar/validar POST /auth/refresh com rotação de refresh token (body e cookie httpOnly).
• Implementar/validar GET /auth/me protegido por bearer token.
• Aplicar regras mínimas de segurança (bcrypt, TTLs, bloqueio de usuário).
• Definir política de cookies (httpOnly, sameSite, secure) e logout com limpeza do cookie.

Backend: base de autorização (RBAC)

• Criar schema de roles, permissions, user_roles, role_permissions.
• Implementar guards de JWT, Roles e Permissions nos controllers-chave.