ligbox-ops-platform/specs/037-dns-multi-cloudflare-orchestration/spec.md

Spec 037 — DNS multi-conta Cloudflare + BYO + Registrador

Criado: 2026-06-22
Solicitado por: Roger
Status: 🔄 Em implementação (Fase A activa · B/C/D em construção)
Prioridade: P1
VM: 112 (wizard API :8090)
Relacionado: 004 cloudflare-zone-provision · 025 · 017 · dns-viewer.md · 035 §5.5

---

Resumo

O passo DNS do onboarding usa três contas Cloudflare gerenciadas pela Ligbox (ligit, itecnologys, ibytera). O wizard:

1. Se a zona já existe numa das 3 contas → aplica apontamentos com o token dessa conta.
2. Se o cliente escolhe «Cloudflare Ligbox» e a zona ainda não existe → o wizard cria a zona do cliente na conta Ligbox correcta (provision-zone), depois aplica MX/SPF/etc.
3. Se o cliente não quer DNS na Ligbox → BYO (token CF dele) ou registrador externo.

Política: não importar domínios alheios nem criar zonas fora do fluxo wizard; sim criar a zona do cliente na CF gerenciada pela Ligbox quando esse for o caminho escolhido.

Evolução (Roger 2026-06-22): cada cliente novo terá conta Cloudflare dedicada — e-mail inicial proj_{id}@ligbox.com.br, dados do domínio do cliente; após go-live, convidar gestor admin@dominio. Ver client-cf-account-lifecycle.md.

Identidade projeto (Roger 2026-06-22): o agente cria proj_{id}@ligbox.com.br no Carbonio, entrega senha ao cliente e referencia em CF, DNS, registry e webhooks. Ver project-email-identity.md.

---

Três contas Ligbox (pré-cadastro)

ID interno	E-mail admin (referência)	Ficheiro token (VM112)	account_id CF
ligit	admin@ligit.com.br	secrets/cloudflare-ligit.token	configurar
itecnologys	admin@itecnologys.com	secrets/cloudflare-itecnologys.token	configurar
ibytera	ibytera@gmail.com	secrets/cloudflare-ibytera.token	configurar

Catálogo: deploy/vm112-wizard/dns-accounts.yaml (não commitar tokens).

Conta legacy cloudflare.token + cloudflare_account_id em config.py → migrar para ibytera ou deprecar após cutover.

---

Fluxo decisão (passo DNS)

flowchart TD
  A[POST validate-domain] --> B[GET /dns/resolve/{domain}]
  B --> C{Zona já existe em conta Ligbox?}
  C -->|sim| D[apply na conta encontrada]
  C -->|não| E{Cliente escolhe caminho}
  E -->|Cloudflare Ligbox| F[provision-zone: cria zona do cliente na conta default]
  F --> G[apply apontamentos]
  E -->|BYO| H[connect-custom + apply]
  E -->|Registrador| I[instructions + verify manual]
  D --> V[GET dns/verify]
  G --> V
  H --> V
  I --> V
  V --> J[account/create]

Regra «zona do cliente na CF Ligbox»

• Existente: probe ligit → itecnologys → ibytera; usa a conta onde a zona já está.
• Nova (wizard): POST provision-zone cria cliente.com.br na conta default_provision_account (yaml, hoje ibytera) — só quando o utilizador escolhe Cloudflare Ligbox.
• Nunca: criar zona sem escolha explícita Ligbox; nunca BYO/registrador criar em conta Ligbox.

---

Endpoints novos / alterados

Método	Path	Descrição
GET	/api/onboarding/dns/resolve/{domain}	Procura zona nas 3 contas; devolve matched_account, zone_id, paths_available
POST	/api/onboarding/dns/cloudflare/connect-custom	Valida token BYO + zona; guarda em vault sessão
POST	/api/onboarding/dns/cloudflare/apply	Alterado: usa conta resolvida, BYO, ou body account_id
POST	/api/onboarding/dns/cloudflare/provision-zone	Cria zona do cliente na CF Ligbox (conta default ou existente) — só caminho Ligbox

