Proxy de aprovisionamento do LNbits

Porquê um proxy

O LNbits expõe uma API administrativa completa. Entregá-la a uma extensão de navegador significaria confiar autoridade sobre toda a instância a cada cliente. O proxy publica apenas o punhado de rotas de que uma carteira realmente precisa, autentica os proprietários com a sua chave Nostr em vez de uma palavra-passe, e mantém a credencial de superutilizador do LNbits no servidor, onde deve estar.

Instâncias próprias do LNbits precisam deste adaptador para que a interface de gestão de carteiras da extensão funcione com elas. Nada na extensão é específico de um operador.

Arquitetura

Os pedidos chegam ao seu proxy reverso por TLS e são encaminhados para o serviço em loopback. O serviço fala com o LNbits por HTTP e lê diretamente duas bases de dados SQLite do LNbits para consultas que a API HTTP não expõe.

Nostr client
     |  HTTPS
     v
Reverse proxy (TLS, zaps.example.com)
     |  HTTP, loopback
     v
LNbits proxy  :3003  --- reads ---> database.sqlite3
     |  HTTP                        ext_lnurlp.sqlite3
     v
LNbits  :5000
     |
     v
Lightning backend (phoenixd, LND, ...)

O serviço escuta apenas em 127.0.0.1. Nunca é acessível diretamente a partir da internet, por isso um proxy reverso à frente é obrigatório, não opcional.

O acesso direto à base de dados é como o proxy associa uma chave pública Nostr a uma carteira do LNbits e como escreve as ligações de pagamento de Lightning Address. Ambos os ficheiros têm de ser legíveis e graváveis pelo utilizador com que o serviço corre.

Pré-requisitos

• Node.js 24 ou superior. O serviço usa o módulo SQLite integrado, que ainda é experimental em versões anteriores.
• Uma instância do LNbits a funcionar com a extensão lnurlp instalada, e a extensão nwcprovider se quiser suporte para Nostr Wallet Connect.
• Um backend Lightning por trás do LNbits. A implementação de referência usa phoenixd, mas ao proxy é indiferente qual utilize.
• A chave API de superutilizador do LNbits, que o serviço usa para criar contas e carteiras. Esta chave nunca é encaminhada para os clientes.

Instalação e configuração

Clone o repositório, instale a única dependência de execução e arranque o serviço com a configuração no ambiente.

Variáveis de ambiente

Cinco variáveis controlam o serviço. Apenas uma é obrigatória.

const DOMAIN = 'zaps.example.com';

O que a sua instância expõe

Abaixo está tudo o que o serviço responde. Qualquer rota que não conste desta lista devolve 404, incluindo o resto da API do LNbits.

Aprovisionamento de carteiras

{
  "challenge": "7f3a…"
}

{
  "event": {
    "kind": 27235,
    "…": "signed NIP-98 event"
  },
  "name": "My Wallet"
}

{
  "walletId": "…",
  "adminkey": "…",
  "inkey": "…",
  "lightningAddress": null
}

Lightning Address

{
  "lightningAddress": "[email protected]"
}

Nostr Wallet Connect

Gestão de concessões NWC limitada a cada carteira. Todas as rotas exigem a chave API de administração dessa carteira no cabeçalho X-Api-Key; chaves apenas de fatura são rejeitadas. Estas rotas não aceitam qualquer cadeia de consulta.

{
  "connections": [],
  "provider": {
    "pubkey": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "relay": "wss://relay.example.com"
  }
}

{
  "name": "My phone",
  "dailyLimit": 10000,
  "days": 90
}

curl -X PUT "https://zaps.example.com/api/nwc/connections/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "X-Api-Key: $WALLET_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My phone","dailyLimit":10000,"days":90}'

Rotas do LNbits encaminhadas

São encaminhados literalmente dois grupos de rotas do LNbits. Tudo o resto é bloqueado.

Rotas LNURL públicas, encaminhadas com CORS permissivo porque as carteiras chamam-nas de outra origem. O cabeçalho Host é reescrito com o seu domínio público para que o LNbits construa URLs de callback corretos.

GET  /.well-known/lnurlp/{username}
GET  /lnurlp/api/v1/lnurl/cb/{id}

Rotas de carteira autenticadas, que exigem um cabeçalho X-Api-Key e são usadas pela vista de carteira da extensão.

GET|POST  /api/v1/wallet
GET|POST  /api/v1/payments

Autenticação NIP-98

O aprovisionamento e todas as alterações de Lightning Address usam desafio-resposta com um evento Nostr assinado. Não há palavras-passe nem sessões.

