# Ligbox Infrastructure Constitution

Constituição de governança para toda a infraestrutura Ligbox / Ibytera no cluster Proxmox `big1`.
Aplica-se a VMs, CTs, rede, segurança, deploys e integrações (mail, ops, portal).

---

## Core Principles

### I. Network Segmentation — vmbr1 como LAN L2 pura

A rede interna das VMs (`10.10.10.0/24`) deve ser servida por **vmbr1**, bridge **sem IPv4 no host Proxmox**:

- `bridge-ports none` — isolada do hardware
- Host **não** actua como gateway na vmbr1
- Gateway das VMs: **pfSense LAN** (`10.10.10.1`)
- Documentação de referência: `docs/network/INTERFACES_PROXMOX.md`

**Drift conhecido (2026-06-08):** VMs operam em `vmbr4000` (Hetzner vSwitch, host `10.10.10.254`). Migração para vmbr1 requer plano aprovado — não improvisar.

### II. Proxmox Interfaces — alteração tripla obrigatória

O ficheiro `/etc/network/interfaces` do host Proxmox é **crítico e imutável sem aprovação**:

1. Descrever intenção real e diff completo antes de qualquer alteração
2. Obter confirmação explícita do Roger **três vezes**
3. Verificar iptables antes e depois; limpar duplicatas; nunca `ifreload` múltiplo sem limpeza

Ordem das regras importa (FIFO). Destino WAN pfSense = `10.0.0.2`, **nunca** LAN `10.10.10.1` em DNAT.

### III. Anti-Scan Hetzner — regras obrigatórias (NON-NEGOTIABLE)

Quatro linhas de proteção FORWARD devem estar activas na secção vmbr1:

```
post-up iptables -I FORWARD -s 10.10.10.0/24 ! -d 10.10.10.0/24 -j DROP
post-up iptables -I FORWARD -s 10.10.10.0/24 ! -d 10.10.10.0/24 -p udp --dport 53 -j ACCEPT
```

**Proibido:** `POSTROUTING MASQUERADE` genérico para `10.10.10.0/24` (causa abuse reports).

Verificação obrigatória: após qualquer alteração de rede e **diariamente**.

### IV. Separation of Concerns — Mail vs Ops

| VM | Papel | Restrição |
|----|-------|-----------|
| **112** | Carbonio mail + portal onboard | Não misturar workloads de ops/monitoring |
| **113** | PMG mail gateway | Filtro SMTP apenas |
| **122** | Ligbox Ops Platform | API, desk, workers — **sem mail stack** |

Comunicação entre 112 e 122 via API/webhook na LAN (`10.10.10.x`), nunca exposição directa à internet.

### V. Security Baseline — toda VM exposta

Toda VM/CT com SSH (LAN ou WAN) deve ter:

- **fail2ban** activo com jail `sshd` (bantime ≥ 3600s, maxretry ≤ 5)
- `PasswordAuthentication` verificado com `sshd -T` (não confiar só no ficheiro principal)
- Ficheiros `sshd_config.d/*.conf` verificados (sobrescrevem config principal)
- Portas de serviço bindadas à LAN quando possível (`10.10.10.x`, não `0.0.0.0`)

### VI. pfSense API — acesso validado

- URL produção: `https://firewall.itecnologys.com/api/v2/` (via Traefik)
- Fallback directo: `https://10.10.10.1:10443/api/v2/`
- Autenticação: **Basic Auth** (`-u user:password`), nunca headers customizados
- Após alterações NAT/firewall: `POST /api/v2/firewall/apply`
- DNAT externo → pfSense WAN (`10.0.0.2`), portas SSH VMs via pfSense (2501–2522)

### VII. Spec-Driven Development — Spec Kit obrigatório

Todo trabalho de feature segue o fluxo Spec Kit **antes** de implementação:

```
/speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.checklist
→ /speckit.plan → /speckit.tasks → /speckit.analyze → /speckit.implement
```

- Constitution (este ficheiro) precede qualquer feature
- Specs em `specs/` com branch `NNN-nome-feature`
- Não implementar sem `plan.md` + `tasks.md` validados
- Backlog livre migra para specs numeradas

### VIII. Documentation First — Obsidian + repo

- Inventário VMs: `obsidian-infra/docs/TABELA_VMS_*.md` — actualizar após cada VM nova
- Decisões arquitecturais: `docs/decisions/DECISAO_*.md`
- Chat bruto / sessões: `obsidian-infra/` (vault principal)
- Código deployável: `/opt/<projeto>/` na VM + sync para `workspace/projects/`

### IX. Simplicity — YAGNI no MVP

- Preferir SQLite a Postgres para ops MVP (VM122)
- Docker compose mínimo (api + worker + redis + frontend)
- Adiar: SOC, Wazuh centralizado, 7 agents, Postgres cluster
- Cada feature justifica complexidade adicional

---

## Security Requirements

| Requisito | Implementação |
|-----------|---------------|
| SSH externo | pfSense NAT `95.216.14.146:PORTA` → VM:22 |
| SSH interno | `root@10.10.10.x` a partir do host ou LAN |
| Webhook secrets | Rotação obrigatória em produção (não usar defaults dev) |
| Credenciais | Nunca commitar em git; usar `.env` local |
| Cloudflare API | Tokens com scope mínimo (zone DNS, não account-wide) |
| Tailscale/scanning | Monitorar regras FORWARD; bloquear vazamento LAN→WAN |

---

## Infrastructure Inventory (referência rápida)

| Componente | IP / Porta | Notas |
|------------|-----------|-------|
| Proxmox host | 95.216.14.162 | vmbr0 |
| pfSense LAN | 10.10.10.1 | VM100, gateway VMs |
| pfSense WAN | 10.0.0.2 | Destino DNAT |
| VM112 mail | 10.10.10.112:2512 | Carbonio + portal |
| VM113 PMG | 10.10.10.113:2513 | Mail gateway |
| VM122 ops | 10.10.10.122:2522 | Ligbox Ops MVP |
| CT119 qtm | 10.10.10.119 | Não migrar — reservado |
| Traefik | CT114 / VM105 | `firewall.itecnologys.com` |

---

## Development Workflow

1. **Constitution** — verificar compliance antes de iniciar feature
2. **Specify** — requisitos (o quê / porquê, sem tech stack)
3. **Clarify + Checklist** — obrigatório para produção
4. **Plan + Tasks** — arquitectura e passos executáveis
5. **Analyze** — consistência cross-artifact antes de implementar
6. **Implement** — código + deploy + verificação
7. **Validate** — testes, fail2ban, iptables, health endpoints
8. **Document** — actualizar inventário VMs e decisões

### Quality gates (bloqueantes)

- [ ] Constitution compliance verificada
- [ ] fail2ban activo na VM alvo
- [ ] Sem alteração não aprovada em `/etc/network/interfaces`
- [ ] Regras anti-scan Hetzner verificadas
- [ ] Health check da feature OK
- [ ] Inventário VMs actualizado

---

## Governance

- Esta constitution **supera** backlog informal, prompts ad-hoc e decisões não documentadas
- Emendas requerem: proposta escrita, aprovação Roger, bump de versão, data de ratificação
- Toda PR / sessão de implementação deve verificar compliance com esta constitution
- Drift de infra (ex.: vmbr1 com IP, VMs em vmbr4000) deve ser documentado em `docs/network/` até resolução
- Complexidade adicional (novo serviço, nova VM, nova bridge) requer spec dedicada — não improvisar

**Version**: 1.0.0 | **Ratified**: 2026-06-08 | **Last Amended**: 2026-06-08