feat: add hub-managed Wallet Connections scaffolding

2026-07-27 02:10:11 +00:00
parent 5860f40e82
commit 9673f6733a
12 changed files with 853 additions and 5 deletions
@@ -0,0 +1,63 @@
+# Wallet Connections
+
+Wallet Connections is a Hub-managed Sovran_SystemsOS feature that lets members create isolated Lightning app connections and reusable Lightning Addresses.
+
+## Enablement flow
+
+Use the existing Hub service tile flow:
+
+1. Open **Wallet Connections** in Bitcoin Apps.
+2. Enable feature.
+3. Complete existing port/domain/DDNS/rebuild flow (80/TCP and 443/TCP).
+4. Reopen tile and manage connections.
+
+Node role behavior is unchanged: Node onboarding still skips global domain/port setup, and the `lightning` domain is configured on demand through feature enablement.
+
+## Architecture
+
+Public path:
+
+`Internet -> DNS/DDNS -> router 80/443 -> Caddy -> LNURL endpoints -> Hub NWC backend -> local LND stack`
+
+Security invariants:
+
+- Alby/NWC management remains local to the host.
+- LNURL callback/discovery are exposed only through Caddy on 80/443.
+- Management APIs are authenticated and remain under `/api/nwc/`.
+- Pairing secrets are returned only on create responses.
+- Invoice attribution enforces wallet isolation with app-id checks.
+
+## Domain and runtime files
+
+- Domain key: `lightning`
+- Runtime domain file: `/var/lib/domains/lightning`
+- Wallet state: `/var/lib/nwc-wallets/state.json`
+
+## API
+
+- `GET /api/nwc/wallets`
+- `POST /api/nwc/wallets`
+- `DELETE /api/nwc/wallets/{id-or-pubkey}`
+- `POST /api/nwc/wallets/{id-or-pubkey}/drain`
+- `POST /api/nwc/addresses/{alias}/test`
+
+Public LNURL:
+
+- `GET /.well-known/lnurlp/{alias}`
+- `GET /lnurlp/{alias}/callback?amount=<msat>`
+
+## Recovery CLI
+
+`nwc-wallet` is included with Hub package:
+
+- `nwc-wallet create <name> <alias> --receive-only`
+- `nwc-wallet create <name> <alias> --limit-sats <amount>`
+- `nwc-wallet list`
+- `nwc-wallet drain <wallet>`
+- `nwc-wallet delete <wallet>`
+- `nwc-wallet address show <alias>`
+- `nwc-wallet health`
+
+## Backup and restore
+
+Wallet Connections state is stored in `/var/lib/nwc-wallets` and is included with `/var/lib` backups. Backups contain sensitive wallet-connection material and must be protected.