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:**
```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`