402-mcp 4.1.1 → 4.2.0

package/build/xlnurlcash/payment.js

@@ -0,0 +1,102 @@
+import { createNoteOps, noteUrl, NoteGone } from '../wallet/lnurlcash-ops.js';
+/**
+ * Mints arrive as bare hosts (`mint.example.com`), origins, or full discovery
+ * URLs. Compared on host so all three forms match a stored note's origin.
+ */
+export function mintHost(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)
+        ? trimmed.replace(/^lnurlw:\/\//i, 'https://')
+        : `https://${trimmed}`;
+    try {
+        const host = new URL(withScheme).host;
+        return host.length > 0 ? host.toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Builds a bearer-note payment for an lnurlcash challenge: an exact-value note
+ * from an accepted mint, or one split at the mint to the exact price so the
+ * paywall is never overpaid and the change stays in the store. Returns null
+ * when no note can cover it, so the caller falls through to another rail.
+ *
+ * The chosen note is held pending before it is returned. Handing a bearer note
+ * to a server puts it beyond our control: the server settles by rotating it,
+ * and only the mint knows whether that happened.
+ */
+export async function attemptLnurlcashPayment(opts) {
+    const { challenge, noteStore } = opts;
+    const ops = opts.ops ?? createNoteOps(noteStore, opts.options ?? {});
+    const accepted = new Set(challenge.mints.map(mintHost).filter((h) => h !== null));
+    if (accepted.size === 0)
+        return null;
+    const needMsat = challenge.amount * 1000;
+    try {
+        await ops.reconcile();
+    }
+    catch { /* best effort; selection below simply sees fewer notes */ }
+    const live = noteStore.live().filter(n => {
+        const host = mintHost(n.mint);
+        return host !== null && accepted.has(host);
+    });
+    // Exact-value notes first: handing one over avoids a split round trip
+    // entirely. Then the smallest note that covers the price, so large notes
+    // stay whole.
+    const candidates = [
+        ...live.filter(n => n.amountMsat === needMsat),
+        ...live.filter(n => n.amountMsat > needMsat).sort((a, b) => a.amountMsat - b.amountMsat),
+    ];
+    for (const candidate of candidates) {
+        // The stored value is a cache. Only the mint knows what a note is worth
+        // now, and a bearer note anyone else holds a copy of may already be spent,
+        // so it is confirmed before it is handed over.
+        const probe = await ops.probeNote(candidate.mint, candidate.secret);
+        if (!probe.ok) {
+            // A mint that refuses the note has retired it: drop it and try the next.
+            // A mint that cannot be reached has said nothing, so nothing is dropped
+            // and no further note is risked against it.
+            if (probe.reason === 'unreachable')
+                return null;
+            noteStore.remove(candidate.secret);
+            continue;
+        }
+        if (probe.note.amountMsat !== candidate.amountMsat) {
+            noteStore.setAmount(candidate.secret, probe.note.amountMsat);
+        }
+        if (probe.note.amountMsat < needMsat)
+            continue;
+        const current = noteStore.find(candidate.secret);
+        if (!current)
+            continue;
+        let exact;
+        try {
+            exact = probe.note.amountMsat === needMsat
+                ? current
+                : await ops.split(current, needMsat);
+        }
+        catch (error) {
+            // A note the mint no longer recognises is normal for a bearer asset:
+            // drop it and try the next. Anything else means the mint is refusing or
+            // unreachable, so stop rather than burn more notes against it.
+            if (error instanceof NoteGone)
+                continue;
+            return null;
+        }
+        noteStore.setState(exact.secret, 'melting');
+        const secret = exact.secret;
+        return {
+            header: noteUrl(exact),
+            amountSats: challenge.amount,
+            settle(granted) {
+                if (granted)
+                    noteStore.remove(secret);
+            },
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=payment.js.map

package/build/xlnurlcash/payment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.js","sourceRoot":"","sources":["../../src/xlnurlcash/payment.ts"],"names":[],"mappings":"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"}

package/llms-full.txt

@@ -85,6 +85,11 @@ src/
   xcashu/
     parse.ts               # Detect X-Cashu header; parse NUT-18 payment request
     payment.ts             # Autonomous ecash payment: coin-select, send exact token amount
+  xlnurlcash/
+    parse.ts               # Detect X-LNURLcash header; parse the lnurlcash payment request
+                           # (v/id/amount-as-string/currency/methodDetails.mints, per the
+                           #  conformance vectors; the older short form is still read)
+    payment.ts             # Autonomous bearer-note payment: pick or split a note to the exact price
   ietf-payment/
     parse.ts               # Detect/parse WWW-Authenticate: Payment challenges (draft-ryan-httpauth-payment-01)
     credential.ts          # Build Authorization: Payment base64url credential after Lightning payment
@@ -277,25 +282,27 @@ The L402 protocol is an extension of HTTP 402 (Payment Required):
 
 ## Supported 402 Protocol Variants
 
-`l402-fetch` detects and handles four HTTP 402 challenge variants. Detection order in source: L402, x402, xCashu, IETF Payment.
+`l402-fetch` detects and handles five HTTP 402 challenge variants. Detection order in source: LNURLcash, x402, IETF Payment, L402, with xCashu tried immediately after LNURLcash.
 
 | Protocol | Detection | Credential sent | Autonomous? |
 |----------|-----------|----------------|-------------|
 | **L402** | `WWW-Authenticate: L402 macaroon=…, invoice=…` | `Authorization: L402 <macaroon>:<preimage>` | Yes (NWC or Cashu) |
 | **IETF Payment** (`draft-ryan-httpauth-payment-01`) | `WWW-Authenticate: Payment id=… method=lightning …` | `Authorization: Payment <base64url-json>` | Yes (NWC or Cashu) |
+| **LNURLcash** (LUD-25) | `X-LNURLcash: lnurlcashreq1<base64url>` | `X-LNURLcash: <bearer note URL>` | Yes (note store only) |
 | **xCashu** (NUT-18) | `X-Cashu: creqA<base64url>` | `X-Cashu: <cashuB-token>` | Yes (Cashu wallet only) |
 | **x402** | `X-Payment-Required: x402` + JSON body | Human presents EIP-681 deeplink | No — on-chain EVM; surfaced to human |
 
-xCashu uses coin selection via `wallet.send(amount, proofs, { includeFees: true })` and restores change proofs to the token store. IETF Payment decodes the base64url charge request to extract the BOLT11 invoice, then pays it through the normal wallet stack and wraps the preimage in a JSON credential.
+LNURLcash is tried before the others because a bearer note is already money in hand: the note URL goes straight into the retry header and the server settles it by rotating the note. A note worth exactly the price is used as it is; otherwise one is split at the mint and the change stays in the store. The chosen note is held pending until the outcome is known, so nothing else can spend it in the meantime. xCashu uses coin selection via `wallet.send(amount, proofs, { includeFees: true })` and restores change proofs to the token store. IETF Payment decodes the base64url charge request to extract the BOLT11 invoice, then pays it through the normal wallet stack and wraps the preimage in a JSON credential.
 
 ## Wallet Priority and Resolution
 
-Wallets are tried in order: NWC → Cashu → Human. The first wallet that succeeds is used.
+Wallets are tried in order: NWC → Cashu → LNURLcash → Human. The first wallet that succeeds is used.
 
 | Wallet | Autonomy | Requirements | Speed |
 |--------|----------|-------------|-------|
 | NWC | Fully autonomous | `NWC_URI_FILE` pointing to a private 0600 bearer file | ~2-5 seconds |
 | Cashu | Fully autonomous | `CASHU_TOKENS` file with ecash tokens | ~3-8 seconds |
+| LNURLcash | Fully autonomous | `LNURLCASH_NOTES` file with LUD-25 bearer notes | ~2-6 seconds |
 | Human | Requires human | None — always available as fallback | Minutes |
 
 The agent can force a specific method per-call using the `paymentMethod` parameter.

package/llms.txt

@@ -120,10 +120,11 @@ Three payer methods are tried in priority order:
 
 The agent can override the payment method per-call, or you can configure only the methods you want available.
 
-`l402-fetch` handles four HTTP 402 challenge variants transparently:
+`l402-fetch` handles five HTTP 402 challenge variants transparently:
 
 - **L402** (`WWW-Authenticate: L402`) — the primary protocol; Lightning invoice paid via the wallet stack.
 - **IETF Payment** (`WWW-Authenticate: Payment`, `draft-ryan-httpauth-payment-01`) — alternative Lightning path; builds a base64url credential after payment.
+- **LNURLcash** (`X-LNURLcash: lnurlcashreq1…`, LUD-25): autonomous bearer-note payment; hands over a note worth exactly the price, splitting one at the mint if needed. Tried first: no Lightning hop and no swap at the mint.
 - **xCashu** (`X-Cashu: creqA…`, NUT-18) — autonomous ecash payment; selects and sends the exact token amount without a Lightning round-trip.
 - **x402** (`X-Payment-Required: x402`) — on-chain EVM payment; surfaces an EIP-681 deeplink to the human (no autonomous settlement).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "402-mcp",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "mcpName": "dev.forgesworn/402-mcp",
   "description": "L402 + x402 client MCP - AI agents discover, pay for, and consume any payment-gated API",
   "type": "module",
@@ -14,6 +14,7 @@
     "./l402/*": "./build/l402/*.js",
     "./x402/*": "./build/x402/*.js",
     "./xcashu/*": "./build/xcashu/*.js",
+    "./xlnurlcash/*": "./build/xlnurlcash/*.js",
     "./ietf-payment/*": "./build/ietf-payment/*.js",
     "./store/*": "./build/store/*.js",
     "./fetch/*": "./build/fetch/*.js",
@@ -81,7 +82,10 @@
     "ai-agent",
     "autonomous-payments",
     "macaroon",
-    "stablecoin"
+    "stablecoin",
+    "lnurlcash",
+    "lud-25",
+    "bearer-notes"
   ],
   "author": "forgesworn",
   "homepage": "https://github.com/forgesworn/402-mcp",