402-mcp 3.15.0 → 3.15.2

package/README.md

@@ -79,7 +79,7 @@ For detailed architecture and payment flow diagrams, see [docs/architecture.md](
 | `CREDENTIAL_STORE` | `~/.402-mcp/credentials.json` | Persistent macaroon/credential storage |
 | `TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
 | `PORT` | 3402 | HTTP server port (when `TRANSPORT=http`) |
-| `TRANSPORT_PREFERENCE` | `clearnet` | Preferred network transport: `clearnet`, `tor`, or `hns` |
+| `TRANSPORT_PREFERENCE` | `onion,hns,https,http` | Preferred transport order for multi-URL services (comma-separated) |
 | `TOR_PROXY` | - | SOCKS5 proxy for `.onion` addresses (e.g. `socks5h://127.0.0.1:9050`) |
 | `SOCKS_PROXY` | - | Generic SOCKS5 proxy for all requests when set |
 | `HNS_GATEWAY_URL` | - | HTTP gateway for Handshake (`.hns`) domains (e.g. `https://hns.to`) |
@@ -126,6 +126,15 @@ Three payment rails, tried in priority order:
 
 The agent can override the method per-call, or you can configure only the methods you want.
 
+`l402-fetch` handles four HTTP 402 challenge variants transparently:
+
+| Protocol | Challenge header | Payment |
+|----------|-----------------|---------|
+| **L402** | `WWW-Authenticate: L402` | Lightning invoice via wallet stack |
+| **IETF Payment** (`draft-ryan-httpauth-payment-01`) | `WWW-Authenticate: Payment` | Lightning invoice via wallet stack |
+| **xCashu** (NUT-18) | `X-Cashu: creqA…` | Ecash token sent directly (requires Cashu wallet) |
+| **x402** | `X-Payment-Required: x402` | On-chain EVM transfer; surfaced to human with EIP-681 deeplink |
+
 ## Safety
 
 `MAX_AUTO_PAY_SATS` caps any single autonomous payment. Above this limit, the agent must ask the human for approval. The agent can read this limit via `l402-config` and factor it into purchasing decisions.
@@ -174,6 +183,23 @@ Built by [@forgesworn](https://github.com/forgesworn).
 
 ---
 
+## Part of the ForgeSworn Toolkit
+
+[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.
+
+| Library | What it does |
+|---------|-------------|
+| [nsec-tree](https://github.com/forgesworn/nsec-tree) | Deterministic sub-identity derivation |
+| [ring-sig](https://github.com/forgesworn/ring-sig) | SAG/LSAG ring signatures on secp256k1 |
+| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen commitment range proofs |
+| [canary-kit](https://github.com/forgesworn/canary-kit) | Coercion-resistant spoken verification |
+| [spoken-token](https://github.com/forgesworn/spoken-token) | Human-speakable verification tokens |
+| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 payment middleware |
+| [geohash-kit](https://github.com/forgesworn/geohash-kit) | Geohash toolkit with polygon coverage |
+| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA verifiable attestations |
+| [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |
+| [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |
+
 ## Licence
 
 [MIT](LICENSE)

package/llms-full.txt

@@ -79,6 +79,15 @@ src/
     detect.ts              # Detect toll-booth vs generic L402 servers
     bolt11.ts              # Decode BOLT11 invoices (amount extraction)
     challenge-cache.ts     # Cache parsed challenges for l402-pay
+  x402/
+    parse.ts               # Detect X-Payment-Required: x402 header; parse EVM challenge
+    payment.ts             # Format payment request with EIP-681 deeplink for human payment
+  xcashu/
+    parse.ts               # Detect X-Cashu header; parse NUT-18 payment request
+    payment.ts             # Autonomous ecash payment: coin-select, send exact token amount
+  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
   store/
     credentials.ts         # Encrypted credential persistence (JSON)
     cashu-tokens.ts        # Cashu token store (add/remove/balance)
@@ -266,6 +275,19 @@ The L402 protocol is an extension of HTTP 402 (Payment Required):
 
 402-mcp handles steps 2–5 automatically within `l402-fetch`.
 
+## Supported 402 Protocol Variants
+
+`l402-fetch` detects and handles four HTTP 402 challenge variants. Detection order in source: L402, x402, xCashu, IETF Payment.
+
+| 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) |
+| **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.
+
 ## Wallet Priority and Resolution
 
 Wallets are tried in order: NWC → Cashu → Human. The first wallet that succeeds is used.

package/llms.txt

@@ -120,6 +120,13 @@ Three payment rails 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** (`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.
+- **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).
+
 ## Safety Model
 
 Two safety primitives protect against runaway spending:

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "402-mcp",
-  "version": "3.15.0",
+  "version": "3.15.2",
+  "mcpName": "dev.forgesworn/402-mcp",
   "description": "L402 + x402 client MCP - AI agents discover, pay for, and consume any payment-gated API",
   "type": "module",
   "bin": {