@getalby/lightning-tools 8.1.0 → 8.2.0

package/dist/esm/402.js

@@ -1257,6 +1257,28 @@ class Invoice {
     }
 }
 
+/** Apply a previously-obtained credential to the outgoing request headers. */
+const applyCredentials = (headers, credentials) => {
+    headers.set(credentials.header, credentials.value);
+};
+/** Attach payment metadata to a response and return it (typed). */
+const attachPayment = (response, payment) => {
+    if (payment) {
+        response.payment = payment;
+    }
+    return response;
+};
+/** Payment metadata describing a request authorized with a reused credential. */
+const reusedCredentialPayment = (credentials) => credentials ? { paid: false, amount: 0, credentials } : undefined;
+/** Satoshi amount of a BOLT11 invoice (0 when it cannot be decoded). */
+const getInvoiceAmount = (invoice) => {
+    try {
+        return new Invoice({ pr: invoice }).satoshi;
+    }
+    catch (_) {
+        return 0;
+    }
+};
 function createGuardedWallet(wallet, maxAmountSats) {
     return {
         payInvoice: async (args) => {
@@ -1308,6 +1330,9 @@ const handleL402Payment = async (l402Header, url, fetchArgs, headers, wallet) =>
     const details = parseL402(l402Header);
     const token = details.token || details.macaroon;
     const invoice = details.invoice;
+    // Preserve the scheme the server challenged with (L402 or LSAT) so the
+    // retry's Authorization header matches what the server expects.
+    const scheme = /^\s*LSAT\b/i.test(l402Header) ? "LSAT" : "L402";
     if (!token) {
         throw new Error("L402: missing token/macaroon in WWW-Authenticate header");
     }
@@ -1315,8 +1340,16 @@ const handleL402Payment = async (l402Header, url, fetchArgs, headers, wallet) =>
         throw new Error("L402: missing invoice in WWW-Authenticate header");
     }
     const invResp = await wallet.payInvoice({ invoice });
-    headers.set("Authorization", `L402 ${token}:${invResp.preimage}`);
-    return fetch(url, fetchArgs);
+    const value = `${scheme} ${token}:${invResp.preimage}`;
+    headers.set("Authorization", value);
+    const response = await fetch(url, fetchArgs);
+    return attachPayment(response, {
+        paid: true,
+        amount: getInvoiceAmount(invoice),
+        feesPaid: invResp.fees_paid,
+        preimage: invResp.preimage,
+        credentials: { header: "Authorization", value },
+    });
 };
 const fetchWithL402 = async (url, fetchArgs, options) => {
     const wallet = options.wallet;
@@ -1330,6 +1363,15 @@ const fetchWithL402 = async (url, fetchArgs, options) => {
     fetchArgs.mode = "cors";
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
+    // If the caller supplied a credential, we MUST use it and never pay again —
+    // even if the server still responds with a 402. Re-paying here is the exact
+    // double-charge this API exists to prevent; the caller decides what to do
+    // with a rejected credential (retry after settlement, top up, etc.).
+    if (options.credentials) {
+        applyCredentials(headers, options.credentials);
+        const reusedResp = await fetch(url, fetchArgs);
+        return attachPayment(reusedResp, reusedCredentialPayment(options.credentials));
+    }
     const initResp = await fetch(url, fetchArgs);
     const header = initResp.headers.get("www-authenticate");
     if (!header) {
@@ -1350,7 +1392,7 @@ const buildX402PaymentSignature = (scheme, network, invoice, requirements) => {
     return btoa(unescape(encodeURIComponent(json)));
 };
 
-const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) => {
+const decodeX402Header = (x402Header) => {
     let parsed;
     try {
         parsed = JSON.parse(decodeURIComponent(escape(atob(x402Header))));
@@ -1361,9 +1403,31 @@ const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) =>
     if (!Array.isArray(parsed.accepts) || parsed.accepts.length === 0) {
         throw new Error("x402: PAYMENT-REQUIRED header contains no payment options");
     }
-    const requirements = parsed.accepts.find((e) => {
-        return e.extra?.paymentMethod === "lightning";
-    });
+    return { accepts: parsed.accepts };
+};
+/**
+ * Probe a PAYMENT-REQUIRED header for a lightning-payable offer without
+ * throwing. Returns the matching requirements, or null if the header has no
+ * lightning entry (e.g. USDC-only endpoints) or is malformed. Used by the
+ * top-level fetch402 dispatcher to decide whether to attempt payment or hand
+ * the 402 back to the caller.
+ */
+const findX402LightningRequirements = (x402Header) => {
+    let accepts;
+    try {
+        ({ accepts } = decodeX402Header(x402Header));
+    }
+    catch (_) {
+        return null;
+    }
+    const requirements = accepts.find((e) => e?.extra?.paymentMethod === "lightning");
+    if (!requirements?.extra?.invoice)
+        return null;
+    return requirements;
+};
+const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) => {
+    const { accepts } = decodeX402Header(x402Header);
+    const requirements = accepts.find((e) => e?.extra?.paymentMethod === "lightning");
     if (!requirements) {
         throw new Error("x402: unsupported x402 network, only Bitcoin lightning network is supported.");
     }
@@ -1374,9 +1438,17 @@ const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) =>
     if (invoice.amountRaw != requirements.amount) {
         throw new Error(`Invalid invoice amount: ${invoice.amountRaw}. expected ${requirements.amount}`);
     }
-    await wallet.payInvoice({ invoice: invoice.paymentRequest });
-    headers.set("payment-signature", buildX402PaymentSignature(requirements.scheme, requirements.network, invoice.paymentRequest, requirements));
-    return fetch(url, fetchArgs);
+    const invResp = await wallet.payInvoice({ invoice: invoice.paymentRequest });
+    const value = buildX402PaymentSignature(requirements.scheme, requirements.network, invoice.paymentRequest, requirements);
+    headers.set("payment-signature", value);
+    const response = await fetch(url, fetchArgs);
+    return attachPayment(response, {
+        paid: true,
+        amount: invoice.satoshi,
+        feesPaid: invResp.fees_paid,
+        preimage: invResp.preimage,
+        credentials: { header: "payment-signature", value },
+    });
 };
 const fetchWithX402 = async (url, fetchArgs, options) => {
     const wallet = options.wallet;
@@ -1387,6 +1459,15 @@ const fetchWithX402 = async (url, fetchArgs, options) => {
     fetchArgs.mode = "cors";
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
+    // If the caller supplied a credential, we MUST use it and never pay again —
+    // even if the server still responds with a 402. Re-paying here is the exact
+    // double-charge this API exists to prevent; the caller decides what to do
+    // with a rejected credential (retry after settlement, top up, etc.).
+    if (options.credentials) {
+        applyCredentials(headers, options.credentials);
+        const reusedResp = await fetch(url, fetchArgs);
+        return attachPayment(reusedResp, reusedCredentialPayment(options.credentials));
+    }
     const initResp = await fetch(url, fetchArgs);
     const header = initResp.headers.get("PAYMENT-REQUIRED");
     if (!header) {
@@ -1533,8 +1614,16 @@ const handleMppChargePayment = async (wwwAuthHeader, url, fetchArgs, headers, wa
     const invResp = await wallet.payInvoice({ invoice });
     // Per spec: Authorization: Payment <base64url-token>  (single token, no wrapper)
     const credential = buildMppCredential(challenge, invResp.preimage);
-    headers.set("Authorization", `Payment ${credential}`);
-    return fetch(url, fetchArgs);
+    const value = `Payment ${credential}`;
+    headers.set("Authorization", value);
+    const response = await fetch(url, fetchArgs);
+    return attachPayment(response, {
+        paid: true,
+        amount: getInvoiceAmount(invoice),
+        feesPaid: invResp.fees_paid,
+        preimage: invResp.preimage,
+        credentials: { header: "Authorization", value },
+    });
 };
 /**
  * Fetch a resource protected by the draft-lightning-charge-00 payment
@@ -1545,9 +1634,11 @@ const handleMppChargePayment = async (wwwAuthHeader, url, fetchArgs, headers, wa
  * the function pays the embedded BOLT11 invoice and retries with the
  * resulting preimage as the credential.
  *
- * Note: lightning-charge uses consume-once challenge semantics – each
- * challenge embeds a fresh invoice, so paid credentials cannot be reused.
- * The `store` option is accepted for API consistency but is not used.
+ * Pass a previous credential via `options.credentials` to reuse it (e.g. when
+ * polling); the credential is applied and the function NEVER pays again, even
+ * if the server still responds with a 402 (that response is returned as-is).
+ * Note: lightning-charge typically uses consume-once challenge semantics, so a
+ * reused credential is only accepted by servers that explicitly support it.
  */
 const fetchWithMpp = async (url, fetchArgs, options) => {
     const wallet = options.wallet;
@@ -1561,6 +1652,15 @@ const fetchWithMpp = async (url, fetchArgs, options) => {
     fetchArgs.mode = "cors";
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
+    // If the caller supplied a credential, we MUST use it and never pay again —
+    // even if the server still responds with a 402. Re-paying here is the exact
+    // double-charge this API exists to prevent; the caller decides what to do
+    // with a rejected credential (retry after settlement, top up, etc.).
+    if (options.credentials) {
+        applyCredentials(headers, options.credentials);
+        const reusedResp = await fetch(url, fetchArgs);
+        return attachPayment(reusedResp, reusedCredentialPayment(options.credentials));
+    }
     const initResp = await fetch(url, fetchArgs);
     const wwwAuthHeader = initResp.headers.get("www-authenticate");
     if (!wwwAuthHeader ||
@@ -1581,20 +1681,38 @@ const fetch402 = async (url, fetchArgs, options) => {
     fetchArgs.mode = "cors";
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
+    // If the caller supplied a credential, we MUST use it and never pay again —
+    // even if the server still responds with a 402. Re-paying here is the exact
+    // double-charge this API exists to prevent; the caller decides what to do
+    // with a rejected credential (retry after settlement, top up, etc.).
+    if (options.credentials) {
+        applyCredentials(headers, options.credentials);
+        const reusedResp = await fetch(url, fetchArgs);
+        return attachPayment(reusedResp, reusedCredentialPayment(options.credentials));
+    }
     const initResp = await fetch(url, fetchArgs);
+    // L402 / LSAT: dedicated scheme, dispatch directly.
     const wwwAuthHeader = initResp.headers.get("www-authenticate");
     if (wwwAuthHeader) {
         const trimmed = wwwAuthHeader.trimStart().toLowerCase();
-        if (trimmed.startsWith("payment")) {
-            return handleMppChargePayment(wwwAuthHeader, url, fetchArgs, headers, wallet);
-        }
         if (trimmed.startsWith("l402") || trimmed.startsWith("lsat")) {
             return handleL402Payment(wwwAuthHeader, url, fetchArgs, headers, wallet);
         }
-        throw new Error(`fetch402: unsupported WWW-Authenticate scheme: ${wwwAuthHeader}`);
     }
+    // A server may advertise multiple payment options at once (e.g. an MPP
+    // USDC challenge in WWW-Authenticate alongside an x402 PAYMENT-REQUIRED
+    // header that lists both USDC and lightning). Try each lightning-payable
+    // handler in turn; only if none matches do we hand the original 402 back
+    // to the caller so they can decide what to do with non-lightning offers.
+    // 1. MPP-lightning challenge (Payment method="lightning" intent="charge").
+    //    parseMppChallenge returns null for any other method, which lets us
+    //    fall through to x402 instead of throwing.
+    if (wwwAuthHeader && parseMppChallenge(wwwAuthHeader)) {
+        return handleMppChargePayment(wwwAuthHeader, url, fetchArgs, headers, wallet);
+    }
+    // 2. x402 PAYMENT-REQUIRED with a lightning entry in `accepts`.
     const x402Header = initResp.headers.get("PAYMENT-REQUIRED");
-    if (x402Header) {
+    if (x402Header && findX402LightningRequirements(x402Header)) {
         return handleX402Payment(x402Header, url, fetchArgs, headers, wallet);
     }
     return initResp;
@@ -1679,5 +1797,5 @@ function parseL402Authorization(input) {
     };
 }
 
-export { createGuardedWallet, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, issueL402Macaroon, makeL402AuthenticateHeader, parseL402, parseL402Authorization, verifyL402Macaroon };
+export { applyCredentials, attachPayment, createGuardedWallet, fetch402, fetchWithL402, fetchWithMpp, fetchWithX402, findX402LightningRequirements, getInvoiceAmount, issueL402Macaroon, makeL402AuthenticateHeader, parseL402, parseL402Authorization, reusedCredentialPayment, verifyL402Macaroon };
 //# sourceMappingURL=402.js.map