ligbox-ops-platform/specs/004-desk-account-management/spec.md

Feature Specification: Desk Account Management & Registration (004)

Criado: 2026-06-10
Concluído: 2026-06-10
Status: ✅ FECHADA — entregue e validada (+ extensão 2FA recovery 2026-06-16)
API: 0.9.4-desk-2fa-recovery
Depende de: Spec 003 (desk-auth-rbac)
Validado por: Roger — cadastro, ativação, e-mail VM108, QR TOTP, login MFA, Minha conta

---

Resumo

Fluxo completo para equipe técnica e ops do Ligbox Ops Desk:

cadastro → aprovação root → ativação 2-de-3 → login → Minha conta (troca de senha)

E-mail operacional via VM108 (@ligbox.com.br). UI em pt-BR.

---

Decisões confirmadas (Roger)

Ponto	Decisão
2FA ativação	Três fatores — candidato completa qualquer 2 de 3
Perfil	Root escolhe na aprovação (ops_lead, technician, noc)
Login	E-mail é o username
Usuários seed	root, admin, mini, noc — sem cadastro
Idioma	Português do Brasil (pt-BR)
E-mail	Ligbox — @ligbox.com.br via VM108 (Carbonio)
Telefone OTP	Por e-mail (SMS futuro)
ntfy	Opcional — ntfy.sh (sem instalar na VM122)
Troca de senha	Self-service em Minha conta; TOTP obrigatório se 2FA ativo
Recuperação 2FA	Link Perdi acesso ao autenticador no login — OTP e-mail + novo QR
Códigos backup	10 códigos de uso único na ativação (e após recuperação)

Regra 2-de-3 (ativação)

#	Fator	Método
1	E-mail	OTP 6 dígitos
2	Telefone	OTP 6 dígitos (por e-mail)
3	App autenticador	QR TOTP + ntfy opcional

---

Fluxo completo (entregue)

flowchart TD
    A[register.html] --> B[Pedido + ticket + e-mail root]
    B --> C[Root aprova — Mensagens]
    C --> D[E-mail + link activate.html]
    D --> E[2 de 3 fatores — 3 colunas]
    E --> F[Conta ativa]
    F --> G{totp_enabled?}
    G -->|Sim| H[Login senha + TOTP]
    G -->|Não| I[Login senha]
    H --> J[Minha conta]
    I --> J
    J --> K[Trocar senha — TOTP se ativo]

---

Componentes entregues

Componente	Estado
register.html	✅ PRG → login
activate.html	✅ 3 colunas, QR local, progresso, ntfy
login.html	✅ MFA step
index.html — Mensagens / Admin / Minha conta	✅
Postfix VM122 → LMTP VM108	✅
ligbox-ops@ligbox.com.br	✅
pyotp + /login/mfa	✅
ntfy push OTP	✅
Tickets cadastro	✅
pt-BR (UI + API + e-mails)	✅
POST /change-password	✅
Formulário Minha conta estável	✅ sem refresh apagando campos

---

API (v0.8)

Método	Endpoint	Descrição
POST	/api/v1/auth/register	Novo pedido
GET	/api/v1/auth/registration-requests	Lista (root)
POST	/api/v1/auth/registration-requests/{id}/approve	Aprovar
POST	/api/v1/auth/registration-requests/{id}/reject	Rejeitar
GET	/api/v1/auth/activate?token=	QR + fatores
POST	/api/v1/auth/activate/send-email-otp	OTP e-mail
POST	/api/v1/auth/activate/send-phone-otp	OTP telefone
POST	/api/v1/auth/activate	2 de {email, phone, totp}
POST	/api/v1/auth/login	Pode retornar mfa_required
POST	/api/v1/auth/login/mfa	Conclui login TOTP
GET	/api/v1/auth/me	Perfil + totp_enabled
POST	/api/v1/auth/change-password	Troca senha (TOTP se ativo)
POST	/api/v1/auth/login/mfa	TOTP ou backup_code
POST	/api/v1/auth/mfa-recovery/send-email	OTP e-mail (sessão 2FA ativa)
POST	/api/v1/auth/mfa-recovery/verify-email	Valida OTP → recovery_token + QR
GET	/api/v1/auth/mfa-recovery/setup	QR pendente (recovery)
POST	/api/v1/auth/mfa-recovery/complete	Novo TOTP + JWT + backup codes

POST /change-password

{
  "current_password": "senha-atual",
  "new_password": "nova-senha-min-8",
  "totp_code": "123456"
}

• totp_code obrigatório quando totp_enabled = true (protege sessão abandonada)
• Nova senha ≠ senha atual; mínimo 8 caracteres

---

UI — telas principais

activate.html

• 3 colunas responsivas · QR em /assets/qrcode.min.js
• Barra X/2 fatores · link ntfy

Minha conta (todos os perfis)

• Dados do perfil (e-mail, role, último login, 2FA)
• Formulário: senha atual · nova · confirmar · TOTP (se ativo)
• Refresh automático não re-renderiza esta tela (preserva digitação)

---

E-mail (arquitetura)

VM	Função
108	Mail Ligbox — mail.ligbox.com.br → LMTP :7025
112	Legado Ibytera — @ibytera.com, @dratcoin.com
122	Postfix local — roteamento por domínio

Env Desk: ligbox-ops@ligbox.com.br · notificações root: admin@ligbox.com.br

Redirect temporário Postfix: @itecnologys.com → @ligbox.com.br

Docs: docs/email-ligbox-vm108.md · docs/postfix-vm122.md

---

Critérios de aceite — todos ✅

• Cadastro com aprovação root
• Ativação 2-de-3 (e-mail, telefone, TOTP)
• QR code funcional (biblioteca local)
• OTP e-mail via VM108
• Login MFA quando TOTP configurado
• Tickets e notificações
• UI pt-BR
• Minha conta — troca de senha self-service
• TOTP obrigatório na troca de senha (se 2FA ativo)
• Recuperação 2FA — perdi autenticador (e-mail OTP + novo QR)
• Códigos backup — 10× uso único na ativação e após recuperação
• Login MFA aceita código de backup
• Formulário Minha conta persistente ao digitar
• Validação E2E Roger — aprovado

---

Fora de escopo (futuro)

Item	Notas
SMS telefone	OTP continua por e-mail
ntfy self-hosted	Usar ntfy.sh por ora
Log auditoria senhas	Backlog ops
Remover redirect @itecnologys.com	Após migrar caixas VM108
must_change_password no 1º login	Opcional v2.1
Regenerar backup codes em Minha conta	Requer TOTP — backlog

---

Referências

• Spec 003 — auth/RBAC
• specs/004-desk-account-management/tasks.md
• specs/004-desk-account-management/quickstart.md
• .cursor/rules/portugues-brasil.mdc