Merge pull request #72 from rede5/codex/expand-backend-authentication-plan
Add backend authentication and access execution plan
This commit is contained in:
Tiago Yamamoto
GitHub
commit
2208d559e9
1 changed files with 163 additions and 0 deletions
163
docs/PLANO_BACKEND_AUTENTICACAO_ACESSO.md
Normal file
163
docs/PLANO_BACKEND_AUTENTICACAO_ACESSO.md
Normal file
|
|
@ -0,0 +1,163 @@
|
||||||
|
# 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`.
|
||||||
|
2. `POST /auth/refresh`
|
||||||
|
- Entrada: `refreshToken`.
|
||||||
|
- Saída: `accessToken`, `refreshToken` (rotacionado).
|
||||||
|
3. `POST /auth/logout`
|
||||||
|
- Entrada: `refreshToken`.
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
### 1.4. Infra/Configuração
|
||||||
|
|
||||||
|
- Variáveis de ambiente:
|
||||||
|
- `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`.
|
||||||
|
- `JWT_ACCESS_TTL`, `JWT_REFRESH_TTL`.
|
||||||
|
- `BCRYPT_ROUNDS`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
Loading…
Reference in a new issue