thunder-bridge 0.8.0

package/dist/index.d.cts

@@ -0,0 +1,435 @@
+/** Where a payment stands, `paid` is the only status that carries a preimage */
+type PaymentStatus = "pending" | "paid" | "expired";
+/** A payment as the gateway reports it, every field is checkable against the recipient */
+interface Payment {
+    id: string;
+    lnAddress: string;
+    amountMsat: number;
+    status: PaymentStatus;
+    paymentHash: string;
+    bolt11: string;
+    preimage: string | null;
+    expiresAt: number;
+    createdAt: number;
+    verifyUrl: string;
+}
+/**
+ * `lnAddresses` is a priority list, the gateway takes the first one that can
+ * issue a provable invoice for `amountMsat` and the rest are the fallback
+ */
+interface CreatePaymentParams {
+    lnAddresses: string[];
+    amountMsat: number;
+    webhookUrl?: string;
+    webhookSecret?: string;
+}
+/**
+ * `lnAddresses` is the same priority list `createPayment` takes, and quoting it
+ * mints nothing and charges the recipient's wallet nothing
+ */
+interface CreateQuoteParams {
+    lnAddresses: string[];
+    amountMsat: number;
+}
+/**
+ * Which address would serve an amount, and what the ones ahead of it refused.
+ * `feeMsat` is always zero, the payer pays the recipient's own invoice and the
+ * gateway is never in the money's path
+ */
+interface Quote {
+    lnAddress: string;
+    amountMsat: number;
+    feeMsat: number;
+    minMsat: number;
+    maxMsat: number;
+    metadata: string;
+    refusals: WalletFailure[];
+}
+/**
+ * What the gateway reports about a payment it is watching, for a trigger stream
+ * or for one you minted yourself. `lnAddress` and `amountMsat` are null when the
+ * gateway was never told them, which is the point of `watchPayment`: what the
+ * watcher needs but the gateway should not know travels in `sealed` instead
+ */
+interface TriggerEvent {
+    id: string;
+    paymentHash: string;
+    verifyUrl: string;
+    status: PaymentStatus;
+    preimage: string | null;
+    expiresAt: number;
+    createdAt: number;
+    sealed: string | null;
+    lnAddress: string | null;
+    amountMsat: number | null;
+}
+/**
+ * An invoice you obtained yourself, handed over to be watched. The gateway is
+ * given no address and no amount, so it cannot refuse one recipient rather than
+ * all of them
+ */
+interface WatchPaymentParams {
+    paymentHash: string;
+    verifyUrl: string;
+    expiresAt: number;
+    trigger?: string;
+    sealed?: string;
+}
+/** 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 {
+    address: string;
+    reason: WalletReason;
+}
+
+interface ThunderBridgeOptions {
+    /**
+     * Prove every payment against the recipient's own server before handing it
+     * back, and refuse a reported settlement whose preimage does not hash to the
+     * payment hash, defaults to true
+     */
+    verify?: boolean;
+    /**
+     * Sent as `Authorization: Bearer`, which a gateway started with
+     * `GATEWAY_TOKEN` requires on every call, the socket handshake included. No
+     * browser WebSocket can carry a header, so setting this also puts every socket
+     * through a ticket
+     */
+    token?: string;
+}
+interface WaitOptions {
+    /** Give up when this aborts, `AbortSignal.timeout(ms)` covers the usual case */
+    signal?: AbortSignal;
+    /**
+     * Mint a short-lived ticket and put that in the socket URL instead of the
+     * payment id. Implied by `token`. The id stays readable inside the ticket,
+     * what changes is that a URL out of a log stops opening anything after a
+     * minute
+     */
+    tickets?: boolean;
+}
+interface CreateOptions {
+    /**
+     * Makes the POST safe to retry. A repeat of a finished request replays its
+     * payment instead of asking a wallet for a second invoice, a repeat that
+     * arrives while the first is still resolving throws
+     * `IdempotencyConflictError`, and the key is held for 24 hours
+     */
+    idempotencyKey?: string;
+    /**
+     * Groups this payment with every other one carrying the same secret, so
+     * `followTrigger` can watch the place rather than the payment. Only its
+     * sha256 reaches the gateway, and the secret itself is what authorises the
+     * stream, so keep it apart from any URL a payer sees
+     */
+    trigger?: string;
+}
+interface FollowOptions {
+    /** Called for the recent settlements replayed on connect, then for each new one */
+    onPayment: (settled: TriggerEvent) => void;
+    /** Called when a connection drops or a frame is refused, the follow keeps going */
+    onError?: (error: unknown) => void;
+    /** Reconnect after a drop, defaults to true */
+    reconnect?: boolean;
+    /**
+     * The first wait after a drop, doubling up to 30 seconds and jittered so a
+     * fleet does not come back in lockstep, defaults to 3000. A connection that
+     * opens puts it back to the first wait
+     */
+    reconnectDelayMs?: number;
+    /**
+     * Mint a short-lived ticket and put that in the socket URL instead of the
+     * secret, one per connection. Keeps the secret out of access logs, at the cost
+     * of a POST before each connect. Implied by `token`. Leave it off for a
+     * microcontroller, where one hardcoded URL and a dumb reconnect loop is the
+     * whole point
+     */
+    tickets?: boolean;
+}
+/** Talks to a Thunder Bridge gateway and trusts it for nothing it can check itself */
+declare class ThunderBridge {
+    private readonly baseUrl;
+    private readonly verify;
+    private readonly token;
+    constructor(baseUrl: string, options?: ThunderBridgeOptions);
+    /**
+     * Ask the gateway for an invoice payable to the first address on your list
+     * that can issue a provable one, throws `NoWalletAvailableError` when none can
+     * and `GatewayCheatError` when what comes back is not what you asked for
+     */
+    createPayment(params: CreatePaymentParams, options?: CreateOptions): Promise<Payment>;
+    /**
+     * Ask which address would serve an amount without minting anything, throws
+     * `NoWalletAvailableError` when none would. A quote is a probe and not a
+     * promise: the address it names can still be refused at create time, because
+     * whether a wallet returns a provable invoice cannot be known without asking
+     * it for one, and asking mints it
+     */
+    createQuote(params: CreateQuoteParams): Promise<Quote>;
+    /** Read a payment back, null when the gateway has never heard of it */
+    getPayment(id: string): Promise<Payment | null>;
+    /**
+     * List what this gateway is watching, newest first. Only a gateway started
+     * with `GATEWAY_TOKEN` serves this, because on a shared one it would hand
+     * every caller everyone else's payments, so a public gateway answers 404.
+     *
+     * `scanned` says how many settled records were looked at to build the page.
+     * Anything older than that window is not in the answer, and the list does not
+     * pretend otherwise
+     */
+    listPayments(limit?: number): Promise<{
+        payments: TriggerEvent[];
+        scanned: number;
+    }>;
+    /**
+     * Follow a payment over WebSocket until it is paid or expired, reconnecting
+     * through a drop. A payment that never answers gives up after a few tries, and
+     * one that has answered is followed until its own expiry, so the wait always
+     * ends by itself
+     */
+    waitForPayment(id: string, options?: WaitOptions): Promise<Payment>;
+    /**
+     * Hand over an invoice you obtained yourself so the gateway watches it without
+     * being told the address or the amount. It can then only refuse everyone
+     * rather than one recipient, which is what makes leaving it cheap. Anything
+     * the watcher needs goes in `sealed`, which the gateway cannot read
+     */
+    watchPayment(params: WatchPaymentParams): Promise<TriggerEvent>;
+    /**
+     * 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
+     * is called. A trigger has no terminal state, so this never resolves
+     */
+    followTrigger(secret: string, options: FollowOptions): () => void;
+    private needsTicket;
+    private wsTicket;
+    private sending;
+    private reading;
+    private proven;
+    private checked;
+}
+
+/**
+ * Encrypt what the watcher needs and the gateway must not have. The gateway
+ * stores the result and hands it back untouched, so anything readable you put
+ * in `sealed` is something you told it, which is what blind mode exists to avoid
+ */
+declare function seal(secret: string, plaintext: string): Promise<string>;
+/**
+ * Read a sealed blob back, null when it was sealed with another secret, edited
+ * on the way, or is not one of ours. A secret too short to be a key throws,
+ * because that is your bug rather than someone else's input
+ */
+declare function unseal(secret: string, sealed: string): Promise<string | null>;
+
+interface TriggerConfig {
+    /** The gateway that quotes the addresses and mints the invoice */
+    gateway: ThunderBridge;
+    /** Priority list, quoted at payRequest and then pinned for the callback */
+    lnAddresses: string[];
+    /**
+     * What this trigger costs right now, called once per payRequest. A plain
+     * function, so a fiat peg or a time of day rule is just code you write
+     */
+    amountMsat: () => number | Promise<number>;
+    /**
+     * Signs the callback URL. Without it anyone could call the callback and make
+     * this endpoint mint invoices on wallets of their choosing
+     */
+    secret: string;
+    /** Groups every payment here so `followTrigger` can watch the place, keep it off the QR */
+    watchSecret?: string;
+    /** Override when a proxy hides the public URL from the request, no trailing slash */
+    baseUrl?: string;
+    /**
+     * Resolve the address here and hand the gateway only a hash and a URL to poll,
+     * instead of asking it to mint. It then cannot tell who is being paid beyond
+     * the domain in the verify URL, nor how much at all, so the only refusal left
+     * to it is refusing everyone. Costs one more round trip and gives up the
+     * gateway's CORS proxying, which a server does not need anyway
+     */
+    blind?: boolean;
+    /**
+     * What the watcher needs and the gateway must not have. `data` returns it and
+     * `secret` encrypts it, so there is no way to hand the gateway something it
+     * can read. Needs 32 characters of randomness, not a passphrase, and every
+     * watcher of this trigger holds the same one
+     */
+    sealed?: {
+        secret: string;
+        data: (minted: Minted) => unknown;
+    };
+}
+interface Minted {
+    lnAddress: string;
+    amountMsat: number;
+    bolt11: string;
+    paymentHash: string;
+    verifyUrl: string;
+    expiresAt: 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.
+ *
+ * It answers both halves of the flow on one path. A bare request is the
+ * payRequest and quotes the list, and a signed one is the callback and mints.
+ * The winner is chosen at payRequest and pinned into the callback URL because
+ * LUD-06 binds the invoice to the metadata already served: if the callback
+ * picked a different address the payer's wallet would refuse the invoice.
+ *
+ * Nothing is stored between the two, so this holds no state of its own.
+ */
+declare function lnurlPayEndpoint(config: TriggerConfig): (request: Request) => Promise<Response>;
+
+/**
+ * Prove the invoice really is the one the recipient issued for what you asked,
+ * before the payer ever sees it, both fetches go straight to the recipient's own
+ * server and none of them goes back to the gateway
+ *
+ * Throws `GatewayCheatError` when a check fails and `UnverifiedRecipientError`
+ * when the recipient could not be reached to run one
+ */
+declare function proveOrigin(payment: Payment, request: CreatePaymentParams): Promise<void>;
+/**
+ * Prove the money arrived by asking the recipient's own server, not the gateway,
+ * returns the preimage when the recipient says it settled and null when it says
+ * it has not, and runs the full origin proof first because a verify url the
+ * gateway made up would otherwise answer for itself
+ */
+declare function proveSettlement(payment: Payment, request: CreatePaymentParams): Promise<string | null>;
+/**
+ * True when the gateway's own report of a settlement is at least self-consistent,
+ * the preimage hashes to the payment hash the invoice itself carries, this is a
+ * sanity check and not a proof, only `proveSettlement` asks the recipient
+ */
+declare function isProvablyPaid(payment: Payment): boolean;
+
+/** What a BOLT11 invoice says about itself, every field null when it does not carry one */
+interface Invoice {
+    paymentHash: string | null;
+    descriptionHash: string | null;
+    amountMsat: number | null;
+    expiresAt: number | null;
+}
+/**
+ * Read a BOLT11 invoice without trusting anyone for its contents, an
+ * undecodable string or a BOLT12 offer yields an invoice with every field null
+ */
+declare function decodeInvoice(bolt11: string): Invoice;
+/** True when `preimage` is the secret behind `paymentHash` */
+declare function preimageMatchesHash(preimage: string, paymentHash: string): boolean;
+
+interface QrOptions {
+    /** SVG width and height in pixels, defaults to 256 */
+    size?: number;
+    /** Dark module color, defaults to `#000` */
+    color?: string;
+}
+/** Render a BOLT11 invoice or a lightning address as an SVG QR code */
+declare function invoiceToSvg(destination: string, options?: QrOptions): string;
+/** SVG data URL for an `<img>` `src` */
+declare function invoiceToDataUrl(destination: string, options?: QrOptions): string;
+/**
+ * Render your own LNURL-pay endpoint, the URL `lnurlPayEndpoint` is mounted on,
+ * as the QR a payer scans. Nothing is minted and nothing expires, so this is the
+ * code a tip jar prints once and an overlay shows all stream
+ */
+declare function lnurlToSvg(endpoint: string, options?: QrOptions): string;
+/** SVG data URL of the endpoint's QR, for an `<img>` `src` */
+declare function lnurlToDataUrl(endpoint: string, options?: QrOptions): string;
+
+/**
+ * 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;
+
+/** How far the gateway's clock may drift from yours before a webhook is refused */
+type WebhookOptions = {
+    toleranceSecs?: number;
+};
+/** Verify the `X-Signature` header against the raw body and the `X-Timestamp` that came with it */
+declare function verifyWebhookSignature(body: string | Uint8Array, signature: string, secret: string, timestamp: string, options?: WebhookOptions): Promise<boolean>;
+/** Verify and parse in one step, returns null on a bad signature or a body that is not a payment */
+declare function parseWebhook(body: string | Uint8Array, signature: string, secret: string, timestamp: string, options?: WebhookOptions): Promise<Payment | null>;
+/**
+ * Verify and parse from a Fetch API `Request` as used by Hono, Next, SvelteKit,
+ * Cloudflare Workers and Deno, WebCrypto only so it runs anywhere fetch does
+ */
+declare function parseWebhookRequest(request: Request, secret: string, options?: WebhookOptions): Promise<Payment | null>;
+
+/**
+ * The way a gateway was caught out, every code is a check that held against the
+ * recipient's own server and failed against what the gateway returned
+ */
+type GatewayCheatCode = "address_not_requested" | "hash_mismatch" | "amount_mismatch" | "description_hash_mismatch" | "verify_url_foreign" | "invoice_not_issued" | "preimage_mismatch";
+/**
+ * Thrown when the gateway demonstrably misbehaved, the invoice it returned is
+ * not the one the address you asked for issued, or a settlement it reported
+ * carries a preimage that does not hash to the payment hash
+ */
+declare class GatewayCheatError extends Error {
+    readonly code: GatewayCheatCode;
+    readonly paymentId: string;
+    constructor(code: GatewayCheatCode, paymentId: string);
+}
+/**
+ * Thrown when the recipient's own server could not be reached to check the
+ * invoice against, a CORS-blocked browser or a provider that is down, this is
+ * not proof the gateway cheated and it is not proof it did not
+ */
+declare class UnverifiedRecipientError extends Error {
+    readonly lnAddress: string;
+    readonly paymentId: string;
+    constructor(lnAddress: string, paymentId: string, cause: unknown);
+}
+/** An RFC 9457 problem document the gateway answered with */
+declare class ProblemError extends Error {
+    readonly type: string;
+    readonly title: string;
+    readonly status: number;
+    readonly detail: string | null;
+    constructor(problem: {
+        type?: string;
+        title?: string;
+        status?: number;
+        detail?: string;
+    });
+}
+declare const NO_WALLET_AVAILABLE = "urn:problem-type:thunder-bridge-direct:no-wallet-available";
+declare const REQUEST_IN_FLIGHT = "urn:problem-type:thunder-bridge-direct:request-in-flight";
+declare const IDEMPOTENCY_KEY_REUSED = "urn:problem-type:thunder-bridge-direct:idempotency-key-reused";
+declare const PAYMENT_ALREADY_WATCHED = "urn:problem-type:thunder-bridge-direct:payment-already-watched";
+/**
+ * Why an `Idempotency-Key` was refused, `request-in-flight` is the benign one and
+ * `key-reused` means the same key was sent for a different request
+ */
+type IdempotencyConflict = "request-in-flight" | "key-reused";
+/**
+ * Thrown when an `Idempotency-Key` is held by another request. On
+ * `request-in-flight` the first attempt is still resolving, so wait and read the
+ * payment back rather than retrying. `key-reused` is a bug in the caller: the key
+ * is bound to the addresses, amount and webhook that claimed it
+ */
+declare class IdempotencyConflictError extends ProblemError {
+    readonly conflict: IdempotencyConflict;
+    constructor(problem: {
+        type?: string;
+        title?: string;
+        status?: number;
+        detail?: string;
+    }, conflict: IdempotencyConflict);
+}
+/** Thrown when no wallet on your list could issue a provable invoice, `wallets` says why each refused */
+declare class NoWalletAvailableError extends ProblemError {
+    readonly wallets: WalletFailure[];
+    constructor(problem: {
+        title?: string;
+        status?: number;
+        detail?: string;
+    }, wallets: WalletFailure[]);
+}
+
+export { type CreateOptions, type CreatePaymentParams, type CreateQuoteParams, type FollowOptions, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type Minted, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, type Payment, type PaymentStatus, ProblemError, type QrOptions, type Quote, REQUEST_IN_FLIGHT, ThunderBridge, type ThunderBridgeOptions, type TriggerConfig, type TriggerEvent, UnverifiedRecipientError, type WaitOptions, type WalletFailure, type WalletReason, type WatchPaymentParams, type WebhookOptions, decodeInvoice, invoiceToDataUrl, invoiceToSvg, isProvablyPaid, lnurlPayEndpoint, lnurlToDataUrl, lnurlToSvg, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, seal, toLnurl, unseal, verifyWebhookSignature };