thunder-bridge 0.8.4 → 0.8.8

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()
@@ -1195,6 +1218,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) {
@@ -1221,6 +1245,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 });
@@ -1231,11 +1258,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) {
@@ -1693,18 +1720,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 +1780,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 +1795,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);
@@ -1761,6 +1862,8 @@ export {
   REQUEST_IN_FLIGHT,
   ThunderBridge,
   UnverifiedRecipientError,
+  answerWebhookChallenge,
+  answerWebhookChallengeRequest,
   bankRail,
   bankTransfer,
   bankVerifyEndpoint,

package/dist/{rail-QZtUN1D-.d.cts → rail-J8QoYbSr.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
@@ -353,6 +362,16 @@ interface BlindLightningRailConfig {
     sealed?: (order: Order) => string | Promise<string>;
     webhookUrl?: string;
     webhookSecret?: string;
+    /**
+     * Where your own `lightningVerifyEndpoint` is mounted, and the secret it
+     * unseals with. Set both and the gateway is handed your URL rather than the
+     * wallet's, so it polls you, never a third party, and learns nothing about
+     * which provider the recipient uses. Leave them out and it polls the wallet
+     */
+    relayVerifyThrough?: {
+        endpoint: string;
+        secret: string;
+    };
     /** What `Leg.rail` reads, for a shop running more than one wallet */
     name?: string;
 }
@@ -378,4 +397,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-J8QoYbSr.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
@@ -353,6 +362,16 @@ interface BlindLightningRailConfig {
     sealed?: (order: Order) => string | Promise<string>;
     webhookUrl?: string;
     webhookSecret?: string;
+    /**
+     * Where your own `lightningVerifyEndpoint` is mounted, and the secret it
+     * unseals with. Set both and the gateway is handed your URL rather than the
+     * wallet's, so it polls you, never a third party, and learns nothing about
+     * which provider the recipient uses. Leave them out and it polls the wallet
+     */
+    relayVerifyThrough?: {
+        endpoint: string;
+        secret: string;
+    };
     /** What `Leg.rail` reads, for a shop running more than one wallet */
     name?: string;
 }
@@ -378,4 +397,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.cjs

@@ -31,7 +31,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var server_exports = {};
 __export(server_exports, {
   blindLightningRail: () => blindLightningRail,
-  lnurlPayEndpoint: () => lnurlPayEndpoint
+  lightningVerifyEndpoint: () => lightningVerifyEndpoint,
+  lnurlPayEndpoint: () => lnurlPayEndpoint,
+  relayedVerifyUrl: () => relayedVerifyUrl
 });
 module.exports = __toCommonJS(server_exports);
 
@@ -41,6 +43,16 @@ function bytesToHex(bytes) {
   for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
   return hex;
 }
+function hexToBytes(hex) {
+  const bytes = new Uint8Array(hex.length >> 1);
+  for (let at = 0; at < bytes.length; at++) {
+    bytes[at] = parseInt(hex.slice(at * 2, at * 2 + 2), 16);
+  }
+  return bytes;
+}
+function isHex(text2) {
+  return /^[0-9a-f]+$/i.test(text2) && text2.length % 2 === 0;
+}
 
 // ../core/hmac.ts
 async function hmacHex(secret, payload) {
@@ -248,6 +260,10 @@ function decodeInvoice(bolt11) {
     expiresAt: expiryOf(parts.words, tagged)
   };
 }
+function preimageMatchesHash(preimage, paymentHash) {
+  if (!isHex(preimage)) return false;
+  return bytesToHex(sha256(hexToBytes(preimage))) === paymentHash.toLowerCase();
+}
 function splitBech32(bolt11) {
   const lower = bolt11.toLowerCase();
   if (isBolt12Encoding(lower)) return null;
@@ -428,19 +444,19 @@ async function refuseUnlessPublic(url) {
   if (!await resolvesNothingPrivate(url)) throw new Error(`${url} resolves to an address we do not reach`);
 }
 async function answerOf(response) {
-  const { status, ok } = response;
+  const { status, ok, headers } = response;
   const reader = response.body?.getReader();
-  if (!reader) return { status, ok, body: "", truncated: false };
+  if (!reader) return { status, ok, body: "", truncated: false, headers };
   const read = [];
   let bytes = 0;
   while (bytes <= BODY_LIMIT_BYTES) {
     const { done, value } = await reader.read();
-    if (done) return { status, ok, body: text(read), truncated: false };
+    if (done) return { status, ok, body: text(read), truncated: false, headers };
     read.push(value);
     bytes += value.length;
   }
   await reader.cancel();
-  return { status, ok, body: text(read), truncated: true };
+  return { status, ok, body: text(read), truncated: true, headers };
 }
 function withoutBody(sent) {
   const headers = { ...sent.headers };
@@ -478,6 +494,10 @@ var NoWalletAvailable = class extends Error {
 // ../core/lnurl.ts
 var VERIFY_WITHOUT_PREIMAGE = ["zeuspay.com", "zeusnuts.com", "ecash.love"];
 var RESOLVE_TIMEOUT_MS = 3e4;
+var MIN_PACE_SECS = 1;
+var MAX_PACE_SECS = 3600;
+var MIN_PER_SECOND = 0.01;
+var MAX_PER_SECOND = 100;
 async function resolve(addresses, amountMsat) {
   const served = await firstThatServes(
     addresses,
@@ -565,6 +585,31 @@ function decodeIssued(address, bolt11) {
   }
   return { paymentHash, descriptionHash, amountMsat, expiresAt };
 }
+async function checkSettled(verifyUrl, paymentHash) {
+  const answer = await answeredJson(verifyUrl);
+  const asked = {
+    pace: paceAskedFor(answer.headers),
+    ceiling: ceilingAskedFor(answer.headers)
+  };
+  if (!answer.said.settled || !answer.said.preimage) return { preimage: null, ...asked };
+  if (!preimageMatchesHash(answer.said.preimage, paymentHash)) {
+    throw new Error(`verify returned a preimage that does not hash to ${paymentHash}`);
+  }
+  return { preimage: answer.said.preimage, ...asked };
+}
+function paceAskedFor(headers) {
+  const asked = /max-age\s*=\s*(\d+)/i.exec(headers.get("cache-control") ?? "");
+  if (!asked) return null;
+  return Math.min(Math.max(Number(asked[1]), MIN_PACE_SECS), MAX_PACE_SECS);
+}
+function ceilingAskedFor(headers) {
+  const asked = /^\s*(\d+)\s*(?:;\s*w\s*=\s*(\d+))?/i.exec(headers.get("ratelimit-limit") ?? "");
+  if (!asked) return null;
+  const perWindow = Number(asked[1]);
+  const window = asked[2] === void 0 ? 1 : Number(asked[2]);
+  if (perWindow === 0 || window === 0) return null;
+  return Math.min(Math.max(perWindow / window, MIN_PER_SECOND), MAX_PER_SECOND);
+}
 function cannotReleaseAPreimage(host) {
   const lowered = host.toLowerCase();
   return VERIFY_WITHOUT_PREIMAGE.some(
@@ -583,12 +628,15 @@ function splitAddress(address) {
   return [user, domain];
 }
 async function fetchJson(url, deadline) {
+  return (await answeredJson(url, deadline)).said;
+}
+async function answeredJson(url, deadline) {
   const answer = await ask(url, { headers: { accept: "application/json" }, deadline });
   if (!answer.ok) throw new Error(`${url} answered ${answer.status}`);
   if (answer.truncated) {
     throw new Error(`${url} answered with more than the ${BODY_LIMIT_BYTES} bytes we read`);
   }
-  return JSON.parse(answer.body);
+  return { said: JSON.parse(answer.body), headers: answer.headers };
 }
 
 // ../core/sealed.ts
@@ -610,6 +658,22 @@ async function seal(secret, plaintext) {
   joined.set(cipher, iv.length);
   return `${VERSION}.${toBase64Url(joined)}`;
 }
+async function unseal(secret, sealed) {
+  const key = await keyFor(secret);
+  if (!sealed.startsWith(`${VERSION}.`)) return null;
+  const joined = fromBase64Url(sealed.slice(VERSION.length + 1));
+  if (joined === null || joined.length <= IV_BYTES) return null;
+  try {
+    const body = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: joined.slice(0, IV_BYTES) },
+      key,
+      joined.slice(IV_BYTES)
+    );
+    return new TextDecoder().decode(body);
+  } catch {
+    return null;
+  }
+}
 async function keyFor(secret) {
   if (secret.length < MIN_SECRET_CHARS) {
     throw new Error(`the sealing secret needs ${MIN_SECRET_CHARS} characters of randomness`);
@@ -634,6 +698,17 @@ function toBase64Url(bytes) {
   for (const byte of bytes) binary += String.fromCharCode(byte);
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
+function fromBase64Url(text2) {
+  if (text2.length === 0 || !/^[A-Za-z0-9_-]+$/.test(text2)) return null;
+  try {
+    const binary = atob(text2.replace(/-/g, "+").replace(/_/g, "/"));
+    const bytes = new Uint8Array(binary.length);
+    for (let at = 0; at < bytes.length; at++) bytes[at] = binary.charCodeAt(at);
+    return bytes;
+  } catch {
+    return null;
+  }
+}
 
 // src/errors.ts
 var ProblemError = class extends Error {
@@ -767,14 +842,46 @@ function isLnAddress(destination) {
   return at > 0 && destination.slice(at + 1).includes(".");
 }
 
+// src/relay.ts
+var DEFAULT_POLL_EVERY_SECS = 5;
+var WALLET = "w";
+function lightningVerifyEndpoint(config) {
+  const paced = {
+    "cache-control": `max-age=${config.pollEverySecs ?? DEFAULT_POLL_EVERY_SECS}`
+  };
+  return async (request) => {
+    const sealed = new URL(request.url).searchParams.get(WALLET);
+    if (sealed === null) return Response.json({ settled: false }, { status: 400 });
+    const opened = await unseal(config.secret, sealed);
+    if (opened === null) return Response.json({ settled: false }, { status: 403 });
+    const wallet = JSON.parse(opened);
+    const asked = await checkSettled(wallet.url, wallet.hash).catch(() => null);
+    if (asked === null) return Response.json({ settled: false }, { status: 502 });
+    return Response.json(
+      { settled: asked.preimage !== null, preimage: asked.preimage },
+      { headers: paced }
+    );
+  };
+}
+async function relayedVerifyUrl(endpoint, wallet, secret) {
+  const relayed = new URL(endpoint);
+  relayed.searchParams.set(WALLET, await seal(secret, JSON.stringify(wallet)));
+  return relayed.toString();
+}
+
 // src/rail.ts
 var LIGHTNING = "lightning";
 function blindLightningRail(config) {
   return async (order) => {
     const resolved = await invoiceFrom(config.lnAddresses, await config.amountMsat(order));
+    const relay = config.relayVerifyThrough;
     const watched = await config.gateway.watchPayment({
       paymentHash: resolved.paymentHash,
-      verifyUrl: resolved.verifyUrl,
+      verifyUrl: relay ? await relayedVerifyUrl(
+        relay.endpoint,
+        { url: resolved.verifyUrl, hash: resolved.paymentHash },
+        relay.secret
+      ) : resolved.verifyUrl,
       expiresAt: resolved.expiresAt,
       trigger: config.trigger,
       sealed: await config.sealed?.(order),
@@ -803,5 +910,7 @@ async function invoiceFrom(lnAddresses, amountMsat) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   blindLightningRail,
-  lnurlPayEndpoint
+  lightningVerifyEndpoint,
+  lnurlPayEndpoint,
+  relayedVerifyUrl
 });

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-J8QoYbSr.cjs';
+export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-J8QoYbSr.cjs';
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */
@@ -61,4 +61,43 @@ interface Minted {
  */
 declare function lnurlPayEndpoint(config: TriggerConfig): (request: Request) => Promise<Response>;
 
-export { type Minted, type TriggerConfig, lnurlPayEndpoint };
+/** The wallet's own LUD-21 URL and the hash its preimage has to match */
+interface Relayed {
+    url: string;
+    hash: string;
+}
+interface LightningVerifyConfig {
+    /** The secret the sealed wallet URL was made with, and nothing else uses it */
+    secret: string;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours rather than the operator's.
+     * Five by default, which is what a Lightning checkout wants
+     */
+    pollEverySecs?: number;
+}
+/**
+ * A verify endpoint of your own that asks the recipient's wallet for you, so the
+ * gateway polls you and never the wallet.
+ *
+ * `relayedVerifyUrl` seals the wallet's own LUD-21 URL into the query with your
+ * secret, so what the gateway stores and replicates is opaque: not the wallet's
+ * host, not which provider the recipient uses, nothing but a blob it cannot read.
+ * This handler unseals it, asks the wallet, and answers the same LUD-21 shape.
+ *
+ * It relays rather than decides. The preimage still comes from the recipient's
+ * own server and still has to hash to the payment hash, so standing between the
+ * two buys privacy and pacing without becoming something anyone has to trust.
+ *
+ * A wallet it cannot reach answers `502` rather than "not settled", because those
+ * are different claims and only one of them is true. The gateway logs a failed
+ * poll and asks again, which is what a broken relay should look like.
+ */
+declare function lightningVerifyEndpoint(config: LightningVerifyConfig): (request: Request) => Promise<Response>;
+/**
+ * The URL to hand the gateway instead of the wallet's own, with the wallet's
+ * sealed inside it. Point it at wherever `lightningVerifyEndpoint` is mounted
+ */
+declare function relayedVerifyUrl(endpoint: string, wallet: Relayed, secret: string): Promise<string>;
+
+export { type LightningVerifyConfig, type Minted, type Relayed, type TriggerConfig, lightningVerifyEndpoint, lnurlPayEndpoint, relayedVerifyUrl };

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-J8QoYbSr.js';
+export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-J8QoYbSr.js';
 
 interface TriggerConfig {
     /** The gateway that quotes the addresses and mints the invoice */
@@ -61,4 +61,43 @@ interface Minted {
  */
 declare function lnurlPayEndpoint(config: TriggerConfig): (request: Request) => Promise<Response>;
 
-export { type Minted, type TriggerConfig, lnurlPayEndpoint };
+/** The wallet's own LUD-21 URL and the hash its preimage has to match */
+interface Relayed {
+    url: string;
+    hash: string;
+}
+interface LightningVerifyConfig {
+    /** The secret the sealed wallet URL was made with, and nothing else uses it */
+    secret: string;
+    /**
+     * How often you want the gateway to ask, in seconds. It goes out as
+     * `Cache-Control: max-age`, so the pace is yours rather than the operator's.
+     * Five by default, which is what a Lightning checkout wants
+     */
+    pollEverySecs?: number;
+}
+/**
+ * A verify endpoint of your own that asks the recipient's wallet for you, so the
+ * gateway polls you and never the wallet.
+ *
+ * `relayedVerifyUrl` seals the wallet's own LUD-21 URL into the query with your
+ * secret, so what the gateway stores and replicates is opaque: not the wallet's
+ * host, not which provider the recipient uses, nothing but a blob it cannot read.
+ * This handler unseals it, asks the wallet, and answers the same LUD-21 shape.
+ *
+ * It relays rather than decides. The preimage still comes from the recipient's
+ * own server and still has to hash to the payment hash, so standing between the
+ * two buys privacy and pacing without becoming something anyone has to trust.
+ *
+ * A wallet it cannot reach answers `502` rather than "not settled", because those
+ * are different claims and only one of them is true. The gateway logs a failed
+ * poll and asks again, which is what a broken relay should look like.
+ */
+declare function lightningVerifyEndpoint(config: LightningVerifyConfig): (request: Request) => Promise<Response>;
+/**
+ * The URL to hand the gateway instead of the wallet's own, with the wallet's
+ * sealed inside it. Point it at wherever `lightningVerifyEndpoint` is mounted
+ */
+declare function relayedVerifyUrl(endpoint: string, wallet: Relayed, secret: string): Promise<string>;
+
+export { type LightningVerifyConfig, type Minted, type Relayed, type TriggerConfig, lightningVerifyEndpoint, lnurlPayEndpoint, relayedVerifyUrl };