thunder-bridge 1.3.0 → 1.4.1

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"],
@@ -92,6 +98,7 @@ them and this table does not repeat them.
 | `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. `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)
@@ -109,6 +116,8 @@ 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. `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.
 
@@ -167,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

package/dist/index.cjs

@@ -897,6 +897,18 @@ function triggerEventFromWire(body) {
     amountMsat: wire["incoming_amount"] === void 0 ? null : msatFrom(wire["incoming_amount"], 1)
   };
 }
+function socketTicketFromWire(body) {
+  const wire = asObject(body);
+  if (wire === null) {
+    return null;
+  }
+  const ticket = text(wire["ticket"]);
+  const expiresAt = secondsFrom(wire["expires_at"]);
+  if (ticket === null || expiresAt === null) {
+    return null;
+  }
+  return { ticket, expiresAt };
+}
 function kindOf(wire) {
   const said = wire["kind"];
   if (said === "minted" || said === "watched") {
@@ -1920,10 +1932,26 @@ var ThunderBridge = class {
       socket?.close();
     };
   }
+  /**
+   * A one minute pass onto one trigger's stream, for something that must hold
+   * neither the token nor the trigger secret. Mint it in a handler and answer
+   * with the ticket alone, because that is all a browser needs to connect and
+   * all it can do anything with. `watchTicketEndpoint` is this method already
+   * wrapped in a route
+   */
+  async createSocketTicket(params) {
+    return await this.mintedTicket({
+      trigger_secret: unguessable(params.trigger),
+      replay: params.replay
+    });
+  }
   needsTicket(asked) {
     return asked === true || this.token !== null;
   }
   async wsTicket(body) {
+    return encodeURIComponent((await this.mintedTicket(body)).ticket);
+  }
+  async mintedTicket(body) {
     const sent = JSON.stringify(body);
     const response = await fetch(`${this.baseUrl}/ws-tickets`, {
       method: "POST",
@@ -1933,14 +1961,14 @@ var ThunderBridge = class {
     if (!response.ok) {
       throw await problemFrom(response);
     }
-    const minted = await response.json().catch(() => null);
-    if (typeof minted?.ticket !== "string") {
+    const ticket = socketTicketFromWire(await response.json().catch(() => null));
+    if (ticket === null) {
       throw new ProblemError({
         status: response.status,
         title: "The gateway answered with something that is not a ticket"
       });
     }
-    return encodeURIComponent(minted.ticket);
+    return ticket;
   }
   async sending(path, body) {
     return { "content-type": "application/json", ...await this.reading("POST", path, body) };

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge, W as WalletFailure, a as ThunderBridgeOptions, b as WatchPaymentParams, c as TriggerEvent, d as WaitOptions, P as Payment, C as CreatePaymentParams, S as Settlement } from './rail-DZzlN-bi.cjs';
-export { B as BankRailConfig, e as CreateOptions, f as CreateQuoteParams, F as FollowOptions, L as Leg, g as LightningRailConfig, O as Order, h as PaymentKind, i as PaymentStatus, Q as Quote, R as Rail, j as WalletReason, k as bankRail, l as lightningRail, t as toLnurl } from './rail-DZzlN-bi.cjs';
+import { T as ThunderBridge, W as WalletFailure, a as ThunderBridgeOptions, b as WatchPaymentParams, c as TriggerEvent, d as WaitOptions, P as Payment, C as CreatePaymentParams, S as Settlement } from './rail-CqUfuYXJ.cjs';
+export { B as BankRailConfig, e as CreateOptions, f as CreateQuoteParams, F as FollowOptions, L as Leg, g as LightningRailConfig, O as Order, h as PaymentKind, i as PaymentStatus, Q as Quote, R as Rail, j as SocketTicket, k as SocketTicketParams, l as WalletReason, m as bankRail, n as lightningRail, t as toLnurl } from './rail-CqUfuYXJ.cjs';
 
 /** What a BOLT11 invoice says about itself, every field null when it does not carry one */
 interface Invoice {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge, W as WalletFailure, a as ThunderBridgeOptions, b as WatchPaymentParams, c as TriggerEvent, d as WaitOptions, P as Payment, C as CreatePaymentParams, S as Settlement } from './rail-DZzlN-bi.js';
-export { B as BankRailConfig, e as CreateOptions, f as CreateQuoteParams, F as FollowOptions, L as Leg, g as LightningRailConfig, O as Order, h as PaymentKind, i as PaymentStatus, Q as Quote, R as Rail, j as WalletReason, k as bankRail, l as lightningRail, t as toLnurl } from './rail-DZzlN-bi.js';
+import { T as ThunderBridge, W as WalletFailure, a as ThunderBridgeOptions, b as WatchPaymentParams, c as TriggerEvent, d as WaitOptions, P as Payment, C as CreatePaymentParams, S as Settlement } from './rail-CqUfuYXJ.js';
+export { B as BankRailConfig, e as CreateOptions, f as CreateQuoteParams, F as FollowOptions, L as Leg, g as LightningRailConfig, O as Order, h as PaymentKind, i as PaymentStatus, Q as Quote, R as Rail, j as SocketTicket, k as SocketTicketParams, l as WalletReason, m as bankRail, n as lightningRail, t as toLnurl } from './rail-CqUfuYXJ.js';
 
 /** What a BOLT11 invoice says about itself, every field null when it does not carry one */
 interface Invoice {

package/dist/index.js

@@ -816,6 +816,18 @@ function triggerEventFromWire(body) {
     amountMsat: wire["incoming_amount"] === void 0 ? null : msatFrom(wire["incoming_amount"], 1)
   };
 }
+function socketTicketFromWire(body) {
+  const wire = asObject(body);
+  if (wire === null) {
+    return null;
+  }
+  const ticket = text(wire["ticket"]);
+  const expiresAt = secondsFrom(wire["expires_at"]);
+  if (ticket === null || expiresAt === null) {
+    return null;
+  }
+  return { ticket, expiresAt };
+}
 function kindOf(wire) {
   const said = wire["kind"];
   if (said === "minted" || said === "watched") {
@@ -1839,10 +1851,26 @@ var ThunderBridge = class {
       socket?.close();
     };
   }
+  /**
+   * A one minute pass onto one trigger's stream, for something that must hold
+   * neither the token nor the trigger secret. Mint it in a handler and answer
+   * with the ticket alone, because that is all a browser needs to connect and
+   * all it can do anything with. `watchTicketEndpoint` is this method already
+   * wrapped in a route
+   */
+  async createSocketTicket(params) {
+    return await this.mintedTicket({
+      trigger_secret: unguessable(params.trigger),
+      replay: params.replay
+    });
+  }
   needsTicket(asked) {
     return asked === true || this.token !== null;
   }
   async wsTicket(body) {
+    return encodeURIComponent((await this.mintedTicket(body)).ticket);
+  }
+  async mintedTicket(body) {
     const sent = JSON.stringify(body);
     const response = await fetch(`${this.baseUrl}/ws-tickets`, {
       method: "POST",
@@ -1852,14 +1880,14 @@ var ThunderBridge = class {
     if (!response.ok) {
       throw await problemFrom(response);
     }
-    const minted = await response.json().catch(() => null);
-    if (typeof minted?.ticket !== "string") {
+    const ticket = socketTicketFromWire(await response.json().catch(() => null));
+    if (ticket === null) {
       throw new ProblemError({
         status: response.status,
         title: "The gateway answered with something that is not a ticket"
       });
     }
-    return encodeURIComponent(minted.ticket);
+    return ticket;
   }
   async sending(path, body) {
     return { "content-type": "application/json", ...await this.reading("POST", path, body) };

package/dist/{rail-DZzlN-bi.d.cts → rail-CqUfuYXJ.d.cts}

@@ -98,6 +98,23 @@ interface WatchPaymentParams {
     sealed?: string;
     webhookUrl?: string;
 }
+/**
+ * A one minute pass onto one trigger's stream. It opens that trigger and nothing
+ * else, which is what makes it the thing to hand a browser when the trigger
+ * secret is not. `expiresAt` is unix seconds, like every other time here
+ */
+interface SocketTicket {
+    ticket: string;
+    expiresAt: number;
+}
+/**
+ * Which trigger the ticket opens, and how many of its settlements the socket
+ * replays on connect, up to the ceiling the gateway's operator set
+ */
+interface SocketTicketParams {
+    trigger: string;
+    replay?: number;
+}
 /** Why one wallet in the list could not be used */
 type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
 interface WalletFailure {
@@ -326,8 +343,17 @@ declare class ThunderBridge {
      * is called. A trigger has no terminal state, so this never resolves
      */
     followTrigger(secret: string, options: FollowOptions): () => void;
+    /**
+     * A one minute pass onto one trigger's stream, for something that must hold
+     * neither the token nor the trigger secret. Mint it in a handler and answer
+     * with the ticket alone, because that is all a browser needs to connect and
+     * all it can do anything with. `watchTicketEndpoint` is this method already
+     * wrapped in a route
+     */
+    createSocketTicket(params: SocketTicketParams): Promise<SocketTicket>;
     private needsTicket;
     private wsTicket;
+    private mintedTicket;
     private sending;
     private reading;
     private speaking;
@@ -586,4 +612,4 @@ declare function nwcRail(config: NwcRailConfig): Rail;
  */
 declare function invoiceFrom(lnAddresses: string[], amountMsat: number): Promise<Resolved>;
 
-export { nwcSettlement as A, type BankRailConfig as B, type CreatePaymentParams as C, nwcVerifyEndpoint as D, nwcVerifyUrl as E, type FollowOptions as F, type Leg as L, type NwcConnection as N, type Order as O, type Payment as P, type Quote as Q, type Rail as R, type Settlement as S, ThunderBridge as T, type WalletFailure as W, type ThunderBridgeOptions as a, type WatchPaymentParams as b, type TriggerEvent as c, type WaitOptions as d, type CreateOptions as e, type CreateQuoteParams as f, type LightningRailConfig as g, type PaymentKind as h, type PaymentStatus as i, type WalletReason as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, type NwcInvoice as n, type NwcRailConfig as o, type NwcVerifyConfig as p, type Resolved as q, askWallet as r, blindLightningRail as s, toLnurl as t, invoiceFrom as u, nwcConnection as v, nwcHoldInvoice as w, nwcInvoice as x, nwcPay as y, nwcRail as z };
+export { nwcPay as A, type BankRailConfig as B, type CreatePaymentParams as C, nwcRail as D, nwcSettlement as E, type FollowOptions as F, nwcVerifyEndpoint as G, nwcVerifyUrl as H, type Leg as L, type NwcConnection as N, type Order as O, type Payment as P, type Quote as Q, type Rail as R, type Settlement as S, ThunderBridge as T, type WalletFailure as W, type ThunderBridgeOptions as a, type WatchPaymentParams as b, type TriggerEvent as c, type WaitOptions as d, type CreateOptions as e, type CreateQuoteParams as f, type LightningRailConfig as g, type PaymentKind as h, type PaymentStatus as i, type SocketTicket as j, type SocketTicketParams as k, type WalletReason as l, bankRail as m, lightningRail as n, type BlindLightningRailConfig as o, type NwcInvoice as p, type NwcRailConfig as q, type NwcVerifyConfig as r, type Resolved as s, toLnurl as t, askWallet as u, blindLightningRail as v, invoiceFrom as w, nwcConnection as x, nwcHoldInvoice as y, nwcInvoice as z };

package/dist/{rail-DZzlN-bi.d.ts → rail-CqUfuYXJ.d.ts}

@@ -98,6 +98,23 @@ interface WatchPaymentParams {
     sealed?: string;
     webhookUrl?: string;
 }
+/**
+ * A one minute pass onto one trigger's stream. It opens that trigger and nothing
+ * else, which is what makes it the thing to hand a browser when the trigger
+ * secret is not. `expiresAt` is unix seconds, like every other time here
+ */
+interface SocketTicket {
+    ticket: string;
+    expiresAt: number;
+}
+/**
+ * Which trigger the ticket opens, and how many of its settlements the socket
+ * replays on connect, up to the ceiling the gateway's operator set
+ */
+interface SocketTicketParams {
+    trigger: string;
+    replay?: number;
+}
 /** Why one wallet in the list could not be used */
 type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
 interface WalletFailure {
@@ -326,8 +343,17 @@ declare class ThunderBridge {
      * is called. A trigger has no terminal state, so this never resolves
      */
     followTrigger(secret: string, options: FollowOptions): () => void;
+    /**
+     * A one minute pass onto one trigger's stream, for something that must hold
+     * neither the token nor the trigger secret. Mint it in a handler and answer
+     * with the ticket alone, because that is all a browser needs to connect and
+     * all it can do anything with. `watchTicketEndpoint` is this method already
+     * wrapped in a route
+     */
+    createSocketTicket(params: SocketTicketParams): Promise<SocketTicket>;
     private needsTicket;
     private wsTicket;
+    private mintedTicket;
     private sending;
     private reading;
     private speaking;
@@ -586,4 +612,4 @@ declare function nwcRail(config: NwcRailConfig): Rail;
  */
 declare function invoiceFrom(lnAddresses: string[], amountMsat: number): Promise<Resolved>;
 
-export { nwcSettlement as A, type BankRailConfig as B, type CreatePaymentParams as C, nwcVerifyEndpoint as D, nwcVerifyUrl as E, type FollowOptions as F, type Leg as L, type NwcConnection as N, type Order as O, type Payment as P, type Quote as Q, type Rail as R, type Settlement as S, ThunderBridge as T, type WalletFailure as W, type ThunderBridgeOptions as a, type WatchPaymentParams as b, type TriggerEvent as c, type WaitOptions as d, type CreateOptions as e, type CreateQuoteParams as f, type LightningRailConfig as g, type PaymentKind as h, type PaymentStatus as i, type WalletReason as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, type NwcInvoice as n, type NwcRailConfig as o, type NwcVerifyConfig as p, type Resolved as q, askWallet as r, blindLightningRail as s, toLnurl as t, invoiceFrom as u, nwcConnection as v, nwcHoldInvoice as w, nwcInvoice as x, nwcPay as y, nwcRail as z };
+export { nwcPay as A, type BankRailConfig as B, type CreatePaymentParams as C, nwcRail as D, nwcSettlement as E, type FollowOptions as F, nwcVerifyEndpoint as G, nwcVerifyUrl as H, type Leg as L, type NwcConnection as N, type Order as O, type Payment as P, type Quote as Q, type Rail as R, type Settlement as S, ThunderBridge as T, type WalletFailure as W, type ThunderBridgeOptions as a, type WatchPaymentParams as b, type TriggerEvent as c, type WaitOptions as d, type CreateOptions as e, type CreateQuoteParams as f, type LightningRailConfig as g, type PaymentKind as h, type PaymentStatus as i, type SocketTicket as j, type SocketTicketParams as k, type WalletReason as l, bankRail as m, lightningRail as n, type BlindLightningRailConfig as o, type NwcInvoice as p, type NwcRailConfig as q, type NwcVerifyConfig as r, type Resolved as s, toLnurl as t, askWallet as u, blindLightningRail as v, invoiceFrom as w, nwcConnection as x, nwcHoldInvoice as y, nwcInvoice as z };

package/dist/server.cjs

@@ -43,7 +43,9 @@ __export(server_exports, {
   nwcSettlement: () => nwcSettlement,
   nwcVerifyEndpoint: () => nwcVerifyEndpoint,
   nwcVerifyUrl: () => nwcVerifyUrl,
-  relayedVerifyUrl: () => relayedVerifyUrl
+  publicWatchTicketEndpoint: () => publicWatchTicketEndpoint,
+  relayedVerifyUrl: () => relayedVerifyUrl,
+  watchTicketEndpoint: () => watchTicketEndpoint
 });
 module.exports = __toCommonJS(server_exports);
 
@@ -1447,6 +1449,18 @@ function lnurlPayEndpoint(config) {
     }
   };
 }
+function watchTicketEndpoint(config) {
+  return async (request) => {
+    const offered = await offeredSecret(request);
+    if (!equalInConstantTime(sha256Hex(offered), sha256Hex(config.watchSecret))) {
+      return Response.json({ reason: "not the watch secret" }, { status: 403 });
+    }
+    return await issue(config);
+  };
+}
+function publicWatchTicketEndpoint(config) {
+  return () => issue(config);
+}
 async function offer(config, url) {
   const amountMsat = await config.amountMsat();
   const quote = await config.gateway.createQuote({
@@ -1531,6 +1545,20 @@ function randomNonce() {
 function refuse(reason) {
   return Response.json({ status: "ERROR", reason });
 }
+async function issue(config) {
+  const issued = await config.gateway.createSocketTicket({
+    trigger: config.watchSecret,
+    replay: config.replay
+  });
+  return Response.json({
+    ticket: issued.ticket,
+    expires_at: new Date(issued.expiresAt * 1e3).toISOString()
+  });
+}
+async function offeredSecret(request) {
+  const body = await request.json().catch(() => null);
+  return typeof body?.secret === "string" ? body.secret : "";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   askWallet,
@@ -1546,5 +1574,7 @@ function refuse(reason) {
   nwcSettlement,
   nwcVerifyEndpoint,
   nwcVerifyUrl,
-  relayedVerifyUrl
+  publicWatchTicketEndpoint,
+  relayedVerifyUrl,
+  watchTicketEndpoint
 });

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge } from './rail-DZzlN-bi.cjs';
-export { m as BlindLightningRailConfig, N as NwcConnection, n as NwcInvoice, o as NwcRailConfig, p as NwcVerifyConfig, q as Resolved, r as askWallet, s as blindLightningRail, u as invoiceFrom, v as nwcConnection, w as nwcHoldInvoice, x as nwcInvoice, y as nwcPay, z as nwcRail, A as nwcSettlement, D as nwcVerifyEndpoint, E as nwcVerifyUrl } from './rail-DZzlN-bi.cjs';
+import { T as ThunderBridge } from './rail-CqUfuYXJ.cjs';
+export { o as BlindLightningRailConfig, N as NwcConnection, p as NwcInvoice, q as NwcRailConfig, r as NwcVerifyConfig, s as Resolved, u as askWallet, v as blindLightningRail, w as invoiceFrom, x as nwcConnection, y as nwcHoldInvoice, z as nwcInvoice, A as nwcPay, D as nwcRail, E as nwcSettlement, G as nwcVerifyEndpoint, H as nwcVerifyUrl } from './rail-CqUfuYXJ.cjs';
 
 /** The wallet's own LUD-21 URL and the hash its preimage has to match */
 interface Relayed {
@@ -92,6 +92,23 @@ interface Minted {
     verifyUrl: string;
     expiresAt: number;
 }
+/**
+ * A trigger's live stream is opened with a ticket rather than with the watch
+ * secret, so something has to hold the secret and trade it for tickets. That is
+ * what these two endpoints are, and they are the only place the gateway's token
+ * has to be
+ */
+interface WatchTicketConfig {
+    /** The gateway that mints the ticket, holding the token this keeps off the wire */
+    gateway: ThunderBridge;
+    /** The trigger to open, the same secret `lnurlPayEndpoint` groups its payments under */
+    watchSecret: string;
+    /**
+     * How many of this trigger's settlements the socket replays on connect, so a
+     * page opened late still shows what it missed, up to the gateway's ceiling
+     */
+    replay?: number;
+}
 /**
  * An LNURL-pay endpoint standing in front of a priority list of addresses, as a
  * Fetch handler so it runs on Deno Deploy, Workers, Hono, Next and Node alike.
@@ -105,5 +122,24 @@ interface Minted {
  * Nothing is stored between the two, so this holds no state of its own.
  */
 declare function lnurlPayEndpoint(config: TriggerConfig): (request: Request) => Promise<Response>;
+/**
+ * Trades the watch secret for a socket ticket, for a board that is not public.
+ * The caller has to know the secret already, so all this adds is that the secret
+ * stops travelling in socket URLs, where the gateway, every proxy in front of it
+ * and the browser's own history all keep a copy. Anyone without it gets a 403.
+ *
+ * POST to it before every connect, because a ticket lives one minute.
+ */
+declare function watchTicketEndpoint(config: WatchTicketConfig): (request: Request) => Promise<Response>;
+/**
+ * Mints a socket ticket for anybody who asks, for a board meant to be read by
+ * strangers. It reads no body and refuses nobody, which makes the trigger's
+ * whole stream public: every viewer gets each settlement's preimage, verify url
+ * and payment hash.
+ *
+ * Only for a trigger where that is the point. Gate anything on those preimages
+ * and a viewer of the board is holding the unlock.
+ */
+declare function publicWatchTicketEndpoint(config: WatchTicketConfig): (request: Request) => Promise<Response>;
 
-export { type LightningVerifyConfig, type Minted, type Relayed, type TriggerConfig, lightningVerifyEndpoint, lnurlPayEndpoint, relayedVerifyUrl };
+export { type LightningVerifyConfig, type Minted, type Relayed, type TriggerConfig, type WatchTicketConfig, lightningVerifyEndpoint, lnurlPayEndpoint, publicWatchTicketEndpoint, relayedVerifyUrl, watchTicketEndpoint };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge } from './rail-DZzlN-bi.js';
-export { m as BlindLightningRailConfig, N as NwcConnection, n as NwcInvoice, o as NwcRailConfig, p as NwcVerifyConfig, q as Resolved, r as askWallet, s as blindLightningRail, u as invoiceFrom, v as nwcConnection, w as nwcHoldInvoice, x as nwcInvoice, y as nwcPay, z as nwcRail, A as nwcSettlement, D as nwcVerifyEndpoint, E as nwcVerifyUrl } from './rail-DZzlN-bi.js';
+import { T as ThunderBridge } from './rail-CqUfuYXJ.js';
+export { o as BlindLightningRailConfig, N as NwcConnection, p as NwcInvoice, q as NwcRailConfig, r as NwcVerifyConfig, s as Resolved, u as askWallet, v as blindLightningRail, w as invoiceFrom, x as nwcConnection, y as nwcHoldInvoice, z as nwcInvoice, A as nwcPay, D as nwcRail, E as nwcSettlement, G as nwcVerifyEndpoint, H as nwcVerifyUrl } from './rail-CqUfuYXJ.js';
 
 /** The wallet's own LUD-21 URL and the hash its preimage has to match */
 interface Relayed {
@@ -92,6 +92,23 @@ interface Minted {
     verifyUrl: string;
     expiresAt: number;
 }
+/**
+ * A trigger's live stream is opened with a ticket rather than with the watch
+ * secret, so something has to hold the secret and trade it for tickets. That is
+ * what these two endpoints are, and they are the only place the gateway's token
+ * has to be
+ */
+interface WatchTicketConfig {
+    /** The gateway that mints the ticket, holding the token this keeps off the wire */
+    gateway: ThunderBridge;
+    /** The trigger to open, the same secret `lnurlPayEndpoint` groups its payments under */
+    watchSecret: string;
+    /**
+     * How many of this trigger's settlements the socket replays on connect, so a
+     * page opened late still shows what it missed, up to the gateway's ceiling
+     */
+    replay?: number;
+}
 /**
  * An LNURL-pay endpoint standing in front of a priority list of addresses, as a
  * Fetch handler so it runs on Deno Deploy, Workers, Hono, Next and Node alike.
@@ -105,5 +122,24 @@ interface Minted {
  * Nothing is stored between the two, so this holds no state of its own.
  */
 declare function lnurlPayEndpoint(config: TriggerConfig): (request: Request) => Promise<Response>;
+/**
+ * Trades the watch secret for a socket ticket, for a board that is not public.
+ * The caller has to know the secret already, so all this adds is that the secret
+ * stops travelling in socket URLs, where the gateway, every proxy in front of it
+ * and the browser's own history all keep a copy. Anyone without it gets a 403.
+ *
+ * POST to it before every connect, because a ticket lives one minute.
+ */
+declare function watchTicketEndpoint(config: WatchTicketConfig): (request: Request) => Promise<Response>;
+/**
+ * Mints a socket ticket for anybody who asks, for a board meant to be read by
+ * strangers. It reads no body and refuses nobody, which makes the trigger's
+ * whole stream public: every viewer gets each settlement's preimage, verify url
+ * and payment hash.
+ *
+ * Only for a trigger where that is the point. Gate anything on those preimages
+ * and a viewer of the board is holding the unlock.
+ */
+declare function publicWatchTicketEndpoint(config: WatchTicketConfig): (request: Request) => Promise<Response>;
 
-export { type LightningVerifyConfig, type Minted, type Relayed, type TriggerConfig, lightningVerifyEndpoint, lnurlPayEndpoint, relayedVerifyUrl };
+export { type LightningVerifyConfig, type Minted, type Relayed, type TriggerConfig, type WatchTicketConfig, lightningVerifyEndpoint, lnurlPayEndpoint, publicWatchTicketEndpoint, relayedVerifyUrl, watchTicketEndpoint };

package/dist/server.js

@@ -1398,6 +1398,18 @@ function lnurlPayEndpoint(config) {
     }
   };
 }
+function watchTicketEndpoint(config) {
+  return async (request) => {
+    const offered = await offeredSecret(request);
+    if (!equalInConstantTime(sha256Hex(offered), sha256Hex(config.watchSecret))) {
+      return Response.json({ reason: "not the watch secret" }, { status: 403 });
+    }
+    return await issue(config);
+  };
+}
+function publicWatchTicketEndpoint(config) {
+  return () => issue(config);
+}
 async function offer(config, url) {
   const amountMsat = await config.amountMsat();
   const quote = await config.gateway.createQuote({
@@ -1482,6 +1494,20 @@ function randomNonce() {
 function refuse(reason) {
   return Response.json({ status: "ERROR", reason });
 }
+async function issue(config) {
+  const issued = await config.gateway.createSocketTicket({
+    trigger: config.watchSecret,
+    replay: config.replay
+  });
+  return Response.json({
+    ticket: issued.ticket,
+    expires_at: new Date(issued.expiresAt * 1e3).toISOString()
+  });
+}
+async function offeredSecret(request) {
+  const body = await request.json().catch(() => null);
+  return typeof body?.secret === "string" ? body.secret : "";
+}
 export {
   askWallet,
   blindLightningRail,
@@ -1496,5 +1522,7 @@ export {
   nwcSettlement,
   nwcVerifyEndpoint,
   nwcVerifyUrl,
-  relayedVerifyUrl
+  publicWatchTicketEndpoint,
+  relayedVerifyUrl,
+  watchTicketEndpoint
 };

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: thunder-bridge, the endpoint your own service serves
-  version: 1.2.0
+  version: 1.4.1
   license:
     name: MIT
     identifier: MIT
@@ -26,8 +26,12 @@ info:
 
     `bankVerifyEndpoint` is the other handler, and it puts a second rail behind the same
     contract: a bank transfer, proved to the gateway by the LUD-21 shape a Lightning wallet
-    would have answered with. Both paths below are therefore yours to mount and yours to
-    serve, and neither of them is the gateway.
+    would have answered with.
+
+    `watchTicketEndpoint` and `publicWatchTicketEndpoint` are the third, and they exist so a
+    browser can read a trigger's live stream without holding the credentials that open it.
+    Every path below is therefore yours to mount and yours to serve, and none of them is the
+    gateway.
 
     The gateway's own API is a separate document, `openapi.yaml` in the repository root, and
     the webhook your server receives is described there under `webhooks`.
@@ -43,6 +47,8 @@ tags:
     description: The two halves of LUD-06, on the one path a lightning address resolves to.
   - name: bank-transfer
     description: The settlement proof for money that arrived over a bank rail instead of Lightning.
+  - name: live-board
+    description: The exchange that lets a page watch a trigger without being given its secret.
 
 paths:
   /.well-known/lnurlp/{name}:
@@ -137,6 +143,57 @@ paths:
                   - $ref: "#/components/schemas/invoice"
                   - $ref: "#/components/schemas/refusal"
 
+  /watch/ticket:
+    post:
+      tags: [live-board]
+      operationId: mintWatchTicket
+      summary: Trade the watch secret for a socket ticket a browser may hold
+      description: |
+        Mounted wherever you like by `watchTicketEndpoint`, or by
+        `publicWatchTicketEndpoint` when the board is meant to be read by strangers. Which
+        one you mounted is the whole difference: the first compares the offered secret in
+        constant time and answers 403 without it, the second reads no body and refuses
+        nobody.
+
+        It exists because the socket is opened at the gateway's `/ws/tickets/{ticket}`, and
+        minting a ticket needs the bearer token and the watch secret. Neither may reach a
+        browser, so this endpoint holds both and hands back only the ticket, which opens one
+        trigger and nothing else.
+
+        The answer is the gateway's own, passed through unchanged. A ticket lives one minute,
+        so a page POSTs here immediately before every connect rather than caching one.
+
+        A public board is public in full. Every viewer of that socket gets each settlement's
+        preimage, verify url and payment hash, which is fine for a tip jar and wrong the
+        moment anything is gated behind those preimages.
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                secret:
+                  type: string
+                  description: |
+                    The same watch secret the trigger groups its payments under. Required by
+                    `watchTicketEndpoint` and ignored by `publicWatchTicketEndpoint`.
+      responses:
+        "200":
+          description: A ticket, good for one socket on one trigger for one minute.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/socket_ticket"
+        "403":
+          description: |
+            The body did not carry the watch secret. Never answered by
+            `publicWatchTicketEndpoint`, which does not read one.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/not_the_secret"
+
   /verify/bank:
     get:
       tags: [bank-transfer]
@@ -274,6 +331,30 @@ components:
           const: false
       required: [settled]
 
+    socket_ticket:
+      type: object
+      description: The gateway's ticket, passed through so a page reading `.ticket` needs no change.
+      properties:
+        ticket:
+          type: string
+          description: |
+            Goes in the gateway's `/ws/tickets/{ticket}` path. Signed, not stored, and bound
+            to the one trigger it was minted for.
+        expires_at:
+          type: string
+          format: date-time
+          description: A minute from minting. A ticket presented after it is refused at the handshake.
+      required: [ticket, expires_at]
+
+    not_the_secret:
+      type: object
+      description: A refusal that says only that the secret was wrong, never what was expected.
+      properties:
+        reason:
+          type: string
+          const: not the watch secret
+      required: [reason]
+
     ln_address:
       type: string
       format: email

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thunder-bridge",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Trustless JavaScript client for the Thunder Bridge Lightning payment gateway. Proves the invoice came from your own wallet before the payer sees it.",
   "author": "i-am-fatik",
   "homepage": "https://agora.gripe/en/tools/thunder-bridge",