Skip to content

ADR 0049 — OOBI Satellite Federation Framework (umbrella)

  • Status: Accepted
  • Date: 2026-05-15
  • Deciders: André Luiz Gallon (Architect/Operator)
  • Supersedes: —
  • Related: ADR 0043 (OOBI VLAN — no VXLAN), ADR 0045 (Hello mesh), ADR 0046 (Hello encryption + PSK), ADR 0048 (ZTP-prem), ADR 0050 (CONNECT.Art Pattern A — companion), ADR 0051 (P2P STUN Pattern B — companion), ADR 0054 (PQC-Everywhere), ADR 0058 (Dual-Stack), ADR 0059 (ACME-Everywhere)
  • Memory references:
  • discuss_oobi_satellite_federation_wan_mtls_2026_05_14.md
  • project_oobi_satellite_dual_pattern_operator_choice_locked_2026_05_14.md
  • project_oobi_satellite_pqc_hybrid_locked_2026_05_14.md
  • project_oobi_satellite_dual_mesh_heartbeat_locked_2026_05_14.md

Context

OCTOPUS clientes operam N Data Centers próprios (não apenas um). Os cenários multi-site recorrentes:

  1. Enterprise dual-DC (active-passive ou active-active) — banco regulado tem DC primário no SP + standby em RJ, ambos próprios do cliente
  2. Multi-site distribuído — telecom com 5 PoPs nacionais, todos conectados ao operador central
  3. SOHO + HQ — escritório remoto cliente conecta ao DC central via internet residencial (CGNAT, dual-NAT)
  4. Defense / Gov sovereign — datacenter cliente NÃO pode depender de cloud público; toda federação cross-DC tem que rodar peer-to-peer entre infra cliente

Os existentes (não-OCTOPUS) cobrem casos com L3 conectividade nativa entre DCs (MPLS, IPsec site-to-site, dedicated fiber). Não cobrem:

  • Cliente em ISP residencial dual-NAT atrás de CGNAT
  • Cliente sovereign sem L3 direto (apenas internet pública)
  • Failure tolerance independente do cloud provider OCTOPUS
  • Operator-controlled relay infrastructure (não-Cisco-hosted)

OOBI Satellite Federation preenche essa lacuna: cross-DC federation L7 sobre mTLS PQC + heartbeat, com operator escolhendo entre dois patterns de discovery.

Esta ADR é a umbrella que define o framework; ADRs 0050 (Pattern A rendezvous) e 0051 (Pattern B P2P STUN) shipam os detalhes específicos.

Decisão

D1 — Cross-DC liveness via L7 heartbeat (NÃO Hello tunnel)

Cada DC mantém seu próprio Hello mesh local (ADR 0045), independente. A liveness cross-DC é provida por um heartbeat L7 dedicado numa stream HTTP/2 do tunnel mTLS — NUNCA por tunelar pacotes Hello multicast/broadcast entre DCs.

Razões (LOCKED em project_oobi_satellite_dual_mesh_heartbeat_locked_2026_05_14): - Multicast/broadcast L2 não tem semântica em L3 tunnel (ADR 0043 deletou VTEP exatamente por isso) - Cadência 30s do Hello é errada para cross-DC; WAN merece 5s - Modelos de falha cross-DC vs intra-DC são distintos - HTTP/2 unicast é fit nativo para tunnel; multicast em userspace = antipattern

Heartbeat schema (LOCKED):

{
  "session_id":           "uuid7",
  "sender_site_id":       "dc1",
  "sequence_number":      12345,
  "local_mesh_nodes":     17,
  "local_mesh_alive":     17,
  "local_license_valid":  true,
  "sent_at":              "2026-05-14T12:34:56.123Z"
}
  • Cifrado com a MESMA PSK do Hello mesh (AES-256-GCM, ADR 0046) — consistência de key management
  • Cadência 5s, limiar 3 missed = DEGRADED, detecção 15s
  • Stream dedicada do HTTP/2 (Stream 1 reservada)

D2 — Operator escolhe Pattern A OU Pattern B por deployment

Toda federação cross-DC usa um de dois patterns:

  • Pattern A — Rendezvous via CONNECT.Art (TURN-like) Ambos peers dial out para servidor cloud; cloud bridges bytes A↔B. Sempre funciona (NAT-agnostic). +10-30ms latência relay. Implementação: ADR 0050.

  • Pattern B — P2P hole-punching via STUN-coord (STUN/ICE-like) Peers descobrem srflx address; conectam direto. 0ms overhead após handshake. Falha em ~30-40% NATs (CGNAT symmetric). Implementação: ADR 0051.

LOCKED em project_oobi_satellite_dual_pattern_operator_choice_locked_2026_05_14:

"Operador escolhe qual padrão usar no momento do deployment, via Dashboard. Decisão é per-deployment (não per-tunnel, não per-customer global)."

