@thecryptodonkey/toll-booth 3.3.1 → 3.5.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/create-invoice.js

@@ -43,18 +43,14 @@ export async function handleCreateInvoice(deps, request) {
         if (!Number.isSafeInteger(requestedAmount) || requestedAmount < 1 || requestedAmount > 2_100_000_000_000_000) {
             return { success: false, error: 'amountSats must be a positive integer' };
         }
-        // Find matching tier or validate amount
+        // Find matching tier for bonus credits, or accept custom amount at 1:1
         let creditSats = requestedAmount;
         if (deps.tiers.length > 0) {
             const tier = deps.tiers.find(t => t.amountSats === requestedAmount);
-            if (!tier) {
-                return {
-                    success: false,
-                    error: 'Invalid amount. Choose from available tiers.',
-                    tiers: deps.tiers,
-                };
+            if (tier) {
+                creditSats = tier.creditSats;
             }
-            creditSats = tier.creditSats;
+            // Custom amounts are accepted at 1:1 (no bonus) — no rejection
         }
         let paymentHash;
         let bolt11;

package/dist/core/toll-booth.js

@@ -77,6 +77,19 @@ export function createTollBooth(config) {
                 if (pricedEntry !== undefined && isTieredPricing(pricedEntry)) {
                     challengeBody.tiers = normaliseTiersMap(pricedEntry);
                 }
+                // Include credit purchase tiers so clients can offer volume discounts
+                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,111 @@
+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;
+            }
+            // 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,8 @@ 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 { 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,7 @@ 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';
 // Utilities
 export { mintMacaroon, verifyMacaroon, parseCaveats } from './macaroon.js';
 export { FreeTier, CreditFreeTier } from './free-tier.js';

package/dist/types.d.ts

@@ -66,12 +66,21 @@ 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;
 }
 /**
  * Configuration for a toll-booth instance.
@@ -158,12 +167,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.3.1",
+  "version": "3.5.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": {}
+  }
 }