Response dns/resolve

{
  "domain": "cliente.com.br",
  "matched": true,
  "account_id": "ligit",
  "account_label": "Ligbox Ligit (admin@ligit.com.br)",
  "zone_id": "…",
  "zone_status": "active",
  "dns_mode": "ligbox_cf_ligit",
  "paths_available": ["apply_ligbox", "byo", "external"]
}

Se matched: false (zona nova):

{
  "matched": false,
  "can_provision_ligbox": true,
  "provision_account_id": "ibytera",
  "paths_available": ["provision_ligbox", "byo", "external"],
  "message": "Domínio novo — pode criar zona na Cloudflare gerenciada pela Ligbox ou usar BYO/registrador."
}

---

BYO Cloudflare (cliente)

1. Cliente cola API Token (scope: DNS Edit + Zone Read só na zona).
2. verify_token() + get_zone_by_name(domain).
3. Token em vault (/var/lib/.../dns_tokens/{session_hash}), TTL 7 dias pós-onboard.
4. apply com CloudflareDNS(token=customer_token).
5. Purge Spec 017 não apaga zona BYO — só registos criados por nós (futuro: tracking).

---

Registrador / DNS externo

Sem mudança funcional core: GET /dns/instructions/{domain} + verificação dns_verify.

Fase 2: adapters EPP/API (Gandi, GoDaddy, Registro.br homologado).

---

DNS Viewer (read-only) — Spec 037-DNS-VIEWER

Painel unificado para exibir apontamentos (staff Desk + gerente Console) sem editar na UI.

Caminho wizard	O viewer mostra
Cloudflare Ligbox	Registos planeados (pré-NS) ou aplicados (pós-apply) + NS CF
BYO / Registrador / externo	DNS actual (público + instructions) — não preview Ligbox

Documento completo: dns-viewer.md — endpoints, links editar, fases V0–V4.

Estado deploy (2026-06-25): V1–V3 produção (VM122/123) · commit 038fb8f · V4 wizard patches prontos · deploy VM112 pendente.

---

Código

Caminho monorepo	Deploy VM112
projects/wizard/backend/app/services/dns_account_registry.py	/opt/ligbox-wizard/backend/app/services/
deploy/vm112-wizard/dns-accounts.yaml	/opt/ligbox-wizard/dns-accounts.yaml
deploy/vm112-wizard/dns-accounts.yaml.example	exemplo versionado

---

Critérios de aceitação (Fase 1)

1. Domínio existente na conta ibytera → resolve retorna matched + apply OK.
2. Domínio novo + caminho Ligbox → provision-zone cria zona na conta default + apply OK.
3. BYO com token válido → apply na conta do cliente.
4. Caminho registrador → sem provision-zone Ligbox.
5. Tokens em secrets/ — nunca no Git.

---

Decisões Roger (2026-06-22, corrigido)

#	Regra
1	Não importar domínios alheios nas contas Ligbox
2	Sim criar zona do cliente na CF gerenciada Ligbox via wizard (escolha explícita)
3	Conta para zona nova: default_provision_account no yaml (hoje ibytera)
4	BYO / registrador = DNS fora das contas Ligbox

---

Fase 2 — Conta CF dedicada por cliente

Ver client-cf-account-lifecycle.md:

Fase	E-mail Cloudflare	Quando
A — Onboarding	proj_{id}@ligbox.com.br	Criação conta + zona
B — Handoff	admin@{dominio_cliente} convidado como gestor	DNS + email + infra OK

Orquestração agentica (edge): cf-agents-sdk-architecture.md — Cloudflare Agents SDK (Durable Objects, multi-agent, human-in-the-loop) + roster Spec 029 A0–A7.