Módulo 01: Autenticação & Acesso

Status: Rascunho Inicial

---

1. Contratos de API (RESTful)

1.1 Login e Sessão

POST /api/auth/login
  Body: { email, senha, tenant_id? }
  Return: { access_token, refresh_token, expires_in, usuario: { id, nome, role, time_id } }

POST /api/auth/logout
  Header: Authorization Bearer {token}
  Return: 204 No Content

POST /api/auth/refresh
  Body: { refresh_token }
  Return: { access_token, expires_in }

GET  /api/auth/me
  Header: Authorization Bearer {token}
  Return: { id, nome, email, role, time, tenant, ultimo_acesso }

1.2 Recuperação de Senha

POST /api/auth/recuperar-senha
  Body: { email }
  Return: 200 OK (sempre, independente de o e-mail existir para prevenir enumeração)

POST /api/auth/redefinir-senha
  Body: { token, nova_senha, confirmar_senha }
  Return: 200 OK | 400 token inválido/expirado

1.3 Registro & Convite

POST /api/auth/registrar
  Body: { nome, email, telefone, cpf, senha, aceite_termos: bool, aceite_privacidade: bool, token_convite? }
  Return: { usuario_id, status: "ATIVO | PENDENTE_VALIDACAO | PENDENTE_APROVACAO" }

POST /api/auth/validar-email
  Body: { token }
  Return: 200 OK | 400 expirado

GET  /api/convites/{token}
  Return: { valido: bool, role, time_id, expirado: bool }

POST /api/convites
  Header: Authorization (Gestor ou Admin)
  Body: { email, role, time_id, expira_em? }
  Return: { token, link_completo, expira_em }

1.4 Termos & Privacidade

GET  /api/termos/vigente
  Return: { versao, conteudo_html, publicado_em }

GET  /api/privacidade/vigente
  Return: { versao, conteudo_html, publicado_em }

POST /api/auth/aceitar-termos
  Header: Authorization Bearer {token}
  Body: { versao_termos, versao_privacidade }
  Return: 200 OK

---

Usuário

{
  "id": "uuid",
  "tenant_id": "uuid",
  "nome": "string",
  "email": "string",
  "cpf": "string",
  "telefone": "string",
  "role": "CONSULTOR | GESTOR | VISTORIADOR | GERENTE | ADMIN",
  "time_id": "uuid | null",
  "status": "ATIVO | PENDENTE_VALIDACAO | PENDENTE_APROVACAO | SUSPENSO | INATIVO",
  "aceites": {
    "termos_versao": "1.0",
    "termos_aceito_em": "datetime",
    "privacidade_versao": "1.0",
    "privacidade_aceito_em": "datetime"
  },
  "seguranca": {
    "tentativas_login": 0,
    "bloqueado_ate": "datetime | null",
    "ultimo_login": "datetime",
    "ultimo_ip": "string"
  },
  "criado_em": "datetime",
  "atualizado_em": "datetime"
}

---

3. Segurança e Boas Práticas (Criptografia)

Item	Padrão Adotado
Algoritmo de senha	bcrypt (custo 12)
JWT — access token	Expira em 15 min
JWT — refresh token	Expira em 7 dias (renovável)
Transporte	HTTPS obrigatório via gateway
Tokens de recuperação	SHA-256, single-use, 60 min de expiração
Logs de acesso	IP + User Agent + timestamp (armazenado por tenant)