LNbits-Provisionierungsproxy

Warum überhaupt ein Proxy

LNbits stellt eine vollständige Administrations-API bereit. Sie einer Browser-Erweiterung zu überlassen hieße, jedem Client Autorität über die gesamte Instanz zuzutrauen. Der Proxy veröffentlicht nur die wenigen Pfade, die eine Wallet wirklich braucht, authentifiziert Wallet-Inhaber über ihren Nostr-Schlüssel statt über ein Passwort und behält die LNbits-Superuser-Zugangsdaten auf dem Server, wo sie hingehören.

Eigene LNbits-Instanzen brauchen diesen Adapter, damit die Wallet-Verwaltung der Erweiterung mit ihnen funktioniert. Nichts in der Erweiterung ist auf einen einzelnen Betreiber zugeschnitten.

Architektur

Anfragen erreichen deinen Reverse Proxy über TLS und werden an den Dienst auf dem Loopback weitergereicht. Der Dienst spricht per HTTP mit LNbits und liest zwei LNbits-SQLite-Datenbanken direkt, für Abfragen, die die HTTP-API nicht anbietet.

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

Der Dienst lauscht ausschließlich auf 127.0.0.1. Er ist nie direkt aus dem Internet erreichbar, ein Reverse Proxy davor ist also Pflicht, nicht Kür.

Über den direkten Datenbankzugriff ordnet der Proxy einen öffentlichen Nostr-Schlüssel einer LNbits-Wallet zu und schreibt die Zahlungslinks der Lightning-Adresse. Beide Dateien müssen für den Benutzer, unter dem der Dienst läuft, les- und schreibbar sein.

Voraussetzungen

• Node.js 24 oder neuer. Der Dienst nutzt das eingebaute SQLite-Modul, das in älteren Versionen noch experimentell ist.
• Eine laufende LNbits-Instanz mit installierter lnurlp-Erweiterung, und der nwcprovider-Erweiterung, wenn du Nostr Wallet Connect unterstützen willst.
• Ein Lightning-Backend hinter LNbits. Das Referenz-Deployment nutzt phoenixd, dem Proxy ist es aber gleich, welches du betreibst.
• Der LNbits-Superuser-API-Schlüssel, mit dem der Dienst Konten und Wallets anlegt. Dieser Schlüssel wird nie an Clients weitergereicht.

Installation und Konfiguration

Klone das Repository, installiere die einzige Laufzeitabhängigkeit und starte den Dienst mit seiner Konfiguration in der Umgebung.

Umgebungsvariablen

Fünf Variablen steuern den Dienst. Nur eine ist erforderlich.

const DOMAIN = 'zaps.example.com';

Was deine Instanz bereitstellt

Unten steht alles, worauf der Dienst antwortet. Jeder Pfad, der nicht in dieser Liste steht, liefert 404, auch der Rest der LNbits-API.

Wallet-Bereitstellung

{
  "challenge": "7f3a…"
}

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

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

Lightning-Adresse

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

Nostr Wallet Connect

Wallet-bezogene Verwaltung von NWC-Freigaben. Jede Route verlangt den Admin-API-Schlüssel dieser Wallet im Header X-Api-Key; reine Rechnungsschlüssel werden abgewiesen. Diese Routen akzeptieren überhaupt keine Query-Parameter.

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

Weitergereichte LNbits-Pfade

Zwei Gruppen von LNbits-Pfaden werden unverändert weitergereicht. Alles andere ist blockiert.

Öffentliche LNURL-Pfade, mit großzügigem CORS weitergereicht, weil Wallets sie von fremden Ursprüngen aufrufen. Der Host-Header wird auf deine öffentliche Domain umgeschrieben, damit LNbits korrekte Callback-URLs bildet.

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

Authentifizierte Wallet-Pfade, die einen X-Api-Key-Header verlangen und von der Wallet-Ansicht der Erweiterung genutzt werden.

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

NIP-98-Authentifizierung

Bereitstellung und jede Änderung an einer Lightning-Adresse laufen über Challenge-Response mit einem signierten Nostr-Ereignis. Keine Passwörter, keine Sitzungen.

