@thecryptodonkey/toll-booth 3.2.2 → 3.2.4

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

@@ -233,11 +233,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/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.js

@@ -159,6 +159,7 @@ export class Booth {
                 this.createInvoiceHandler = createExpressCreateInvoiceHandler({
                     deps: createInvoiceDeps,
                     trustProxy: config.trustProxy,
+                    getClientIp: config.getClientIp,
                 });
                 if (nwcPayDeps)
                     this.nwcPayHandler = createExpressNwcHandler(nwcPayDeps);
@@ -231,6 +232,13 @@ export class Booth {
             }, 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++;
                 }

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.4",
   "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": {