Proxy de aprovisionamiento de LNbits

Por qué un proxy

LNbits expone una API administrativa completa. Entregarla a una extensión de navegador significaría confiar autoridad sobre toda la instancia a cada cliente. El proxy publica solo el puñado de rutas que un monedero necesita realmente, autentica a los propietarios con su clave Nostr en lugar de una contraseña, y mantiene la credencial de superusuario de LNbits en el servidor, que es donde corresponde.

Las instancias propias de LNbits necesitan este adaptador para que la interfaz de gestión de monederos de la extensión funcione con ellas. Nada en la extensión es específico de un operador.

Arquitectura

Las peticiones llegan a tu proxy inverso por TLS y se reenvían al servicio en loopback. El servicio habla con LNbits por HTTP y lee directamente dos bases de datos SQLite de LNbits para consultas que la API HTTP no expone.

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, ...)

El servicio escucha únicamente en 127.0.0.1. Nunca es accesible directamente desde internet, así que un proxy inverso delante es obligatorio, no opcional.

El acceso directo a la base de datos es como el proxy asocia una clave pública de Nostr con un monedero de LNbits y como escribe los enlaces de pago de Lightning Address. Ambos archivos deben ser legibles y escribibles por el usuario con el que se ejecuta el servicio.

Requisitos previos

• Node.js 24 o superior. El servicio usa el módulo SQLite integrado, que sigue siendo experimental en versiones anteriores.
• Una instancia de LNbits funcionando con la extensión lnurlp instalada, y la extensión nwcprovider si quieres soporte para Nostr Wallet Connect.
• Un backend Lightning detrás de LNbits. El despliegue de referencia usa phoenixd, pero al proxy le da igual cuál ejecutes.
• La clave API de superusuario de LNbits, que el servicio usa para crear cuentas y monederos. Esta clave nunca se reenvía a los clientes.

Instalación y configuración

Clona el repositorio, instala la única dependencia de ejecución y arranca el servicio con su configuración en el entorno.

Variables de entorno

Cinco variables controlan el servicio. Solo una es obligatoria.

const DOMAIN = 'zaps.example.com';

Lo que expone tu instancia

A continuación está todo lo que responde el servicio. Cualquier ruta que no aparezca aquí devuelve 404, incluido el resto de la API de LNbits.

Aprovisionamiento de monederos

{
  "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

Gestión de concesiones NWC limitada a cada monedero. Todas las rutas exigen la clave API de administración de ese monedero en la cabecera X-Api-Key; las claves de solo factura se rechazan. Estas rutas no aceptan ninguna cadena 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}'

Rutas de LNbits redirigidas

Se reenvían literalmente dos grupos de rutas de LNbits. Todo lo demás queda bloqueado.

Rutas LNURL públicas, reenviadas con CORS permisivo porque los monederos las llaman desde otro origen. La cabecera Host se reescribe con tu dominio público para que LNbits construya URLs de callback correctas.

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

Rutas de monedero autenticadas, que requieren una cabecera X-Api-Key y que usa la vista de monedero de la extensión.

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

Autenticación NIP-98

El aprovisionamiento y todas las modificaciones de Lightning Address usan desafío-respuesta con un evento Nostr firmado. No hay contraseñas ni sesiones.

1. Solicita un desafío.
2. Construye un evento de tipo 27235 que lleve el desafío y la petición exacta que autoriza.
3. Fírmalo con la clave Nostr de la persona y envíalo en el campo event del cuerpo POST.
4. El servicio verifica la firma Schnorr antes de consumir el desafío, de modo que un intento fallido no lo gasta.

Etiquetas obligatorias

Las tres etiquetas son obligatorias y se comprueban de forma exacta. La etiqueta u debe ser la URL absoluta completa del endpoint invocado en tu propio dominio, y la etiqueta method debe coincidir con el 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());

Tiempos

Se aplican dos ventanas independientes: el desafío caduca 60 segundos después de emitirse, y el created_at del evento debe estar dentro de los 60 segundos de la hora del servidor. Un cliente con el reloj muy desviado fallará incluso con un desafío recién emitido.

Proxy inverso

Termina TLS y reenvía al puerto de loopback. El bloque siguiente es la configuración de referencia.

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;

Gestión del proceso

Sirve cualquier supervisor. El despliegue de referencia usa pm2, con la configuración inyectada en el entorno del proceso y la lista de procesos guardada para que sobreviva a un reinicio.

Inyecta la clave de superusuario mediante tu supervisor o un archivo de entorno que nunca se suba al repositorio. No debe vivir en el código.

Monitorización

Merece la pena ejecutar dos vigilantes independientes: una comprobación de salud del conjunto y un watchdog para el backend Lightning.

Watchdog del backend Lightning

phoenixd puede quedar en un estado en el que el proceso está vivo y escuchando pero su API HTTP no responde nunca, porque un bucle de reconexión al LSP bloquea el bucle de eventos. Los monederos informan de pagos fallidos mientras systemctl da el servicio por activo. Un temporizador que sondea la API y reinicia tras dos fallos consecutivos se recupera de esto sin que nadie se levante de madrugada.

# /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

La doble comprobación importa: un único tiempo de espera agotado suele ser un parpadeo, y reiniciar el backend en cada parpadeo es peor que el fallo.

Comprobación de salud del conjunto

Una comprobación periódica que ejercita LNbits, el proxy, las rutas LNURL públicas y la generación de facturas de extremo a extremo, y envía correo cuando cambia el estado. Ejecútala desde cron en el mismo host.

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

Límites y validación

Límites de tasa

Por dirección de cliente y por minuto. Las peticiones que superan el límite reciben 429.

Nombres de usuario de Lightning Address

Los nombres deben tener entre 3 y 30 caracteres, alfanuméricos en minúscula con puntos, guiones y guiones bajos, empezando y terminando por un carácter alfanumérico.

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

Estos nombres están bloqueados:

admin  support  help  info  noreply
postmaster  webmaster  abuse  root  system

Ajustes de conexión NWC

• Nombre de la conexión: de 1 a 50 caracteres, sin caracteres de control.
• Límite diario: de 1 a 9.999.999 sats, aplicado en una ventana móvil de 24 horas.
• Caducidad: de 1 a 365 días.
• Máximo de 50 conexiones activas por monedero.

Cuerpos de las peticiones

64 KB para aprovisionamiento y peticiones de Lightning Address, 4 KB para la creación de conexiones NWC.

Código fuente

El servicio es un único archivo Node con una sola dependencia de ejecución. Léelo antes de ejecutarlo. github.com/nostr-wot/LNbits-proxy