thunder-bridge 2.1.1 → 2.2.0

package/dist/{bank-CEIuNhV_.d.cts → bank-Bg6RjuO-.d.cts}

@@ -15,6 +15,120 @@ type Verified = {
 /** Carries one request to an address ask() already verified, so nothing resolves the name again */
 type Send = (url: string, sent: Sent, signal: AbortSignal, at: readonly Verified[]) => Promise<Response>;
 
+/** A wallet reachable over NIP-47, as its `nostr+walletconnect://` URI describes it */
+interface NwcConnection {
+    /** The wallet service's public key, which is what its answers have to be signed by */
+    walletPubkey: string;
+    /** Where to reach it, tried in order until one answers */
+    relays: string[];
+    /** Our own private key on this connection, and the only thing that authorises it */
+    secret: string;
+}
+/** A minted invoice and everything needed to watch it */
+interface NwcInvoice {
+    bolt11: string;
+    paymentHash: string;
+    expiresAt: number;
+}
+/** The endpoint the gateway polls for an NWC payment, answering off your own wallet */
+interface NwcVerifyConfig {
+    /** The wallet this endpoint speaks for. It never leaves this process */
+    connection: NwcConnection;
+    /** The secret the payment hash was sealed with, and nothing else uses it */
+    secret: string;
+    /** How often the gateway should ask, in seconds, sent as `Cache-Control: max-age`, `5` by default */
+    pollEverySecs?: number;
+    /** How long one `lookup_invoice` may take before the wallet counts as unreachable, `10_000` by default */
+    askTimeoutMs?: number;
+}
+/**
+ * Read a `nostr+walletconnect://` URI. Refuses a relay that is not `wss`, for the
+ * reason the gateway refuses a verify URL that is not https
+ */
+declare function nwcConnection(uri: string): NwcConnection;
+/** Mint an invoice on the connected wallet, decoded so the caller need not trust its word */
+declare function nwcInvoice(connection: NwcConnection, amountMsat: number, description: string, timeoutMs?: number): Promise<NwcInvoice>;
+/**
+ * Mint a hold invoice on a hash the wallet does not hold the preimage for, which
+ * is what lets an operator be paid only by paying somebody else first. The hash
+ * has to come from the recipient's own invoice, and the invoice that comes back
+ * is decoded rather than believed
+ */
+declare function nwcHoldInvoice(connection: NwcConnection, held: {
+    paymentHash: string;
+    amountMsat: number;
+    description: string;
+    expirySecs: number;
+    minCltvExpiryDelta?: number;
+}, timeoutMs?: number): Promise<NwcInvoice>;
+/**
+ * The preimage the wallet released for this hash, null while it has released
+ * none. A preimage that does not hash to what was asked for is a lie rather than
+ * an answer, so it throws instead of being passed on
+ */
+declare function nwcSettlement(connection: NwcConnection, paymentHash: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * Pay an invoice and keep the preimage the network handed back. Whoever pays
+ * learns it, which is what makes delivery provable to a recipient publishing no
+ * LUD-21 of their own. A preimage that does not hash to the invoice's own hash is
+ * a lie rather than a receipt, so it throws instead of being passed on
+ */
+declare function nwcPay(connection: NwcConnection, bolt11: string, timeoutMs?: number): Promise<string>;
+/**
+ * A verify endpoint of your own that asks your wallet over NIP-47, so the gateway
+ * polls you and never learns the connection, the relay, or which wallet it is.
+ *
+ * `nwcVerifyUrl` seals the payment hash into the query with your secret, which is
+ * what stops a stranger driving your wallet through this handler. It answers the
+ * LUD-21 shape the gateway already speaks, so nothing on that side changes.
+ *
+ * A wallet it cannot reach answers `502` rather than "not settled", because those
+ * are different claims and only one of them is true.
+ */
+declare function nwcVerifyEndpoint(config: NwcVerifyConfig): (request: Request) => Promise<Response>;
+/**
+ * The URL to hand the gateway, with the payment hash sealed inside it. Point it at
+ * wherever `nwcVerifyEndpoint` is mounted
+ */
+declare function nwcVerifyUrl(endpoint: string, paymentHash: string, secret: string): Promise<string>;
+/**
+ * One NIP-47 call, for a method this SDK does not wrap. The wallet's own info
+ * event lists what it will answer, and anything it refuses comes back as a
+ * `WalletRefused` whose `reason` says which kind of refusal it was
+ */
+declare function askWallet(connection: NwcConnection, method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
+/** A Lightning rail minting on a wallet of your own over NIP-47, bound once per shop */
+interface NwcRailConfig extends RailConfig {
+    /** The wallet that mints, which never leaves this process */
+    connection: NwcConnection;
+    /**
+     * What to charge for one order, the order's own price converted at `rate` by
+     * default. Give it a function and the price is whatever you say
+     */
+    amount?: (order: Order) => Amount;
+    /** Where the default conversion gets its rate, the median of four venues by default */
+    rate?: Ticker;
+    /** Where `nwcVerifyEndpoint` is mounted, and the secret the hash is sealed with */
+    verifyThrough: {
+        endpoint: string;
+        secret: string;
+    };
+    /** What the payer's wallet shows, the order's reference by default */
+    description?: (order: Order) => string;
+    /** Sealed before the gateway sees it, the way the blind Lightning rail does */
+    sealed?: {
+        secret: string;
+        data: (order: Order) => unknown;
+    };
+}
+/**
+ * Sell for Lightning against a wallet of your own over NIP-47, for a wallet that
+ * has no LUD-21 address to be watched at. Your node mints the invoice and releases
+ * the preimage, so the proof comes from one hop nearer than any hosted address can
+ * manage, and the gateway sees a hash and a URL of yours
+ */
+declare function nwcRail(gateway: ThunderBridge, config: NwcRailConfig): Rail;
+
 /** 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 */
@@ -139,6 +253,13 @@ declare class Rails {
     blindLightning(config: BlindLightningRailConfig): Rail;
     /** A bank transfer, proved the way a Lightning payment is */
     bank(config: BankRailConfig): Rail;
+    /**
+     * Lightning against a wallet of your own over NIP-47, for a wallet that has no
+     * LUD-21 address to be watched at. Your node mints the invoice and releases the
+     * preimage, so the proof comes from one hop nearer than any hosted address can
+     * manage, and the gateway sees a hash and a URL of yours
+     */
+    nwc(config: NwcRailConfig): Rail;
     /**
      * One bank transfer without building a rail first, for a shop that asks for
      * them one at a time rather than beside another payment method
@@ -358,26 +479,39 @@ interface Provable {
     bolt11?: string | null;
 }
 /**
- * A report `carriesProof` has already accepted, so the preimage is there and the
- * status is settled. Nothing downstream of the check needs a null guard
+ * A report `agreesWithItself` has already accepted, so the preimage is there and
+ * the status is settled. Nothing downstream of the check needs a null guard
  */
-type Proven<T extends Provable> = T & {
+type SelfConsistent<T extends Provable> = T & {
     status: "paid";
     preimage: string;
 };
 /**
- * Whether a report proves what it claims: it says paid, and it carries a preimage
+ * What `SelfConsistent` was called before 2.2.0
+ *
+ * @deprecated Use `SelfConsistent`, which says the report was checked against itself and nothing else
+ */
+type Proven<T extends Provable> = SelfConsistent<T>;
+/**
+ * Whether a report agrees with itself: it says paid, and it carries a preimage
  * that hashes to the payment hash it itself names. Where an invoice comes with it,
  * the invoice's own hash has to agree too.
  *
  * A payment, a settlement delivered to a webhook and a frame off a trigger all
- * answer this, because all three carry those fields and no other question about
- * one matters.
+ * answer this, because all three carry those fields.
+ *
+ * It asks nobody anything and holds the report against nothing you hold, so a
+ * gateway that invents a preimage and names its hash passes it. Checking against
+ * the hash you hold is what `payment` and `settled` do, and only
+ * `proveSettlement` asks the recipient
+ */
+declare function agreesWithItself<T extends Provable>(report: T): report is SelfConsistent<T>;
+/**
+ * What `agreesWithItself` was called before 2.2.0
  *
- * It asks nobody anything, so it costs no round trip and is not a proof of
- * arrival. Only `proveSettlement` asks the recipient
+ * @deprecated Use `agreesWithItself`, because it proves nothing beyond the report itself
  */
-declare function carriesProof<T extends Provable>(report: T): report is Proven<T>;
+declare const carriesProof: typeof agreesWithItself;
 /**
  * The most an operator may add over the recipient's own amount, in millisatoshi.
  * The proportion is what routing and the liquidity behind it costs, and the base
@@ -402,9 +536,15 @@ declare function wrapFeeCeiling(amountMsat: number, allowance?: WrapAllowance):
  */
 declare function proveWrapped(wrapped: string, recipient: string, allowance?: WrapAllowance): void;
 
-/** How far the gateway's clock may drift from yours before a webhook is refused */
+/**
+ * How far the gateway's clock may drift from yours before a webhook is refused,
+ * and the URL you registered when a proxy in front of you hands requests on under
+ * another one. A delivery is signed for the URL it was sent to, so one made for
+ * somebody else's endpoint is refused here
+ */
 type WebhookOptions = {
     toleranceSecs?: number;
+    url?: string;
 };
 /**
  * What checks a delivery: the hex the gateway publishes at `/webhook-key`. There
@@ -434,7 +574,7 @@ interface WebhookHandlers {
      * A settlement that proves itself: it says paid and its preimage hashes to the
      * payment hash it names. This is the only callback a shop needs
      */
-    onSettled?: (settlement: Proven<Settlement>) => void | Promise<void>;
+    onSettled?: (settlement: SelfConsistent<Settlement>) => void | Promise<void>;
     /**
      * A delivery that carries no proof, so an expiry. Left unset, the handler
      * answers `202` and does nothing, because acting on an unproven claim is the
@@ -450,14 +590,21 @@ interface WebhookHandlers {
     credential?: WebhookCredential;
     /** How far the gateway's clock may drift from yours, five minutes by default */
     toleranceSecs?: number;
+    /**
+     * The URL you registered, when a proxy in front of you hands the request on
+     * under another host or scheme. Left unset, the request's own URL is what the
+     * delivery has to have been signed for
+     */
+    url?: string;
 }
 /**
  * Everything one gateway lets you mount, in one place so a caller never has to
  * know which handler needs the gateway and which does not. Most of these took it
  * as a config field before, and reaching them through the gateway deleted it.
  *
- * `verify` and `bankVerify` need nothing from the gateway and are here anyway,
- * because a reader looking for a handler should find every handler in one list
+ * `lightningVerify`, `bankVerify` and `nwcVerify` need nothing from the gateway and
+ * are here anyway, because a reader looking for a handler should find every handler
+ * in one list
  */
 declare class Serve {
     private readonly gateway;
@@ -478,13 +625,24 @@ declare class Serve {
      * A verify endpoint of your own that asks the recipient's wallet for you, so
      * the gateway polls you and never the wallet
      */
+    lightningVerify(config: LightningVerifyConfig): Handler;
+    /**
+     * What `lightningVerify` was called before 2.2.0
+     *
+     * @deprecated Use `lightningVerify`, beside `bankVerify` and `nwcVerify`
+     */
     verify(config: LightningVerifyConfig): Handler;
     /** The verify endpoint a bank rail is polled at, answering off your own statement */
     bankVerify(config: BankVerifyConfig): Handler;
+    /**
+     * The verify endpoint an NWC rail is polled at, asking your own wallet over
+     * NIP-47, so the gateway never learns the connection, the relay or the wallet
+     */
+    nwcVerify(config: NwcVerifyConfig): Handler;
     /**
      * The whole webhook route: it answers the gateway's challenge, checks the
      * signature against the key the gateway publishes, refuses a settlement that
-     * proves nothing, and calls you for the one that does.
+     * proves nothing, and calls you once for the one that does.
      *
      * `export const POST = gateway.serve.webhook({ onSettled: fulfil })` is the
      * entire integration
@@ -706,6 +864,10 @@ declare class ThunderBridge {
      * the recipient's own wallet minted it, so a payer who pays the loser afterwards
      * really does pay twice and that shows up on `follow` as a second settlement to
      * refund.
+     *
+     * A leg the gateway is caught lying about before any leg is paid ends the wait
+     * with its `GatewayCheatError`, even when another leg is paid after it, so a
+     * detected cheat is never traded for a later win.
      */
     firstSettled(held: Held[], options?: WaitOptions): Promise<Payment | null>;
     /**
@@ -893,4 +1055,4 @@ interface BankAgentConfig {
  */
 declare function bankAgent(config: BankAgentConfig): () => void;
 
-export { type AttendOptions as A, type BankAgentConfig as B, type Credit as C, type WebhookOptions as D, type WrapAllowance as E, type FollowOptions as F, answerVerifyChallenge as G, type Handler as H, carriesProof as I, invoiceFrom as J, proveOrigin as K, type Leg as L, type Minted as M, proveSettlement as N, type Order as O, type PaymentRequest as P, proveWrapped as Q, type RailConfig as R, type Statement as S, ThunderBridge as T, relayedVerifyUrl as U, wrapFeeCeiling as V, type WaitOptions as W, type BankOrder as a, type BankTransfer as b, type BankTransferParams as c, type BankVerifyConfig as d, bankAgent as e, type Rail as f, type ThunderBridgeOptions as g, type BankRailConfig as h, type BlindLightningRailConfig as i, type CreateOptions as j, type LightningRailConfig as k, type LightningVerifyConfig as l, type PaymentRequestInit as m, type PaymentRequestOptions as n, type Provable as o, type Proven as p, Rails as q, type Range as r, type Relayed as s, type Send as t, Serve as u, type TicketOptions as v, type TriggerConfig as w, type WatchTicketConfig as x, type WebhookCredential as y, type WebhookHandlers as z };
+export { type WebhookOptions as $, type AttendOptions as A, type BankAgentConfig as B, type Credit as C, type Proven as D, type RailConfig as E, type FollowOptions as F, Rails as G, type Handler as H, type Range as I, type Relayed as J, type SelfConsistent as K, type Leg as L, type Minted as M, type NwcConnection as N, type Order as O, type PaymentRequest as P, type Send as Q, type Rail as R, type Statement as S, ThunderBridge as T, Serve as U, type TicketOptions as V, type WaitOptions as W, type TriggerConfig as X, type WatchTicketConfig as Y, type WebhookCredential as Z, type WebhookHandlers as _, type BankOrder as a, type WrapAllowance as a0, agreesWithItself as a1, answerVerifyChallenge as a2, carriesProof as a3, invoiceFrom as a4, proveOrigin as a5, proveSettlement as a6, proveWrapped as a7, relayedVerifyUrl as a8, wrapFeeCeiling as a9, type BankTransfer as b, type BankTransferParams as c, type BankVerifyConfig as d, bankAgent as e, nwcVerifyEndpoint as f, type NwcInvoice as g, type NwcRailConfig as h, type NwcVerifyConfig as i, askWallet as j, nwcConnection as k, nwcHoldInvoice as l, nwcInvoice as m, nwcRail as n, nwcPay as o, nwcSettlement as p, nwcVerifyUrl as q, type ThunderBridgeOptions as r, type BankRailConfig as s, type BlindLightningRailConfig as t, type CreateOptions as u, type LightningRailConfig as v, type LightningVerifyConfig as w, type PaymentRequestInit as x, type PaymentRequestOptions as y, type Provable as z };

package/dist/bank.cjs

@@ -150,7 +150,6 @@ var INITIAL_STATE = new Uint32Array([
 
 // ../core/sealed.ts
 var MIN_SECRET_CHARS = 32;
-var INFO = new TextEncoder().encode("thunder-bridge/sealed");
 function refuseAWeakSecret(secret) {
   if (secret.length < MIN_SECRET_CHARS) {
     throw new Error(`the sealing secret needs ${MIN_SECRET_CHARS} characters of randomness`);

package/dist/bank.d.cts

@@ -1,5 +1,5 @@
-import { S as Statement } from './bank-CEIuNhV_.cjs';
-export { B as BankAgentConfig, a as BankOrder, b as BankTransfer, c as BankTransferParams, d as BankVerifyConfig, C as Credit, e as bankAgent } from './bank-CEIuNhV_.cjs';
+import { S as Statement } from './bank-Bg6RjuO-.cjs';
+export { B as BankAgentConfig, a as BankOrder, b as BankTransfer, c as BankTransferParams, d as BankVerifyConfig, C as Credit, e as bankAgent } from './bank-Bg6RjuO-.cjs';
 import './qr-CF-YeXU1.cjs';
 import './types-DYZ9EkmJ.cjs';
 

package/dist/bank.d.ts

@@ -1,5 +1,5 @@
-import { S as Statement } from './bank-M8flcMks.js';
-export { B as BankAgentConfig, a as BankOrder, b as BankTransfer, c as BankTransferParams, d as BankVerifyConfig, C as Credit, e as bankAgent } from './bank-M8flcMks.js';
+import { S as Statement } from './bank-B5MxT_6u.js';
+export { B as BankAgentConfig, a as BankOrder, b as BankTransfer, c as BankTransferParams, d as BankVerifyConfig, C as Credit, e as bankAgent } from './bank-B5MxT_6u.js';
 import './qr-CF-YeXU1.js';
 import './types-DYZ9EkmJ.js';
 

package/dist/bank.js

@@ -123,7 +123,6 @@ var INITIAL_STATE = new Uint32Array([
 
 // ../core/sealed.ts
 var MIN_SECRET_CHARS = 32;
-var INFO = new TextEncoder().encode("thunder-bridge/sealed");
 function refuseAWeakSecret(secret) {
   if (secret.length < MIN_SECRET_CHARS) {
     throw new Error(`the sealing secret needs ${MIN_SECRET_CHARS} characters of randomness`);

package/dist/{errors-DriqW-lp.d.cts → errors-DJmsalYZ.d.cts}

@@ -123,4 +123,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { AmountError as A, type GatewayCheatCode as G, type IdempotencyConflict as I, NoWalletAvailableError as N, ProblemError as P, UnverifiedRecipientError as U, type WrapRefusalCode as W, type AmountFault as a, GatewayCheatError as b, IdempotencyConflictError as c, WrapRefusedError as d };
+export { AmountError as A, GatewayCheatError as G, type IdempotencyConflict as I, NoWalletAvailableError as N, ProblemError as P, UnverifiedRecipientError as U, type WrapRefusalCode as W, type AmountFault as a, type GatewayCheatCode as b, IdempotencyConflictError as c, WrapRefusedError as d };

package/dist/{errors-ZEUT-MhO.d.ts → errors-VX0R18oE.d.ts}

@@ -123,4 +123,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { AmountError as A, type GatewayCheatCode as G, type IdempotencyConflict as I, NoWalletAvailableError as N, ProblemError as P, UnverifiedRecipientError as U, type WrapRefusalCode as W, type AmountFault as a, GatewayCheatError as b, IdempotencyConflictError as c, WrapRefusedError as d };
+export { AmountError as A, GatewayCheatError as G, type IdempotencyConflict as I, NoWalletAvailableError as N, ProblemError as P, UnverifiedRecipientError as U, type WrapRefusalCode as W, type AmountFault as a, type GatewayCheatCode as b, IdempotencyConflictError as c, WrapRefusedError as d };