thunder-bridge 0.8.6 → 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.
@@ -248,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

package/dist/index.cjs

@@ -1290,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) {
@@ -1316,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 });
@@ -1326,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) {

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-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';
+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

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-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';
+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

package/dist/index.js

@@ -1218,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) {
@@ -1244,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 });
@@ -1254,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) {

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

@@ -362,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;
 }

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

@@ -362,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;
 }

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-CdKeyVGn.cjs';
-export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-CdKeyVGn.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-CdKeyVGn.js';
-export { m as BlindLightningRailConfig, n as blindLightningRail } from './rail-CdKeyVGn.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 };

package/dist/server.js

@@ -4,6 +4,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) {
@@ -211,6 +221,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;
@@ -391,19 +405,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 };
@@ -441,6 +455,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,
@@ -528,6 +546,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(
@@ -546,12 +589,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
@@ -573,6 +619,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`);
@@ -597,6 +659,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 {
@@ -730,14 +803,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),
@@ -765,5 +870,7 @@ async function invoiceFrom(lnAddresses, amountMsat) {
 }
 export {
   blindLightningRail,
-  lnurlPayEndpoint
+  lightningVerifyEndpoint,
+  lnurlPayEndpoint,
+  relayedVerifyUrl
 };

package/package.json

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