Wave 1 ships AMBOS patterns. Wave 2 (futura) adicionará modo Auto/Hybrid estilo Tailscale (tenta P2P primeiro, fallback rendezvous se falhar).

D3 — PQC hybrid OBRIGATÓRIO no MVP

PQC hybrid (X25519 + ML-KEM-768 KEX) é mandatório já no MVP. Sem fallback classical-only. LOCKED em project_oobi_satellite_pqc_hybrid_locked_2026_05_14:

"PQC hybrid é OBRIGATÓRIO já no MVP — não é opt-in, não é fase 2, não tem fallback para classical-only. Ambos os peers DEVEM suportar PQC hybrid ou o handshake é rejeitado."

Algoritmos LOCKED:

Função Classical PQC Combinação
KEX X25519 ML-KEM-768 (NIST Level 3) Hybrid obrigatório — HKDF(X25519_shared, ML-KEM_shared)
Sigs handshake Ed25519 ML-DSA-65 Hybrid recomendado; classical-only aceito MVP enquanto ML-DSA stdlib não disponível
AEAD bulk AES-256-GCM ou ChaCha20-Poly1305 n/a Inalterado
HKDF SHA-384 n/a Inalterado
PSK envelope AES-256-GCM n/a Inalterado

Razões: - "Harvest now, decrypt later" é ameaça ativa hoje - Janela de proteção precisa começar AGORA - Go 1.26.3 crypto/mlkem stdlib disponível - Custo de adicionar depois é alto (rolling upgrade cross-DC) - NIST SP 800-208 + CNSA 2.0 sinalizam PQC obrigatório federal por ~2030 - Hybrid não enfraquece classical (atacante quebra ambos)

D4 — Triple-encryption (defense-in-depth)

A federação L7 mTLS cross-DC usa 3 camadas independentes:

  1. Tunnel mTLS PQC — TLS 1.3 com X25519+ML-KEM-768, cert chain Cisco Satellite Root CA
  2. Payload AEAD — Heartbeat + control plane msgs cifradas com PSK AES-256-GCM (ADR 0046 reused)
  3. Per-app encryption (quando aplicável) — payloads que carregam dados de cliente já vêm cifrados pelo módulo emissor

Cloud rendezvous (Pattern A) é blind tunnel — não terminava mTLS interno (que continua end-to-end entre os GATEWAYs). Cloud vê apenas TCP bytes + cert metadata.

D5 — Lives em pkg/oobi/satellite/ (novo pacote)

Toda a Satellite Federation tem código distinto:

  • pkg/oobi/satellite/heartbeat/ — L7 heartbeat over HTTP/2
  • pkg/oobi/satellite/tunnel/ — mTLS PQC tunnel manager
  • pkg/oobi/satellite/pattern_a/ — Pattern A client (uses pkg/octopus/connect-art/ server)
  • pkg/oobi/satellite/pattern_b/ — Pattern B client (uses pkg/octopus/stun-coord/ server)
  • pkg/oobi/satellite/policy/ — operator-config-driven pattern selector

NÃO modifica pkg/oobi/hello/ (ADR 0045 mesh permanece intacto).

Wave de implementação

11 PRs estimados, ~11k LoC, 20-24 semanas. Ordem (DAG):

# PR Esforço Dependencies
PR-OSF-1 (este) ADR 0049 + reviewer checklist 1d —
PR-OSF-2 ADR 0050 Pattern A formalization 1-2d PR-OSF-1
PR-OSF-3 ADR 0051 Pattern B formalization 1-2d PR-OSF-1
PR-OSF-4 pkg/oobi/satellite/ scaffold (types + interfaces) 1w PR-OSF-1
PR-OSF-5 L7 heartbeat over HTTP/2 stream 1 2-3w PR-OSF-4
PR-OSF-6 PQC hybrid application-layer (X25519+ML-KEM-768) 3-4w PR-OSF-4
PR-OSF-7 Pattern A client lib (uses CONNECT.Art server) 2-3w PR-OSF-6
PR-OSF-8 Pattern B client lib (uses STUN-coord server) 3-4w PR-OSF-6
PR-OSF-9 Operator policy + Dashboard pattern selector UI 2-3w PR-OSF-7+8
PR-OSF-10 E2E smoke tests + chaos suite 2w PR-OSF-9
PR-OSF-11 Docs + runbook + observability dashboard 1-2w PR-OSF-10

Wave 2 futura: modo Auto/Hybrid (Tailscale-style) — ~3 semanas adicionais, ADR 0049-A.

PR reviewer checklist (mandatory)

Toda PR-OSF-* DEVE passar nas verificações de pkg/octopus/docs/07-development/pr-checklist-satellite-federation.md (ships com PR-OSF-1).

