thunder-bridge 0.8.4 → 0.8.8

package/README.md

@@ -112,6 +112,8 @@ them and this table does not repeat them.
 | `bankTransfer(params)` | register a Czech QR platba as a watched payment. Refuses a gateway that serves strangers |
 | `bankVerifyEndpoint(config)` | the other half, the LUD-21 shape backed by your own statement |
 | `fioStatement(config)` | a `Statement` reading a Fio account, several tokens used strictly in turn |
+| `lightningVerifyEndpoint(config)` | the same shape for Lightning, asking the wallet on the gateway's behalf. From `thunder-bridge/server` |
+| `relayedVerifyUrl(mount, wallet, secret)` | the URL to hand the gateway instead of the wallet's, with the wallet's sealed inside |
 
 What your service answers once those handlers are mounted is written out in
 [`openapi.yaml`](openapi.yaml), shipped with this package.
@@ -167,7 +169,8 @@ const tipJar = lnurlToSvg("https://agora.gripe/tip");
 
 **Webhooks** - [`src/webhook.ts`](src/webhook.ts): `parseWebhookRequest`,
 `parseWebhook`, `parseWatchedWebhookRequest`, `parseWatchedWebhook`,
-`verifyWebhookSignature`. See [Webhooks](#webhooks).
+`verifyWebhookSignature`, `answerWebhookChallengeRequest`,
+`answerWebhookChallenge`. See [Webhooks](#webhooks).
 
 **Errors** - [`src/errors.ts`](src/errors.ts): `ProblemError`,
 `NoWalletAvailableError`, `GatewayCheatError`, `UnverifiedRecipientError`,
@@ -247,6 +250,53 @@ already in the account:
 Neither has been seen with Fio, which forwards the message untouched. Check it
 against the banks your payers actually use before you promise them a rail.
 
+## Making the gateway poll nobody but you
+
+By default a Lightning watch hands the gateway the wallet's own verify URL, so the
+gateway polls `blink.sv` or `coinos.io` directly and its logs, its ledger and its
+peers all carry that domain. If you would rather it never touched a third party and
+never learned which provider your recipient uses, put your own endpoint in between.
+
+```ts
+import { blindLightningRail, lightningVerifyEndpoint } from "thunder-bridge/server";
+
+app.get("/verify/lightning", (context) =>
+  lightningVerifyEndpoint({ secret: RELAY_SECRET, pollEverySecs: 5 })(context.req.raw),
+);
+
+const rail = blindLightningRail({
+  gateway,
+  lnAddresses: ["you@blink.sv"],
+  amountMsat: (order) => order.amountMinor * 40,
+  relayVerifyThrough: { endpoint: "https://shop.example/verify/lightning", secret: RELAY_SECRET },
+});
+```
+
+The wallet's URL is sealed into the query with your secret, so what the gateway
+stores and replicates is a blob it cannot read. It polls you, you ask the wallet,
+and the preimage still comes from the recipient's own server and still has to hash
+to the payment hash, so standing in the middle buys privacy and pacing without
+making you something anyone has to trust. A wallet you cannot reach answers `502`
+rather than "not settled", because those are different claims.
+
+Both rails then run through endpoints of yours, on a pace you set, and the gateway
+is only ever talking to servers that asked to be talked to. It costs you a service
+that has to stay up: a browser-only integration cannot do this, and should keep
+letting the gateway poll the wallet.
+
+### How often the gateway asks
+
+Your endpoint decides, not the gateway. `bankVerifyEndpoint` answers with
+`Cache-Control: max-age=30`, and the gateway uses that as the interval for every
+payment on your host. Set `pollEverySecs` to whatever your bank's own refresh makes
+sensible: reading a statement that moves once an hour every five seconds only burns
+your rate limit.
+
+The gateway also asks the URL once, before it accepts the watch, and refuses with
+`424` if it does not answer this shape. So deploy the endpoint first and register
+second. That is what stops anyone pointing a gateway at a server that never asked to
+be polled for three days.
+
 ## What is still trusted
 
 - **The gateway chooses which of your addresses gets paid.** Nothing here can
@@ -339,17 +389,34 @@ try {
 
 Pass `webhookUrl` and optionally `webhookSecret` when you create a payment, or on
 any rail. Once it reaches `paid` the gateway POSTs the same JSON the API returns,
-so the body is a `Payment`. Every delivery carries `x-timestamp`, and with a secret set
-`x-signature: sha256=<hmac>` over `<timestamp>.<body>` rather than the body alone,
-so a captured delivery cannot be replayed at you later. Six attempts on a widening
-backoff, then it parks. An invoice that expires fires nothing.
+so the body is a `Payment`. Every delivery carries `x-timestamp` and an
+`x-signature` over `<timestamp>.<body>` rather than the body alone, so a captured
+delivery cannot be replayed at you later. With a secret set it is
+`sha256=<hmac>` keyed with that secret, and without one it is `ed25519=<signature>`
+from the gateway's own key, which is the better default and is below. Retries widen
+until the payment itself runs out, never sooner than an hour. An invoice that expires
+fires nothing.
 
 Delivery is at-least-once, so deduplicate on `id`.
 
+Your handler answers one challenge before any of that. The gateway POSTs
+`{"type":"webhook-challenge","nonce":"..."}` to the URL while the create is still open
+and refuses the payment with a 424 unless the nonce comes back, so the endpoint has to
+be deployed before you register it. `answerWebhookChallengeRequest` verifies that
+challenge and hands you the response to return, or `null` when the delivery was a real
+settlement, and it leaves the body unread either way.
+
 ```ts
-import { parseWebhookRequest, proveSettlement } from "thunder-bridge";
+import {
+  answerWebhookChallengeRequest,
+  parseWebhookRequest,
+  proveSettlement,
+} from "thunder-bridge";
 
 app.post("/hooks/paid", async (context) => {
+  const challenge = await answerWebhookChallengeRequest(context.req.raw, secret);
+  if (challenge) return challenge;
+
   const payment = await parseWebhookRequest(context.req.raw, secret);
   if (payment === null) return context.text("bad signature", 401);
 
@@ -382,7 +449,38 @@ app.post("/hooks/bank", async (context) => {
 ```
 
 Give each rail its own path, as above, and neither endpoint has to guess which body
-it was handed.
+it was handed. Both events also carry `kind`, `"minted"` or `"watched"`, so a single
+path serving a trigger that both rails settle on can branch on the field instead of
+on which fields are missing.
+
+### Or hand the gateway no secret at all
+
+A secret you give the gateway is kept in its ledger and replicated to its peers,
+because any instance may be the one that delivers. Leave `webhookSecret` out and the
+delivery is signed with the gateway's own key instead, `x-signature:
+ed25519=<signature>` over the same `<timestamp>.<body>`. Fetch the public half once
+and pass it as `{ publicKey }` wherever a secret would go.
+
+```ts
+const publicKey = await gateway.webhookKey();
+
+app.post("/hooks/paid", async (context) => {
+  const challenge = await answerWebhookChallengeRequest(context.req.raw, { publicKey });
+  if (challenge) return challenge;
+
+  const payment = await parseWebhookRequest(context.req.raw, { publicKey });
+  if (payment === null) return context.text("bad signature", 401);
+  ...
+});
+```
+
+Answering echoes the nonce and nothing else here, because there is no secret to sign it
+with. Holding the URL the gateway challenged is the whole proof in that case.
+
+The key is derived from the gateway's `CLUSTER_KEY`, so every instance in one cluster
+signs alike and an operator rotating that key changes this one too. Neither
+credential is ever accepted for the other's scheme, so a secret cannot check an
+`ed25519=` delivery and a public key cannot check a `sha256=` one.
 
 `parseWebhookRequest` refuses anything more than five minutes out of date,
 adjustable with `toleranceSecs`. The signature proves the body came from someone

package/dist/index.cjs

@@ -30,6 +30,8 @@ __export(index_exports, {
   REQUEST_IN_FLIGHT: () => REQUEST_IN_FLIGHT,
   ThunderBridge: () => ThunderBridge,
   UnverifiedRecipientError: () => UnverifiedRecipientError,
+  answerWebhookChallenge: () => answerWebhookChallenge,
+  answerWebhookChallengeRequest: () => answerWebhookChallengeRequest,
   bankRail: () => bankRail,
   bankTransfer: () => bankTransfer,
   bankVerifyEndpoint: () => bankVerifyEndpoint,
@@ -632,6 +634,7 @@ function triggerEventFromWire(body) {
   if (sealed !== null && typeof sealed !== "string") return null;
   return {
     id,
+    kind: kindOf(wire),
     paymentHash,
     verifyUrl,
     status,
@@ -643,6 +646,11 @@ function triggerEventFromWire(body) {
     amountMsat: wire["incoming_amount"] === void 0 ? null : msatFrom(wire["incoming_amount"], 1)
   };
 }
+function kindOf(wire) {
+  const said = wire["kind"];
+  if (said === "minted" || said === "watched") return said;
+  return text(wire["ln_address"]) === null ? "watched" : "minted";
+}
 function toAmount(msat) {
   return { value: String(msat), asset_code: ASSET_CODE, asset_scale: ASSET_SCALE };
 }
@@ -780,6 +788,23 @@ var ThunderBridge = class {
     return quote;
   }
   /** Read a payment back, null when the gateway has never heard of it */
+  /**
+   * The key this gateway signs webhooks with when you registered none of your own,
+   * ready to hand to `parseWebhookRequest` as `{ publicKey }`. Fetch it once and
+   * keep it: it is the same for every instance in the cluster
+   */
+  async webhookKey() {
+    const response = await fetch(`${this.baseUrl}/webhook-key`);
+    if (!response.ok) throw await problemFrom(response);
+    const body = await response.json().catch(() => null);
+    if (body?.algorithm !== "ed25519" || typeof body.public_key !== "string") {
+      throw new ProblemError({
+        status: response.status,
+        title: "The gateway published no ed25519 webhook key"
+      });
+    }
+    return body.public_key;
+  }
   async getPayment(id) {
     const response = await fetch(`${this.baseUrl}/incoming-payments/${encodeURIComponent(id)}`, {
       headers: this.reading()
@@ -1265,6 +1290,7 @@ function minorScaleOf(currency) {
 // src/bank.ts
 var DEFAULT_CURRENCY = "CZK";
 var DEFAULT_LOOK_BACK_SECS = 7 * 24 * 60 * 60;
+var DEFAULT_POLL_EVERY_SECS = 30;
 var IBAN = /^[A-Z]{2}[0-9]{2}[0-9A-Z]{8,30}$/;
 var FORBIDDEN_IN_SPD = "*";
 async function bankTransfer(params) {
@@ -1291,6 +1317,9 @@ async function bankTransfer(params) {
   return { id: watched.id, paymentHash: watched.paymentHash, verifyUrl, spd };
 }
 function bankVerifyEndpoint(config) {
+  const paced = {
+    "cache-control": `max-age=${config.pollEverySecs ?? DEFAULT_POLL_EVERY_SECS}`
+  };
   return async (request) => {
     const asked = readQuery(new URL(request.url));
     if (asked === null) return Response.json({ settled: false }, { status: 400 });
@@ -1301,11 +1330,11 @@ function bankVerifyEndpoint(config) {
     }
     const since = unixNow() - (config.lookBackSecs ?? DEFAULT_LOOK_BACK_SECS);
     const landed = (await config.statement(since)).some((credit) => pays(credit, asked));
-    if (!landed) return Response.json({ settled: false });
-    return Response.json({
-      settled: true,
-      preimage: await hmacHex(config.secret, `preimage|${subject}`)
-    });
+    if (!landed) return Response.json({ settled: false }, { headers: paced });
+    return Response.json(
+      { settled: true, preimage: await hmacHex(config.secret, `preimage|${subject}`) },
+      { headers: paced }
+    );
   };
 }
 function readQuery(url) {
@@ -1763,18 +1792,59 @@ function refusals2(answers) {
   ).join("; ");
 }
 
+// ../core/ed25519.ts
+var ALGORITHM = { name: "Ed25519" };
+var SIGNATURE_BYTES = 64;
+var PUBLIC_KEY_BYTES = 32;
+var PKCS8_HEADER = hexToBytes("302e020100300506032b657004220420");
+async function verifyHex(publicKeyHex, signatureHex, payload) {
+  if (!isHex(publicKeyHex) || publicKeyHex.length !== PUBLIC_KEY_BYTES * 2) return false;
+  if (!isHex(signatureHex) || signatureHex.length !== SIGNATURE_BYTES * 2) return false;
+  try {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      asBuffer2(hexToBytes(publicKeyHex)),
+      ALGORITHM,
+      false,
+      ["verify"]
+    );
+    return await crypto.subtle.verify(
+      ALGORITHM,
+      key,
+      asBuffer2(hexToBytes(signatureHex)),
+      asBuffer2(payload)
+    );
+  } catch {
+    return false;
+  }
+}
+function asBuffer2(bytes) {
+  return bytes.buffer instanceof ArrayBuffer ? bytes : new Uint8Array(bytes);
+}
+
 // src/webhook.ts
 var SIGNATURE_HEADER = "x-signature";
 var TIMESTAMP_HEADER = "x-timestamp";
-var SIGNATURE_PREFIX = "sha256=";
+var SHARED_SECRET_PREFIX = "sha256=";
+var GATEWAY_KEY_PREFIX = "ed25519=";
 var DEFAULT_TOLERANCE_SECS = 300;
-async function verifyWebhookSignature(body, signature, secret, timestamp, options = {}) {
+var CHALLENGE = "webhook-challenge";
+async function verifyWebhookSignature(body, signature, credential, timestamp, options = {}) {
   if (!recent(timestamp, options.toleranceSecs ?? DEFAULT_TOLERANCE_SECS)) return false;
-  const received = signature.startsWith(SIGNATURE_PREFIX) ? signature.slice(SIGNATURE_PREFIX.length) : signature;
-  return equalInConstantTime(await sign(secret, timestamp, body), received.toLowerCase());
+  if (typeof credential !== "string") {
+    if (!signature.startsWith(GATEWAY_KEY_PREFIX)) return false;
+    return verifyHex(
+      credential.publicKey.toLowerCase(),
+      signature.slice(GATEWAY_KEY_PREFIX.length).toLowerCase(),
+      signed(timestamp, body)
+    );
+  }
+  if (signature.startsWith(GATEWAY_KEY_PREFIX)) return false;
+  const received = signature.startsWith(SHARED_SECRET_PREFIX) ? signature.slice(SHARED_SECRET_PREFIX.length) : signature;
+  return equalInConstantTime(await sign(credential, timestamp, body), received.toLowerCase());
 }
-async function parseWebhook(body, signature, secret, timestamp, options = {}) {
-  if (!await verifyWebhookSignature(body, signature, secret, timestamp, options)) return null;
+async function parseWebhook(body, signature, credential, timestamp, options = {}) {
+  if (!await verifyWebhookSignature(body, signature, credential, timestamp, options)) return null;
   const text2 = typeof body === "string" ? body : new TextDecoder().decode(body);
   try {
     return paymentFromWire(JSON.parse(text2));
@@ -1782,14 +1852,14 @@ async function parseWebhook(body, signature, secret, timestamp, options = {}) {
     return null;
   }
 }
-async function parseWebhookRequest(request, secret, options = {}) {
+async function parseWebhookRequest(request, credential, options = {}) {
   const signature = request.headers.get(SIGNATURE_HEADER);
   const timestamp = request.headers.get(TIMESTAMP_HEADER);
   if (signature === null || timestamp === null) return null;
-  return parseWebhook(await request.text(), signature, secret, timestamp, options);
+  return parseWebhook(await request.text(), signature, credential, timestamp, options);
 }
-async function parseWatchedWebhook(body, signature, secret, timestamp, options = {}) {
-  if (!await verifyWebhookSignature(body, signature, secret, timestamp, options)) return null;
+async function parseWatchedWebhook(body, signature, credential, timestamp, options = {}) {
+  if (!await verifyWebhookSignature(body, signature, credential, timestamp, options)) return null;
   const text2 = typeof body === "string" ? body : new TextDecoder().decode(body);
   try {
     return triggerEventFromWire(JSON.parse(text2));
@@ -1797,11 +1867,44 @@ async function parseWatchedWebhook(body, signature, secret, timestamp, options =
     return null;
   }
 }
-async function parseWatchedWebhookRequest(request, secret, options = {}) {
+async function parseWatchedWebhookRequest(request, credential, options = {}) {
   const signature = request.headers.get(SIGNATURE_HEADER);
   const timestamp = request.headers.get(TIMESTAMP_HEADER);
   if (signature === null || timestamp === null) return null;
-  return parseWatchedWebhook(await request.text(), signature, secret, timestamp, options);
+  return parseWatchedWebhook(await request.text(), signature, credential, timestamp, options);
+}
+async function answerWebhookChallenge(body, signature, credential, timestamp, options = {}) {
+  if (!await verifyWebhookSignature(body, signature, credential, timestamp, options)) return null;
+  const text2 = typeof body === "string" ? body : new TextDecoder().decode(body);
+  const nonce = challenged(text2);
+  if (nonce === null) return null;
+  if (typeof credential !== "string") return JSON.stringify({ nonce });
+  return JSON.stringify({
+    nonce,
+    signature: `${SHARED_SECRET_PREFIX}${await hmacHex(credential, nonce)}`
+  });
+}
+async function answerWebhookChallengeRequest(request, credential, options = {}) {
+  const signature = request.headers.get(SIGNATURE_HEADER);
+  const timestamp = request.headers.get(TIMESTAMP_HEADER);
+  if (signature === null || timestamp === null) return null;
+  const answer = await answerWebhookChallenge(
+    await request.clone().text(),
+    signature,
+    credential,
+    timestamp,
+    options
+  );
+  return answer === null ? null : new Response(answer, { headers: { "content-type": "application/json" } });
+}
+function challenged(text2) {
+  try {
+    const said = JSON.parse(text2);
+    if (said["type"] !== CHALLENGE || typeof said["nonce"] !== "string") return null;
+    return said["nonce"];
+  } catch {
+    return null;
+  }
 }
 function recent(timestamp, toleranceSecs) {
   const sent = Number(timestamp);
@@ -1832,6 +1935,8 @@ function signed(timestamp, body) {
   REQUEST_IN_FLIGHT,
   ThunderBridge,
   UnverifiedRecipientError,
+  answerWebhookChallenge,
+  answerWebhookChallengeRequest,
   bankRail,
   bankTransfer,
   bankVerifyEndpoint,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge, P as Payment, C as CreatePaymentParams, a as TriggerEvent, W as WalletFailure } from './rail-QZtUN1D-.cjs';
-export { B as BankRailConfig, b as CreateOptions, c as CreateQuoteParams, F as FollowOptions, L as Leg, d as LightningRailConfig, O as Order, e as PaymentStatus, Q as Quote, R as Rail, f as ThunderBridgeOptions, g as WaitOptions, h as WalletReason, i as WatchPaymentParams, j as bankRail, l as lightningRail } from './rail-QZtUN1D-.cjs';
+import { T as ThunderBridge, P as Payment, C as CreatePaymentParams, a as TriggerEvent, W as WalletFailure } from './rail-J8QoYbSr.cjs';
+export { B as BankRailConfig, b as CreateOptions, c as CreateQuoteParams, F as FollowOptions, L as Leg, d as LightningRailConfig, O as Order, e as PaymentKind, f as PaymentStatus, Q as Quote, R as Rail, g as ThunderBridgeOptions, h as WaitOptions, i as WalletReason, j as WatchPaymentParams, k as bankRail, l as lightningRail } from './rail-J8QoYbSr.cjs';
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -98,6 +98,13 @@ interface BankVerifyConfig {
     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;
 }
 /**
  * Ask for a bank transfer and put it under the gateway's watch, so it settles
@@ -338,23 +345,42 @@ declare function toLnurl(endpoint: string): string;
 type WebhookOptions = {
     toleranceSecs?: number;
 };
+/**
+ * What checks a delivery. A string is the `webhook.secret` you registered. Pass
+ * `{ publicKey }` instead, the hex from the gateway's `/webhook-key`, when you
+ * registered no secret and would rather it held nothing of yours
+ */
+type WebhookCredential = string | {
+    publicKey: string;
+};
 /** 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>;
+declare function verifyWebhookSignature(body: string | Uint8Array, signature: string, credential: WebhookCredential, 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>;
+declare function parseWebhook(body: string | Uint8Array, signature: string, credential: WebhookCredential, 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>;
+declare function parseWebhookRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<Payment | null>;
 /**
  * The same, for a payment the gateway only watched. A bank transfer and a blind
  * Lightning leg carry no address, amount or invoice, so they arrive in the shape
  * `followTrigger` and `getWatched` hand back rather than the minted one
  */
-declare function parseWatchedWebhook(body: string | Uint8Array, signature: string, secret: string, timestamp: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
+declare function parseWatchedWebhook(body: string | Uint8Array, signature: string, credential: WebhookCredential, timestamp: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
 /** `parseWatchedWebhook` from a Fetch API `Request`, the way `parseWebhookRequest` is */
-declare function parseWatchedWebhookRequest(request: Request, secret: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
+declare function parseWatchedWebhookRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<TriggerEvent | null>;
+/**
+ * Answer the one challenge the gateway sends before it will watch a payment your
+ * webhook is registered on. Returns the body to send back with a 200, or null when
+ * this delivery is not a challenge, so a handler tries this first and then parses
+ */
+declare function answerWebhookChallenge(body: string | Uint8Array, signature: string, credential: WebhookCredential, timestamp: string, options?: WebhookOptions): Promise<string | null>;
+/**
+ * `answerWebhookChallenge` from a Fetch API `Request`, leaving the body unread so
+ * the same handler can go on to `parseWebhookRequest` when this was no challenge
+ */
+declare function answerWebhookChallengeRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<Response | null>;
 
 /**
  * The way a gateway was caught out, every code is a check that held against the
@@ -432,4 +458,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, type Statement, ThunderBridge, type Ticker, TriggerEvent, UnverifiedRecipientError, WalletFailure, type WebhookOptions, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };
+export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, type Statement, ThunderBridge, type Ticker, TriggerEvent, UnverifiedRecipientError, WalletFailure, type WebhookCredential, type WebhookOptions, answerWebhookChallenge, answerWebhookChallengeRequest, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge, P as Payment, C as CreatePaymentParams, a as TriggerEvent, W as WalletFailure } from './rail-QZtUN1D-.js';
-export { B as BankRailConfig, b as CreateOptions, c as CreateQuoteParams, F as FollowOptions, L as Leg, d as LightningRailConfig, O as Order, e as PaymentStatus, Q as Quote, R as Rail, f as ThunderBridgeOptions, g as WaitOptions, h as WalletReason, i as WatchPaymentParams, j as bankRail, l as lightningRail } from './rail-QZtUN1D-.js';
+import { T as ThunderBridge, P as Payment, C as CreatePaymentParams, a as TriggerEvent, W as WalletFailure } from './rail-J8QoYbSr.js';
+export { B as BankRailConfig, b as CreateOptions, c as CreateQuoteParams, F as FollowOptions, L as Leg, d as LightningRailConfig, O as Order, e as PaymentKind, f as PaymentStatus, Q as Quote, R as Rail, g as ThunderBridgeOptions, h as WaitOptions, i as WalletReason, j as WatchPaymentParams, k as bankRail, l as lightningRail } from './rail-J8QoYbSr.js';
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -98,6 +98,13 @@ interface BankVerifyConfig {
     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;
 }
 /**
  * Ask for a bank transfer and put it under the gateway's watch, so it settles
@@ -338,23 +345,42 @@ declare function toLnurl(endpoint: string): string;
 type WebhookOptions = {
     toleranceSecs?: number;
 };
+/**
+ * What checks a delivery. A string is the `webhook.secret` you registered. Pass
+ * `{ publicKey }` instead, the hex from the gateway's `/webhook-key`, when you
+ * registered no secret and would rather it held nothing of yours
+ */
+type WebhookCredential = string | {
+    publicKey: string;
+};
 /** 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>;
+declare function verifyWebhookSignature(body: string | Uint8Array, signature: string, credential: WebhookCredential, 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>;
+declare function parseWebhook(body: string | Uint8Array, signature: string, credential: WebhookCredential, 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>;
+declare function parseWebhookRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<Payment | null>;
 /**
  * The same, for a payment the gateway only watched. A bank transfer and a blind
  * Lightning leg carry no address, amount or invoice, so they arrive in the shape
  * `followTrigger` and `getWatched` hand back rather than the minted one
  */
-declare function parseWatchedWebhook(body: string | Uint8Array, signature: string, secret: string, timestamp: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
+declare function parseWatchedWebhook(body: string | Uint8Array, signature: string, credential: WebhookCredential, timestamp: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
 /** `parseWatchedWebhook` from a Fetch API `Request`, the way `parseWebhookRequest` is */
-declare function parseWatchedWebhookRequest(request: Request, secret: string, options?: WebhookOptions): Promise<TriggerEvent | null>;
+declare function parseWatchedWebhookRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<TriggerEvent | null>;
+/**
+ * Answer the one challenge the gateway sends before it will watch a payment your
+ * webhook is registered on. Returns the body to send back with a 200, or null when
+ * this delivery is not a challenge, so a handler tries this first and then parses
+ */
+declare function answerWebhookChallenge(body: string | Uint8Array, signature: string, credential: WebhookCredential, timestamp: string, options?: WebhookOptions): Promise<string | null>;
+/**
+ * `answerWebhookChallenge` from a Fetch API `Request`, leaving the body unread so
+ * the same handler can go on to `parseWebhookRequest` when this was no challenge
+ */
+declare function answerWebhookChallengeRequest(request: Request, credential: WebhookCredential, options?: WebhookOptions): Promise<Response | null>;
 
 /**
  * The way a gateway was caught out, every code is a check that held against the
@@ -432,4 +458,4 @@ declare class NoWalletAvailableError extends ProblemError {
     }, wallets: WalletFailure[]);
 }
 
-export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, type Statement, ThunderBridge, type Ticker, TriggerEvent, UnverifiedRecipientError, WalletFailure, type WebhookOptions, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };
+export { type BankTransfer, type BankTransferParams, type BankVerifyConfig, CreatePaymentParams, type Credit, type FioConfig, type GatewayCheatCode, GatewayCheatError, IDEMPOTENCY_KEY_REUSED, type IdempotencyConflict, IdempotencyConflictError, type Invoice, type MedianOptions, NO_WALLET_AVAILABLE, NoWalletAvailableError, PAYMENT_ALREADY_WATCHED, Payment, ProblemError, type QrOptions, REQUEST_IN_FLIGHT, type Statement, ThunderBridge, type Ticker, TriggerEvent, UnverifiedRecipientError, WalletFailure, type WebhookCredential, type WebhookOptions, answerWebhookChallenge, answerWebhookChallengeRequest, bankTransfer, bankVerifyEndpoint, bitstamp, coinbase, coinmate, decodeInvoice, fioStatement, invoiceToDataUrl, invoiceToSvg, isProblemType, isProvablyPaid, kraken, lnurlToDataUrl, lnurlToSvg, medianOf, minorScaleOf, minorUnitsOf, msatFor, parseWatchedWebhook, parseWatchedWebhookRequest, parseWebhook, parseWebhookRequest, preimageMatchesHash, proveOrigin, proveSettlement, qrToDataUrl, qrToSvg, seal, spdToDataUrl, spdToSvg, toLnurl, unseal, verifyWebhookSignature };