thunder-bridge 1.5.0 → 2.1.1

package/dist/qr.js

@@ -77,6 +77,8 @@ var INITIAL_STATE = new Uint32Array([
 ]);
 
 // ../core/bolt11.ts
+var BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
+var BECH32_GENERATOR = [996825010, 642813549, 513874426, 1027748829, 705979059];
 var MSAT_PER_BTC = 1e11;
 var HRP_MULTIPLIER_MSAT = {
   m: MSAT_PER_BTC / 1e3,
@@ -84,10 +86,25 @@ var HRP_MULTIPLIER_MSAT = {
   n: MSAT_PER_BTC / 1e9,
   p: MSAT_PER_BTC / 1e12
 };
+function expandedHrp(hrp) {
+  const codes = [...hrp].map((char) => char.charCodeAt(0));
+  return [...codes.map((code) => code >> 5), 0, ...codes.map((code) => code & 31)];
+}
+function bech32Polymod(values) {
+  let checksum = 1;
+  for (const value of values) {
+    const top = checksum >> 25;
+    checksum = (checksum & 33554431) << 5 ^ value;
+    for (let bit = 0; bit < 5; bit++) {
+      if (top >> bit & 1) {
+        checksum ^= BECH32_GENERATOR[bit];
+      }
+    }
+  }
+  return checksum;
+}
 
 // ../core/lnurl.ts
-var BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
-var BECH32_GENERATOR = [996825010, 642813549, 513874426, 1027748829, 705979059];
 var CHECKSUM_SLOTS = [0, 1, 2, 3, 4, 5];
 var LNURL_HRP = "lnurl";
 function toLnurl(endpoint) {
@@ -124,30 +141,10 @@ function toWords(bytes) {
   return words;
 }
 function checksumWords(hrp, words) {
-  const expanded = [...hrp].map((char) => char.charCodeAt(0));
-  const values = [
-    ...expanded.map((code) => code >> 5),
-    0,
-    ...expanded.map((code) => code & 31),
-    ...words,
-    ...CHECKSUM_SLOTS.map(() => 0)
-  ];
+  const values = [...expandedHrp(hrp), ...words, ...CHECKSUM_SLOTS.map(() => 0)];
   const polymod = bech32Polymod(values) ^ 1;
   return CHECKSUM_SLOTS.map((slot) => polymod >> 5 * (5 - slot) & 31);
 }
-function bech32Polymod(values) {
-  let checksum = 1;
-  for (const value of values) {
-    const top = checksum >> 25;
-    checksum = (checksum & 33554431) << 5 ^ value;
-    for (let bit = 0; bit < 5; bit++) {
-      if (top >> bit & 1) {
-        checksum ^= BECH32_GENERATOR[bit];
-      }
-    }
-  }
-  return checksum;
-}
 
 // src/qr.ts
 import { encode } from "uqr";

package/dist/{types-BNPmVnA7.d.cts → types-DYZ9EkmJ.d.cts}

@@ -166,6 +166,15 @@ interface WatchedPayment extends Reported {
  * needs an assertion to read
  */
 type Payment = MintedPayment | WatchedPayment;
+/**
+ * A payment as the caller already knows it: what the gateway calls it and the
+ * hash it settles against. Every `Payment` is one, and a caller reading back
+ * after a restart builds one from the two fields it stored
+ */
+interface Held {
+    id: string;
+    paymentHash: string;
+}
 /**
  * Who is paid and how much. `to` is a priority list when it is an array: the
  * gateway takes the first address that can issue a provable invoice for the
@@ -203,7 +212,7 @@ interface Handover {
      * Needs `trigger`, defaults to none
      */
     replay?: number;
-    /** Sealed with `seal`, so the gateway stores what it cannot read */
+    /** Sealed with `seal` for this payment hash, so the gateway stores what it cannot read or move */
     sealed?: string;
     webhookUrl?: string;
 }
@@ -249,4 +258,4 @@ interface Settlement {
     settledAt: number;
 }
 
-export { type Amount as A, type Charge as C, type FiatOptions as F, type Handover as H, type MedianOptions as M, type Payment as P, type Quote as Q, type Settlement as S, type Ticker as T, type WalletFailure as W, coinmate as a, bitstamp as b, coinbase as c, msatFor as d, type MintedPayment as e, type Msat as f, type PaymentStatus as g, type Priced as h, type SocketTicket as i, type WalletReason as j, kraken as k, type WatchedPayment as l, medianOf as m, fiat as n, msat as o, sats as s };
+export { type Amount as A, type Charge as C, type FiatOptions as F, type Handover as H, type MedianOptions as M, type Payment as P, type Quote as Q, type Settlement as S, type Ticker as T, type WalletFailure as W, coinmate as a, bitstamp as b, coinbase as c, msatFor as d, type Held as e, type MintedPayment as f, type Msat as g, type PaymentStatus as h, type Priced as i, type SocketTicket as j, kraken as k, type WalletReason as l, medianOf as m, type WatchedPayment as n, fiat as o, msat as p, sats as s };

package/dist/{types-BNPmVnA7.d.ts → types-DYZ9EkmJ.d.ts}

@@ -166,6 +166,15 @@ interface WatchedPayment extends Reported {
  * needs an assertion to read
  */
 type Payment = MintedPayment | WatchedPayment;
+/**
+ * A payment as the caller already knows it: what the gateway calls it and the
+ * hash it settles against. Every `Payment` is one, and a caller reading back
+ * after a restart builds one from the two fields it stored
+ */
+interface Held {
+    id: string;
+    paymentHash: string;
+}
 /**
  * Who is paid and how much. `to` is a priority list when it is an array: the
  * gateway takes the first address that can issue a provable invoice for the
@@ -203,7 +212,7 @@ interface Handover {
      * Needs `trigger`, defaults to none
      */
     replay?: number;
-    /** Sealed with `seal`, so the gateway stores what it cannot read */
+    /** Sealed with `seal` for this payment hash, so the gateway stores what it cannot read or move */
     sealed?: string;
     webhookUrl?: string;
 }
@@ -249,4 +258,4 @@ interface Settlement {
     settledAt: number;
 }
 
-export { type Amount as A, type Charge as C, type FiatOptions as F, type Handover as H, type MedianOptions as M, type Payment as P, type Quote as Q, type Settlement as S, type Ticker as T, type WalletFailure as W, coinmate as a, bitstamp as b, coinbase as c, msatFor as d, type MintedPayment as e, type Msat as f, type PaymentStatus as g, type Priced as h, type SocketTicket as i, type WalletReason as j, kraken as k, type WatchedPayment as l, medianOf as m, fiat as n, msat as o, sats as s };
+export { type Amount as A, type Charge as C, type FiatOptions as F, type Handover as H, type MedianOptions as M, type Payment as P, type Quote as Q, type Settlement as S, type Ticker as T, type WalletFailure as W, coinmate as a, bitstamp as b, coinbase as c, msatFor as d, type Held as e, type MintedPayment as f, type Msat as g, type PaymentStatus as h, type Priced as i, type SocketTicket as j, kraken as k, type WalletReason as l, medianOf as m, type WatchedPayment as n, fiat as o, msat as p, sats as s };

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: thunder-bridge, the endpoint your own service serves
-  version: 1.5.0
+  version: 2.1.1
   license:
     name: MIT
     identifier: MIT
@@ -71,14 +71,17 @@ paths:
       summary: Quote the price, or mint the invoice for a quote already given
       description: |
         Without `to` this answers the payRequest. It calls your `amountMsat()` once, quotes
-        your address list through the gateway, and returns the first address that answers and
-        accepts the amount, along with that wallet's own LUD-06 metadata string byte for byte.
+        your address list, through the gateway or by itself when the trigger is blind, and
+        returns the first address that answers and accepts the amount, along with that
+        wallet's own LUD-06 metadata string byte for byte. A quote naming an address you did
+        not list is refused, so a gateway cannot put its own address in front of your payers.
         `minSendable` and `maxSendable` are both the price, so the payer's wallet offers no
         amount field and the payment is exactly what you asked for.
 
         With `to` this is the callback. The signature is checked first, and a request that was
         not signed by this service is refused before anything is minted, which is what stops a
-        stranger making your endpoint mint invoices on wallets of their choosing. The invoice
+        stranger making your endpoint mint invoices on wallets of their choosing. An address
+        you have since taken off the list is refused too, signed or not. The invoice
         then comes from the recipient's own wallet, never from this service and never from the
         gateway, and `verify` on the answer points at that recipient's LUD-21 endpoint.
 
@@ -200,48 +203,35 @@ paths:
       operationId: verifyBankTransfer
       summary: Say whether the transfer landed, and release the preimage when it did
       description: |
-        Mounted wherever you passed `verifyUrl` to `bankTransfer`, which puts what to look for
-        in the query and signs it. The gateway polls this exactly as it polls a wallet's LUD-21
-        endpoint, and it cannot tell the difference, which is the whole point.
+        Mounted wherever you passed `verifyUrl` to `bankTransfer`, which seals what to look for
+        into the query. The gateway polls this exactly as it polls a wallet's LUD-21 endpoint,
+        and it cannot tell the difference, which is the whole point.
 
-        A query this service did not sign is refused. Without that check the endpoint would
-        answer "did anyone send you this amount with this note" to whoever asked, which is a
-        bank statement handed out one question at a time.
+        A query this service did not seal is refused, and so is one sealed for another
+        account. Without that check the endpoint would answer "did anyone send you this amount
+        with this note" to whoever asked, which is a bank statement handed out one question at
+        a time.
 
-        The preimage is an HMAC of the reference, the amount and the currency under a secret
-        only this service holds, so the gateway can check it hashes to what it was given and
-        still cannot produce it. Nothing is stored between calls.
+        A credit pays when its amount and currency match exactly and the reference stands as a
+        whole word in what the payer wrote, across every field the bank puts a note in, so
+        noise around it is fine. A credit that also names another reference shaped like it, a
+        second order number of the same kind, pays neither.
+
+        The preimage is an HMAC of the account, the amount, the currency, the expiry and the
+        reference under a secret only this service holds, so the gateway can check it hashes to
+        what it was given and still cannot produce it, and a second order under the same
+        reference is another payment. Nothing is stored between calls.
       parameters:
-        - name: ref
+        - name: q
           in: query
           required: true
           description: |
-            What the payer had to leave on the transfer. Matched as a substring against every
-            field the bank puts a note in, so noise around it is fine.
-          schema:
-            type: string
-        - name: minor
-          in: query
-          required: true
-          description: The price in the smallest unit of the currency, so 48055 is 480.55 CZK.
-          schema:
-            type: integer
-            minimum: 1
-        - name: cc
-          in: query
-          required: true
-          description: The three letter currency code the credit has to be in.
+            One blob sealed by `bankTransfer` under the rail secret, naming the account, the
+            amount in minor units, the currency, the expiry and the reference. Padded to one
+            size class, so its length says nothing about what it carries.
           schema:
             type: string
-            minLength: 3
-            maxLength: 3
-        - name: sig
-          in: query
-          required: true
-          description: Hex HMAC-SHA256 over `<ref>|<minor>|<cc>`, minted by `bankTransfer`.
-          schema:
-            type: string
-            pattern: "^[0-9a-f]{64}$"
+            pattern: "^v2\\."
       responses:
         "200":
           description: |
@@ -258,7 +248,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/unsettled"
         "403":
-          description: The signature does not hold, so this service never minted the question.
+          description: The blob does not open under this service's secret, or was sealed for another account, so it never asked the question.
           content:
             application/json:
               schema:

package/package.json

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

package/dist/bank-B3mHISn1.d.cts

@@ -1,92 +0,0 @@
-/** One incoming payment as the bank booked it, in the smallest unit of its currency */
-interface Credit {
-    amountMinor: number;
-    currency: string;
-    /** Whatever the payer wrote, wherever this bank puts it. Matching is a substring, so noise around it is fine */
-    reference: string;
-    /**
-     * Unix seconds. A bank that books a day rather than an instant, as Fio does,
-     * gives the day's midnight in its own zone, so rendering this in UTC can show
-     * the day before. Nothing here matches on it, it is yours to read
-     */
-    bookedAt: number;
-}
-/**
- * Recent credits on one account, oldest or newest first, it makes no difference.
- * This is the whole plugin seam: a bank is a function of this shape, and
- * `fioStatement` is one implementation of it
- */
-type Statement = (sinceUnix: number) => Promise<Credit[]>;
-/** One transfer to ask for: what is owed, where it lands, and where its arrival is read back from */
-interface BankTransferParams {
-    /** Long lived and server side. The preimage is derived from it, so losing it loses every proof */
-    secret: string;
-    /** What the payer must leave on the transfer, an order id or a nonce. It is matched, not stored */
-    reference: string;
-    /** The price in the smallest unit, so 48055 is 480.55 CZK */
-    amountMinor: number;
-    /** The account the money goes to, as an IBAN */
-    iban: string;
-    /** Where `bankVerifyEndpoint` is mounted, a public https URL with no query of its own */
-    verifyUrl: string;
-    /** When the offer dies, in unix seconds. Money in a bank moves on banking days, so give it days */
-    expiresAt: number;
-    /** Defaults to CZK */
-    currency?: string;
-    /** Up to ten digits, for accounting systems that still want one */
-    variableSymbol?: string;
-    /**
-     * Groups this transfer with everything else paid to the same secret, so one
-     * `followTrigger` socket hears about it. Give the Lightning leg of the same
-     * order the same secret and both rails arrive on one stream
-     */
-    trigger?: string;
-    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
-    replay?: number;
-    /**
-     * Handed back untouched on that stream, so a watcher learns which order settled
-     * without asking anyone. `seal` it and the gateway cannot read it either
-     */
-    sealed?: string;
-    /**
-     * Where the gateway posts once the money lands, a public https URL. Without one
-     * a transfer is only ever learned by following the trigger or asking
-     */
-    webhookUrl?: string;
-    /**
-     * Register on a gateway you do not own anyway. The verify URL names the amount
-     * and the reference, so its operator ends up reading your order book, and the
-     * URL itself answers whether that order was paid. Say true only when the order
-     * book is not worth hiding
-     */
-    allowPublicGateway?: boolean;
-}
-/** A transfer the gateway is now watching, and the descriptor the payer scans */
-interface BankTransfer {
-    /** The watched payment's id at the gateway, which is how you read this order back */
-    id: string;
-    /** What the gateway was given, and what the preimage has to hash to */
-    paymentHash: string;
-    /** The same URL you mounted, carrying what to look for and a signature over it */
-    verifyUrl: string;
-    /** The payer scans this, it is a Short Payment Descriptor, the Czech QR platba format */
-    spd: string;
-}
-/** The endpoint the gateway polls for a bank transfer, answering off your own statement */
-interface BankVerifyConfig {
-    /** The same secret `bankTransfer` was given */
-    secret: string;
-    /** The account to read */
-    statement: Statement;
-    /** How far back a credit still counts, seven days by default */
-    lookBackSecs?: number;
-    /**
-     * How often you want the gateway to ask, in seconds. It goes out as
-     * `Cache-Control: max-age`, so the pace is yours to set rather than the
-     * gateway's, and a bank that updates once a minute should say so instead of
-     * being polled every few seconds. Thirty by default, clamped to an hour
-     */
-    pollEverySecs?: number;
-}
-
-export type { BankTransfer as B, Credit as C, Statement as S, BankTransferParams as a, BankVerifyConfig as b };

package/dist/bank-B3mHISn1.d.ts

@@ -1,92 +0,0 @@
-/** One incoming payment as the bank booked it, in the smallest unit of its currency */
-interface Credit {
-    amountMinor: number;
-    currency: string;
-    /** Whatever the payer wrote, wherever this bank puts it. Matching is a substring, so noise around it is fine */
-    reference: string;
-    /**
-     * Unix seconds. A bank that books a day rather than an instant, as Fio does,
-     * gives the day's midnight in its own zone, so rendering this in UTC can show
-     * the day before. Nothing here matches on it, it is yours to read
-     */
-    bookedAt: number;
-}
-/**
- * Recent credits on one account, oldest or newest first, it makes no difference.
- * This is the whole plugin seam: a bank is a function of this shape, and
- * `fioStatement` is one implementation of it
- */
-type Statement = (sinceUnix: number) => Promise<Credit[]>;
-/** One transfer to ask for: what is owed, where it lands, and where its arrival is read back from */
-interface BankTransferParams {
-    /** Long lived and server side. The preimage is derived from it, so losing it loses every proof */
-    secret: string;
-    /** What the payer must leave on the transfer, an order id or a nonce. It is matched, not stored */
-    reference: string;
-    /** The price in the smallest unit, so 48055 is 480.55 CZK */
-    amountMinor: number;
-    /** The account the money goes to, as an IBAN */
-    iban: string;
-    /** Where `bankVerifyEndpoint` is mounted, a public https URL with no query of its own */
-    verifyUrl: string;
-    /** When the offer dies, in unix seconds. Money in a bank moves on banking days, so give it days */
-    expiresAt: number;
-    /** Defaults to CZK */
-    currency?: string;
-    /** Up to ten digits, for accounting systems that still want one */
-    variableSymbol?: string;
-    /**
-     * Groups this transfer with everything else paid to the same secret, so one
-     * `followTrigger` socket hears about it. Give the Lightning leg of the same
-     * order the same secret and both rails arrive on one stream
-     */
-    trigger?: string;
-    /** How many settlements of that trigger the gateway keeps replayable past the hour, needs `trigger` */
-    replay?: number;
-    /**
-     * Handed back untouched on that stream, so a watcher learns which order settled
-     * without asking anyone. `seal` it and the gateway cannot read it either
-     */
-    sealed?: string;
-    /**
-     * Where the gateway posts once the money lands, a public https URL. Without one
-     * a transfer is only ever learned by following the trigger or asking
-     */
-    webhookUrl?: string;
-    /**
-     * Register on a gateway you do not own anyway. The verify URL names the amount
-     * and the reference, so its operator ends up reading your order book, and the
-     * URL itself answers whether that order was paid. Say true only when the order
-     * book is not worth hiding
-     */
-    allowPublicGateway?: boolean;
-}
-/** A transfer the gateway is now watching, and the descriptor the payer scans */
-interface BankTransfer {
-    /** The watched payment's id at the gateway, which is how you read this order back */
-    id: string;
-    /** What the gateway was given, and what the preimage has to hash to */
-    paymentHash: string;
-    /** The same URL you mounted, carrying what to look for and a signature over it */
-    verifyUrl: string;
-    /** The payer scans this, it is a Short Payment Descriptor, the Czech QR platba format */
-    spd: string;
-}
-/** The endpoint the gateway polls for a bank transfer, answering off your own statement */
-interface BankVerifyConfig {
-    /** The same secret `bankTransfer` was given */
-    secret: string;
-    /** The account to read */
-    statement: Statement;
-    /** How far back a credit still counts, seven days by default */
-    lookBackSecs?: number;
-    /**
-     * How often you want the gateway to ask, in seconds. It goes out as
-     * `Cache-Control: max-age`, so the pace is yours to set rather than the
-     * gateway's, and a bank that updates once a minute should say so instead of
-     * being polled every few seconds. Thirty by default, clamped to an hour
-     */
-    pollEverySecs?: number;
-}
-
-export type { BankTransfer as B, Credit as C, Statement as S, BankTransferParams as a, BankVerifyConfig as b };