Critérios de rejeição automática: 1. Adiciona código em pkg/oobi/hello/ que olha para outro DC 2. Adiciona serviço de relay-multicast cross-DC 3. Configura IGMP querier ou PIM-SM no manifest K8s 4. Propaga Hello packets pelo tunnel mTLS 5. Não emite métricas oobi_satellite_heartbeat_* 6. Implementa ACME/cliente sem PQC hybrid no KEX 7. Aceita fallback classical-only no handshake 8. Dashboard renderiza cross-site mesh edges como Hello mesh (deve ser tunnel link distinto)

Alternativas consideradas

Alternativa Por que rejeitada
Tunelar Hello mcast cross-DC Reinventa multicast em userspace; contraria ADR 0043; cadência 30s inadequada
Pattern A only (rendezvous) Latency-critical apps + sovereign customers querem P2P
Pattern B only (P2P) Falha em ~30-40% NATs (CGNAT symmetric) — exclui SOHO/residential
PQC opt-in / fase 2 "Harvest now, decrypt later" — perde janela de proteção 2-3 anos
Modo Auto/Hybrid no MVP Complexidade aumenta debugging; Tailscale levou 5 anos para amadurecer DERP
Mesh único via VXLAN over WAN Contraria ADR 0047 (VXLAN é só test payload)

Consequências

Positivas

  • N-site federation unlocked para enterprise/telecom/sovereign
  • CGNAT residential funciona (Pattern A fallback)
  • Latência baixa em NATs cooperativos (Pattern B direct)
  • PQC future-proof desde MVP — protege janela 2026-2030+
  • Triple encryption = defense-in-depth contra qualquer single-layer breach
  • Operator escolha = não força um trade-off

Negativas

  • Complexidade dobrada — manter 2 patterns + selector logic
  • MVP timeline maior vs single-pattern (3-4 sem extras)
  • PQC overhead handshake ~5% — desprezível steady-state mas mensurável
  • Cloud-hosted rendezvous opcional = decisão operacional adicional por cliente (Cisco-hosted vs customer-hosted vs sovereign)

Neutras

  • Dashboard UI complexity — pattern selector + state visualization são features novas mas alinhadas com Customer Dashboard Wave-3
  • Audit chain registra tunnel_pattern: a|b per session

Compliance mapping

Standard Requirement Where
NIST SP 800-208 Crypto Agility D3 PQC hybrid + classical fallback architecture
CNSA 2.0 PQC mandatory federal by ~2030 D3 PQC obrigatório MVP
SOC 2 CC6.1 Logical access controls D4 triple-encryption + ZTP-prem
ISO 27001 A.13.1.1 Network controls mTLS PQC tunnel
GDPR Art. 32 State-of-the-art crypto PQC hybrid + AES-256-GCM

Patent considerations

A combinação PQC hybrid mTLS + operator-choice dual-pattern federation + L7 heartbeat (não Hello tunnel) é arquitetura única no espaço. Pode integrar Patent Family E (Hyperscale Federation):

  • Claim adicional: "Operator-selectable rendezvous/P2P dual-pattern federation with PQC hybrid KEX and L7 heartbeat over mTLS tunnel"
  • Prior art differentiation: Tailscale (single mode w/ DERP fallback), Cloudflare Argo Tunnel (rendezvous-only), ZeroTier (rendezvous-only)

Avaliar com IP counsel após Wave 1 ship completo.

Open items / future work

  • ADR 0049-A (Wave 2) — Auto/Hybrid mode (Tailscale-style)
  • ADR 0049-B (Wave 3) — Multi-DC mesh (>2 sites) com transitive routing
  • ADR 0049-C (Q3 2026) — ML-DSA-65 signature hybrid quando Go 1.27 stdlib

Memory + cross-references

Atualizar MEMORY.md index para apontar este ADR como AUTHORITATIVE:

ADR 0049 — docs/ADR/0049-oobi-satellite-federation-framework.md ← umbrella ADR 0050 — Pattern A rendezvous (CONNECT.Art) — PR-OSF-2 ADR 0051 — Pattern B P2P STUN — PR-OSF-3 Checklist — pkg/octopus/docs/07-development/pr-checklist-satellite-federation.md

Cross-references: - ADR 0043 (OOBI VLAN no VXLAN) — base architectural constraint - ADR 0045 (Hello mesh) — local mesh unchanged - ADR 0046 (Hello PSK encryption) — PSK reused para heartbeat AES-256-GCM - ADR 0048 (ZTP-prem) — defense-in-depth posture - ADR 0054 (PQC-Everywhere) — D3 alinhado - ADR 0058 (Dual-Stack) — federation funciona v4 + v6 paridade - ADR 0059 (ACME-Everywhere) — cert SAN public-trusted para tunnel endpoint