thunder-bridge 0.8.10 → 1.1.0

package/dist/{rail-J8QoYbSr.d.cts → rail-Dp8bs6uZ.d.cts}

@@ -23,7 +23,6 @@ interface CreatePaymentParams {
     lnAddresses: string[];
     amountMsat: number;
     webhookUrl?: string;
-    webhookSecret?: string;
 }
 /**
  * `lnAddresses` is the same priority list `createPayment` takes, and quoting it
@@ -78,7 +77,6 @@ interface WatchPaymentParams {
     trigger?: string;
     sealed?: string;
     webhookUrl?: string;
-    webhookSecret?: string;
 }
 /** Why one wallet in the list could not be used */
 type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
@@ -86,6 +84,17 @@ interface WalletFailure {
     address: string;
     reason: WalletReason;
 }
+/**
+ * What a delivery carries. Everything needed to act on a settlement and to check
+ * it, and nothing else, so a retry is the same size every time
+ */
+interface Settlement {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    preimage: string | null;
+    settledAt: number;
+}
 
 interface ThunderBridgeOptions {
     /**
@@ -101,6 +110,13 @@ interface ThunderBridgeOptions {
      * through a ticket
      */
     token?: string;
+    /**
+     * The same long lived server side secret your rail derives its preimages from.
+     * Given here, every call carries a signature the gateway reads as your identity,
+     * so a payment you create is handed back to you and to nobody else. Withheld,
+     * you are anonymous and any holder of an id can read what it names
+     */
+    secret?: string;
 }
 interface WaitOptions {
     /** Give up when this aborts, `AbortSignal.timeout(ms)` covers the usual case */
@@ -159,7 +175,9 @@ declare class ThunderBridge {
     private readonly baseUrl;
     private readonly verify;
     private readonly token;
+    private readonly secret;
     private strangers;
+    private speaks;
     constructor(baseUrl: string, options?: ThunderBridgeOptions);
     /**
      * Whether a token was given, which is what makes an instance yours: a gateway
@@ -262,6 +280,14 @@ declare class ThunderBridge {
      * the watcher needs goes in `sealed`, which the gateway cannot read
      */
     watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
+    /**
+     * What this payment is called, which you can work out before any gateway has
+     * heard of it. Every gateway you hand the same invoice to answers with the same
+     * name, so watching at several of them adds up to one payment rather than
+     * several, and no gateway's key is in the answer. Null when no secret was given,
+     * because then the gateway names the payment and only it can
+     */
+    nameFor(paymentHash: string): Promise<string | null>;
     /**
      * Follow every payment made to one trigger, replayed from the recent ones on
      * connect and then live, reconnecting on its own until the returned function
@@ -272,10 +298,25 @@ declare class ThunderBridge {
     private wsTicket;
     private sending;
     private reading;
+    private speaking;
     private proven;
     private checked;
 }
 
+type Resolved = {
+    address: string;
+    bolt11: string;
+    verifyUrl: string;
+    paymentHash: string;
+    expiresAt: number;
+};
+/**
+ * Bech32-encode a pay endpoint as the `LNURL1` string LUD-01 defines, uppercase
+ * because that is the form it asks a QR to carry. An onion endpoint is http
+ * rather than https, which LUD-17 spells out, so both are taken here
+ */
+declare function toLnurl(endpoint: string): string;
+
 /** What a shop knows about a sale before any rail exists */
 interface Order {
     /** The bank matches it on the statement, and Lightning keys idempotency on it */
@@ -324,7 +365,6 @@ interface BankRailConfig {
     /** Up to ten digits, for accounting systems that still want one */
     variableSymbol?: (order: Order) => string | undefined;
     webhookUrl?: string;
-    webhookSecret?: string;
     /** Register on a gateway you do not own anyway, on the terms `bankTransfer` sets out */
     allowPublicGateway?: boolean;
     /** What `Leg.rail` reads, for a shop running more than one account */
@@ -345,7 +385,6 @@ interface LightningRailConfig {
      */
     idempotencyKey?: (order: Order) => string | undefined;
     webhookUrl?: string;
-    webhookSecret?: string;
     /** What `Leg.rail` reads, for a shop running more than one wallet */
     name?: string;
 }
@@ -361,7 +400,6 @@ interface BlindLightningRailConfig {
     /** Only a watched leg has anywhere to carry this */
     sealed?: (order: Order) => string | Promise<string>;
     webhookUrl?: string;
-    webhookSecret?: string;
     /**
      * Where your own `lightningVerifyEndpoint` is mounted, and the secret it
      * unseals with. Set both and the gateway is handed your URL rather than the
@@ -396,5 +434,15 @@ declare function lightningRail(config: LightningRailConfig): Rail;
  * refusing everyone.
  */
 declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
+/**
+ * A provable invoice from the first address on the list that will issue one, which
+ * is what a client mints for itself rather than asking a gateway to. Everything the
+ * gateway needs to watch it comes back with everything you need to prove it came
+ * from the address you asked for, so you can hand over the first and keep the second.
+ *
+ * Server side: it resolves hostnames and refuses a private one, which no browser can
+ * do. Throws `NoWalletAvailableError` when no address on the list would serve
+ */
+declare function invoiceFrom(lnAddresses: string[], amountMsat: number): Promise<Resolved>;
 
-export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, ThunderBridge as T, type WalletFailure as W, type TriggerEvent as a, type CreateOptions as b, type CreateQuoteParams as c, type LightningRailConfig as d, type PaymentKind as e, type PaymentStatus as f, type ThunderBridgeOptions as g, type WaitOptions as h, type WalletReason as i, type WatchPaymentParams as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, blindLightningRail as n };
+export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, type Settlement as S, ThunderBridge as T, type WatchPaymentParams as W, type ThunderBridgeOptions as a, type TriggerEvent as b, type WaitOptions as c, type WalletFailure 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 Resolved as n, blindLightningRail as o, invoiceFrom as p, toLnurl as t };

package/dist/{rail-J8QoYbSr.d.ts → rail-Dp8bs6uZ.d.ts}

@@ -23,7 +23,6 @@ interface CreatePaymentParams {
     lnAddresses: string[];
     amountMsat: number;
     webhookUrl?: string;
-    webhookSecret?: string;
 }
 /**
  * `lnAddresses` is the same priority list `createPayment` takes, and quoting it
@@ -78,7 +77,6 @@ interface WatchPaymentParams {
     trigger?: string;
     sealed?: string;
     webhookUrl?: string;
-    webhookSecret?: string;
 }
 /** Why one wallet in the list could not be used */
 type WalletReason = "address-unusable" | "unreachable" | "amount-not-accepted" | "cannot-prove-delivery" | "invoice-refused";
@@ -86,6 +84,17 @@ interface WalletFailure {
     address: string;
     reason: WalletReason;
 }
+/**
+ * What a delivery carries. Everything needed to act on a settlement and to check
+ * it, and nothing else, so a retry is the same size every time
+ */
+interface Settlement {
+    id: string;
+    status: PaymentStatus;
+    paymentHash: string;
+    preimage: string | null;
+    settledAt: number;
+}
 
 interface ThunderBridgeOptions {
     /**
@@ -101,6 +110,13 @@ interface ThunderBridgeOptions {
      * through a ticket
      */
     token?: string;
+    /**
+     * The same long lived server side secret your rail derives its preimages from.
+     * Given here, every call carries a signature the gateway reads as your identity,
+     * so a payment you create is handed back to you and to nobody else. Withheld,
+     * you are anonymous and any holder of an id can read what it names
+     */
+    secret?: string;
 }
 interface WaitOptions {
     /** Give up when this aborts, `AbortSignal.timeout(ms)` covers the usual case */
@@ -159,7 +175,9 @@ declare class ThunderBridge {
     private readonly baseUrl;
     private readonly verify;
     private readonly token;
+    private readonly secret;
     private strangers;
+    private speaks;
     constructor(baseUrl: string, options?: ThunderBridgeOptions);
     /**
      * Whether a token was given, which is what makes an instance yours: a gateway
@@ -262,6 +280,14 @@ declare class ThunderBridge {
      * the watcher needs goes in `sealed`, which the gateway cannot read
      */
     watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
+    /**
+     * What this payment is called, which you can work out before any gateway has
+     * heard of it. Every gateway you hand the same invoice to answers with the same
+     * name, so watching at several of them adds up to one payment rather than
+     * several, and no gateway's key is in the answer. Null when no secret was given,
+     * because then the gateway names the payment and only it can
+     */
+    nameFor(paymentHash: string): Promise<string | null>;
     /**
      * Follow every payment made to one trigger, replayed from the recent ones on
      * connect and then live, reconnecting on its own until the returned function
@@ -272,10 +298,25 @@ declare class ThunderBridge {
     private wsTicket;
     private sending;
     private reading;
+    private speaking;
     private proven;
     private checked;
 }
 
+type Resolved = {
+    address: string;
+    bolt11: string;
+    verifyUrl: string;
+    paymentHash: string;
+    expiresAt: number;
+};
+/**
+ * Bech32-encode a pay endpoint as the `LNURL1` string LUD-01 defines, uppercase
+ * because that is the form it asks a QR to carry. An onion endpoint is http
+ * rather than https, which LUD-17 spells out, so both are taken here
+ */
+declare function toLnurl(endpoint: string): string;
+
 /** What a shop knows about a sale before any rail exists */
 interface Order {
     /** The bank matches it on the statement, and Lightning keys idempotency on it */
@@ -324,7 +365,6 @@ interface BankRailConfig {
     /** Up to ten digits, for accounting systems that still want one */
     variableSymbol?: (order: Order) => string | undefined;
     webhookUrl?: string;
-    webhookSecret?: string;
     /** Register on a gateway you do not own anyway, on the terms `bankTransfer` sets out */
     allowPublicGateway?: boolean;
     /** What `Leg.rail` reads, for a shop running more than one account */
@@ -345,7 +385,6 @@ interface LightningRailConfig {
      */
     idempotencyKey?: (order: Order) => string | undefined;
     webhookUrl?: string;
-    webhookSecret?: string;
     /** What `Leg.rail` reads, for a shop running more than one wallet */
     name?: string;
 }
@@ -361,7 +400,6 @@ interface BlindLightningRailConfig {
     /** Only a watched leg has anywhere to carry this */
     sealed?: (order: Order) => string | Promise<string>;
     webhookUrl?: string;
-    webhookSecret?: string;
     /**
      * Where your own `lightningVerifyEndpoint` is mounted, and the secret it
      * unseals with. Set both and the gateway is handed your URL rather than the
@@ -396,5 +434,15 @@ declare function lightningRail(config: LightningRailConfig): Rail;
  * refusing everyone.
  */
 declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
+/**
+ * A provable invoice from the first address on the list that will issue one, which
+ * is what a client mints for itself rather than asking a gateway to. Everything the
+ * gateway needs to watch it comes back with everything you need to prove it came
+ * from the address you asked for, so you can hand over the first and keep the second.
+ *
+ * Server side: it resolves hostnames and refuses a private one, which no browser can
+ * do. Throws `NoWalletAvailableError` when no address on the list would serve
+ */
+declare function invoiceFrom(lnAddresses: string[], amountMsat: number): Promise<Resolved>;
 
-export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, ThunderBridge as T, type WalletFailure as W, type TriggerEvent as a, type CreateOptions as b, type CreateQuoteParams as c, type LightningRailConfig as d, type PaymentKind as e, type PaymentStatus as f, type ThunderBridgeOptions as g, type WaitOptions as h, type WalletReason as i, type WatchPaymentParams as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, blindLightningRail as n };
+export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, type Settlement as S, ThunderBridge as T, type WatchPaymentParams as W, type ThunderBridgeOptions as a, type TriggerEvent as b, type WaitOptions as c, type WalletFailure 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 Resolved as n, blindLightningRail as o, invoiceFrom as p, toLnurl as t };

package/dist/server.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var server_exports = {};
 __export(server_exports, {
   blindLightningRail: () => blindLightningRail,
+  invoiceFrom: () => invoiceFrom,
   lightningVerifyEndpoint: () => lightningVerifyEndpoint,
   lnurlPayEndpoint: () => lnurlPayEndpoint,
   relayedVerifyUrl: () => relayedVerifyUrl
@@ -926,8 +927,7 @@ function blindLightningRail(config) {
       expiresAt: resolved2.expiresAt,
       trigger: config.trigger,
       sealed: await config.sealed?.(order),
-      webhookUrl: config.webhookUrl,
-      webhookSecret: config.webhookSecret
+      webhookUrl: config.webhookUrl
     });
     return {
       id: watched.id,
@@ -951,6 +951,7 @@ async function invoiceFrom(lnAddresses, amountMsat) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   blindLightningRail,
+  invoiceFrom,
   lightningVerifyEndpoint,
   lnurlPayEndpoint,
   relayedVerifyUrl

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge } from './rail-J8QoYbSr.cjs';
-export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-J8QoYbSr.cjs';
+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';
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge } from './rail-J8QoYbSr.js';
-export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-J8QoYbSr.js';
+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';
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */

package/dist/server.js

@@ -887,8 +887,7 @@ function blindLightningRail(config) {
       expiresAt: resolved2.expiresAt,
       trigger: config.trigger,
       sealed: await config.sealed?.(order),
-      webhookUrl: config.webhookUrl,
-      webhookSecret: config.webhookSecret
+      webhookUrl: config.webhookUrl
     });
     return {
       id: watched.id,
@@ -911,6 +910,7 @@ async function invoiceFrom(lnAddresses, amountMsat) {
 }
 export {
   blindLightningRail,
+  invoiceFrom,
   lightningVerifyEndpoint,
   lnurlPayEndpoint,
   relayedVerifyUrl

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: thunder-bridge, the endpoint your own service serves
-  version: 0.8.1
+  version: 1.1.0
   license:
     name: MIT
     identifier: MIT
@@ -207,6 +207,48 @@ paths:
               schema:
                 $ref: "#/components/schemas/unsettled"
 
+    post:
+      tags: [bank-transfer]
+      operationId: answerVerifyChallenge
+      summary: Agree to be polled, before the gateway will watch anything pointed here
+      description: |
+        The gateway will not poll a URL a caller merely named. It POSTs a nonce here first and
+        watches nothing unless this endpoint hands the same nonce back, which is how a caller
+        shows the endpoint consented to the traffic rather than being volunteered for it. A
+        registration whose verify URL will not answer is refused with `verify-unconsented`.
+
+        Every verify endpoint the SDK builds answers this as its first line, before it parses
+        its own query, so `bankVerifyEndpoint`, `lightningVerifyEndpoint` and anything wrapping
+        `answerVerifyChallengeRequest` already do it.
+
+        There is nothing to sign. Echoing a nonce grants the asker nothing, so this holds no
+        secret and checks none.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                type:
+                  type: string
+                  enum: [verify-challenge]
+                nonce:
+                  type: string
+                  pattern: "^[0-9a-f]{64}$"
+              required: [type, nonce]
+      responses:
+        "200":
+          description: The same nonce, and nothing else.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  nonce:
+                    type: string
+                required: [nonce]
+
 components:
   schemas:
     settlement:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thunder-bridge",
-  "version": "0.8.10",
+  "version": "1.1.0",
   "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",