@thecryptodonkey/toll-booth 3.2.2 → 3.2.5

package/dist/adapters/express.d.ts

@@ -36,6 +36,7 @@ export declare function createExpressInvoiceStatusHandler(deps: InvoiceStatusDep
 export interface CreateInvoiceHandlerConfig {
     deps: CreateInvoiceDeps;
     trustProxy?: boolean;
+    getClientIp?: (req: Request) => string;
 }
 /**
  * Returns an Express `RequestHandler` that creates a new Lightning invoice.

package/dist/adapters/express.js

@@ -136,7 +136,8 @@ export function createExpressMiddleware(engineOrConfig, upstreamArg) {
                     const tollCostHeader = upstream_res.headers.get('x-toll-cost');
                     if (tollCostHeader !== null && /^\d+$/.test(tollCostHeader)) {
                         const actualCost = parseInt(tollCostHeader, 10);
-                        if (Number.isSafeInteger(actualCost) && actualCost >= 0) {
+                        const maxAllowed = (result.estimatedCost ?? actualCost) * 10;
+                        if (Number.isSafeInteger(actualCost) && actualCost >= 0 && actualCost <= maxAllowed) {
                             const reconciled = engine.reconcile(result.paymentHash, actualCost);
                             if (reconciled.adjusted) {
                                 res.setHeader('X-Credit-Balance', String(reconciled.newBalance));
@@ -233,11 +234,13 @@ export function createExpressCreateInvoiceHandler(depsOrConfig) {
         if (rejectOversizedBody(req, res))
             return;
         const body = req.body ?? {};
-        const ip = config.trustProxy
-            ? parseForwardedIp(typeof req.headers['x-forwarded-for'] === 'string' ? req.headers['x-forwarded-for'] : undefined) ??
-                parseForwardedIp(typeof req.headers['x-real-ip'] === 'string' ? req.headers['x-real-ip'] : undefined) ??
-                req.socket.remoteAddress ?? '127.0.0.1'
-            : req.socket.remoteAddress ?? '127.0.0.1';
+        const ip = config.getClientIp
+            ? config.getClientIp(req)
+            : config.trustProxy
+                ? parseForwardedIp(typeof req.headers['x-forwarded-for'] === 'string' ? req.headers['x-forwarded-for'] : undefined) ??
+                    parseForwardedIp(typeof req.headers['x-real-ip'] === 'string' ? req.headers['x-real-ip'] : undefined) ??
+                    req.socket.remoteAddress ?? '127.0.0.1'
+                : req.socket.remoteAddress ?? '127.0.0.1';
         const result = await handleCreateInvoice(deps, { ...body, clientIp: ip });
         if (!result.success) {
             jsonWithSensitiveHeaders(res, { error: result.error, tiers: result.tiers }, result.status ?? 400);

package/dist/adapters/proxy-headers.js

@@ -63,8 +63,10 @@ const IPV6_RE = /^[0-9a-fA-F:]{2,45}$/;
 export function isPlausibleIp(value) {
     if (!value || value.length > 45)
         return false;
-    if (IPV4_RE.test(value))
-        return true;
+    if (IPV4_RE.test(value)) {
+        // Reject octets > 255
+        return value.split('.').every(o => parseInt(o, 10) <= 255);
+    }
     // IPv6 must contain at least one colon
     return IPV6_RE.test(value) && value.includes(':');
 }

package/dist/adapters/web-standard.js

@@ -123,7 +123,8 @@ export function createWebStandardMiddleware(engineOrConfig, upstreamArg) {
                     const tollCostHeader = res.headers.get('x-toll-cost');
                     if (tollCostHeader !== null && /^\d+$/.test(tollCostHeader)) {
                         const actualCost = parseInt(tollCostHeader, 10);
-                        if (Number.isSafeInteger(actualCost) && actualCost >= 0) {
+                        const maxAllowed = (result.estimatedCost ?? actualCost) * 10;
+                        if (Number.isSafeInteger(actualCost) && actualCost >= 0 && actualCost <= maxAllowed) {
                             const reconciled = engine.reconcile(result.paymentHash, actualCost);
                             if (reconciled.adjusted) {
                                 responseHeaders.set('X-Credit-Balance', String(reconciled.newBalance));

package/dist/backends/cln.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 import { PAYMENT_HASH_RE } from '../core/types.js';
 /**
  * Lightning backend adapter for Core Lightning's REST API (clnrest).
@@ -18,7 +19,7 @@ export function clnBackend(config) {
     };
     return {
         async createInvoice(amountSats, memo) {
-            const label = `toll-booth-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const label = `toll-booth-${Date.now()}-${randomBytes(6).toString('hex')}`;
             const res = await fetch(`${baseUrl}/v1/invoice`, {
                 method: 'POST',
                 headers: { ...headers, 'Content-Type': 'application/json' },

package/dist/booth.d.ts

@@ -34,6 +34,7 @@ export declare class Booth {
     private readonly rootKey;
     private readonly redeemCashu?;
     private readonly pruneTimer?;
+    private closed;
     constructor(config: BoothOptions & EventHandler);
     /** Reset free-tier counters for all IPs. */
     resetFreeTier(): void;

package/dist/booth.js

@@ -54,6 +54,7 @@ export class Booth {
     rootKey;
     redeemCashu;
     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');
@@ -159,6 +160,7 @@ export class Booth {
                 this.createInvoiceHandler = createExpressCreateInvoiceHandler({
                     deps: createInvoiceDeps,
                     trustProxy: config.trustProxy,
+                    getClientIp: config.getClientIp,
                 });
                 if (nwcPayDeps)
                     this.nwcPayHandler = createExpressNwcHandler(nwcPayDeps);
@@ -196,8 +198,8 @@ export class Booth {
         // Auto-recover any pending Cashu claims from a previous crash
         if (this.redeemCashu) {
             const fn = this.redeemCashu;
-            this.recoverPendingClaims(fn).catch(() => {
-                // Recovery failures are non-fatal; claims stay pending for next restart
+            this.recoverPendingClaims(fn).catch((err) => {
+                console.warn('[toll-booth] Cashu recovery failed:', err instanceof Error ? err.message : err);
             });
         }
     }
@@ -221,16 +223,29 @@ export class Booth {
         let recovered = 0;
         const renewIntervalMs = Math.max(1_000, Math.floor(REDEEM_LEASE_MS / 2));
         for (const claim of claims) {
+            if (this.closed)
+                break;
             // Respect active leases so startup recovery does not race in-flight requests
             // (or another process already handling this claim).
             const leasedClaim = this.storage.tryAcquireRecoveryLease(claim.paymentHash, REDEEM_LEASE_MS);
             if (!leasedClaim)
                 continue;
             const timer = setInterval(() => {
+                if (this.closed) {
+                    clearInterval(timer);
+                    return;
+                }
                 this.storage.extendRecoveryLease(leasedClaim.paymentHash, REDEEM_LEASE_MS);
             }, renewIntervalMs);
             try {
                 const credited = await redeemFn(leasedClaim.token, leasedClaim.paymentHash);
+                // Guard against overpayment (same check as handleCashuRedeem)
+                const invoice = this.storage.getInvoice(leasedClaim.paymentHash);
+                if (invoice?.amountSats !== undefined && credited > invoice.amountSats) {
+                    console.warn(`[toll-booth] Recovery: rejecting overpayment for ${leasedClaim.paymentHash}: ` +
+                        `expected ${invoice.amountSats}, got ${credited}`);
+                    continue;
+                }
                 if (this.storage.settleWithCredit(leasedClaim.paymentHash, credited)) {
                     recovered++;
                 }
@@ -246,6 +261,7 @@ export class Booth {
         return recovered;
     }
     close() {
+        this.closed = true;
         if (this.pruneTimer)
             clearInterval(this.pruneTimer);
         this.storage.close();

package/dist/core/cashu-redeem.js

@@ -41,6 +41,9 @@ export async function handleCashuRedeem(deps, request) {
                     if (credited < 0) {
                         return { success: false, error: 'Redeem callback returned negative amount', status: 500 };
                     }
+                    if (invoice.amountSats !== undefined && credited > invoice.amountSats) {
+                        return { success: false, error: 'Redeemed amount exceeds invoice amount', status: 400 };
+                    }
                     const settlementSecret = randomBytes(32).toString('hex');
                     const newlySettled = deps.storage.settleWithCredit(paymentHash, credited, settlementSecret);
                     return {
@@ -61,6 +64,14 @@ export async function handleCashuRedeem(deps, request) {
             if (credited < 0) {
                 return { success: false, error: 'Redeem callback returned negative amount', status: 500 };
             }
+            if (invoice.amountSats !== undefined && credited !== invoice.amountSats) {
+                console.warn(`[toll-booth] Cashu redeem amount mismatch for ${paymentHash}: ` +
+                    `expected ${invoice.amountSats}, got ${credited}`);
+                // Reject overpayment to prevent credit inflation via a malicious redeem callback
+                if (credited > invoice.amountSats) {
+                    return { success: false, error: 'Redeemed amount exceeds invoice amount', status: 400 };
+                }
+            }
             const settlementSecret = randomBytes(32).toString('hex');
             const newlySettled = deps.storage.settleWithCredit(paymentHash, credited, settlementSecret);
             return {

package/dist/core/l402-rail.js

@@ -70,8 +70,11 @@ export function createL402Rail(config) {
             // First-time settlement — credits the balance.
             // Only reachable with a valid proof (Lightning preimage or Cashu secret).
             // If settleWithCredit loses a race, another request already settled — continue.
+            // Use a random settlement secret rather than the raw preimage to avoid
+            // leaking the bearer credential via getSettlementSecret / invoice-status.
             if (!storage.isSettled(paymentHash)) {
-                storage.settleWithCredit(paymentHash, creditBalance, preimage);
+                const secret = randomBytes(32).toString('hex');
+                storage.settleWithCredit(paymentHash, creditBalance, secret);
             }
             // Return current balance — engine will debit and check sufficiency
             const remaining = storage.balance(paymentHash);

package/dist/core/x402-rail.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 import { DEFAULT_USDC_ASSETS } from './x402-types.js';
 export function createX402Rail(config) {
     const { receiverAddress, network, asset = DEFAULT_USDC_ASSETS[network], facilitator, creditMode = true, facilitatorUrl, storage, } = config;
@@ -51,9 +52,11 @@ export function createX402Rail(config) {
                     return { authenticated: false, paymentId: result.txHash || '', mode: 'per-request', currency: 'usd' };
                 }
                 // Credit mode: persist balance to storage (mirrors L402 rail's settleWithCredit).
-                // Use the txHash as the settlement secret since x402 has no preimage equivalent.
+                // Generate a random settlement secret; the txHash is public on-chain
+                // and must never be used as a bearer credential.
                 if (creditMode && storage && !storage.isSettled(result.txHash)) {
-                    storage.settleWithCredit(result.txHash, result.amount, result.txHash, 'usd');
+                    const settlementSecret = randomBytes(32).toString('hex');
+                    storage.settleWithCredit(result.txHash, result.amount, settlementSecret, 'usd');
                 }
                 const creditBalance = creditMode && storage
                     ? storage.balance(result.txHash, 'usd')

package/dist/demo.js

@@ -157,10 +157,23 @@ export async function startDemo() {
         storage,
     });
     // Gateway server
+    const MAX_BODY = 65_536;
     const server = createServer((nodeReq, nodeRes) => {
         const chunks = [];
-        nodeReq.on('data', (chunk) => chunks.push(chunk));
+        let totalBytes = 0;
+        nodeReq.on('data', (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > MAX_BODY) {
+                nodeReq.destroy();
+                nodeRes.statusCode = 413;
+                nodeRes.end('Request body too large');
+                return;
+            }
+            chunks.push(chunk);
+        });
         nodeReq.on('end', () => {
+            if (totalBytes > MAX_BODY)
+                return;
             const body = Buffer.concat(chunks);
             const webReq = toWebRequest(nodeReq, body);
             currentClientIp = nodeReq.socket.remoteAddress ?? '127.0.0.1';

package/dist/storage/memory.js

@@ -168,8 +168,18 @@ export function memoryStorage() {
             return pruned;
         },
         pruneStaleRecords(_maxAgeMs) {
-            // Memory storage is for testing only — no long-running pruning needed
-            return 0;
+            // Prune expired unsettled claims only. Settlement markers must never
+            // be removed; doing so would allow spent credentials to be replayed
+            // (isSettled returns false, settleWithCredit re-credits the balance).
+            let pruned = 0;
+            const now = Date.now();
+            for (const [hash, claim] of claims) {
+                if (!settled.has(hash) && now > claim.leaseExpiresAt + _maxAgeMs) {
+                    claims.delete(hash);
+                    pruned++;
+                }
+            }
+            return pruned;
         },
         close() {
             balances.clear();

package/dist/storage/sqlite.js

@@ -165,10 +165,9 @@ export function sqliteStorage(config) {
     WHERE balance_sats <= 0 AND balance_usd <= 0
       AND datetime(updated_at) <= datetime('now', '-' || ? || ' seconds')
   `);
-    const stmtPruneSettlements = db.prepare(`
-    DELETE FROM settlements
-    WHERE datetime(settled_at) <= datetime('now', '-' || ? || ' seconds')
-  `);
+    // Settlement markers must NEVER be pruned — doing so would allow spent
+    // credentials to be replayed (isSettled returns false, settleWithCredit
+    // re-credits the balance). This matches the memory storage invariant.
     const stmtPruneClaims = db.prepare(`
     DELETE FROM claims
     WHERE payment_hash IN (SELECT payment_hash FROM settlements)
@@ -368,7 +367,7 @@ export function sqliteStorage(config) {
             const maxAgeSecs = Math.floor(maxAgeMs / 1000);
             let total = 0;
             total += stmtPruneZeroCredits.run(maxAgeSecs).changes;
-            total += stmtPruneSettlements.run(maxAgeSecs).changes;
+            // Settlement markers are intentionally never pruned (replay protection).
             total += stmtPruneClaims.run(maxAgeSecs).changes;
             return total;
         }),

package/llms.txt

@@ -1,12 +1,12 @@
 # toll-booth
 
-> toll-booth lets AI agents discover, pay for, and consume any HTTP API using Lightning, Cashu, or NWC - no accounts, no API keys, no human in the loop. It's L402 payment middleware that embeds in your Node.js app as middleware, supporting Express 5, Deno, Bun, and Cloudflare Workers.
+> toll-booth lets AI agents discover, pay for, and consume any HTTP API using Lightning, Cashu, NWC, or x402 stablecoins - no accounts, no API keys, no human in the loop. It's payment-rail agnostic HTTP 402 middleware that embeds in your Node.js app, supporting Express 5, Hono, Deno, Bun, and Cloudflare Workers.
 
-toll-booth embeds in your existing Node.js application as middleware (not a separate proxy). It supports Express 5, Deno, Bun, and Cloudflare Workers. Five Lightning backends are supported (Phoenixd, LND, Core Lightning, LNbits, NWC), or you can run in Cashu-only mode with no Lightning node at all — ideal for serverless and edge deployments.
+toll-booth embeds in your existing Node.js application as middleware (not a separate proxy). It supports Express 5, Hono, Deno, Bun, and Cloudflare Workers. Five Lightning backends are supported (Phoenixd, LND, Core Lightning, LNbits, NWC), or you can run in Cashu-only mode with no Lightning node at all - ideal for serverless and edge deployments. x402 stablecoin payments (Coinbase's on-chain payment protocol) are also supported via a pluggable payment rail.
 
-The closest alternative is Aperture (Lightning Labs), a Go reverse proxy that requires LND. toll-booth is TypeScript middleware that works with any Lightning backend, runs serverless, and supports Cashu ecash payments.
+The closest alternative is Aperture (Lightning Labs), a Go reverse proxy that requires LND. toll-booth is TypeScript middleware that works with any Lightning backend, runs serverless, supports Cashu ecash, and accepts x402 stablecoins.
 
-Compared to x402 (Coinbase's on-chain stablecoin payment protocol), toll-booth settles in milliseconds over Lightning instead of waiting for block confirmations, charges fractions-of-a-sat routing fees instead of gas, and works with any Lightning wallet - no Coinbase dependency. As USDT-over-Lightning bridges go live, toll-booth APIs automatically accept stablecoins with zero code changes.
+Payment rails are pluggable - a single toll-booth deployment can accept Lightning, Cashu, and x402 stablecoins simultaneously. The seller doesn't care how they get paid.
 
 Try it instantly: `npx @thecryptodonkey/toll-booth demo`
 
@@ -62,7 +62,8 @@ const booth = new Booth({
 - **Payment methods** — Lightning (via any backend), Cashu ecash tokens (via `redeemCashu` callback), or Nostr Wallet Connect (via `nwcPayInvoice` callback). Methods can be combined.
 - **Credit system** — payments grant a credit balance. Each request deducts from the balance. Volume discount tiers available via `creditTiers`.
 - **Free tier** — optional per-IP daily allowance. Request-based: `freeTier: { requestsPerDay: N }`. Usage-based: `freeTier: { creditsPerDay: N }` (daily sats budget debited by each request's cost). Requests within the allowance bypass payment.
-- **Adapters** — `'express'` for Express 4/5, `'web-standard'` for Deno, Bun, and Cloudflare Workers.
+- **Payment rails** — pluggable payment rail abstraction (`PaymentRail` interface). Built-in rails: `createL402Rail()` for Lightning/macaroon auth, `createX402Rail()` for on-chain stablecoin payments. Multiple rails can run simultaneously on the same deployment.
+- **Adapters** — `'express'` for Express 4/5, `'web-standard'` for Deno, Bun, and Cloudflare Workers, `'hono'` for Hono. For Hono, use `createHonoTollBooth()` directly for idiomatic integration (auth middleware + payment route sub-app).
 
 ## API Surface
 
@@ -78,6 +79,11 @@ Subpath imports for tree-shaking:
 - `@thecryptodonkey/toll-booth/storage/memory` — in-memory storage (testing)
 - `@thecryptodonkey/toll-booth/adapters/express` — Express middleware factory
 - `@thecryptodonkey/toll-booth/adapters/web-standard` — Web Standard handler factory
+- `@thecryptodonkey/toll-booth/hono` — Hono middleware + payment route sub-app (`createHonoTollBooth`)
+
+Payment rail factories (for multi-rail setups):
+- `createL402Rail(config)` — L402 Lightning + macaroon rail
+- `createX402Rail(config)` — x402 on-chain stablecoin rail (requires a facilitator)
 
 Booth instance properties:
 - `.middleware` — main request handler (checks auth, proxies upstream)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecryptodonkey/toll-booth",
-  "version": "3.2.2",
+  "version": "3.2.5",
   "type": "module",
   "description": "Monetise any API with HTTP 402 payments. Payment-rail agnostic middleware for Express, Hono, Deno, Bun, and Workers.",
   "license": "MIT",
@@ -27,7 +27,9 @@
     "api-monetisation",
     "payment-gateway",
     "ai-agents",
-    "machine-payments"
+    "machine-payments",
+    "api-monetization",
+    "x402"
   ],
   "repository": {
     "type": "git",
@@ -87,6 +89,7 @@
   "files": [
     "dist",
     "!dist/**/*.map",
+    "!dist/**/*.d.ts.map",
     "llms.txt"
   ],
   "scripts": {