thunder-bridge 0.8.4 → 0.8.6

package/README.md

@@ -167,7 +167,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`,
@@ -339,17 +340,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 +400,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()
@@ -1763,18 +1788,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 +1848,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 +1863,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, 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;
-  return parseWatchedWebhook(await request.text(), signature, secret, timestamp, options);
+  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 +1931,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-CdKeyVGn.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-CdKeyVGn.cjs';
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -338,23 +338,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 +451,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-CdKeyVGn.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-CdKeyVGn.js';
 
 /**
  * Encrypt what the watcher needs and the gateway must not have. The gateway
@@ -338,23 +338,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 +451,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.js

@@ -562,6 +562,7 @@ function triggerEventFromWire(body) {
   if (sealed !== null && typeof sealed !== "string") return null;
   return {
     id,
+    kind: kindOf(wire),
     paymentHash,
     verifyUrl,
     status,
@@ -573,6 +574,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 };
 }
@@ -710,6 +716,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()
@@ -1693,18 +1716,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));
@@ -1712,14 +1776,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));
@@ -1727,11 +1791,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, 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;
-  return parseWatchedWebhook(await request.text(), signature, secret, timestamp, options);
+  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);
@@ -1761,6 +1858,8 @@ export {
   REQUEST_IN_FLIGHT,
   ThunderBridge,
   UnverifiedRecipientError,
+  answerWebhookChallenge,
+  answerWebhookChallengeRequest,
   bankRail,
   bankTransfer,
   bankVerifyEndpoint,

package/dist/{rail-QZtUN1D-.d.cts → rail-CdKeyVGn.d.cts}

@@ -1,5 +1,7 @@
 /** Where a payment stands, `paid` is the only status that carries a preimage */
 type PaymentStatus = "pending" | "paid" | "expired";
+/** Whether the gateway resolved the address and got the invoice, or was handed one to watch */
+type PaymentKind = "minted" | "watched";
 /** A payment as the gateway reports it, every field is checkable against the recipient */
 interface Payment {
     id: string;
@@ -53,6 +55,7 @@ interface Quote {
  */
 interface TriggerEvent {
     id: string;
+    kind: PaymentKind;
     paymentHash: string;
     verifyUrl: string;
     status: PaymentStatus;
@@ -189,6 +192,12 @@ declare class ThunderBridge {
      */
     createQuote(params: CreateQuoteParams): Promise<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
+     */
+    webhookKey(): Promise<string>;
     getPayment(id: string): Promise<Payment | null>;
     /**
      * Read back a payment the gateway is only watching, null when it has never
@@ -378,4 +387,4 @@ declare function lightningRail(config: LightningRailConfig): Rail;
  */
 declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
 
-export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, ThunderBridge as T, type WalletFailure as W, type TriggerEvent as a, type CreateOptions as b, type CreateQuoteParams as c, type LightningRailConfig as d, type PaymentStatus as e, type ThunderBridgeOptions as f, type WaitOptions as g, type WalletReason as h, type WatchPaymentParams as i, bankRail as j, type BlindLightningRailConfig as k, lightningRail as l, blindLightningRail as m };
+export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, ThunderBridge as T, type WalletFailure as W, type TriggerEvent as a, type CreateOptions as b, type CreateQuoteParams as c, type LightningRailConfig as d, type PaymentKind as e, type PaymentStatus as f, type ThunderBridgeOptions as g, type WaitOptions as h, type WalletReason as i, type WatchPaymentParams as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, blindLightningRail as n };

package/dist/{rail-QZtUN1D-.d.ts → rail-CdKeyVGn.d.ts}

@@ -1,5 +1,7 @@
 /** Where a payment stands, `paid` is the only status that carries a preimage */
 type PaymentStatus = "pending" | "paid" | "expired";
+/** Whether the gateway resolved the address and got the invoice, or was handed one to watch */
+type PaymentKind = "minted" | "watched";
 /** A payment as the gateway reports it, every field is checkable against the recipient */
 interface Payment {
     id: string;
@@ -53,6 +55,7 @@ interface Quote {
  */
 interface TriggerEvent {
     id: string;
+    kind: PaymentKind;
     paymentHash: string;
     verifyUrl: string;
     status: PaymentStatus;
@@ -189,6 +192,12 @@ declare class ThunderBridge {
      */
     createQuote(params: CreateQuoteParams): Promise<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
+     */
+    webhookKey(): Promise<string>;
     getPayment(id: string): Promise<Payment | null>;
     /**
      * Read back a payment the gateway is only watching, null when it has never
@@ -378,4 +387,4 @@ declare function lightningRail(config: LightningRailConfig): Rail;
  */
 declare function blindLightningRail(config: BlindLightningRailConfig): Rail;
 
-export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, ThunderBridge as T, type WalletFailure as W, type TriggerEvent as a, type CreateOptions as b, type CreateQuoteParams as c, type LightningRailConfig as d, type PaymentStatus as e, type ThunderBridgeOptions as f, type WaitOptions as g, type WalletReason as h, type WatchPaymentParams as i, bankRail as j, type BlindLightningRailConfig as k, lightningRail as l, blindLightningRail as m };
+export { type BankRailConfig as B, type CreatePaymentParams as C, type FollowOptions as F, type Leg as L, type Order as O, type Payment as P, type Quote as Q, type Rail as R, ThunderBridge as T, type WalletFailure as W, type TriggerEvent as a, type CreateOptions as b, type CreateQuoteParams as c, type LightningRailConfig as d, type PaymentKind as e, type PaymentStatus as f, type ThunderBridgeOptions as g, type WaitOptions as h, type WalletReason as i, type WatchPaymentParams as j, bankRail as k, lightningRail as l, type BlindLightningRailConfig as m, blindLightningRail as n };

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge } from './rail-QZtUN1D-.cjs';
-export { k as BlindLightningRailConfig, m as blindLightningRail } from './rail-QZtUN1D-.cjs';
+import { T as ThunderBridge } from './rail-CdKeyVGn.cjs';
+export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-CdKeyVGn.cjs';
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { T as ThunderBridge } from './rail-QZtUN1D-.js';
-export { k as BlindLightningRailConfig, m as blindLightningRail } from './rail-QZtUN1D-.js';
+import { T as ThunderBridge } from './rail-CdKeyVGn.js';
+export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-CdKeyVGn.js';
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */

package/package.json

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