1. Fordere eine Challenge an.
2. Baue ein Ereignis der Art 27235, das die Challenge und genau die Anfrage trägt, die es autorisiert.
3. Signiere es mit dem Nostr-Schlüssel der Person und sende es im Feld event des POST-Körpers.
4. Der Dienst prüft die Schnorr-Signatur, bevor er die Challenge verbraucht, ein Fehlversuch verbrennt sie also nicht.

Erforderliche Tags

Alle drei Tags sind Pflicht und werden exakt geprüft. Das u-Tag muss die vollständige absolute URL des aufgerufenen Endpunkts auf deiner eigenen Domain sein, und das method-Tag muss zur HTTP-Methode passen.

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());

Zeitfenster

Es gelten zwei unabhängige Fenster: Die Challenge verfällt 60 Sekunden nach der Ausgabe, und das created_at des Ereignisses muss innerhalb von 60 Sekunden der Serverzeit liegen. Ein Client mit stark abweichender Uhr scheitert selbst mit einer frischen Challenge.

Reverse Proxy

Beende TLS und leite an den Loopback-Port weiter. Der Block unten ist die Referenzkonfiguration.

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;

Prozessverwaltung

Jeder Supervisor taugt. Das Referenz-Deployment nutzt pm2, mit der Konfiguration in der Prozessumgebung und gespeicherter Prozessliste, damit sie einen Neustart übersteht.

Gib den Superuser-Schlüssel über deinen Supervisor oder eine Umgebungsdatei weiter, die nie eingecheckt wird. Im Repository hat er nichts verloren.

Überwachung

Zwei unabhängige Wächter lohnen sich: eine Gesundheitsprüfung für den Gesamtaufbau und ein Watchdog für das Lightning-Backend.

Watchdog für das Lightning-Backend

phoenixd kann in einen Zustand geraten, in dem der Prozess lebt und lauscht, seine HTTP-API aber nie antwortet, weil eine Reconnect-Schleife zum LSP die Event-Loop blockiert. Wallets melden fehlgeschlagene Zahlungen, während systemctl den Dienst als aktiv führt. Ein Timer, der die API abfragt und nach zwei aufeinanderfolgenden Fehlschlägen neu startet, behebt das, ohne dass jemand aufstehen muss.

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

Die doppelte Prüfung ist wichtig: Eine einzelne Zeitüberschreitung ist meist ein Aussetzer, und das Backend bei jedem Aussetzer neu zu starten ist schlimmer als der Fehler selbst.

Gesundheitsprüfung des Aufbaus

Eine regelmäßige Prüfung, die LNbits, den Proxy, die öffentlichen LNURL-Pfade und die Rechnungserzeugung von Anfang bis Ende durchspielt und bei Zustandswechseln eine E-Mail schickt. Führe sie per cron auf demselben Host aus.

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

Grenzwerte und Validierung

Ratenbegrenzung

Pro Client-Adresse und Minute. Anfragen über dem Limit erhalten 429.

Benutzernamen für Lightning-Adressen

Namen müssen 3 bis 30 Zeichen lang sein, alphanumerisch in Kleinbuchstaben mit Punkten, Bindestrichen und Unterstrichen, und mit einem alphanumerischen Zeichen beginnen und enden.

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

Diese Namen sind gesperrt:

admin  support  help  info  noreply
postmaster  webmaster  abuse  root  system

NWC-Verbindungseinstellungen

• Verbindungsname: 1 bis 50 Zeichen, keine Steuerzeichen.
• Tageslimit: 1 bis 9.999.999 Sats, durchgesetzt über ein gleitendes 24-Stunden-Fenster.
• Ablauf: 1 bis 365 Tage.
• Höchstens 50 aktive Verbindungen pro Wallet.

Anfragekörper

64 KB für Bereitstellung und Lightning-Adress-Anfragen, 4 KB für das Anlegen einer NWC-Verbindung.

Quelltext

Der Dienst ist eine einzige Node-Datei mit einer einzigen Laufzeitabhängigkeit. Lies ihn, bevor du ihn betreibst. github.com/nostr-wot/LNbits-proxy