Ícone de uma chave branca sobre uma seta circular de rotação.
Gerallndbtcpay-servermacaroons

Rotacionar um Macaroon do LND Comprometido no BTCPay Server

O aviso do BTCPay Server de 7 de agosto não se resolve só atualizando. Mostramos como rotacionar o seu macaroon do LND e matar qualquer credencial roubada, sem mover fundos nem mexer nos seus canais.

Librería de Satoshi ·

Um exercício de resposta a incidentes de 5 minutos que você pode rodar no seu próprio nó.

O aviso do BTCPay Server de 7 de agosto é claro: atualize para a 2.4.2 e pronto. O update regenera os seus macaroons automaticamente.

É verdade, mas só para as portas que o BTCPay controla.

Se você expõe o seu nó LND por conta própria (um reverse proxy seu, uma porta redirecionada, o seu próprio túnel Tor), esse macaroon roubado continua vivo depois do update. O BTCPay não consegue rotacionar uma credencial em uma porta que ele não sabe que existe. E esse é exatamente o tipo de configuração que operadores avançados costumam ter.

Este tutorial é para dois casos:

  • (a) Você expõe o LND por conta própria, além de pelo BTCPay.
  • (b) Você ainda não conseguiu atualizar e quer rotacionar como medida temporária.

Já atualizou para a 2.4.2 em uma instalação padrão e não expõe o LND por conta própria? Os macaroons já foram rotacionados sozinhos, você não precisa rodar este tutorial. Mesmo assim, siga com o resto do checklist abaixo (revisar atividade suspeita, mover fundos da hot wallet etc.).

Primeiro, calma: os macaroons são credenciais de acesso, não as chaves dos seus fundos. Rotacioná-los não move moedas, não fecha canais e não muda a identidade do seu nó. A sua seed fica intacta.

O que você vai fazer

  1. Identificar o macaroon atual e confirmar que ele funciona.
  2. Apagar os macaroons e o banco de dados da root key.
  3. Reiniciar o LND a partir do host.
  4. Verificar que a nova credencial funciona e a antiga é rejeitada, mesmo nó, mesmos fundos.

Pré-requisitos

  • Um BTCPay Server rodando com o contêiner do LND (bitcoin): btcpayserver_lnd_bitcoin.
  • Acesso por shell ao host.

O modelo mental (leia isto primeiro)

Um macaroon é um token assinado. O LND não guarda o token como fonte da verdade: guarda uma root key em macaroons.db e assa macaroons a partir dela quando são necessários.

Esse único fato define todo o procedimento:

Apagar os arquivos .macaroon não faz nada. O LND assa de novo cópias idênticas byte a byte a partir da root key na próxima inicialização. Para rotacionar de verdade, é preciso destruir a root key macaroons.db para forçar o LND a gerar uma nova.

Apague os tokens e a chave. Não só os tokens.

Passo 1 - Capturar o estado “antes”

Entre no nó e confirme que a credencial atual é válida.

docker exec -it btcpayserver_lnd_bitcoin bash

# ---- ahora dentro del contenedor ----
cd /root/.lnd
alias li='lncli --macaroonpath /root/.lnd/admin.macaroon'
# Identifica el macaroon actual
sha256sum admin.macaroon

# Guarda una copia para probar que después muere.
cp admin.macaroon OLD.bak

# Comprueba que funciona: el nodo responde.
li getinfo | grep identity_pubkey

Anote o identity_pubkey. Ele tem que ser idêntico no final. Se mudar, você rotacionou o nó, não a credencial - esse é um resultado diferente (e incorreto).

Passo 2 - Rotacionar: apagar os macaroons e a root key

Você continua dentro do contêiner.

