Прокси provisioning для LNbits

Зачем вообще прокси

LNbits предоставляет полноценный административный API. Отдать его браузерному расширению означало бы доверить каждому клиенту власть над всем экземпляром. Прокси публикует только те несколько путей, которые кошельку действительно нужны, аутентифицирует владельцев по ключу Nostr вместо пароля и держит учётные данные суперпользователя LNbits на сервере, где им и место.

Собственным экземплярам LNbits нужен этот адаптер, чтобы интерфейс управления кошельками в расширении работал с ними. Ничто в расширении не привязано к одному оператору.

Архитектура

Запросы приходят на ваш обратный прокси по TLS и передаются сервису на петлевом интерфейсе. Сервис общается с LNbits по HTTP и напрямую читает две базы SQLite LNbits для выборок, которых нет в HTTP API.

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

Сервис слушает только 127.0.0.1. Он никогда не доступен из интернета напрямую, поэтому обратный прокси перед ним обязателен, а не желателен.

Прямой доступ к базе — это то, как прокси связывает публичный ключ Nostr с кошельком LNbits и записывает платёжные ссылки Lightning Address. Оба файла должны быть доступны на чтение и запись пользователю, от имени которого работает сервис.

Требования

• Node.js 24 или новее. Сервис использует встроенный модуль SQLite, который в более ранних версиях ещё экспериментальный.
• Работающий экземпляр LNbits с установленным расширением lnurlp, а также расширением nwcprovider, если нужна поддержка Nostr Wallet Connect.
• Lightning-бэкенд за LNbits. В эталонной установке используется phoenixd, но прокси безразлично, какой у вас.
• Ключ API суперпользователя LNbits, с которым сервис создаёт аккаунты и кошельки. Этот ключ никогда не передаётся клиентам.

Установка и настройка

Склонируйте репозиторий, установите единственную зависимость времени выполнения и запустите сервис с конфигурацией в окружении.

Переменные окружения

Работу сервиса определяют пять переменных. Обязательна только одна.

const DOMAIN = 'zaps.example.com';

Что предоставляет ваш экземпляр

Ниже перечислено всё, на что отвечает сервис. Любой путь вне этого списка возвращает 404, включая остальной API LNbits.

Создание кошелька

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

Управление разрешениями NWC в пределах одного кошелька. Каждый маршрут требует админский ключ API этого кошелька в заголовке X-Api-Key; ключи только для счетов отклоняются. Эти маршруты вообще не принимают строку запроса.

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

Проксируемые пути LNbits

Две группы путей LNbits передаются без изменений. Всё остальное заблокировано.

Публичные пути LNURL, передаваемые с разрешающим CORS, потому что кошельки обращаются к ним с другого источника. Заголовок Host переписывается на ваш публичный домен, чтобы LNbits формировал корректные URL обратного вызова.

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

Аутентифицированные пути кошелька, требующие заголовок X-Api-Key; их использует раздел кошелька в расширении.

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

Аутентификация NIP-98

Создание кошелька и любые изменения Lightning Address используют схему challenge-response с подписанным событием Nostr. Ни паролей, ни сессий.

1. Запросите challenge.
2. Составьте событие вида 27235, несущее challenge и именно тот запрос, который оно авторизует.
3. Подпишите его ключом Nostr пользователя и отправьте в поле event тела POST.
4. Сервис проверяет подпись Schnorr до того, как израсходовать challenge, поэтому неудачная попытка его не сжигает.

Обязательные теги

Все три тега обязательны и проверяются на точное совпадение. Тег u должен быть полным абсолютным URL вызываемого эндпоинта на вашем домене, а тег method должен совпадать с 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());

Временные окна

Действуют два независимых окна: challenge истекает через 60 секунд после выдачи, а created_at события должен укладываться в 60 секунд от времени сервера. Клиент с сильно сбитыми часами получит отказ даже со свежим challenge.

Обратный прокси

Терминируйте TLS и передавайте на петлевой порт. Блок ниже — эталонная конфигурация.

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;

Управление процессом

Подойдёт любой супервизор. В эталонной установке используется pm2: конфигурация передаётся в окружение процесса, а список процессов сохраняется, чтобы пережить перезагрузку.

Передавайте ключ суперпользователя через супервизор или файл окружения, который никогда не попадает в репозиторий. В коде ему не место.

Мониторинг

Стоит держать два независимых наблюдателя: проверку состояния всей связки и сторожевой таймер для Lightning-бэкенда.

Сторожевой таймер Lightning-бэкенда

phoenixd может оказаться в состоянии, когда процесс жив и слушает порт, но его HTTP API не отвечает никогда, потому что цикл переподключения к LSP блокирует цикл событий. Кошельки сообщают о неудачных платежах, а systemctl считает сервис активным. Таймер, который опрашивает API и перезапускает после двух неудач подряд, устраняет это без ночных подъёмов.

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

Двойная проверка важна: одиночный таймаут обычно просто сбой связи, а перезапускать бэкенд на каждом сбое хуже самой неисправности.

Проверка состояния связки

Периодическая проверка, которая задействует LNbits, прокси, публичные пути LNURL и сквозную генерацию счёта, и шлёт письмо при смене состояния. Запускайте её из cron на том же хосте.

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

Ограничения и валидация

Ограничения частоты

На адрес клиента в минуту. Запросы сверх лимита получают 429.

Имена пользователей Lightning Address

Имя должно быть длиной от 3 до 30 символов, из строчных букв и цифр с точками, дефисами и подчёркиваниями, начинаться и заканчиваться буквой или цифрой.

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

Эти имена заблокированы:

admin  support  help  info  noreply
postmaster  webmaster  abuse  root  system

Параметры подключения NWC

• Имя подключения: от 1 до 50 символов, без управляющих символов.
• Дневной лимит: от 1 до 9 999 999 сатоши, в скользящем окне 24 часа.
• Срок действия: от 1 до 365 дней.
• Не более 50 активных подключений на кошелёк.

Тело запроса

64 КБ для создания кошелька и запросов Lightning Address, 4 КБ для создания подключения NWC.

Исходный код

Сервис — один файл на Node с единственной зависимостью времени выполнения. Прочитайте его прежде, чем запускать. github.com/nostr-wot/LNbits-proxy