Docs: Spec 032 purge extra-auth codes and cross-refs in 017.

Document Infra authorization codes for protected domains (myvexx.com) and update backlog.
2026-06-19 22:22:14 +00:00 · 2026-06-19 22:22:14 +00:00 · 2168d432f7
commit 2168d432f7
parent a39618afb8
4 changed files with 236 additions and 2 deletions
--- a/BACKLOG.md
+++ b/BACKLOG.md
@ -1,6 +1,6 @@
 # Backlog — Ligbox Ops Platform (VM122)

-**Última atualização:** 2026-06-17 (Specs **014–025** + VM123 finance stack)  
+**Última atualização:** 2026-06-19 (Specs **026–032** purge extra-auth)  
 **Projeto:** `ligbox-ops-platform`  
 **VM122:** `ligbox-ops` · `10.10.10.122` · SSH WAN `:2522`  
 **VM112:** Portal/Wizard — integração **API + webhooks** (fora do compose)  
@ -87,6 +87,8 @@
 | **023** | `billing-recurrence-desk-visibility` | P1 | 🔄 | **Fase 1 ✅** · Fase 2 gateway ASAAS/Iugu |
 | **024** | `openpanel-fossbilling` | P1 | ✅ | v1 piloto concluído 17/06 |
 | **025** | `wizard-onboarding-continuity` | **P0** | 🔄 | **Fase 1 ✅** · Fase 2 resume + RAM 16GB |
+| **026** | `purge-traefik-validation` | **P0** | ✅ | YAML seguro + smoke onboard pós-purge |
+| **032** | `purge-domain-extra-auth` | P1 | ✅ | Códigos Infra · myvexx.com · ver spec |

 ---

--- a/specs/017-vm112-domain-orchestration/spec.md
+++ b/specs/017-vm112-domain-orchestration/spec.md
@ -1,7 +1,7 @@
 # Feature Specification: Domínios VM112 — Purge & Histórico (017)

 **Criado:** 2026-06-16  
-**Actualizado:** 2026-06-16 (v2 — histórico de purges)  
+**Actualizado:** 2026-06-19 (extensões Spec 026 · Spec 032)  
 **Solicitado por:** Roger  
 **Status:** v1 + v2 concluídos · Fase 3 VM112 pendente  
 **Prioridade:** P1 (testes E2E + padrão de limpeza)  
@ -204,6 +204,30 @@ curl -s -H "Authorization: Bearer $TOKEN" \

 ---

+## Extensão — Spec 026 (purge Traefik validation)
+
+Validação YAML + smoke onboard pós-remoção Traefik (CT114). Incidente 2026-06-19: `dynamic.yml` inválido após purge → 404 global no onboard.
+
+**Spec dedicada:** `specs/026-purge-traefik-validation/spec.md`
+
+---
+
+## Extensão — Spec 032 (purge autorização extra)
+
+Domínios em `PURGE_EXTRA_AUTH_DOMAINS` (ex.: `myvexx.com`) exigem **código de autorização** gerado pelo root em **Infra** (senha Root), além da validação purge normal.
+
+| Camada | Regra |
+|--------|--------|
+| Blocklist | `ligbox.com.br`, `itecnologys.com` — purge proibido |
+| Extra auth | Código único + senha Root |
+| Normal | Senha Root (Spec 017 v1) |
+
+**Spec dedicada:** `specs/032-purge-domain-extra-auth/spec.md`  
+**UI geração:** Infraestrutura → «Códigos autorização purge»  
+**UI consumo:** Serviços → modal purge (campo código)
+
+---
+
 ## Fase 3 — VM112 passos em tempo real (pendente)

 VM112 (`/opt/ligbox-wizard`) emitir passos individuais durante execução (Carbonio, CF, Traefik) em vez de bloco único + heartbeat. Alterações no wizard, não só no Desk.
@ -241,6 +265,8 @@ A Spec 017 cobre o ciclo completo de purge de domínio VM112:
 | Fase 2 | Jobs async, polling, persistência SQLite | ✅ |
 | Fase 2 SSE | Timeline drawer (legado) | ✅ |
 | **v2** | Histórico em Eventos — lista + modal audit trail | ✅ |
+| **032** | Códigos autorização extra (myvexx.com) — Infra + Serviços | ✅ |
+| **026** | Validação Traefik pós-purge | ✅ |
 | Fase 3 | Passos VM112 em tempo real no wizard | ⏳ |

 **Purges registados (exemplo):** `myvexx.com`, `diarissima.com`, `ibytera.com` — visíveis em Eventos → Histórico de purges.
--- a/specs/020-purge-history-desk/spec.md
+++ b/specs/020-purge-history-desk/spec.md
@ -6,6 +6,7 @@

 Ver secções:
 - **v2 — Histórico de purges**
+- **Extensão Spec 032** (códigos autorização — purge extra-auth)
 - **Conclusão (2026-06-16)**

 Não criar documentação duplicada aqui.
--- a/specs/032-purge-domain-extra-auth/spec.md
+++ b/specs/032-purge-domain-extra-auth/spec.md
@ -0,0 +1,205 @@
+# 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:**
+```json
+{
+  "domain": "myvexx.com",
+  "root_password": "********",
+  "note": "Autorizado call Roger 19/06",
+  "ttl_hours": 24
+}
+```
+
+**Resposta (única exibição do código):**
+```json
+{
+  "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:
+
+```json
+{
+  "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`