ligbox-ops-platform/specs/032-purge-domain-extra-auth/spec.md

Spec 032 — Purge domínio: autorização extra (códigos Infra)

Criado: 2026-06-19
Solicitado por: Roger
Prioridade: P1 (domínios críticos / conferência)
Status: ✅ Implementado (Desk VM122, 2026-06-19)
Sistema: Desk VM122 · página Infra + Serviços (Spec 018)
Relacionado: Spec 017 (purge domínio) · Spec 018 (orquestração Serviços) · Spec 003 (RBAC)

---

Resumo

Domínios em PURGE_EXTRA_AUTH_DOMAINS (inicial: myvexx.com) não podem ser apagados em Serviços apenas com confirmação do domínio + senha Root.

Exigem um código de autorização gerado pelo super_admin (root) em Infraestrutura, com senha Root, para uso em conferência com quem executa o purge.

Motivo: evitar purge acidental ou não autorizado de tenants críticos / produção, mantendo o fluxo Spec 017 para o resto dos domínios.

---

Níveis de proteção purge

Nível	Domínios	Requisitos purge
Blocklist	ligbox.com.br, itecnologys.com	Purge proibido (HTTP 400)
Extra auth	myvexx.com (+ lista configurável)	Senha Root + código autorização (uso único)
Normal	restantes	Senha Root + confirmação domínio (Spec 017)

---

Fluxo operacional (conferência)

1. Root abre Infraestrutura → card «Códigos autorização purge».
2. Preenche domínio (myvexx.com), nota opcional (ex.: ticket, call), validade (horas), senha Root.
3. Sistema gera código formato XXXX-XXXX — mostrado uma vez; root comunica na call.
4. Operador (Admin) abre Serviços → modal purge do domínio.
5. Preenche confirmação domínio, senha Root e código autorização.
6. Purge segue fluxo Spec 017 (job async + drawer + histórico).

---

RBAC

Acção	Perfil
Gerar código (Infra)	super_admin apenas
Listar códigos activos (Infra)	super_admin apenas
Executar purge (com código)	super_admin, ops_lead + senha Root
Ver domínios protegidos	qualquer utilizador autenticado (API metadata)

Geração exige senha Root do utilizador root em desk_users (mesma validação do purge Spec 017).

---

API Desk (VM122)

Metadata

Método	Path	Descrição
GET	/api/v1/infra/purge-auth-domains	Lista PURGE_EXTRA_AUTH_DOMAINS + can_generate

Geração / listagem (super_admin)

Método	Path	Descrição
POST	/api/v1/infra/purge-auth-codes	Gera código (body abaixo)
GET	/api/v1/infra/purge-auth-codes?active_only=1&limit=50	Códigos activos (sem revelar hash)

Body POST geração:

{
  "domain": "myvexx.com",
  "root_password": "********",
  "note": "Autorizado call Roger 19/06",
  "ttl_hours": 24
}

Resposta (única exibição do código):

{
  "ok": true,
  "id": "a1b2c3d4e5f67890",
  "domain": "myvexx.com",
  "code": "D25C-0B12",
  "expires_at": "2026-06-20T22:06:39+00:00",
  "ttl_hours": 24,
  "note": "Autorizado call Roger 19/06"
}

Purge (Spec 017 — campo extra)

Todos os endpoints purge aceitam campo opcional:

{
  "confirm_domain": "myvexx.com",
  "root_password": "********",
  "purge_auth_code": "D25C-0B12"
}

Situação	HTTP
Domínio extra-auth sem código	403 — exige código gerado em Infra
Código inválido / expirado / já usado	403
Domínio blocklist	400

Detalhe domínio (GET /api/v1/vm112/domains/{domain}) inclui:

• purge_extra_auth_required: true para domínios extra-auth
• purge_blocked: true para blocklist

---

Persistência

Campo	Valor
Base	/var/lib/ligbox-ops-platform/ops.db (Docker: /data/ops.db)
Tabela	purge_auth_codes
Código	Hash bcrypt — não recuperável após geração
Uso	Único — used_at + used_by ao validar no purge
TTL	1–168 h (env PURGE_AUTH_CODE_TTL_HOURS default 24)

Colunas: id, domain, code_hash, note, created_by, created_at, expires_at, used_at, used_by.

---

UI Desk

Infraestrutura

Card «Códigos autorização purge»:

• Lista domínios protegidos
• Formulário geração (super_admin)
• Tabela códigos activos (domínio, nota, expira, criador)
• Código gerado em destaque — copiar na conferência

Serviços (Spec 018)

Modal purge do domínio:

• Se purge_extra_auth_required: campo «Código autorização purge»
• Aviso: gerar em Infra (root)
• Validação client-side: campo obrigatório se visível

---

Implementação (referência)

Ficheiro	Alteração
api/app/vm112_domains.py	PURGE_EXTRA_AUTH_DOMAINS, requires_purge_extra_auth()
api/app/purge_auth_codes.py	Schema, geração, validação, consumo
api/app/purge_auth_routes.py	Rotas /api/v1/infra/purge-auth-*
api/app/vm112_domains_routes.py	purge_auth_code no body purge
api/app/main.py	Router + init_purge_auth_schema no startup
frontend/assets/app.js	renderPurgeAuthInfraPanel()
frontend/assets/servicos.js	Campo código no purge
frontend/assets/styles.css	Estilos card/código

Commit: a39618a (VM130 ligbox-ops-platform)

---

Critérios de aceitação

1. myvexx.com purge falha sem purge_auth_code (403).
2. Root gera código em Infra com senha Root → código XXXX-XXXX exibido uma vez.
3. Purge com código válido + senha Root → job inicia (Spec 017).
4. Segundo purge com mesmo código → 403 (código consumido).
5. Código expirado → 403.
6. technician / noc não vêem form de geração em Infra.
7. Domínios blocklist continuam impossíveis de purge.
8. Detalhe domínio em Serviços mostra campo código só para extra-auth.

---

Fora de escopo

• Códigos reutilizáveis ou multi-domínio
• Notificação push/email do código
• Integração OTRS/ticket automático ao gerar
• Histórico de códigos usados na UI Eventos (só listagem activos em Infra)
• Geração via CLI/SSH (apenas UI Infra + API)

---

Evolução

Item	Prioridade
Adicionar domínios a PURGE_EXTRA_AUTH_DOMAINS via env/config	P2
Audit log dedicado «código gerado / consumido»	P2
Link Serviços → Infra para domínios protegidos	P3

---

Conclusão

A Spec 032 complementa a 017: o purge completo mantém-se igual, mas domínios críticos exigem dupla confirmação (senha Root + código de conferência gerado pelo root em Infra).

Domínio inicial protegido: myvexx.com