rm -f *.macaroon \
      data/chain/bitcoin/regtest/*.macaroon \
      data/chain/bitcoin/regtest/macaroons.db

ls OLD.bak     # nuestra copia guardada sobrevive
exit

Explicação: “Apagar só os arquivos .macaroon não faz nada, o LND assa de novo cópias idênticas a partir da root key. A root key mora em macaroons.db, então ela também tem que ir embora.”

Nota sobre os caminhos: os caminhos dos macaroons codificam a sua rede. Este exemplo é regtest. Em um nó real, troque para mainnet (data/chain/bitcoin/mainnet/...). Verifique o seu caminho real com ls data/chain/bitcoin/.

Passo 3 - Reiniciar o LND a partir do host

No host:

docker restart btcpayserver_lnd_bitcoin

Explicação: “O LND mantém o macaroons.db aberto e é o PID 1 do seu próprio contêiner, não dá para reiniciá-lo de forma limpa por dentro. O reinício vem de fora. Ao iniciar sem root key, o LND gera uma nova e regenera os seus macaroons.”

Dê alguns segundos para ele desbloquear e voltar a ficar ativo.

Passo 4 - Verificar: a nova funciona, a antiga está morta, o nó não mudou

Entre de novo e compare lado a lado.

docker exec -it btcpayserver_lnd_bitcoin bash
cd /root/.lnd
alias li='lncli --macaroonpath /root/.lnd/admin.macaroon'

# Huella NUEVA - debe ser DISTINTA a la del Paso 1
sha256sum admin.macaroon

# La vieja, para comparar lado a lado
sha256sum OLD.bak

# La credencial NUEVA funciona - y es el MISMO nodo
li getinfo | grep identity_pubkey

# La credencial VIEJA es rechazada: "signature mismatch" = MUERTA
lncli --macaroonpath /root/.lnd/OLD.bak getinfo

# Limpieza
rm -f OLD.bak
exit

Explicação: “Hash novo, a root key rotacionou de verdade. O novo macaroon funciona. A cópia roubada agora é rejeitada com um signature mismatch. Mesma pubkey, então os canais e os fundos nunca se moveram. O BTCPay e o RTL já se reconectaram sozinhos.”

Critérios de sucesso:

Verificação Resultado esperado
sha256sum admin.macaroon Diferente do Passo 1
Novo macaroon com getinfo Funciona
identity_pubkey Igual ao do Passo 1
OLD.bak getinfo Erro signature mismatch

Se as quatro se cumprem: a fechadura mudou, a chave roubada virou sucata e o nó nunca saiu do lugar.

Reconectar os seus clientes

A conexão interna do BTCPay com o LND e o RTL (incluído) normalmente se reconectam sozinhos. Tudo o que usa um macaroon exportado precisa ser pareado de novo com o novo:

  • Zeus / carteiras móveis - escaneie de novo o novo QR de conexão.
  • RTL (independente), scripts, APIs - envie o novo admin.macaroon (ou um macaroon de bakery com permissões restritas).
  • Qualquer integração personalizada que tenha o macaroon antigo em hex/base64 - atualize-a.

A credencial antiga agora é inválida em todo lugar, então tudo o que você não atualizar vai falhar na autenticação até ser pareado de novo. Esse é justamente o objetivo.

Onde isto entra na resposta completa

Rotacionar o macaroon é um passo. Para o incidente de 7 de agosto, a lista completa é:

  1. Atualizar para a 2.4.2 - Painel de Admin → Server → Maintenance → Update. Confirme a versão no rodapé e que o LND ficou na 0.21.1. Em uma instalação padrão, isso já regenera os macaroons automaticamente. (Não pode atualizar agora? Desligue o servidor, um servidor desligado não pode ser explorado.)
  2. Rotacionar macaroons + macaroons.db manualmente - este tutorial. Necessário só se você expõe o LND por conta própria (proxy, Tor ou porta própria) ou enquanto ainda não consegue atualizar.
  3. Rotacionar a autenticação em cada backend de Lightning e atualizar as integrações.
  4. Tirar os fundos de qualquer hot wallet on-chain criada pelo BTCPay e depois recriá-la.
  5. Atualizar o NBXplorer para a 2.6.10 se você o usa.

Na maioria dos casos, o update já troca a fechadura por você. Os passos manuais de rotação são para as portas que o BTCPay não consegue ver nem fechar sozinho.

Alerta de golpe

Depois dos avisos públicos, aparecem golpes do tipo “eu te ajudo a migrar os seus fundos”. A regra nunca muda:

Nenhuma parte legítima, nem o BTCPay, nem ninguém vai pedir jamais a sua seed, chave privada, senha ou macaroons.

Verifique cada instrução nos canais oficiais antes de agir.

Perguntas que este tutorial responde de antemão:

  • “Eu perco os meus canais Lightning se regenerar os macaroons?” - Não. Os macaroons são credenciais de acesso, não chaves de fundos. Os canais e os saldos ficam intactos.
  • “Isso afeta a minha hardware wallet?” - Não. Este é um problema do operador do servidor, separado de qualquer incidente de hardware wallet.