thunder-bridge 1.1.0 → 1.4.0

package/dist/server.d.cts

@@ -1,5 +1,44 @@
-import { T as ThunderBridge } from './rail-Dp8bs6uZ.cjs';
-export { m as BlindLightningRailConfig, n as Resolved, o as blindLightningRail, p as invoiceFrom } from './rail-Dp8bs6uZ.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 {
+    url: string;
+    hash: string;
+}
+interface LightningVerifyConfig {
+    /** The secret the sealed wallet URL was made with, and nothing else uses it */
+    secret: string;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours rather than the operator's.
+     * Five by default, which is what a Lightning checkout wants
+     */
+    pollEverySecs?: number;
+}
+/**
+ * A verify endpoint of your own that asks the recipient's wallet for you, so the
+ * gateway polls you and never the wallet.
+ *
+ * `relayedVerifyUrl` seals the wallet's own LUD-21 URL into the query with your
+ * secret, so what the gateway stores and replicates is opaque: not the wallet's
+ * host, not which provider the recipient uses, nothing but a blob it cannot read.
+ * This handler unseals it, asks the wallet, and answers the same LUD-21 shape.
+ *
+ * It relays rather than decides. The preimage still comes from the recipient's
+ * own server and still has to hash to the payment hash, so standing between the
+ * two buys privacy and pacing without becoming something anyone has to trust.
+ *
+ * A wallet it cannot reach answers `502` rather than "not settled", because those
+ * are different claims and only one of them is true. The gateway logs a failed
+ * poll and asks again, which is what a broken relay should look like.
+ */
+declare function lightningVerifyEndpoint(config: LightningVerifyConfig): (request: Request) => Promise<Response>;
+/**
+ * The URL to hand the gateway instead of the wallet's own, with the wallet's
+ * sealed inside it. Point it at wherever `lightningVerifyEndpoint` is mounted
+ */
+declare function relayedVerifyUrl(endpoint: string, wallet: Relayed, secret: string): Promise<string>;
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */
@@ -18,6 +57,12 @@ interface TriggerConfig {
     secret: string;
     /** Groups every payment here so `followTrigger` can watch the place, keep it off the QR */
     watchSecret?: string;
+    /**
+     * How many settlements of this place the gateway keeps replayable past the hour
+     * it would otherwise forget them in, up to the ceiling its operator set. What a
+     * page that opens later still gets to see. Needs `watchSecret`
+     */
+    replay?: number;
     /** Override when a proxy hides the public URL from the request, no trailing slash */
     baseUrl?: string;
     /**
@@ -47,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.
@@ -60,44 +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>;
-
-/** The wallet's own LUD-21 URL and the hash its preimage has to match */
-interface Relayed {
-    url: string;
-    hash: string;
-}
-interface LightningVerifyConfig {
-    /** The secret the sealed wallet URL was made with, and nothing else uses it */
-    secret: string;
-    /**
-     * How often you want the gateway to ask, in seconds. It goes out as
-     * `Cache-Control: max-age`, so the pace is yours rather than the operator's.
-     * Five by default, which is what a Lightning checkout wants
-     */
-    pollEverySecs?: number;
-}
 /**
- * A verify endpoint of your own that asks the recipient's wallet for you, so the
- * gateway polls you and never the wallet.
- *
- * `relayedVerifyUrl` seals the wallet's own LUD-21 URL into the query with your
- * secret, so what the gateway stores and replicates is opaque: not the wallet's
- * host, not which provider the recipient uses, nothing but a blob it cannot read.
- * This handler unseals it, asks the wallet, and answers the same LUD-21 shape.
- *
- * It relays rather than decides. The preimage still comes from the recipient's
- * own server and still has to hash to the payment hash, so standing between the
- * two buys privacy and pacing without becoming something anyone has to trust.
+ * 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.
  *
- * A wallet it cannot reach answers `502` rather than "not settled", because those
- * are different claims and only one of them is true. The gateway logs a failed
- * poll and asks again, which is what a broken relay should look like.
+ * POST to it before every connect, because a ticket lives one minute.
  */
-declare function lightningVerifyEndpoint(config: LightningVerifyConfig): (request: Request) => Promise<Response>;
+declare function watchTicketEndpoint(config: WatchTicketConfig): (request: Request) => Promise<Response>;
 /**
- * The URL to hand the gateway instead of the wallet's own, with the wallet's
- * sealed inside it. Point it at wherever `lightningVerifyEndpoint` is mounted
+ * 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 relayedVerifyUrl(endpoint: string, wallet: Relayed, secret: string): Promise<string>;
+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,44 @@
-import { T as ThunderBridge } from './rail-Dp8bs6uZ.js';
-export { m as BlindLightningRailConfig, n as Resolved, o as blindLightningRail, p as invoiceFrom } from './rail-Dp8bs6uZ.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 {
+    url: string;
+    hash: string;
+}
+interface LightningVerifyConfig {
+    /** The secret the sealed wallet URL was made with, and nothing else uses it */
+    secret: string;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours rather than the operator's.
+     * Five by default, which is what a Lightning checkout wants
+     */
+    pollEverySecs?: number;
+}
+/**
+ * A verify endpoint of your own that asks the recipient's wallet for you, so the
+ * gateway polls you and never the wallet.
+ *
+ * `relayedVerifyUrl` seals the wallet's own LUD-21 URL into the query with your
+ * secret, so what the gateway stores and replicates is opaque: not the wallet's
+ * host, not which provider the recipient uses, nothing but a blob it cannot read.
+ * This handler unseals it, asks the wallet, and answers the same LUD-21 shape.
+ *
+ * It relays rather than decides. The preimage still comes from the recipient's
+ * own server and still has to hash to the payment hash, so standing between the
+ * two buys privacy and pacing without becoming something anyone has to trust.
+ *
+ * A wallet it cannot reach answers `502` rather than "not settled", because those
+ * are different claims and only one of them is true. The gateway logs a failed
+ * poll and asks again, which is what a broken relay should look like.
+ */
+declare function lightningVerifyEndpoint(config: LightningVerifyConfig): (request: Request) => Promise<Response>;
+/**
+ * The URL to hand the gateway instead of the wallet's own, with the wallet's
+ * sealed inside it. Point it at wherever `lightningVerifyEndpoint` is mounted
+ */
+declare function relayedVerifyUrl(endpoint: string, wallet: Relayed, secret: string): Promise<string>;
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */
@@ -18,6 +57,12 @@ interface TriggerConfig {
     secret: string;
     /** Groups every payment here so `followTrigger` can watch the place, keep it off the QR */
     watchSecret?: string;
+    /**
+     * How many settlements of this place the gateway keeps replayable past the hour
+     * it would otherwise forget them in, up to the ceiling its operator set. What a
+     * page that opens later still gets to see. Needs `watchSecret`
+     */
+    replay?: number;
     /** Override when a proxy hides the public URL from the request, no trailing slash */
     baseUrl?: string;
     /**
@@ -47,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.
@@ -60,44 +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>;
-
-/** The wallet's own LUD-21 URL and the hash its preimage has to match */
-interface Relayed {
-    url: string;
-    hash: string;
-}
-interface LightningVerifyConfig {
-    /** The secret the sealed wallet URL was made with, and nothing else uses it */
-    secret: string;
-    /**
-     * How often you want the gateway to ask, in seconds. It goes out as
-     * `Cache-Control: max-age`, so the pace is yours rather than the operator's.
-     * Five by default, which is what a Lightning checkout wants
-     */
-    pollEverySecs?: number;
-}
 /**
- * A verify endpoint of your own that asks the recipient's wallet for you, so the
- * gateway polls you and never the wallet.
- *
- * `relayedVerifyUrl` seals the wallet's own LUD-21 URL into the query with your
- * secret, so what the gateway stores and replicates is opaque: not the wallet's
- * host, not which provider the recipient uses, nothing but a blob it cannot read.
- * This handler unseals it, asks the wallet, and answers the same LUD-21 shape.
- *
- * It relays rather than decides. The preimage still comes from the recipient's
- * own server and still has to hash to the payment hash, so standing between the
- * two buys privacy and pacing without becoming something anyone has to trust.
+ * 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.
  *
- * A wallet it cannot reach answers `502` rather than "not settled", because those
- * are different claims and only one of them is true. The gateway logs a failed
- * poll and asks again, which is what a broken relay should look like.
+ * POST to it before every connect, because a ticket lives one minute.
  */
-declare function lightningVerifyEndpoint(config: LightningVerifyConfig): (request: Request) => Promise<Response>;
+declare function watchTicketEndpoint(config: WatchTicketConfig): (request: Request) => Promise<Response>;
 /**
- * The URL to hand the gateway instead of the wallet's own, with the wallet's
- * sealed inside it. Point it at wherever `lightningVerifyEndpoint` is mounted
+ * 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 relayedVerifyUrl(endpoint: string, wallet: Relayed, secret: string): Promise<string>;
+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 };