@getalby/lightning-tools 7.0.2 → 8.0.0

package/dist/cjs/index.cjs

@@ -834,8 +834,12 @@ const decodeInvoice = (paymentRequest) => {
             return null;
         const paymentHash = hashTag.value;
         let satoshi = 0;
+        let millisatoshi = 0;
+        let amountRaw = "0";
         const amountTag = decoded.sections.find((value) => value.name === "amount");
         if (amountTag?.name === "amount" && amountTag.value) {
+            amountRaw = amountTag.value;
+            millisatoshi = parseInt(amountTag.value);
             satoshi = parseInt(amountTag.value) / 1000; // millisats
         }
         const timestampTag = decoded.sections.find((value) => value.name === "timestamp");
@@ -854,6 +858,8 @@ const decodeInvoice = (paymentRequest) => {
         return {
             paymentHash,
             satoshi,
+            millisatoshi,
+            amountRaw,
             timestamp,
             expiry,
             description,
@@ -1183,6 +1189,8 @@ class Invoice {
         }
         this.paymentHash = decodedInvoice.paymentHash;
         this.satoshi = decodedInvoice.satoshi;
+        this.millisatoshi = decodedInvoice.millisatoshi;
+        this.amountRaw = decodedInvoice.amountRaw;
         this.timestamp = decodedInvoice.timestamp;
         this.expiry = decodedInvoice.expiry;
         this.createdDate = new Date(this.timestamp * 1000);
@@ -1659,24 +1667,18 @@ class LightningAddress {
     }
 }
 
-class MemoryStorage {
-    constructor(initial) {
-        this.storage = initial || {};
-    }
-    getItem(key) {
-        return this.storage[key];
-    }
-    setItem(key, value) {
-        this.storage[key] = value;
-    }
-}
-class NoStorage {
-    constructor(initial) { }
-    getItem(key) {
-        return null;
-    }
-    setItem(key, value) { }
+function createGuardedWallet(wallet, maxAmountSats) {
+    return {
+        payInvoice: async (args) => {
+            const invoice = new Invoice({ pr: args.invoice });
+            if (invoice.satoshi > maxAmountSats) {
+                throw new Error(`Invoice amount (${invoice.satoshi} sats) exceeds maxAmount (${maxAmountSats} sats)`);
+            }
+            return wallet.payInvoice(args);
+        },
+    };
 }
+
 const parseL402 = (input) => {
     // Remove the L402 and LSAT identifiers
     const string = input.replace("L402", "").replace("LSAT", "").trim();
@@ -1693,55 +1695,301 @@ const parseL402 = (input) => {
     }
     return keyValuePairs;
 };
-const makeAuthenticateHeader = (args) => {
-    const key = args.key || "L402";
-    return `${key} macaroon="${args.macaroon}", invoice="${args.invoice}"`;
-};
 
-const memoryStorage = new MemoryStorage();
-const HEADER_KEY = "L402";
-const fetchWithL402 = async (url, fetchArgs, options) => {
-    if (!options) {
-        options = {};
+const handleL402Payment = async (l402Header, url, fetchArgs, headers, wallet) => {
+    const details = parseL402(l402Header);
+    const token = details.token || details.macaroon;
+    const invoice = details.invoice;
+    if (!token) {
+        throw new Error("L402: missing token/macaroon in WWW-Authenticate header");
+    }
+    if (!invoice) {
+        throw new Error("L402: missing invoice in WWW-Authenticate header");
     }
-    const headerKey = options.headerKey || HEADER_KEY;
+    const invResp = await wallet.payInvoice({ invoice });
+    headers.set("Authorization", `L402 ${token}:${invResp.preimage}`);
+    return fetch(url, fetchArgs);
+};
+const fetchWithL402 = async (url, fetchArgs, options) => {
     const wallet = options.wallet;
     if (!wallet) {
         throw new Error("wallet is missing");
     }
-    const store = options.store || memoryStorage;
     if (!fetchArgs) {
         fetchArgs = {};
     }
     fetchArgs.cache = "no-store";
     fetchArgs.mode = "cors";
-    if (!fetchArgs.headers) {
-        fetchArgs.headers = {};
+    const headers = new Headers(fetchArgs.headers ?? undefined);
+    fetchArgs.headers = headers;
+    const initResp = await fetch(url, fetchArgs);
+    const header = initResp.headers.get("www-authenticate");
+    if (!header) {
+        return initResp;
+    }
+    return handleL402Payment(header, url, fetchArgs, headers, wallet);
+};
+
+const buildX402PaymentSignature = (scheme, network, invoice, requirements) => {
+    const json = JSON.stringify({
+        x402Version: 2,
+        scheme,
+        network,
+        payload: { invoice },
+        accepted: requirements,
+    });
+    // btoa only handles latin1; encode via UTF-8 to be safe
+    return btoa(unescape(encodeURIComponent(json)));
+};
+
+const handleX402Payment = async (x402Header, url, fetchArgs, headers, wallet) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(decodeURIComponent(escape(atob(x402Header))));
     }
-    const cachedL402Data = store.getItem(url);
-    if (cachedL402Data) {
-        const data = JSON.parse(cachedL402Data);
-        fetchArgs.headers["Authorization"] =
-            `${headerKey} ${data.token}:${data.preimage}`;
-        return await fetch(url, fetchArgs);
+    catch (_) {
+        throw new Error("x402: invalid PAYMENT-REQUIRED header (not valid base64-encoded JSON)");
+    }
+    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";
+    });
+    if (!requirements) {
+        throw new Error("x402: unsupported x402 network, only Bitcoin lightning network is supported.");
+    }
+    if (!requirements.extra?.invoice) {
+        throw new Error("x402: payment requirements missing lightning invoice");
+    }
+    const invoice = new Invoice({ pr: requirements.extra.invoice });
+    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 fetchWithX402 = async (url, fetchArgs, options) => {
+    const wallet = options.wallet;
+    if (!fetchArgs) {
+        fetchArgs = {};
     }
-    fetchArgs.headers["Accept-Authenticate"] = headerKey;
+    fetchArgs.cache = "no-store";
+    fetchArgs.mode = "cors";
+    const headers = new Headers(fetchArgs.headers ?? undefined);
+    fetchArgs.headers = headers;
     const initResp = await fetch(url, fetchArgs);
-    const header = initResp.headers.get("www-authenticate");
+    const header = initResp.headers.get("PAYMENT-REQUIRED");
     if (!header) {
         return initResp;
     }
-    const details = parseL402(header);
-    const token = details.token || details.macaroon;
-    const inv = details.invoice;
-    const invResp = await wallet.sendPayment(inv);
-    store.setItem(url, JSON.stringify({
-        token: token,
-        preimage: invResp.preimage,
-    }));
-    fetchArgs.headers["Authorization"] =
-        `${headerKey} ${token}:${invResp.preimage}`;
-    return await fetch(url, fetchArgs);
+    return handleX402Payment(header, url, fetchArgs, headers, wallet);
+};
+
+/**
+ * Parse a `WWW-Authenticate: Payment …` header produced by a
+ * draft-lightning-charge-00 server. Expected format:
+ *
+ *   Payment id="<id>", realm="<realm>", method="lightning",
+ *           intent="charge", request="<base64url>" [, expires="<rfc3339>"]
+ *
+ * Returns null when the header is not a Payment lightning/charge challenge.
+ */
+const parseMppChallenge = (header) => {
+    if (!header.trimStart().toLowerCase().startsWith("payment")) {
+        return null;
+    }
+    const rest = header
+        .slice(header.toLowerCase().indexOf("payment") + "payment".length)
+        .trim();
+    const result = {};
+    const regex = /(\w+)=("([^"]*)"|'([^']*)'|([^,\s]*))/g;
+    let match;
+    while ((match = regex.exec(rest)) !== null) {
+        result[match[1]] = match[3] ?? match[4] ?? match[5] ?? "";
+    }
+    if (result.method !== "lightning" ||
+        result.intent !== "charge" ||
+        !result.id ||
+        !result.realm ||
+        !result.request) {
+        return null;
+    }
+    return {
+        id: result.id,
+        realm: result.realm,
+        method: result.method,
+        intent: result.intent,
+        request: result.request,
+        ...(result.expires ? { expires: result.expires } : {}),
+    };
+};
+/** Decode a base64url string (no padding required) to a UTF-8 string. */
+const decodeBase64url = (input) => {
+    const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return new TextDecoder("utf-8").decode(bytes);
+};
+/** Encode a UTF-8 string to base64url without padding. */
+const encodeBase64url = (input) => {
+    const bytes = new TextEncoder().encode(input);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+};
+/**
+ * JSON Canonicalization Scheme (RFC 8785).
+ * Produces compact JSON with object keys sorted lexicographically.
+ */
+const jcs = (value) => {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map(jcs).join(",") + "]";
+    }
+    const keys = Object.keys(value).sort();
+    return ("{" +
+        keys
+            .map((k) => JSON.stringify(k) + ":" + jcs(value[k]))
+            .join(",") +
+        "}");
+};
+/**
+ * Build the base64url-encoded credential token for the `Authorization` header.
+ *
+ * Per the spec the credential is a JCS-serialised JSON object that echoes all
+ * challenge auth-params (id, realm, method, intent, request, expires) and
+ * carries the HTLC preimage that proves payment:
+ *
+ *   {
+ *     "challenge": { "id": "…", "intent": "charge",
+ *                    "method": "lightning", "realm": "…", "request": "…" },
+ *     "payload":   { "preimage": "<64-char lowercase hex>" }
+ *   }
+ *
+ * Keys are sorted lexicographically at every level per JCS.
+ */
+const buildMppCredential = (challenge, preimage, source) => {
+    const challengeEcho = {
+        id: challenge.id,
+        intent: challenge.intent,
+        method: challenge.method,
+        realm: challenge.realm,
+        request: challenge.request,
+    };
+    if (challenge.expires) {
+        challengeEcho.expires = challenge.expires;
+    }
+    const credential = {
+        challenge: challengeEcho,
+        payload: { preimage },
+    };
+    return encodeBase64url(jcs(credential));
+};
+
+/**
+ * Handle a `WWW-Authenticate: Payment …` challenge produced by a
+ * draft-lightning-charge-00 server.
+ *
+ * Flow:
+ *  1. Parse the challenge from the header.
+ *  2. Decode the `request` auth-param to find the BOLT11 invoice.
+ *  3. Pay the invoice via the wallet; receive the HTLC preimage.
+ *  4. Build the `Authorization: Payment <credential>` header.
+ *  5. Retry the original request with the credential.
+ */
+const handleMppChargePayment = async (wwwAuthHeader, url, fetchArgs, headers, wallet) => {
+    const challenge = parseMppChallenge(wwwAuthHeader);
+    if (!challenge) {
+        throw new Error("mpp: invalid or unsupported WWW-Authenticate challenge (expected Payment method=lightning intent=charge)");
+    }
+    let request;
+    try {
+        request = JSON.parse(decodeBase64url(challenge.request));
+    }
+    catch (_) {
+        throw new Error("mpp: invalid request auth-param (not valid base64url-encoded JSON)");
+    }
+    const invoice = request.methodDetails?.invoice;
+    if (!invoice) {
+        throw new Error("mpp: missing invoice in charge request");
+    }
+    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);
+};
+/**
+ * Fetch a resource protected by the draft-lightning-charge-00 payment
+ * authentication protocol.
+ *
+ * On a `402 Payment Required` response that carries a
+ * `WWW-Authenticate: Payment method="lightning" intent="charge" …` header
+ * 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.
+ */
+const fetchWithMpp = async (url, fetchArgs, options) => {
+    const wallet = options.wallet;
+    if (!wallet) {
+        throw new Error("wallet is missing");
+    }
+    if (!fetchArgs) {
+        fetchArgs = {};
+    }
+    fetchArgs.cache = "no-store";
+    fetchArgs.mode = "cors";
+    const headers = new Headers(fetchArgs.headers ?? undefined);
+    fetchArgs.headers = headers;
+    const initResp = await fetch(url, fetchArgs);
+    const wwwAuthHeader = initResp.headers.get("www-authenticate");
+    if (!wwwAuthHeader ||
+        !wwwAuthHeader.trimStart().toLowerCase().startsWith("payment")) {
+        return initResp;
+    }
+    return handleMppChargePayment(wwwAuthHeader, url, fetchArgs, headers, wallet);
+};
+
+const fetch402 = async (url, fetchArgs, options) => {
+    const wallet = options.maxAmount
+        ? createGuardedWallet(options.wallet, options.maxAmount)
+        : options.wallet;
+    if (!fetchArgs) {
+        fetchArgs = {};
+    }
+    fetchArgs.cache = "no-store";
+    fetchArgs.mode = "cors";
+    const headers = new Headers(fetchArgs.headers ?? undefined);
+    fetchArgs.headers = headers;
+    const initResp = await fetch(url, fetchArgs);
+    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}`);
+    }
+    const x402Header = initResp.headers.get("PAYMENT-REQUIRED");
+    if (x402Header) {
+        return handleX402Payment(x402Header, url, fetchArgs, headers, wallet);
+    }
+    return initResp;
 };
 
 const numSatsInBtc = 100000000;
@@ -1797,10 +2045,12 @@ exports.DEFAULT_PROXY = DEFAULT_PROXY;
 exports.Invoice = Invoice;
 exports.LN_ADDRESS_REGEX = LN_ADDRESS_REGEX;
 exports.LightningAddress = LightningAddress;
-exports.MemoryStorage = MemoryStorage;
-exports.NoStorage = NoStorage;
+exports.createGuardedWallet = createGuardedWallet;
 exports.decodeInvoice = decodeInvoice;
+exports.fetch402 = fetch402;
 exports.fetchWithL402 = fetchWithL402;
+exports.fetchWithMpp = fetchWithMpp;
+exports.fetchWithX402 = fetchWithX402;
 exports.fromHexString = fromHexString;
 exports.generateZapEvent = generateZapEvent;
 exports.getEventHash = getEventHash;
@@ -1811,9 +2061,7 @@ exports.getFormattedFiatValue = getFormattedFiatValue;
 exports.getSatoshiValue = getSatoshiValue;
 exports.isUrl = isUrl;
 exports.isValidAmount = isValidAmount;
-exports.makeAuthenticateHeader = makeAuthenticateHeader;
 exports.parseKeysendResponse = parseKeysendResponse;
-exports.parseL402 = parseL402;
 exports.parseLnUrlPayResponse = parseLnUrlPayResponse;
 exports.parseNostrResponse = parseNostrResponse;
 exports.sendBoostagram = sendBoostagram;