@thecryptodonkey/toll-booth 3.4.0 → 3.6.0

package/README.md

@@ -1,5 +1,6 @@
 # toll-booth
 
+[![CI](https://github.com/TheCryptoDonkey/toll-booth/actions/workflows/ci.yml/badge.svg)](https://github.com/TheCryptoDonkey/toll-booth/actions/workflows/ci.yml)
 [![MIT licence](https://img.shields.io/badge/licence-MIT-blue.svg)](./LICENSE)
 [![Nostr](https://img.shields.io/badge/Nostr-Zap%20me-purple)](https://primal.net/p/npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2)
 [![npm](https://img.shields.io/npm/v/@thecryptodonkey/toll-booth)](https://www.npmjs.com/package/@thecryptodonkey/toll-booth)
@@ -110,7 +111,7 @@ curl -H "Authorization: L402 <macaroon>:<preimage>" https://jokes.trotters.dev/a
 
 - **L402 protocol** - industry-standard HTTP 402 payment flow with macaroon credentials
 - **Multiple Lightning backends** - Phoenixd, LND, CLN, LNbits, NWC (any Nostr Wallet Connect wallet)
-- **Alternative payment methods** - Cashu ecash tokens
+- **Alternative payment methods** - Cashu ecash tokens and xcashu (NUT-24) direct-header payments
 - **Cashu-only mode** - no Lightning node required; ideal for serverless and edge deployments
 - **Credit system** - pre-paid balance with volume discount tiers
 - **Free tier** - configurable daily allowance (IP-hashed, no PII stored)
@@ -241,6 +242,26 @@ const booth = new Booth({
 
 No Lightning node, no channels, no liquidity management. Ideal for serverless and edge deployments.
 
+### xcashu (Cashu ecash via NUT-24)
+
+```typescript
+import { Booth } from '@thecryptodonkey/toll-booth'
+
+const booth = new Booth({
+  adapter: 'web-standard',
+  xcashu: {
+    mints: ['https://mint.minibits.cash'],
+    unit: 'sat',
+  },
+  pricing: { '/api': 10 },
+  upstream: 'http://localhost:3000',
+})
+```
+
+Clients pay by sending `X-Cashu: cashuB...` tokens in the request header. Proofs are verified and swapped at the configured mint(s) using cashu-ts.
+
+Unlike the `redeemCashu` callback (which integrates Cashu into the L402 payment-and-redeem flow), `xcashu` is a self-contained payment rail: the client attaches a token directly to the API request and gets access in one step — no separate redeem endpoint required. Both rails can run simultaneously; the 402 challenge will include both `WWW-Authenticate` (L402) and `X-Cashu` headers.
+
 ---
 
 ## Lightning backends

package/dist/booth.js

@@ -2,6 +2,7 @@ import { normalisePricingTable } from './core/payment-rail.js';
 import { createTollBooth } from './core/toll-booth.js';
 import { createL402Rail } from './core/l402-rail.js';
 import { createX402Rail } from './core/x402-rail.js';
+import { createXCashuRail } from './core/xcashu-rail.js';
 import { sqliteStorage } from './storage/sqlite.js';
 import { StatsCollector } from './stats.js';
 import { randomBytes } from 'node:crypto';
@@ -56,8 +57,8 @@ export class Booth {
     pruneTimer;
     closed = false;
     constructor(config) {
-        if (!config.backend && !config.redeemCashu && !config.x402) {
-            throw new Error('At least one payment method required: provide a Lightning backend, redeemCashu callback, or x402 config');
+        if (!config.backend && !config.redeemCashu && !config.x402 && !config.xcashu) {
+            throw new Error('At least one payment method required: provide a Lightning backend, redeemCashu callback, x402 config, or xcashu config');
         }
         let rootKeyInput;
         if (config.rootKey) {
@@ -97,6 +98,9 @@ export class Booth {
         if (config.x402) {
             rails.push(createX402Rail({ ...config.x402, storage: this.storage }));
         }
+        if (config.xcashu) {
+            rails.push(createXCashuRail(config.xcashu, this.storage));
+        }
         this.engine = createTollBooth({
             backend: config.backend,
             storage: this.storage,
@@ -108,6 +112,8 @@ export class Booth {
             freeTier: config.freeTier,
             strictPricing: config.strictPricing,
             creditTiers: config.creditTiers,
+            serviceName: config.serviceName,
+            description: config.description,
             rails,
             onPayment: (event) => {
                 stats.recordPayment(event);

package/dist/core/melt-to-lightning.d.ts

@@ -0,0 +1,24 @@
+import type { Proof } from '@cashu/cashu-ts';
+export type MeltResult = {
+    paid: true;
+    amountSats: number;
+    preimage?: string;
+} | {
+    paid: false;
+    error: string;
+};
+/**
+ * Melts Cashu proofs to pay a Lightning invoice on the operator's node.
+ * Handles the full flow: invoice creation → melt quote → coin selection → melt.
+ * Discards change proofs (fee overpayment donated to mint).
+ *
+ * @param opts.mintUrl - The mint that issued the proofs
+ * @param opts.proofs - Server-side proofs from wallet.receive()
+ * @param opts.createInvoice - Callback to create a BOLT11 invoice on the operator's node
+ */
+export declare function meltToLightning(opts: {
+    mintUrl: string;
+    proofs: Proof[];
+    createInvoice: (amountSats: number) => Promise<string>;
+}): Promise<MeltResult>;
+//# sourceMappingURL=melt-to-lightning.d.ts.map

package/dist/core/melt-to-lightning.js

@@ -0,0 +1,43 @@
+import { Wallet } from '@cashu/cashu-ts';
+/**
+ * Melts Cashu proofs to pay a Lightning invoice on the operator's node.
+ * Handles the full flow: invoice creation → melt quote → coin selection → melt.
+ * Discards change proofs (fee overpayment donated to mint).
+ *
+ * @param opts.mintUrl - The mint that issued the proofs
+ * @param opts.proofs - Server-side proofs from wallet.receive()
+ * @param opts.createInvoice - Callback to create a BOLT11 invoice on the operator's node
+ */
+export async function meltToLightning(opts) {
+    const { mintUrl, proofs, createInvoice } = opts;
+    const totalSats = proofs.reduce((sum, p) => sum + p.amount, 0);
+    if (totalSats <= 0) {
+        return { paid: false, error: 'No proofs to melt' };
+    }
+    const wallet = new Wallet(mintUrl, { unit: 'sat' });
+    // Create invoice for the full proof amount
+    const invoice = await createInvoice(totalSats);
+    // Get melt quote to learn fee_reserve
+    const meltQuote = await wallet.createMeltQuoteBolt11(invoice);
+    const needed = meltQuote.amount + meltQuote.fee_reserve;
+    if (needed > totalSats) {
+        return {
+            paid: false,
+            error: `Proofs insufficient for fees (have ${totalSats}, need ${needed} including ${meltQuote.fee_reserve} fee reserve)`,
+        };
+    }
+    // Coin selection
+    const { send } = await wallet.send(needed, proofs, { includeFees: true });
+    // Melt — pay the Lightning invoice via the mint
+    const meltResponse = await wallet.meltProofsBolt11(meltQuote, send);
+    if (meltResponse.quote.state === 'PAID') {
+        // Discard change proofs (keep + change) — bearer instruments not retained
+        return {
+            paid: true,
+            amountSats: meltQuote.amount,
+            preimage: meltResponse.quote.payment_preimage ?? undefined,
+        };
+    }
+    return { paid: false, error: `Melt state: ${meltResponse.quote.state}` };
+}
+//# sourceMappingURL=melt-to-lightning.js.map

package/dist/core/toll-booth.js

@@ -81,6 +81,15 @@ export function createTollBooth(config) {
                 if (config.creditTiers && config.creditTiers.length > 0) {
                     challengeBody.credit_tiers = config.creditTiers;
                 }
+                // Agent-friendly service metadata (only when serviceName is configured).
+                // auth_hint is L402-specific; x402/xcashu have different auth mechanisms.
+                if (config.serviceName) {
+                    challengeBody.booth = {
+                        name: config.serviceName,
+                        ...(config.description && { description: config.description }),
+                    };
+                    challengeBody.auth_hint = 'Pay the invoice, then send header \u2014 Authorization: L402 <macaroon>:<preimage>';
+                }
                 // Store invoice data from L402 rail if present
                 const l402Data = challengeBody.l402;
                 if (l402Data?.payment_hash) {

package/dist/core/types.d.ts

@@ -60,6 +60,8 @@ export interface TollBoothCoreConfig {
     normalisedPricing?: Record<string, PriceInfo>;
     /** Human-readable service name for invoice descriptions. Defaults to 'toll-booth'. */
     serviceName?: string;
+    /** Service description for 402 response bodies. */
+    description?: string;
     onPayment?: (event: PaymentEvent) => void;
     onRequest?: (event: RequestEvent) => void;
     onChallenge?: (event: ChallengeEvent) => void;

package/dist/core/xcashu-rail.d.ts

@@ -0,0 +1,5 @@
+import type { PaymentRail } from './payment-rail.js';
+import type { XCashuConfig } from '../types.js';
+import type { StorageBackend } from '../storage/interface.js';
+export declare function createXCashuRail(config: XCashuConfig, storage?: StorageBackend): PaymentRail;
+//# sourceMappingURL=xcashu-rail.d.ts.map

package/dist/core/xcashu-rail.js

@@ -0,0 +1,123 @@
+import { randomBytes } from 'node:crypto';
+import { Wallet, getDecodedToken } from '@cashu/cashu-ts';
+const FAIL = { authenticated: false, paymentId: '', mode: 'credit', currency: 'sat' };
+/**
+ * Encode a NUT-18-style payment request for the X-Cashu header.
+ * Simplified JSON encoding — full CBOR encoding can be added later
+ * if cashu-ts exposes a PaymentRequest builder.
+ */
+function encodePaymentRequest(amount, unit, mints) {
+    const payload = JSON.stringify({ a: amount, u: unit, m: mints });
+    return 'creqA' + Buffer.from(payload).toString('base64url');
+}
+export function createXCashuRail(config, storage) {
+    const unit = config.unit ?? 'sat';
+    const mintUrls = config.mints;
+    // Lazily initialised wallets per mint (loadMint is async, done on first use)
+    const wallets = new Map();
+    const walletReady = new Map();
+    async function getWallet(mintUrl) {
+        const existing = walletReady.get(mintUrl);
+        if (existing)
+            return existing;
+        const promise = (async () => {
+            const wallet = new Wallet(mintUrl, { unit });
+            await wallet.loadMint();
+            wallets.set(mintUrl, wallet);
+            return wallet;
+        })();
+        walletReady.set(mintUrl, promise);
+        return promise;
+    }
+    return {
+        type: 'xcashu',
+        creditSupported: true,
+        canChallenge(price) {
+            return price.sats !== undefined;
+        },
+        detect(req) {
+            const header = req.headers['x-cashu'];
+            return typeof header === 'string' && header.startsWith('cashuB');
+        },
+        async challenge(_route, price) {
+            const amount = price.sats;
+            const encoded = encodePaymentRequest(amount, unit, mintUrls);
+            return {
+                headers: { 'X-Cashu': encoded },
+                body: {
+                    xcashu: { amount, unit, mints: mintUrls },
+                },
+            };
+        },
+        async verify(req) {
+            const header = req.headers['x-cashu'];
+            if (typeof header !== 'string' || !header.startsWith('cashuB')) {
+                return FAIL;
+            }
+            let decoded;
+            try {
+                decoded = getDecodedToken(header);
+            }
+            catch {
+                return FAIL;
+            }
+            // Validate mint is accepted
+            const tokenMint = decoded.mint;
+            if (!tokenMint || !mintUrls.includes(tokenMint)) {
+                return FAIL;
+            }
+            // Validate unit matches
+            if (decoded.unit && decoded.unit !== unit) {
+                return FAIL;
+            }
+            // Get or initialise wallet for this mint
+            let wallet;
+            try {
+                wallet = await getWallet(tokenMint);
+            }
+            catch {
+                return FAIL;
+            }
+            // Swap proofs at the mint to verify and claim them
+            let receivedProofs;
+            try {
+                receivedProofs = await wallet.receive(header);
+            }
+            catch {
+                // Mint unreachable, proofs already spent, or other error
+                return FAIL;
+            }
+            const creditedAmount = receivedProofs.reduce((sum, p) => sum + p.amount, 0);
+            if (creditedAmount <= 0) {
+                return FAIL;
+            }
+            // Fire onProofsReceived callback (non-blocking, fire-and-forget)
+            if (config.onProofsReceived) {
+                try {
+                    const cbResult = config.onProofsReceived(receivedProofs, tokenMint, creditedAmount);
+                    if (cbResult && typeof cbResult.catch === 'function') {
+                        cbResult.catch(() => { });
+                    }
+                }
+                catch {
+                    // Callback errors silently discarded — never block the payment flow
+                }
+            }
+            // Generate payment ID and settlement secret
+            const paymentId = randomBytes(32).toString('hex');
+            const settlementSecret = randomBytes(32).toString('hex');
+            // Settle credit if storage available
+            if (storage && !storage.isSettled(paymentId)) {
+                storage.settleWithCredit(paymentId, creditedAmount, settlementSecret, unit);
+            }
+            return {
+                authenticated: true,
+                paymentId,
+                mode: 'credit',
+                currency: unit,
+                creditBalance: creditedAmount,
+            };
+        },
+    };
+}
+//# sourceMappingURL=xcashu-rail.js.map

package/dist/index.d.ts

@@ -27,6 +27,10 @@ export type { L402RailConfig } from './core/l402-rail.js';
 export { createX402Rail } from './core/x402-rail.js';
 export type { X402RailConfig, X402Facilitator, X402Payment, X402VerifyResult } from './core/x402-types.js';
 export { DEFAULT_USDC_ASSETS } from './core/x402-types.js';
+export { createXCashuRail } from './core/xcashu-rail.js';
+export type { XCashuConfig } from './types.js';
+export { meltToLightning } from './core/melt-to-lightning.js';
+export type { MeltResult } from './core/melt-to-lightning.js';
 export { mintMacaroon, verifyMacaroon, parseCaveats } from './macaroon.js';
 export type { VerifyContext, VerifyResult } from './macaroon.js';
 export { FreeTier, CreditFreeTier } from './free-tier.js';

package/dist/index.js

@@ -17,6 +17,8 @@ export { normalisePricing, normalisePricingTable, isTieredPricing } from './core
 export { createL402Rail } from './core/l402-rail.js';
 export { createX402Rail } from './core/x402-rail.js';
 export { DEFAULT_USDC_ASSETS } from './core/x402-types.js';
+export { createXCashuRail } from './core/xcashu-rail.js';
+export { meltToLightning } from './core/melt-to-lightning.js';
 // Utilities
 export { mintMacaroon, verifyMacaroon, parseCaveats } from './macaroon.js';
 export { FreeTier, CreditFreeTier } from './free-tier.js';

package/dist/types.d.ts

@@ -43,6 +43,7 @@ export interface LightningBackend {
      */
     checkInvoice(paymentHash: string): Promise<InvoiceStatus>;
 }
+import type { Proof } from '@cashu/cashu-ts';
 import type { Currency, PricingEntry } from './core/payment-rail.js';
 import type { X402RailConfig } from './core/x402-types.js';
 /**
@@ -66,12 +67,27 @@ export interface CreditTier {
     creditSats: number;
     /** Human-readable label for this tier. */
     label: string;
-    /** Pricing tier this credit tier belongs to (e.g. 'default', 'premium'). */
-    tier?: string;
     /** x402 tier amount in cents (USD). */
     amountUsd?: number;
     /** x402 tier credit in cents (USD). */
     creditUsd?: number;
+    /** What the agent gets for this tier, e.g. "1 request", "10 minutes access". */
+    yields?: string;
+}
+/**
+ * Configuration for the xcashu (NUT-24) payment rail.
+ */
+export interface XCashuConfig {
+    /** Accepted Cashu mint URLs (1+) */
+    mints: string[];
+    /** Currency unit, default 'sat' */
+    unit?: Currency;
+    /**
+     * Called after successful token swap with the server-side proofs.
+     * Fire-and-forget — the rail does NOT await this callback.
+     * Use for melting, persisting, or forwarding received ecash.
+     */
+    onProofsReceived?: (proofs: Proof[], mintUrl: string, amount: number) => void | Promise<void>;
 }
 /**
  * Configuration for a toll-booth instance.
@@ -158,12 +174,22 @@ export interface BoothConfig {
     redeemCashu?: (token: string, paymentHash: string) => Promise<number>;
     /** x402 stablecoin payment rail configuration. */
     x402?: X402RailConfig;
+    /**
+     * xcashu (NUT-24) config — accept Cashu ecash via X-Cashu header.
+     * Proofs are swapped at the configured mint(s) using cashu-ts.
+     */
+    xcashu?: XCashuConfig;
     /**
      * Human-readable service name used in Lightning invoice descriptions.
      * Defaults to `'toll-booth'`. Example: `'satgate'` produces invoices
      * like `"satgate: 1000 sats credit"`.
      */
     serviceName?: string;
+    /**
+     * Service description shown in 402 response bodies.
+     * Only included when `serviceName` is also set.
+     */
+    description?: string;
     /**
      * Timeout in milliseconds for upstream proxy requests.
      * Defaults to 30000 (30 seconds).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecryptodonkey/toll-booth",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "type": "module",
   "description": "Monetise any API with HTTP 402 payments. Payment-rail agnostic middleware for Express, Hono, Deno, Bun, and Workers.",
   "license": "MIT",
@@ -103,6 +103,7 @@
     "prepare": "patch-package"
   },
   "dependencies": {
+    "@cashu/cashu-ts": "^3.6.0",
     "better-sqlite3": "^11.8.0",
     "macaroon": "^3.0.4",
     "nostr-core": "^0.4.0",
@@ -121,7 +122,6 @@
     }
   },
   "devDependencies": {
-    "@cashu/cashu-ts": "^3.5.0",
     "@hono/node-server": "^1.19.11",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
@@ -136,6 +136,5 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
-  },
-  "optionalDependencies": {}
+  }
 }