Proxy de provisionnement LNbits

Pourquoi un proxy

LNbits expose une API d'administration complète. La confier à une extension de navigateur reviendrait à accorder à chaque client une autorité sur l'instance entière. Le proxy ne publie que la poignée de routes dont un portefeuille a réellement besoin, authentifie les propriétaires avec leur clé Nostr plutôt qu'un mot de passe, et garde l'identifiant super-utilisateur de LNbits sur le serveur, là où il doit rester.

Les instances LNbits personnalisées ont besoin de cet adaptateur pour que l'interface de gestion des portefeuilles de l'extension fonctionne avec elles. Rien dans l'extension n'est propre à un opérateur.

Architecture

Les requêtes arrivent sur votre proxy inverse en TLS et sont transmises au service sur la boucle locale. Le service dialogue avec LNbits en HTTP et lit directement deux bases SQLite de LNbits pour les recherches que l'API HTTP n'expose pas.

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

Le service n'écoute que sur 127.0.0.1. Il n'est jamais joignable directement depuis internet, donc un proxy inverse devant lui est obligatoire, pas optionnel.

L'accès direct à la base est ce qui permet au proxy d'associer une clé publique Nostr à un portefeuille LNbits et d'écrire les liens de paiement Lightning Address. Les deux fichiers doivent être lisibles et modifiables par l'utilisateur sous lequel tourne le service.

Prérequis

• Node.js 24 ou plus récent. Le service utilise le module SQLite intégré, encore expérimental sur les versions antérieures.
• Une instance LNbits fonctionnelle avec l'extension lnurlp installée, et l'extension nwcprovider si vous voulez la prise en charge de Nostr Wallet Connect.
• Un backend Lightning derrière LNbits. Le déploiement de référence utilise phoenixd, mais le proxy se moque de celui que vous employez.
• La clé API super-utilisateur de LNbits, dont le service se sert pour créer comptes et portefeuilles. Cette clé n'est jamais transmise aux clients.

Installation et configuration

Clonez le dépôt, installez l'unique dépendance d'exécution et démarrez le service avec sa configuration dans l'environnement.

Variables d'environnement

Cinq variables pilotent le service. Une seule est obligatoire.

const DOMAIN = 'zaps.example.com';

Ce que votre instance expose

Tout ce à quoi le service répond figure ci-dessous. Toute route absente de cette liste renvoie 404, y compris le reste de l'API LNbits.

Provisionnement de portefeuille

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

Gestion des autorisations NWC limitée à chaque portefeuille. Chaque route exige la clé API d'administration de ce portefeuille dans l'en-tête X-Api-Key ; les clés de facturation seule sont rejetées. Ces routes n'acceptent aucune chaîne de requête.

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

Routes LNbits relayées

Deux groupes de routes LNbits sont transmis tels quels. Tout le reste est bloqué.

Routes LNURL publiques, transmises avec un CORS permissif parce que les portefeuilles les appellent depuis une autre origine. L'en-tête Host est réécrit avec votre domaine public pour que LNbits construise des URL de rappel correctes.

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

Routes de portefeuille authentifiées, qui exigent un en-tête X-Api-Key et que la vue portefeuille de l'extension utilise.

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

Authentification NIP-98

Le provisionnement et chaque modification de Lightning Address utilisent un défi-réponse avec un événement Nostr signé. Ni mots de passe, ni sessions.

1. Demandez un défi.
2. Construisez un événement de type 27235 portant le défi et la requête exacte qu'il autorise.
3. Signez-le avec la clé Nostr de la personne et envoyez-le dans le champ event du corps POST.
4. Le service vérifie la signature Schnorr avant de consommer le défi, si bien qu'une tentative ratée ne le gaspille pas.

Balises obligatoires

Les trois balises sont obligatoires et vérifiées à l'identique. La balise u doit être l'URL absolue complète de l'endpoint appelé sur votre propre domaine, et la balise method doit correspondre à la méthode 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());

Fenêtres de temps

Deux fenêtres indépendantes s'appliquent : le défi expire 60 secondes après son émission, et le created_at de l'événement doit se situer à moins de 60 secondes de l'heure du serveur. Un client dont l'horloge dérive fortement échouera même avec un défi tout neuf.

Proxy inverse

Terminez le TLS et transmettez vers le port de boucle locale. Le bloc ci-dessous est la configuration de référence.

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;

Gestion du processus

N'importe quel superviseur convient. Le déploiement de référence utilise pm2, avec la configuration injectée dans l'environnement du processus et la liste des processus enregistrée pour survivre à un redémarrage.

Injectez la clé super-utilisateur via votre superviseur ou un fichier d'environnement qui n'est jamais versionné. Elle ne doit pas vivre dans le dépôt.

Supervision

Deux veilleurs indépendants méritent d'être en place : un contrôle de santé de l'ensemble, et un chien de garde pour le backend Lightning.

Chien de garde du backend Lightning

phoenixd peut atteindre un état où le processus est vivant et à l'écoute mais où son API HTTP ne répond plus, parce qu'une boucle de reconnexion vers le LSP bloque la boucle d'événements. Les portefeuilles signalent des paiements échoués pendant que systemctl donne le service pour actif. Un minuteur qui sonde l'API et redémarre après deux échecs consécutifs corrige cela sans réveiller personne.

# /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 double vérification compte : un seul dépassement de délai est souvent un hoquet, et redémarrer le backend à chaque hoquet est pire que la panne.

Contrôle de santé de l'ensemble

Un contrôle périodique qui sollicite LNbits, le proxy, les routes LNURL publiques et la génération de facture de bout en bout, et envoie un courriel à chaque changement d'état. Lancez-le depuis cron sur le même hôte.

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

Limites et validation

Limites de débit

Par adresse cliente et par minute. Les requêtes au-delà de la limite reçoivent 429.

Noms d'utilisateur Lightning Address

Les noms doivent faire de 3 à 30 caractères, alphanumériques minuscules avec points, tirets et tirets bas, en commençant et en finissant par un caractère alphanumérique.

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

Ces noms sont bloqués :

admin  support  help  info  noreply
postmaster  webmaster  abuse  root  system

Réglages de connexion NWC

• Nom de la connexion : de 1 à 50 caractères, sans caractères de contrôle.
• Limite quotidienne : de 1 à 9 999 999 sats, appliquée sur une fenêtre glissante de 24 heures.
• Expiration : de 1 à 365 jours.
• Maximum de 50 connexions actives par portefeuille.

Corps des requêtes

64 Ko pour le provisionnement et les requêtes Lightning Address, 4 Ko pour la création de connexion NWC.

Code source

Le service tient dans un seul fichier Node avec une unique dépendance d'exécution. Lisez-le avant de le lancer. github.com/nostr-wot/LNbits-proxy