Rede, segredos e rotação na Nero

Para: Dev, Adm — Conferido em 2026-10-18.

O que a Nero configura do seu lado: onde ficam as credenciais, quem pode alcançar o Dracma, como girar chave e segredo sem parar. Os conceitos gerais estão em Autenticação e Segredos e vazamento.

O que é

Os materiais

Material Onde vive na Nero Rotação
Chave de chamada key_test_ ou key_live_ e o segredo Arquivo 0400 do usuário Linux do nero_payments, entregue pelo ops da Nero a partir do seeder da aplicação ou do cofre Até 2 chaves ativas; a antiga é revogada depois que a nova entra em uso. Política da Nero: girar a cada 90 dias
Segredo de webhook whsec_ Arquivo 0400, uma linha por segredo ativo (1 ou 2) Sobreposição de até 7 dias entre o novo e o anterior. Política da Nero: girar a cada 90 dias
Lista de IPs de saída do Dracma Não disponível: o Dracma não publica a lista Não filtre a rota do webhook por IP

Nomes de variável usados pelos exemplos (adapte ao seed da Nero):

Variável Conteúdo
DRACMA_BASE_URL Base com /v1 (hml para a operação Teste, prd para a Real). Os hosts 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)

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.

Não disponível

O Dracma não emite certificado de cliente (mTLS) hoje: o painel mostra que a emissão ainda não está disponível. A autenticação das chamadas é por HMAC (chave e segredo). Não há item de mTLS no go-live da Nero. Veja Rede, allowlist e mTLS.

Quando usar

Ao provisionar o servidor do nero_payments, ao ensaiar a rotação antes do go-live e ao responder a um vazamento.

Como funciona

IPs nos dois sentidos

flowchart LR subgraph NERO["Bet Nero"] NP["nero_payments (usuário Linux próprio)"] NAT["IPs de saída (NAT)"] CAD["Caddy: rota /api/payments/dracma/webhook"] end subgraph DR["Dracma"] API["API /v1"] WH["Emissor de webhooks"] end NP --> NAT --> API WH --> CAD --> NP

Nero para o Dracma. Cadastre no painel todos os IPs de saída que o nero_payments pode usar (cluster, NAT redundante, DR), para que a lista fique registrada.

Não disponível

A lista de IPs fica registrada, mas hoje não é aplicada às chamadas: uma chamada de um IP fora da lista não é recusada por isso. A defesa das chamadas é a assinatura HMAC. Veja IPs do conector.

Egress restrito. Só o usuário Linux do nero_payments alcança o host do Dracma (nftables por UID ou cgroup). Nenhum outro serviço da bet consegue usar a credencial, mesmo se for comprometido. Esta é a defesa da Nero no lugar da lista de IPs.

Dracma para a Nero (Caddy). A autenticidade do webhook vem da assinatura e do fetch-back. O Dracma não publica lista de IPs de saída hoje; se um dia vier por contrato, aplique-a só na rota do webhook, como camada extra. Dentro do serviço, confie em X-Forwarded-For somente quando o salto anterior for o próprio Caddy. O Dracma não garante IP fixo em hml.

Rotação sem parar

Chave de chamada. O pedido de chave nova precisa da aprovação de outra pessoa e de 24 horas de espera, e o segredo é revelado uma vez a quem pediu (Chaves de API).

sequenceDiagram participant A as Admin da Nero (painel) 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 Note over D: espera de 24 h D-->>A: key_NOVA e segredo, exibidos 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. O primeiro segredo só aparece quando você aciona "Rotacionar" no painel. Em cada rotação o Dracma assina com os dois segredos por até 7 dias. Passos: (1) o ops acrescenta o segredo novo ao arquivo (duas linhas); (2) confirme webhooks aceitos (nero_dracma_webhook_verify_total{result="ok"}); (3) depois que a sobreposição terminar, remova o antigo. Não existe "revogar" o segredo antigo: encerrar a sobreposição é fazer uma segunda rotação (Segredo e rotação).

Vazou?

  1. Chave de chamada: "Revogar" no painel. A revogação vale em até 30 segundos em todas as réplicas. Peça outra chave e entregue pelo ops.
  2. Segredo de webhook: faça uma rotação e remova o anterior do arquivo quando a sobreposição terminar. Enquanto isso, o fetch-back garante que um segredo vazado não cria dinheiro.
  3. Pânico geral: "Suspender automático" na tela de Emergência de Regras. O efeito é imediato (saque automático da moeda desligado); uma segunda pessoa precisa confirmar em até 24 horas.

Relógio

A janela de assinatura é de ±300 segundos nos dois sentidos. Use chrony com 3 ou mais fontes no host do nero_payments. Um job chama GET /v1/ping e alerta se |server_time - agora| passar de 5 segundos; o cmd/ping dos exemplos Go faz isso.

Exemplos

O ping assinado e o desvio de relógio, nos Exemplos executáveis. A verificação de que só o usuário do serviço alcança o Dracma está no item N2 do Go-live da Nero.

Erros e casos de borda

  • Chave nova gravada à mão no servidor em vez do seeder: some no próximo redeploy do ambiente. Passe sempre pelo ops.
  • Duas linhas no arquivo de segredos de webhook, mas só uma é aceita: confira o fim de linha e o espaço no fim.
  • 401 invalid_signature depois da troca de chave: o serviço ainda assina com a antiga ou o DRACMA_KEY_ID aponta para outra.

Veja também