@getalby/lightning-tools 7.0.2 → 8.0.0

package/README.md

@@ -10,7 +10,7 @@ Before you start coding, look at example scenarios in our **[Developer Sandbox](
 
 ## 🤖 🚀 ⚡ For Developers using Agents / LLMs / Vibe Coding
 
-Skip the rest of this README and use the [Alby Bitcoin Payments Agent Skill](https://github.com/getAlby/alby-agent-skill) instead. It will handle the rest!
+Skip the rest of this README and use the [Alby Bitcoin Builder Skill](https://github.com/getAlby/builder-skill) instead. It will handle the rest!
 
 ## Manual Installation
 
@@ -28,7 +28,7 @@ or for use without any build tools:
 
 ```html
 <script type="module">
-  import { LightningAddress } from "https://esm.sh/@getalby/lightning-tools@5.0.0"; // jsdelivr.net, skypack.dev also work
+  import { LightningAddress } from "https://esm.sh/@getalby/lightning-tools@7"; // jsdelivr.net, skypack.dev also work
 
   // use LightningAddress normally...
   (async () => {
@@ -168,7 +168,45 @@ Native zaps without a browser extension are possible by using a Nostr Wallet Con
 
 See [examples/zaps-nwc](examples/zaps-nwc.js)
 
-### L402
+> All examples in the [examples/](examples/) directory are runnable. See [examples/README.md](examples/README.md) for setup instructions.
+
+### HTTP 402 - requesting HTTP resources that require a payment
+
+L402, X402, MPP are protocol standards based on the HTTP 402 `Payment Required` code
+for machine-to-machine payments. It is used to charge for HTTP API requests, tool calls, or agentic payments.
+
+This library includes functions to consome those resources.
+
+#### fetch402(url: string, fetchArgs, options)
+
+`fetch402` is a single function that transparently handles L402 and X402 and MPP protected resources. Use it when you don't know or don't care which protocol the server uses — it will detect the protocol from the response headers and pay accordingly.
+
+- url: the protected URL
+- fetchArgs: arguments are passed to the underlying `fetch()` function used to do the HTTP request
+- options:
+  - wallet: any object that implements `payInvoice({ invoice })` and returns `{ preimage }`. Used to pay L402, X402 and MPP invoices.
+
+##### Examples
+
+```js
+import { fetch402 } from "@getalby/lightning-tools/402";
+import { NWCClient } from "@getalby/sdk";
+
+const nwc = new NWCClient({
+  nostrWalletConnectUrl: "nostr+walletconnect://...",
+});
+
+await fetch402(
+  "https://example.com/protected-resource",
+  {},
+  { wallet: nwc },
+)
+  .then((res) => res.json())
+  .then(console.log)
+  .finally(() => nwc.close());
+```
+
+#### L402
 
 L402 is a protocol standard based on the HTTP 402 Payment Required error code
 designed to support the use case of charging for services and
@@ -176,59 +214,101 @@ authenticating users in distributed networks.
 
 This library includes a `fetchWithL402` function to consume L402 protected resources.
 
-#### fetchWithL402(url: string, fetchArgs, options)
+##### fetchWithL402(url: string, fetchArgs, options)
 
 - url: the L402 protected URL
 - fetchArgs: arguments are passed to the underlying `fetch()` function used to do the HTTP request
 - options:
-  - wallet: any object that implements `sendPayment(paymentRequest)` and returns `{ preimage }`. Used to pay the L402 invoice.
-  - store: a key/value store object to persiste the l402 for each URL. The store must implement a `getItem()`/`setItem()` function as the browser's localStorage. By default a memory storage is used.
-  - headerKey: defaults to L402 but if you need to consume an old LSAT API set this to LSAT
+  - wallet: any object (e.g. a NWC client) that implements `payInvoice({ invoice })` and returns `{ preimage }`. Used to pay the L402 invoice.
 
 ##### Examples
 
 ```js
-import { fetchWithL402 } from "@getalby/lightning-tools/l402";
+import { fetchWithL402 } from "@getalby/lightning-tools/402/l402";
+import { NWCClient } from "@getalby/sdk";
+
+const nwc = new NWCClient({
+  nostrWalletConnectUrl: "nostr+walletconnect://...",
+});
 
-// pass a wallet that implements sendPayment()
-// the tokens/preimage data will be stored in the browser's localStorage and used for any following request
 await fetchWithL402(
-  "https://lsat-weather-api.getalby.repl.co/kigali",
+  "https://l402.example.com/protected-resource",
   {},
-  { wallet: myWallet, store: window.localStorage },
+  { wallet: nwc },
 )
   .then((res) => res.json())
-  .then(console.log);
+  .then(console.log)
+  .finally(() => nwc.close());
 ```
 
+#### X402
+
+Similar to L402 X402 is an open protocol for machine-to-machine payments built on the HTTP 402 Payment Required status code.
+It enables APIs and resources to request payments inline, without prior registration or authentication. 
+
+This library includes a `fetchWithX402` function to consume X402-protected resources that support the lightning network. 
+(Note: X402 works also with other coins and network. This library supports X402 resources that accept Bitcoin on the lightning network)
+
+##### fetchWithX402(url: string, fetchArgs, options)
+
+- url: the X402 protected URL
+- fetchArgs: arguments are passed to the underlying `fetch()` function used to do the HTTP request
+- options:
+  - wallet: any object (e.g. a NWC client) that implements `payInvoice({ invoice })` and returns `{ preimage }`. Used to pay the X402 invoice.
+
+##### Examples
+
 ```js
-import { fetchWithL402 } from "@getalby/lightning-tools/l402";
-import { NostrWebLNProvider } from "@getalby/sdk";
+import { fetchWithX402 } from "@getalby/lightning-tools/402/x402";
+import { NWCClient } from "@getalby/sdk";
 
-// use a NWC provider as the wallet to do the payments
-const nwc = new NostrWebLNProvider({
-  nostrWalletConnectUrl: loadNWCUrl(),
+const nwc = new NWCClient({
+  nostrWalletConnectUrl: "nostr+walletconnect://...",
 });
 
-// this will fetch the resource and pay the invoice using the NWC wallet
-await fetchWithL402(
-  "https://lsat-weather-api.getalby.repl.co/kigali",
+await fetchWithX402(
+  "https://x402.example.com/protected-resource",
   {},
   { wallet: nwc },
 )
   .then((res) => res.json())
-  .then(console.log);
+  .then(console.log)
+  .finally(() => nwc.close());
 ```
 
+#### MPP
+
+MPP is an open protocol for machine-to-machine payments built on the HTTP 402 Payment Required status code.
+Charge for API requests, tool calls, or content—agents and apps pay per request in the same HTTP call.
+
+This library includes a `fetchWithMpp` function to consume MPP-protected resources that support the lightning network. 
+(Note: MPP works also with other payment methods. This library supports resources that accept Bitcoin on the lightning network)
+
+##### fetchWithMpp(url: string, fetchArgs, options)
+
+- url: the MPP protected URL
+- fetchArgs: arguments are passed to the underlying `fetch()` function used to do the HTTP request
+- options:
+  - wallet: any object (e.g. a NWC client) that implements `payInvoice({ invoice })` and returns `{ preimage }`. Used to pay the X402 invoice.
+
+##### Examples
+
 ```js
-import { fetchWithL402, NoStorage } from "@getalby/lightning-tools/l402";
+import { fetchWithMpp } from "@getalby/lightning-tools/402/mpp";
+import { NWCClient } from "@getalby/sdk";
 
-// do not store the tokens
-await fetchWithL402(
-  "https://lsat-weather-api.getalby.repl.co/kigali",
+const nwc = new NWCClient({
+  nostrWalletConnectUrl: "nostr+walletconnect://...",
+});
+
+await fetchWithMpp(
+  "https://mpp.example.com/protected-resource",
   {},
-  { store: new NoStorage() },
-);
+  { wallet: nwc },
+)
+  .then((res) => res.json())
+  .then(console.log)
+  .finally(() => nwc.close());
 ```
 
 ### Basic invoice decoding

package/dist/cjs/402/l402.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+const parseL402 = (input) => {
+    // Remove the L402 and LSAT identifiers
+    const string = input.replace("L402", "").replace("LSAT", "").trim();
+    // Initialize an object to store the key-value pairs
+    const keyValuePairs = {};
+    // Regular expression to match key and (quoted or unquoted) value
+    const regex = /(\w+)=("([^"]*)"|'([^']*)'|([^,]*))/g;
+    let match;
+    // Use regex to find all key-value pairs
+    while ((match = regex.exec(string)) !== null) {
+        // Key is always match[1]
+        // Value is either match[3] (double-quoted), match[4] (single-quoted), or match[5] (unquoted)
+        keyValuePairs[match[1]] = match[3] || match[4] || match[5];
+    }
+    return keyValuePairs;
+};
+
+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 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");
+    }
+    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 header = initResp.headers.get("www-authenticate");
+    if (!header) {
+        return initResp;
+    }
+    return handleL402Payment(header, url, fetchArgs, headers, wallet);
+};
+
+exports.fetchWithL402 = fetchWithL402;
+//# sourceMappingURL=l402.cjs.map

package/dist/cjs/402/l402.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"l402.cjs","sources":["../../../src/402/l402/utils.ts","../../../src/402/l402/l402.ts"],"sourcesContent":["export const parseL402 = (input: string): Record<string, string> => {\n  // Remove the L402 and LSAT identifiers\n  const string = input.replace(\"L402\", \"\").replace(\"LSAT\", \"\").trim();\n\n  // Initialize an object to store the key-value pairs\n  const keyValuePairs = {};\n\n  // Regular expression to match key and (quoted or unquoted) value\n  const regex = /(\\w+)=(\"([^\"]*)\"|'([^']*)'|([^,]*))/g;\n  let match;\n\n  // Use regex to find all key-value pairs\n  while ((match = regex.exec(string)) !== null) {\n    // Key is always match[1]\n    // Value is either match[3] (double-quoted), match[4] (single-quoted), or match[5] (unquoted)\n    keyValuePairs[match[1]] = match[3] || match[4] || match[5];\n  }\n\n  return keyValuePairs;\n};\n\nexport const makeL402AuthenticateHeader = (args: {\n  macaroon?: string;\n  token?: string;\n  invoice: string;\n}) => {\n  if (args.macaroon) {\n    return `L402 version=\"0\" macaroon=\"${args.macaroon}\", invoice=\"${args.invoice}\"`;\n  } else {\n    return `L402 version=\"0\" token=\"${args.token}\", invoice=\"${args.invoice}\"`;\n  }\n};\n","import { Wallet } from \"../utils\";\nimport { parseL402 } from \"./utils\";\n\nexport const handleL402Payment = async (\n  l402Header: string,\n  url: string,\n  fetchArgs: RequestInit,\n  headers: Headers,\n  wallet: Wallet,\n): Promise<Response> => {\n  const details = parseL402(l402Header);\n  const token = details.token || details.macaroon;\n  const invoice = details.invoice;\n\n  if (!token) {\n    throw new Error(\"L402: missing token/macaroon in WWW-Authenticate header\");\n  }\n  if (!invoice) {\n    throw new Error(\"L402: missing invoice in WWW-Authenticate header\");\n  }\n\n  const invResp = await wallet.payInvoice({ invoice });\n  headers.set(\"Authorization\", `L402 ${token}:${invResp.preimage}`);\n  return fetch(url, fetchArgs);\n};\n\nexport const fetchWithL402 = async (\n  url: string,\n  fetchArgs: RequestInit,\n  options: {\n    wallet: Wallet;\n  },\n) => {\n  const wallet = options.wallet;\n  if (!wallet) {\n    throw new Error(\"wallet is missing\");\n  }\n  if (!fetchArgs) {\n    fetchArgs = {};\n  }\n  fetchArgs.cache = \"no-store\";\n  fetchArgs.mode = \"cors\";\n  const headers = new Headers(fetchArgs.headers ?? undefined);\n  fetchArgs.headers = headers;\n\n  const initResp = await fetch(url, fetchArgs);\n  const header = initResp.headers.get(\"www-authenticate\");\n  if (!header) {\n    return initResp;\n  }\n\n  return handleL402Payment(header, url, fetchArgs, headers, wallet);\n};\n"],"names":[],"mappings":";;AAAO,MAAM,SAAS,GAAG,CAAC,KAAa,KAA4B;;IAEjE,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE;;IAGnE,MAAM,aAAa,GAAG,EAAE;;IAGxB,MAAM,KAAK,GAAG,sCAAsC;AACpD,IAAA,IAAI,KAAK;;AAGT,IAAA,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE;;;QAG5C,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC;IAC5D;AAEA,IAAA,OAAO,aAAa;AACtB,CAAC;;AChBM,MAAM,iBAAiB,GAAG,OAC/B,UAAkB,EAClB,GAAW,EACX,SAAsB,EACtB,OAAgB,EAChB,MAAc,KACO;AACrB,IAAA,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,CAAC;IACrC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,QAAQ;AAC/C,IAAA,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO;IAE/B,IAAI,CAAC,KAAK,EAAE;AACV,QAAA,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC;IAC5E;IACA,IAAI,CAAC,OAAO,EAAE;AACZ,QAAA,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC;IACrE;IAEA,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;AACpD,IAAA,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAA,KAAA,EAAQ,KAAK,CAAA,CAAA,EAAI,OAAO,CAAC,QAAQ,CAAA,CAAE,CAAC;AACjE,IAAA,OAAO,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC;AAC9B,CAAC;AAEM,MAAM,aAAa,GAAG,OAC3B,GAAW,EACX,SAAsB,EACtB,OAEC,KACC;AACF,IAAA,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM;IAC7B,IAAI,CAAC,MAAM,EAAE;AACX,QAAA,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC;IACtC;IACA,IAAI,CAAC,SAAS,EAAE;QACd,SAAS,GAAG,EAAE;IAChB;AACA,IAAA,SAAS,CAAC,KAAK,GAAG,UAAU;AAC5B,IAAA,SAAS,CAAC,IAAI,GAAG,MAAM;IACvB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,SAAS,CAAC,OAAO,IAAI,SAAS,CAAC;AAC3D,IAAA,SAAS,CAAC,OAAO,GAAG,OAAO;IAE3B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC;IAC5C,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IACvD,IAAI,CAAC,MAAM,EAAE;AACX,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,OAAO,iBAAiB,CAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC;AACnE;;;;"}

package/dist/cjs/402/mpp.cjs

@@ -0,0 +1,179 @@
+'use strict';
+
+/**
+ * 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);
+};
+
+exports.fetchWithMpp = fetchWithMpp;
+//# sourceMappingURL=mpp.cjs.map

package/dist/cjs/402/mpp.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mpp.cjs","sources":["../../../src/402/mpp/utils.ts","../../../src/402/mpp/mpp.ts"],"sourcesContent":["export interface MppChallenge {\n  id: string;\n  realm: string;\n  method: string;\n  intent: string;\n  request: string;\n  expires?: string;\n}\n\nexport interface MppChargeRequest {\n  amount: string;\n  currency: string;\n  description?: string;\n  recipient?: string;\n  externalId?: string;\n  methodDetails: {\n    invoice: string;\n    paymentHash?: string;\n    network?: string;\n  };\n}\n\n/**\n * Parse a `WWW-Authenticate: Payment …` header produced by a\n * draft-lightning-charge-00 server. Expected format:\n *\n *   Payment id=\"<id>\", realm=\"<realm>\", method=\"lightning\",\n *           intent=\"charge\", request=\"<base64url>\" [, expires=\"<rfc3339>\"]\n *\n * Returns null when the header is not a Payment lightning/charge challenge.\n */\nexport const parseMppChallenge = (header: string): MppChallenge | null => {\n  if (!header.trimStart().toLowerCase().startsWith(\"payment\")) {\n    return null;\n  }\n  const rest = header\n    .slice(header.toLowerCase().indexOf(\"payment\") + \"payment\".length)\n    .trim();\n  const result: Record<string, string> = {};\n  const regex = /(\\w+)=(\"([^\"]*)\"|'([^']*)'|([^,\\s]*))/g;\n  let match;\n  while ((match = regex.exec(rest)) !== null) {\n    result[match[1]] = match[3] ?? match[4] ?? match[5] ?? \"\";\n  }\n\n  if (\n    result.method !== \"lightning\" ||\n    result.intent !== \"charge\" ||\n    !result.id ||\n    !result.realm ||\n    !result.request\n  ) {\n    return null;\n  }\n\n  return {\n    id: result.id,\n    realm: result.realm,\n    method: result.method,\n    intent: result.intent,\n    request: result.request,\n    ...(result.expires ? { expires: result.expires } : {}),\n  };\n};\n\n/** Decode a base64url string (no padding required) to a UTF-8 string. */\nexport const decodeBase64url = (input: string): string => {\n  const base64 = input.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const binary = atob(base64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i);\n  }\n  return new TextDecoder(\"utf-8\").decode(bytes);\n};\n\n/** Encode a UTF-8 string to base64url without padding. */\nconst encodeBase64url = (input: string): string => {\n  const bytes = new TextEncoder().encode(input);\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=/g, \"\");\n};\n\n/**\n * JSON Canonicalization Scheme (RFC 8785).\n * Produces compact JSON with object keys sorted lexicographically.\n */\nconst jcs = (value: unknown): string => {\n  if (value === null || typeof value !== \"object\") {\n    return JSON.stringify(value);\n  }\n  if (Array.isArray(value)) {\n    return \"[\" + (value as unknown[]).map(jcs).join(\",\") + \"]\";\n  }\n  const keys = Object.keys(value as object).sort();\n  return (\n    \"{\" +\n    keys\n      .map(\n        (k) =>\n          JSON.stringify(k) + \":\" + jcs((value as Record<string, unknown>)[k]),\n      )\n      .join(\",\") +\n    \"}\"\n  );\n};\n\n/**\n * Build the base64url-encoded credential token for the `Authorization` header.\n *\n * Per the spec the credential is a JCS-serialised JSON object that echoes all\n * challenge auth-params (id, realm, method, intent, request, expires) and\n * carries the HTLC preimage that proves payment:\n *\n *   {\n *     \"challenge\": { \"id\": \"…\", \"intent\": \"charge\",\n *                    \"method\": \"lightning\", \"realm\": \"…\", \"request\": \"…\" },\n *     \"payload\":   { \"preimage\": \"<64-char lowercase hex>\" }\n *   }\n *\n * Keys are sorted lexicographically at every level per JCS.\n */\nexport const buildMppCredential = (\n  challenge: MppChallenge,\n  preimage: string,\n  source?: string,\n): string => {\n  const challengeEcho: Record<string, string> = {\n    id: challenge.id,\n    intent: challenge.intent,\n    method: challenge.method,\n    realm: challenge.realm,\n    request: challenge.request,\n  };\n  if (challenge.expires) {\n    challengeEcho.expires = challenge.expires;\n  }\n\n  const credential: Record<string, unknown> = {\n    challenge: challengeEcho,\n    payload: { preimage },\n  };\n  if (source) {\n    credential.source = source;\n  }\n\n  return encodeBase64url(jcs(credential));\n};\n\n/**\n * Construct a `WWW-Authenticate` header for testing / server implementations.\n *\n * The auth scheme is `Payment` per [I-D.httpauth-payment].\n */\nexport const makeMppWwwAuthenticateHeader = (args: {\n  id: string;\n  realm: string;\n  request: string;\n  expires?: string;\n}): string => {\n  let header =\n    `Payment id=\"${args.id}\", realm=\"${args.realm}\", method=\"lightning\",` +\n    ` intent=\"charge\", request=\"${args.request}\"`;\n  if (args.expires) {\n    header += `, expires=\"${args.expires}\"`;\n  }\n  return header;\n};\n\n/** Encode an MppChargeRequest as a base64url string suitable for the `request` auth-param. */\nexport const encodeMppChargeRequest = (request: MppChargeRequest): string =>\n  encodeBase64url(jcs(request));\n","import { Wallet } from \"../utils\";\nimport {\n  buildMppCredential,\n  decodeBase64url,\n  MppChargeRequest,\n  parseMppChallenge,\n} from \"./utils\";\n\n/**\n * Handle a `WWW-Authenticate: Payment …` challenge produced by a\n * draft-lightning-charge-00 server.\n *\n * Flow:\n *  1. Parse the challenge from the header.\n *  2. Decode the `request` auth-param to find the BOLT11 invoice.\n *  3. Pay the invoice via the wallet; receive the HTLC preimage.\n *  4. Build the `Authorization: Payment <credential>` header.\n *  5. Retry the original request with the credential.\n */\nexport const handleMppChargePayment = async (\n  wwwAuthHeader: string,\n  url: string,\n  fetchArgs: RequestInit,\n  headers: Headers,\n  wallet: Wallet,\n): Promise<Response> => {\n  const challenge = parseMppChallenge(wwwAuthHeader);\n  if (!challenge) {\n    throw new Error(\n      \"mpp: invalid or unsupported WWW-Authenticate challenge (expected Payment method=lightning intent=charge)\",\n    );\n  }\n\n  let request: MppChargeRequest;\n  try {\n    request = JSON.parse(decodeBase64url(challenge.request));\n  } catch (_) {\n    throw new Error(\n      \"mpp: invalid request auth-param (not valid base64url-encoded JSON)\",\n    );\n  }\n\n  const invoice = request.methodDetails?.invoice;\n  if (!invoice) {\n    throw new Error(\"mpp: missing invoice in charge request\");\n  }\n\n  const invResp = await wallet.payInvoice({ invoice });\n\n  // Per spec: Authorization: Payment <base64url-token>  (single token, no wrapper)\n  const credential = buildMppCredential(challenge, invResp.preimage);\n  headers.set(\"Authorization\", `Payment ${credential}`);\n\n  return fetch(url, fetchArgs);\n};\n\n/**\n * Fetch a resource protected by the draft-lightning-charge-00 payment\n * authentication protocol.\n *\n * On a `402 Payment Required` response that carries a\n * `WWW-Authenticate: Payment method=\"lightning\" intent=\"charge\" …` header\n * the function pays the embedded BOLT11 invoice and retries with the\n * resulting preimage as the credential.\n *\n * Note: lightning-charge uses consume-once challenge semantics – each\n * challenge embeds a fresh invoice, so paid credentials cannot be reused.\n * The `store` option is accepted for API consistency but is not used.\n */\nexport const fetchWithMpp = async (\n  url: string,\n  fetchArgs: RequestInit,\n  options: { wallet: Wallet },\n): Promise<Response> => {\n  const wallet = options.wallet;\n  if (!wallet) {\n    throw new Error(\"wallet is missing\");\n  }\n  if (!fetchArgs) {\n    fetchArgs = {};\n  }\n  fetchArgs.cache = \"no-store\";\n  fetchArgs.mode = \"cors\";\n  const headers = new Headers(fetchArgs.headers ?? undefined);\n  fetchArgs.headers = headers;\n\n  const initResp = await fetch(url, fetchArgs);\n  const wwwAuthHeader = initResp.headers.get(\"www-authenticate\");\n  if (\n    !wwwAuthHeader ||\n    !wwwAuthHeader.trimStart().toLowerCase().startsWith(\"payment\")\n  ) {\n    return initResp;\n  }\n\n  return handleMppChargePayment(wwwAuthHeader, url, fetchArgs, headers, wallet);\n};\n"],"names":[],"mappings":"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"}