1. Peça um desafio.
2. Construa um evento do tipo 27235 que transporte o desafio e o pedido exato que autoriza.
3. Assine-o com a chave Nostr da pessoa e envie-o no campo event do corpo POST.
4. O serviço verifica a assinatura Schnorr antes de consumir o desafio, pelo que uma tentativa falhada não o gasta.

Etiquetas obrigatórias

As três etiquetas são obrigatórias e verificadas de forma exata. A etiqueta u tem de ser o URL absoluto completo do endpoint invocado no seu próprio domínio, e a etiqueta method tem de corresponder ao método HTTP.

const { challenge } = await fetch(
  "https://zaps.example.com/api/provision/challenge"
).then(r => r.json());

const event = await window.nostr.signEvent({
  kind: 27235,
  created_at: Math.floor(Date.now() / 1000),
  tags: [
    ["u", "https://zaps.example.com/api/provision"],
    ["method", "POST"],
    ["challenge", challenge],
  ],
  content: "",
});

const wallet = await fetch("https://zaps.example.com/api/provision", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ event, name: "My Wallet" }),
}).then(r => r.json());

Tempos

Aplicam-se duas janelas independentes: o desafio expira 60 segundos depois de emitido, e o created_at do evento tem de estar dentro de 60 segundos da hora do servidor. Um cliente com o relógio muito desviado falhará mesmo com um desafio acabado de emitir.

Proxy reverso

Termine o TLS e encaminhe para a porta de loopback. O bloco seguinte é a configuração de referência.

server {
    listen 443 ssl;
    server_name zaps.example.com;

    ssl_certificate     /etc/letsencrypt/live/zaps.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/zaps.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3003;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
    }
}

server {
    listen 80;
    server_name zaps.example.com;
    return 301 https://$host$request_uri;
}

# Inside the server block, before location /
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
# ... the rest of your CDN's published ranges
real_ip_header CF-Connecting-IP;
real_ip_recursive on;

Gestão do processo

Qualquer supervisor serve. A implementação de referência usa pm2, com a configuração injetada no ambiente do processo e a lista de processos guardada para sobreviver a um reinício.

Injete a chave de superutilizador através do seu supervisor ou de um ficheiro de ambiente que nunca vá para o repositório. Não pode viver no código.

Monitorização

Vale a pena correr dois vigilantes independentes: uma verificação de saúde do conjunto e um watchdog para o backend Lightning.

Watchdog do backend Lightning

O phoenixd pode ficar num estado em que o processo está vivo e à escuta mas a sua API HTTP nunca responde, porque um ciclo de reconexão ao LSP bloqueia o ciclo de eventos. As carteiras reportam pagamentos falhados enquanto o systemctl dá o serviço como ativo. Um temporizador que sonda a API e reinicia após duas falhas consecutivas recupera disto sem ninguém ter de acordar.

# /etc/systemd/system/check-phoenixd.timer
[Unit]
Description=Run phoenixd health check every 2 minutes

[Timer]
OnBootSec=60
OnUnitActiveSec=120
AccuracySec=10

[Install]
WantedBy=timers.target

A dupla verificação importa: um único tempo esgotado costuma ser um soluço, e reiniciar o backend a cada soluço é pior do que a falha.

Verificação de saúde do conjunto

Uma verificação periódica que exercita o LNbits, o proxy, as rotas LNURL públicas e a geração de faturas de ponta a ponta, e envia email quando o estado muda. Corra-a a partir do cron no mesmo anfitrião.

*/5 * * * * /usr/bin/node /srv/monitor/monitor.mjs >> /srv/monitor/cron.log 2>&1

Limites e validação

Limites de taxa

Por endereço de cliente e por minuto. Os pedidos acima do limite recebem 429.

Nomes de utilizador de Lightning Address

Os nomes têm de ter entre 3 e 30 caracteres, alfanuméricos minúsculos com pontos, hífenes e sublinhados, começando e terminando por um carácter alfanumérico.

/^[a-z0-9][a-z0-9._-]{1,28}[a-z0-9]$/

Estes nomes estão bloqueados:

admin  support  help  info  noreply
postmaster  webmaster  abuse  root  system

Definições de ligação NWC

• Nome da ligação: de 1 a 50 caracteres, sem caracteres de controlo.
• Limite diário: de 1 a 9 999 999 sats, aplicado numa janela móvel de 24 horas.
• Validade: de 1 a 365 dias.
• Máximo de 50 ligações ativas por carteira.

Corpos dos pedidos

64 KB para aprovisionamento e pedidos de Lightning Address, 4 KB para a criação de ligações NWC.

Código-fonte

O serviço é um único ficheiro Node com uma só dependência de execução. Leia-o antes de o executar. github.com/nostr-wot/LNbits-proxy