@getalby/lightning-tools 8.0.0 → 8.1.1

package/dist/cjs/402.cjs

@@ -1176,6 +1176,19 @@ const decodeInvoice = (paymentRequest) => {
         return null;
     }
 };
+function validatePreimage(preimage, paymentHash) {
+    try {
+        if (!/^[0-9a-fA-F]{64}$/.test(preimage))
+            return false;
+        if (!/^[0-9a-fA-F]{64}$/.test(paymentHash))
+            return false;
+        const preimageHash = bytesToHex(sha256(fromHexString(preimage)));
+        return paymentHash === preimageHash;
+    }
+    catch {
+        return false;
+    }
+}
 
 class Invoice {
     constructor(args) {
@@ -1215,13 +1228,7 @@ class Invoice {
     validatePreimage(preimage) {
         if (!preimage || !this.paymentHash)
             return false;
-        try {
-            const preimageHash = bytesToHex(sha256(fromHexString(preimage)));
-            return this.paymentHash === preimageHash;
-        }
-        catch {
-            return false;
-        }
+        return validatePreimage(preimage, this.paymentHash);
     }
     async verifyPayment() {
         try {
@@ -1264,6 +1271,11 @@ function createGuardedWallet(wallet, maxAmountSats) {
     };
 }
 
+/**
+ * Client: parse "www-authenticate" header from server response
+ * @param input
+ * @returns details from the header value (token or macaroon, invoice)
+ */
 const parseL402 = (input) => {
     // Remove the L402 and LSAT identifiers
     const string = input.replace("L402", "").replace("LSAT", "").trim();
@@ -1278,6 +1290,19 @@ const parseL402 = (input) => {
         // Value is either match[3] (double-quoted), match[4] (single-quoted), or match[5] (unquoted)
         keyValuePairs[match[1]] = match[3] || match[4] || match[5];
     }
+    if (!keyValuePairs["token"] && keyValuePairs["macaroon"]) {
+        // fallback to old naming
+        keyValuePairs["token"] = keyValuePairs["macaroon"];
+        delete keyValuePairs["macaroon"];
+    }
+    if (!("token" in keyValuePairs) ||
+        typeof keyValuePairs["token"] !== "string") {
+        throw new Error("No macaroon or token found in www-authenticate header");
+    }
+    if (!("invoice" in keyValuePairs) ||
+        typeof keyValuePairs["invoice"] !== "string") {
+        throw new Error("No invoice found in www-authenticate header");
+    }
     return keyValuePairs;
 };
 
@@ -1327,7 +1352,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))));
@@ -1338,9 +1363,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.");
     }
@@ -1559,27 +1606,121 @@ const fetch402 = async (url, fetchArgs, options) => {
     const headers = new Headers(fetchArgs.headers ?? undefined);
     fetchArgs.headers = headers;
     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;
 };
 
+async function issueL402Macaroon(secret, paymentHash, params) {
+    if (params !== undefined &&
+        Object.prototype.hasOwnProperty.call(params, "paymentHash")) {
+        throw new Error("paymentHash is reserved");
+    }
+    const payload = { ...params, paymentHash };
+    const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+    const mac = await sign(secret, encoded);
+    return `${encoded}.${mac}`;
+}
+async function verifyL402Macaroon(secret, token) {
+    const { timingSafeEqual } = await import('crypto');
+    const dotIndex = token.lastIndexOf(".");
+    if (dotIndex === -1)
+        throw new Error("Invalid macaroon token");
+    const encoded = token.slice(0, dotIndex);
+    const mac = token.slice(dotIndex + 1);
+    // Constant-time comparison to prevent timing attacks
+    const expectedMac = await sign(secret, encoded);
+    try {
+        if (!timingSafeEqual(Buffer.from(mac, "hex"), Buffer.from(expectedMac, "hex"))) {
+            throw new Error("Invalid macaroon token");
+        }
+    }
+    catch (e) {
+        throw new Error("Invalid macaroon token");
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            Array.isArray(parsed) ||
+            typeof parsed.paymentHash !== "string") {
+            throw new Error("Invalid macaroon payload");
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error("Invalid macaroon token");
+    }
+}
+async function sign(secret, payload) {
+    const { createHmac } = await import('crypto');
+    return createHmac("sha256", secret).update(payload).digest("hex");
+}
+
+/**
+ * Server: create a WWW-Authenticate header for a given macaroon and invoice
+ * @param args the macaroon/token and invoice generated for the client's request
+ * @returns the header value
+ */
+const makeL402AuthenticateHeader = (args) => {
+    if (!args.token) {
+        throw new Error("token must be provided");
+    }
+    return `L402 version="0" token="${args.token}", invoice="${args.invoice}"`;
+};
+/**
+ * Server: parse "authorization" header sent from client
+ * @param input value from authorization header
+ * @returns the macaroon and preimage
+ */
+function parseL402Authorization(input) {
+    // Backwards compat: LSAT was the former name of L402
+    const normalized = input.replace(/^LSAT /, "L402 ");
+    const prefix = "L402 ";
+    if (!normalized.startsWith(prefix))
+        return null;
+    const credentials = normalized.slice(prefix.length);
+    const colonIndex = credentials.indexOf(":");
+    if (colonIndex === -1) {
+        throw new Error("Invalid authorization header value");
+    }
+    return {
+        token: credentials.slice(0, colonIndex),
+        preimage: credentials.slice(colonIndex + 1),
+    };
+}
+
 exports.createGuardedWallet = createGuardedWallet;
 exports.fetch402 = fetch402;
 exports.fetchWithL402 = fetchWithL402;
 exports.fetchWithMpp = fetchWithMpp;
 exports.fetchWithX402 = fetchWithX402;
+exports.findX402LightningRequirements = findX402LightningRequirements;
+exports.issueL402Macaroon = issueL402Macaroon;
+exports.makeL402AuthenticateHeader = makeL402AuthenticateHeader;
+exports.parseL402 = parseL402;
+exports.parseL402Authorization = parseL402Authorization;
+exports.verifyL402Macaroon = verifyL402Macaroon;
 //# sourceMappingURL=402.cjs.map