Rede, segredos e rotação na Nero

Detalhes gerais em ../autenticacao.md. Aqui fica o que a Nero configura.

1. Os quatro materiais

Material Onde vive na Nero Validade Rotação
Chave de chamada key_test_…/key_live_… + segredo (sk_…) arquivo 0400 do user Linux do nero_payments, entregue pelo ops da Nero a partir do seeder (/nero/.env) ou cofre ≤ 90 dias (alerta aos 75) até 2 chaves ativas; a antiga expira ≤ 7 dias depois da nova entrar em uso
Segredo de webhook whsec_… arquivo 0400, uma linha por segredo ativo (1 ou 2) ≤ 90 dias o Dracma assina com os dois por ≤ 7 dias
Certificado mTLS de cliente (produção) + chave privada arquivos 0400 do user do nero_payments; de preferência não exportável (TPM/HSM) ≤ 90 dias, renovar aos 60 2 certificados válidos na troca
Lista de IPs de egress do Dracma Caddy da bet, rota do webhook versionada aviso ≥ 30 dias, período com as duas listas

Nomes de variável sugeridos (os mesmos dos exemplos; adapte ao seed da Nero):

Variável Conteúdo
DRACMA_BASE_URL base com /v1 (hml → sandbox; prd → produção). Hosts reais chegam no onboarding
DRACMA_KEY_ID key_test_… em hml, key_live_… em prd
DRACMA_KEY_SECRET_FILE caminho do arquivo com o segredo
DRACMA_WEBHOOK_SECRETS_FILE caminho do arquivo com os segredos de webhook (um por linha)
DRACMA_MTLS_CERT_FILE / DRACMA_MTLS_KEY_FILE certificado e chave privada de cliente (prd)

Nunca: segredo em repositório, imagem, log, ticket, variável de front (NEXT_PUBLIC_*), linha de comando ou header logado inteiro (Dracma-Signature). O Dracma é chamado só do servidor.

2. IPs nos dois sentidos

flowchart LR
  subgraph NERO["Bet Nero"]
    NP["nero_payments (user Linux próprio)"]
    NAT["IPs de saída (NAT)"]
    CAD["Caddy: rota /api/payments/dracma/webhook"]
  end
  subgraph DR["Dracma"]
    API["API /v1: allowlist da operação"]
    WH["Emissor de webhooks: IPs de egress fixos"]
  end
  NP --> NAT -->|"só IPs cadastrados"| API
  WH -->|"só IPs do Dracma"| CAD --> NP

Nero → Dracma (allowlist da operação no Dracma):

  • Cadastre todos os IPs de saída que o nero_payments pode usar (cluster, NAT redundante, DR), em IPv4 e/ou IPv6. Prefixo mais largo aceito: /24 (IPv4) e /56 (IPv6); IP solto vira /32//128.
  • Mudança de allowlist é ação de painel com aprovação dupla: IP novo entra antes de o tráfego mudar.
  • Em produção, lista vazia = sem acesso. Em sandbox, lista vazia aceita qualquer IP — mesmo assim cadastre, para ensaiar.
  • 403 ip_not_allowed com chave válida gera alerta no Dracma (credencial usada fora do lugar).

Egress restrito (SEGURANCA R13): só o user Linux do nero_payments alcança o host do Dracma (nftables por UID/cgroup). Nenhum outro serviço da bet consegue usar a credencial, mesmo se for comprometido.

Dracma → Nero (Caddy): aplique a lista de IPs de egress do Dracma só na rota do webhook. Dentro do serviço, confie em X-Forwarded-For somente quando o salto anterior for o próprio Caddy. A lista ainda não tem endpoint público (D-H3 em ../divergencias.md); ela chega no onboarding.

3. mTLS

  • Obrigatório em produção; recomendado em sandbox. TLS 1.3 (1.2 só com AEAD).
  • Certificado por operação, emitido pela CA privada do Dracma; CAs de sandbox e produção são distintas.
  • Hoje a verificação do certificado fica na borda de produção do Dracma; o cruzamento chave × certificado ainda não está no código da API (D-A1). Não misture chave e certificado de operações diferentes.

4. Rotação sem downtime

Chave de chamada:

sequenceDiagram
  participant A as Admin Nero (painel Dracma)
  participant A2 as Segundo aprovador
  participant D as Dracma
  participant O as ops da Nero
  participant C as nero_payments
  A->>D: pede chave nova (step-up)
  A2->>D: aprova (4-eyes)
  D-->>A: key_live_NOVA + segredo, exibido uma vez
  A->>O: grava no seeder ou cofre (nunca à mão no servidor)
  O->>C: redeploy: passa a assinar com a NOVA
  D-->>A: painel mostra o último uso de cada chave
  A->>D: revoga a ANTIGA quando o último uso tiver mais de 1 h e zero erros

Segredo de webhook: (1) o ops acrescenta o segredo novo ao arquivo (2 linhas); (2) confirme webhooks aceitos (nero_dracma_webhook_verify_total{result="ok"}); (3) quando o painel encerrar a sobreposição, remova o antigo.

Certificado mTLS: instale o novo aos 60 dias (os dois valem), troque, confirme, remova o antigo.

Vazou? "Revogar agora" no painel (1 pessoa + step-up), efeito em ≤ 5 min em todos os nós; gere outra e entregue pelo ops. Para pânico geral: "Suspender operação" (todas as rotas → 403 operation_suspended). O fetch-back garante que um segredo de webhook vazado não cria dinheiro nesse intervalo.

5. Relógio

A janela de assinatura é ±300 s nos dois sentidos. Chrony com ≥ 3 fontes no host do nero_payments; um job chama GET /v1/ping e alerta se |server_time − agora| > 5 s (o go run ./cmd/ping dos exemplos faz isso).