402-mcp 4.1.2 → 4.2.1

package/build/xlnurlcash/parse.js

@@ -0,0 +1,71 @@
+/**
+ * Payment requests are prefixed like a bech32 human-readable part so a bare
+ * string is self-describing, the way NUT-18 uses `creqA`.
+ */
+const PREFIX = 'lnurlcashreq1';
+/** Detects whether a 402 response carries an lnurlcash challenge. */
+export function isLnurlcashChallenge(headers) {
+    const value = headers.get('x-lnurlcash');
+    return !!value && value.startsWith(PREFIX);
+}
+/** A whole number of sats that survives the conversion to msat everything downstream works in. */
+function satsFrom(value) {
+    const n = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && /^[0-9]+$/.test(value)
+            ? Number(value)
+            : NaN;
+    if (!Number.isSafeInteger(n) || n <= 0)
+        return null;
+    return Number.isSafeInteger(n * 1000) ? n : null;
+}
+function stringsFrom(value) {
+    if (!Array.isArray(value))
+        return null;
+    const out = value.filter((m) => typeof m === 'string' && m.length > 0);
+    return out.length > 0 ? out : null;
+}
+/**
+ * Parses an lnurlcash payment request from the X-LNURLcash header value:
+ * `lnurlcashreq1` followed by unpadded base64url of the request's RFC 8785
+ * canonical JSON.
+ *
+ * The request is `{ v, id, amount, currency, methodDetails: { mints } }`,
+ * with the amount a decimal STRING of whole sats. That is the shape the
+ * conformance vectors pin and `lnurlcash-kit` encodes.
+ *
+ * A shorter object, `{ a: number, u, m }`, briefly went out under the same
+ * prefix before the format settled. It is still read here, because a decoder
+ * that returns nothing on a string it can plainly understand helps no one,
+ * and because the kit's own decoder accepts it too. Nothing emits it.
+ *
+ * Only `sat` exists today; anything else returns null rather than guessing at
+ * a denomination.
+ */
+export function parseLnurlcashChallenge(header) {
+    if (!header.startsWith(PREFIX))
+        return null;
+    try {
+        const b64 = header.slice(PREFIX.length);
+        const json = Buffer.from(b64, 'base64url').toString('utf-8');
+        const data = JSON.parse(json);
+        if (typeof data !== 'object' || data === null)
+            return null;
+        const details = data.methodDetails;
+        const longForm = data.amount !== undefined || data.v !== undefined;
+        const amount = satsFrom(longForm ? data.amount : data.a);
+        const currency = longForm ? data.currency : data.u;
+        const mints = stringsFrom(longForm
+            ? typeof details === 'object' && details !== null
+                ? details.mints
+                : undefined
+            : data.m);
+        if (amount === null || currency !== 'sat' || !mints)
+            return null;
+        return { amount, unit: 'sat', mints };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=parse.js.map

package/build/xlnurlcash/parse.js.map

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

package/build/xlnurlcash/payment.d.ts

@@ -0,0 +1,37 @@
+import type { LnurlcashNoteStore } from '../store/lnurlcash-notes.js';
+import { type NoteOps, type NoteOpsOptions } from '../wallet/lnurlcash-ops.js';
+import type { LnurlcashChallenge } from './parse.js';
+export interface LnurlcashPaymentResult {
+    /** The bearer note URL to send in the X-LNURLcash header. */
+    header: string;
+    /** Amount in sats the note covers. */
+    amountSats: number;
+    /**
+     * Records what the paywall did with the note. `true` means it granted
+     * access, so it rotated the note and our secret is dead. `false` leaves the
+     * note held pending: only the mint can say whether it was rotated, and the
+     * next lnurlcash operation asks.
+     */
+    settle: (accepted: boolean) => void;
+}
+/**
+ * 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 declare function mintHost(value: string): string | 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 declare function attemptLnurlcashPayment(opts: {
+    challenge: LnurlcashChallenge;
+    noteStore: LnurlcashNoteStore;
+    ops?: NoteOps;
+    options?: NoteOpsOptions;
+}): Promise<LnurlcashPaymentResult | null>;

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":"AACA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAqC,MAAM,4BAA4B,CAAA;AAiBhH;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACrC,MAAM,UAAU,GAAG,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC;QACzD,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,UAAU,CAAC;QAC9C,CAAC,CAAC,WAAW,OAAO,EAAE,CAAA;IACxB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAA;QACrC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,IAK7C;IACC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAA;IAEpE,MAAM,QAAQ,GAAG,IAAI,GAAG,CACtB,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CACrE,CAAA;IACD,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEpC,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,GAAG,IAAI,CAAA;IAExC,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,SAAS,EAAE,CAAA;IACvB,CAAC;IAAC,MAAM,CAAC,CAAC,0DAA0D,CAAC,CAAC;IAEtE,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;QACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAC7B,OAAO,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC5C,CAAC,CAAC,CAAA;IAEF,sEAAsE;IACtE,yEAAyE;IACzE,cAAc;IACd,MAAM,UAAU,GAAG;QACjB,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC;QAC9C,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;KACzF,CAAA;IAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,wEAAwE;QACxE,2EAA2E;QAC3E,+CAA+C;QAC/C,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;QACnE,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;YACd,yEAAyE;YACzE,wEAAwE;YACxE,4CAA4C;YAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,aAAa;gBAAE,OAAO,IAAI,CAAA;YAC/C,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;YAClC,SAAQ;QACV,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,UAAU,EAAE,CAAC;YACnD,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAC9D,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,QAAQ;YAAE,SAAQ;QAE9C,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;QAChD,IAAI,CAAC,OAAO;YAAE,SAAQ;QAEtB,IAAI,KAAK,CAAA;QACT,IAAI,CAAC;YACH,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,KAAK,QAAQ;gBACxC,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;QACxC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qEAAqE;YACrE,wEAAwE;YACxE,+DAA+D;YAC/D,IAAI,KAAK,YAAY,QAAQ;gBAAE,SAAQ;YACvC,OAAO,IAAI,CAAA;QACb,CAAC;QAED,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;QAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAA;QAE3B,OAAO;YACL,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC;YACtB,UAAU,EAAE,SAAS,CAAC,MAAM;YAC5B,MAAM,CAAC,OAAgB;gBACrB,IAAI,OAAO;oBAAE,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YACvC,CAAC;SACF,CAAA;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC"}

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.2",
+  "version": "4.2.1",
   "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",