thunder-bridge 0.8.6 → 0.8.9

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,11 @@ var NoWalletAvailable = class extends Error {
 // ../core/lnurl.ts
 var VERIFY_WITHOUT_PREIMAGE = ["zeuspay.com", "zeusnuts.com", "ecash.love"];
 var RESOLVE_TIMEOUT_MS = 3e4;
+var NAMES_ONE_ACCOUNT = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*$/;
+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 +547,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(
@@ -540,18 +584,29 @@ function withAmount(callback, amountMsat) {
 }
 function splitAddress(address) {
   const [user, domain, ...rest] = address.split("@");
-  if (!user || !domain || rest.length > 0 || !publicHttps(`https://${domain}/`)) {
+  if (!user || !domain || rest.length > 0 || !NAMES_ONE_ACCOUNT.test(user) || !isNothingButAHost(domain) || !publicHttps(`https://${domain}/`)) {
     throw new WalletRefused("address-unusable", `${address} is not a usable lightning address`);
   }
   return [user, domain];
 }
+function isNothingButAHost(domain) {
+  try {
+    const parsed = new URL(`https://${domain}/`);
+    return parsed.host === domain.toLowerCase() && parsed.pathname === "/" && parsed.search === "" && parsed.hash === "";
+  } catch {
+    return false;
+  }
+}
 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 +628,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 +668,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 {
@@ -719,6 +801,30 @@ function refuse(reason) {
   return Response.json({ status: "ERROR", reason });
 }
 
+// ../core/ed25519.ts
+var PKCS8_HEADER = hexToBytes("302e020100300506032b657004220420");
+
+// src/webhook.ts
+var VERIFY_CHALLENGE = "verify-challenge";
+function nonceOf(text2, type) {
+  try {
+    const said = JSON.parse(text2);
+    if (said["type"] !== type || typeof said["nonce"] !== "string") return null;
+    return said["nonce"];
+  } catch {
+    return null;
+  }
+}
+function answerVerifyChallenge(body) {
+  const nonce = nonceOf(body, VERIFY_CHALLENGE);
+  return nonce === null ? null : JSON.stringify({ nonce });
+}
+async function answerVerifyChallengeRequest(request) {
+  if (request.method !== "POST") return null;
+  const answer = answerVerifyChallenge(await request.clone().text());
+  return answer === null ? null : new Response(answer, { headers: { "content-type": "application/json" } });
+}
+
 // src/qr.ts
 import { encode } from "uqr";
 function encodeForQr(destination) {
@@ -730,14 +836,48 @@ 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 consented = await answerVerifyChallengeRequest(request);
+    if (consented !== null) return consented;
+    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 +905,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.9",
   "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",