thunder-bridge 1.1.0 → 1.4.0

package/README.md

@@ -34,10 +34,16 @@ A page can run the whole flow with no backend of its own. The gateway answers
 every origin, and coinos, Alby and Stacker News serve their LNURL endpoints with
 CORS open, so the proof fetches work from a browser too.
 
+The url below is a shared demo that answers anyone and forgets everything on
+restart. It is there so this snippet runs as written. It is a base url rather than a
+page, so opening it in a browser gives a `404` and
+[`/health`](https://public.thunder-bridge.agora.gripe/health) is what tells you it is
+up. Point production at a gateway of your own, which takes one command.
+
 ```ts
 import { ThunderBridge, invoiceToSvg, type CreatePaymentParams } from "thunder-bridge";
 
-const gateway = new ThunderBridge("https://thunder-bridge-production.up.railway.app");
+const gateway = new ThunderBridge("https://public.thunder-bridge.agora.gripe");
 
 const request: CreatePaymentParams = {
   lnAddresses: ["alice@coinos.io", "alice@getalby.com"],
@@ -91,7 +97,8 @@ them and this table does not repeat them.
 | `gateway.waitForWatched(id, options?)` | the same for a watched one, answering the shape both rails share |
 | `gateway.firstToSettle(ids, options?)` | wait on several legs, keep the first really paid, drop the losers |
 | `gateway.watchPayment(params)` | hand over an invoice you obtained yourself, without the address or the amount |
-| `gateway.followTrigger(secret, options)` | stream every payment carrying one trigger, reconnecting on its own |
+| `gateway.followTrigger(secret, options)` | stream every payment carrying one trigger, reconnecting on its own. `replay` asks for how many past settlements on connect |
+| `gateway.createSocketTicket(params)` | a one minute pass onto one trigger's stream, to hand something that must not hold the secret |
 | `gateway.isPrivate` | whether a token was given |
 
 **Proving it** - [`src/verify.ts`](src/verify.ts)
@@ -108,7 +115,9 @@ them and this table does not repeat them.
 
 | Export | What it does |
 |---|---|
-| `lnurlPayEndpoint(config)` | a whole LNURL-pay endpoint as one Fetch handler, so a static QR points at your domain. From `thunder-bridge/server` |
+| `lnurlPayEndpoint(config)` | a whole LNURL-pay endpoint as one Fetch handler, so a static QR points at your domain. `replay` keeps its last settlements on the gateway for a page that opens later. From `thunder-bridge/server` |
+| `watchTicketEndpoint(config)` | mints socket tickets for callers who already know the watch secret, 403 for the rest. From `thunder-bridge/server` |
+| `publicWatchTicketEndpoint(config)` | the same for a board strangers are meant to read, minting for anyone. From `thunder-bridge/server` |
 | `seal(secret, plaintext)`, `unseal` | the blob the gateway stores and cannot read |
 | `toLnurl(url)` | bech32-encode an endpoint url |
 | `bankTransfer(params)` | register a Czech QR platba as a watched payment. Refuses a gateway that serves strangers |
@@ -117,6 +126,16 @@ them and this table does not repeat them.
 | `lightningVerifyEndpoint(config)` | the same shape for Lightning, asking the wallet on the gateway's behalf. From `thunder-bridge/server` |
 | `relayedVerifyUrl(mount, wallet, secret)` | the URL to hand the gateway instead of the wallet's, with the wallet's sealed inside |
 
+There are two ticket endpoints rather than one taking a flag, so the call site
+says which board this is. Mount one on its own path and POST to it from the page
+before every connect, because a ticket lives a minute. Whichever you mount, the
+page never holds the watch secret, which is the reason to mount either.
+
+A public board is public in full: every viewer of that socket gets each
+settlement's preimage, verify url and payment hash. Fine for a tip jar, wrong the
+moment anything is gated behind those preimages, because then a viewer holds the
+unlock.
+
 What your service answers once those handlers are mounted is written out in
 [`openapi.yaml`](openapi.yaml), shipped with this package.
 
@@ -132,6 +151,7 @@ whatever runtime you keep state in.
 | `bankRail(config)` | a `Rail` selling for a bank transfer, reading back through any `Statement` |
 | `lightningRail(config)` | a `Rail` where the gateway mints the invoice, so it learns the address and the amount |
 | `blindLightningRail(config)` | a `Rail` that resolves the address itself and tells the gateway only a hash. From `thunder-bridge/server` |
+| `nwcRail(config)` | a `Rail` that mints on a wallet of your own over NIP-47, for a wallet with no LUD-21 address to be watched at. From `thunder-bridge/server` |
 
 `Rail` is `(order: Order) => Promise<Leg>`. Everything that differs between rails
 is bound once when the rail is built, so the only thing passed per sale is which
@@ -166,9 +186,13 @@ BOLT12 offer is not handled, because this gateway never returns one.
 import { invoiceToSvg, lnurlToSvg } from "thunder-bridge";
 
 const toPay = invoiceToSvg(payment.bolt11, { size: 320, color: "#1a1a2e" });
-const tipJar = lnurlToSvg("https://agora.gripe/tip");
+const tipJar = lnurlToSvg("https://thunder-bridge.agora.gripe/.well-known/lnurlp/21sats");
 ```
 
+That second url is live and built with this library, a fixed 21 sat tip served by
+`lnurlPayEndpoint`, so the QR it returns is one you can scan to see the whole flow
+end to end.
+
 **Minting your own invoice** - [`src/rail.ts`](src/rail.ts): `invoiceFrom`, from
 `thunder-bridge/server`. A gateway that does not mint is one that never sees an
 address or an amount, so this is how a client gets a provable invoice itself and hands
@@ -293,6 +317,40 @@ is only ever talking to servers that asked to be talked to. It costs you a servi
 that has to stay up: a browser-only integration cannot do this, and should keep
 letting the gateway poll the wallet.
 
+### A wallet with no LUD-21 address at all
+
+`nwcRail` is the same arrangement with the far side swapped. Your wallet answers
+over [NIP-47](https://github.com/nostr-protocol/nips/blob/master/47.md) instead of
+over an address, so a recipient whose provider publishes no `verify` - or publishes
+one with no preimage, which is worse - is watchable anyway.
+
+```ts
+import { nwcConnection, nwcRail, nwcVerifyEndpoint } from "thunder-bridge/server";
+
+const connection = nwcConnection(process.env.NWC_URI);
+
+app.get("/verify/nwc", (context) =>
+  nwcVerifyEndpoint({ connection, secret: NWC_SECRET })(context.req.raw),
+);
+
+const rail = nwcRail({
+  gateway,
+  connection,
+  amountMsat: (order) => order.amountMinor * 40,
+  verifyThrough: { endpoint: "https://shop.example/verify/nwc", secret: NWC_SECRET },
+});
+```
+
+`make_invoice` mints it, `lookup_invoice` reads the preimage back, and the payment
+hash is sealed into the query for the reason the wallet's URL is sealed above: it
+is what stops a stranger driving your wallet through your own handler. Only the
+hash travels, so the gateway never holds the connection, the relay or the wallet
+key, and every answer is refused unless the wallet's own key signed it.
+
+Take the connection string scoped. ZEUS, Alby Hub and Blink all issue one per app
+with its own permissions and budget, and this needs `make_invoice` and
+`lookup_invoice` and nothing else - never `pay_invoice`.
+
 ### How often the gateway asks
 
 Your endpoint decides, not the gateway. `bankVerifyEndpoint` answers with
@@ -301,10 +359,59 @@ payment on your host. Set `pollEverySecs` to whatever your bank's own refresh ma
 sensible: reading a statement that moves once an hour every five seconds only burns
 your rate limit.
 
+How long one answer may take is the other half of the pacing. The gateway abandons a
+poll after 15 seconds, and `askTimeoutMs` is one deadline over the whole connection
+rather than one per relay, so a connection listing four relays still answers inside
+that window.
+
 The gateway also asks the URL once, before it accepts the watch, and refuses with
 `424` if it does not answer this shape. So deploy the endpoint first and register
 second. That is what stops anyone pointing a gateway at a server that never asked to
-be polled for three days.
+be polled for thirty days.
+
+## Paying through an operator who fronts the liquidity
+
+A recipient with no inbound liquidity cannot be paid at all. An operator with a node
+can stand in the middle without holding anything: it takes the recipient's own
+invoice, mints a **hold invoice on the same payment hash** for the amount plus a fee,
+and can settle its own only by revealing the preimage it learned from paying the
+recipient. Claiming and delivering are one act, so there is no moment where it keeps
+the money and walks away.
+
+This SDK does not wrap. `proveWrapped` checks a wrap somebody else offers, and the
+NIP-47 primitives an operator would build one from, `nwcHoldInvoice` and `nwcPay`,
+are on `thunder-bridge/server` with nothing here driving them.
+
+```ts
+import { invoiceFrom } from "thunder-bridge/server";
+import { proveWrapped, wrapFeeCeiling } from "thunder-bridge";
+
+const real = await invoiceFrom(["you@blink.sv"], 21_000_000);
+const wrapped = await myOperator.wrap(real.bolt11);
+
+proveWrapped(wrapped, real.bolt11);
+```
+
+`proveWrapped` compares two invoices and asks nobody anything, so it runs in a
+browser. It refuses a wrap on another hash, one that cannot cover what the recipient
+asked, one charging over the allowance, and one that outlives the invoice it has to
+forward to.
+
+The allowance is the **client's ceiling**, not a fee the operator names per payment,
+so it sits deliberately above any list price: `1%` by default with a floor of one
+satoshi. An operator running this charges `0.75%`, which leaves room for a wrap a
+shade over list to still go through. Set `proportion` under an operator's price and
+you refuse that operator, which is the point of it being yours.
+`wrapFeeCeiling(amountMsat, allowance)` is the same number if you want to show it.
+
+There is no settlement check to add. Both invoices carry one payment hash, so the
+preimage that settles the wrap is the one the recipient released, and
+`proveSettlement` already reads it from the recipient's own server. The gateway needs
+no change either: it watches that hash and polls the recipient's verify URL, and a
+wrap is invisible to it.
+
+What this does not cover: an operator that accepts the payment and stalls until the
+HTLC times out. Your money comes back, and it was locked meanwhile.
 
 ## What is still trusted
 
@@ -501,11 +608,13 @@ on that route and not a JSON one.
 import express from "express";
 import { parseWebhook } from "thunder-bridge";
 
+const signs = { publicKey: await gateway.webhookKey() };
+
 app.post("/hooks/paid", express.raw({ type: "application/json" }), async (request, response) => {
   const payment = await parseWebhook(
     request.body,
     request.get("x-signature") ?? "",
-    secret,
+    signs,
     request.get("x-timestamp") ?? "",
   );
   response.sendStatus(payment === null ? 401 : 200);