@thecryptodonkey/toll-booth 3.2.1 → 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

@@ -162,6 +162,7 @@ export function createExpressMiddleware(engineOrConfig, upstreamArg) {
         }
         catch (err) {
             // Distinguish upstream network errors from programming errors
+            setSensitiveHeaders(res);
             if (err instanceof TypeError && (err.message.includes('fetch') || err.message.includes('network'))) {
                 res.status(502).json({ error: 'Upstream unavailable' });
             }
@@ -232,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/hono.js

@@ -7,9 +7,44 @@ import { handleNwcPay } from '../core/nwc-pay.js';
 import { handleCashuRedeem } from '../core/cashu-redeem.js';
 import { applySecurityHeaders, appendVary, parseForwardedIp } from './proxy-headers.js';
 const MAX_BODY_BYTES = 65_536;
+/**
+ * Reads the request body as text with a streaming byte limit.
+ * Aborts mid-stream when the limit is exceeded, preventing memory
+ * exhaustion from large chunked requests without a Content-Length header.
+ */
+async function readBodyTextWithinLimit(c, maxBytes) {
+    const body = c.req.raw.body;
+    if (!body)
+        return '';
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let totalBytes = 0;
+    let text = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            totalBytes += value.byteLength;
+            if (totalBytes > maxBytes) {
+                await reader.cancel();
+                return undefined;
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+        return text + decoder.decode();
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 /**
  * Parses request body as JSON with a size limit.
  * Returns undefined on oversized, empty, or malformed bodies.
+ * Uses streaming reads to abort early on large chunked payloads.
  */
 async function safeParseJson(c, maxBytes = MAX_BODY_BYTES) {
     const contentLength = c.req.header('content-length');
@@ -19,8 +54,8 @@ async function safeParseJson(c, maxBytes = MAX_BODY_BYTES) {
             return undefined;
     }
     try {
-        const text = await c.req.text();
-        if (new TextEncoder().encode(text).byteLength > maxBytes)
+        const text = await readBodyTextWithinLimit(c, maxBytes);
+        if (text === undefined)
             return undefined;
         if (!text.trim())
             return {};
@@ -44,6 +79,12 @@ async function safeParseJson(c, maxBytes = MAX_BODY_BYTES) {
  */
 export function createHonoTollBooth(config) {
     const { engine } = config;
+    // Warn when free-tier is enabled without trustProxy or getClientIp
+    if (engine.freeTier && !config.trustProxy && !config.getClientIp) {
+        console.error('[toll-booth] WARNING: freeTier enabled without trustProxy in Hono adapter. ' +
+            'All clients will share the 0.0.0.0 IP bucket. ' +
+            'Set trustProxy: true or provide a getClientIp callback.');
+    }
     const authMiddleware = async (c, next) => {
         const req = c.req.raw;
         const ip = config.getClientIp?.(c)

package/dist/adapters/proxy-headers.js

@@ -39,6 +39,7 @@ export function applySecurityHeaders(headers) {
     headers.set('X-Frame-Options', 'DENY');
     headers.set('Referrer-Policy', 'no-referrer');
     headers.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()');
+    headers.set('Content-Security-Policy', "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; form-action 'none'; frame-ancestors 'none'");
     return headers;
 }
 export function appendVary(headers, value) {
@@ -58,11 +59,16 @@ export function appendVary(headers, value) {
  * via crafted X-Forwarded-For headers.
  */
 const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
-const IPV6_RE = /^[0-9a-fA-F:]+$/;
+const IPV6_RE = /^[0-9a-fA-F:]{2,45}$/;
 export function isPlausibleIp(value) {
     if (!value || value.length > 45)
         return false;
-    return IPV4_RE.test(value) || IPV6_RE.test(value);
+    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(':');
 }
 /**
  * Extracts and validates the client IP from an X-Forwarded-For header value.

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/backends/nwc.js

@@ -46,6 +46,9 @@ export function nwcBackend(config) {
             return { bolt11: tx.invoice, paymentHash: tx.payment_hash };
         },
         async checkInvoice(paymentHash) {
+            if (!/^[0-9a-f]{64}$/.test(paymentHash)) {
+                return { paid: false };
+            }
             const nwc = await getClient();
             try {
                 const tx = await nwc.lookupInvoice({ payment_hash: paymentHash });

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/toll-booth.js

@@ -160,13 +160,24 @@ export function createTollBooth(config) {
                         }
                         // Track estimated cost with currency for reconciliation
                         if (result.paymentId) {
-                            // Evict stale entries
+                            // Evict stale entries; if still at cap, drop oldest entries
                             if (estimatedCosts.size >= MAX_ESTIMATED_COSTS) {
                                 const now = Date.now();
                                 for (const [key, entry] of estimatedCosts) {
                                     if (now - entry.ts > MAX_AGE_MS)
                                         estimatedCosts.delete(key);
                                 }
+                                // Force-evict oldest entries if still at capacity
+                                if (estimatedCosts.size >= MAX_ESTIMATED_COSTS) {
+                                    const overflow = estimatedCosts.size - MAX_ESTIMATED_COSTS + 1;
+                                    let evicted = 0;
+                                    for (const key of estimatedCosts.keys()) {
+                                        if (evicted >= overflow)
+                                            break;
+                                        estimatedCosts.delete(key);
+                                        evicted++;
+                                    }
+                                }
                             }
                             estimatedCosts.set(result.paymentId, { cost, ts: Date.now(), currency: result.currency });
                         }

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;
@@ -50,9 +51,12 @@ export function createX402Rail(config) {
                 if (!result.valid) {
                     return { authenticated: false, paymentId: result.txHash || '', mode: 'per-request', currency: 'usd' };
                 }
-                // Credit mode: persist balance to storage (mirrors L402 rail's settleWithCredit)
+                // Credit mode: persist balance to storage (mirrors L402 rail's settleWithCredit).
+                // 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, undefined, '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/free-tier.js

@@ -1,13 +1,17 @@
 // src/free-tier.ts
 /** Maximum number of distinct IPs tracked before new IPs are denied. */
 const MAX_TRACKED_IPS = 100_000;
-/** Plausible IP format check to prevent arbitrary strings filling the tracking map. */
+/**
+ * Validates that a string is a plausible IP address or IP hash.
+ * More permissive than the proxy-headers version because the toll-booth
+ * engine passes hashIp() output (32-char hex) to freeTier.check().
+ */
 const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
-const IPV6_RE = /^[0-9a-fA-F:]+$/;
-function isPlausibleIp(value) {
-    if (!value || value.length > 45)
+const HEX_OR_IPV6_RE = /^[0-9a-fA-F:]{2,64}$/;
+function isPlausibleIpOrHash(value) {
+    if (!value || value.length > 64)
         return false;
-    return IPV4_RE.test(value) || IPV6_RE.test(value);
+    return IPV4_RE.test(value) || HEX_OR_IPV6_RE.test(value);
 }
 export class FreeTier {
     requestsPerDay;
@@ -25,7 +29,7 @@ export class FreeTier {
     }
     check(ip, _cost) {
         // Reject non-IP strings to prevent arbitrary values filling the tracking map
-        if (!isPlausibleIp(ip)) {
+        if (!isPlausibleIpOrHash(ip)) {
             return { allowed: false, remaining: 0 };
         }
         const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
@@ -66,7 +70,7 @@ export class CreditFreeTier {
     }
     check(ip, cost) {
         // Reject non-IP strings to prevent arbitrary values filling the tracking map
-        if (!isPlausibleIp(ip)) {
+        if (!isPlausibleIpOrHash(ip)) {
             return { allowed: false, remaining: 0 };
         }
         const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD

package/dist/storage/memory.js

@@ -161,14 +161,25 @@ export function memoryStorage() {
             for (const [hash, inv] of invoices) {
                 if (inv.createdAt < cutoff && !claims.has(hash)) {
                     invoices.delete(hash);
+                    invoiceIps.delete(hash);
                     pruned++;
                 }
             }
             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)
@@ -364,14 +363,14 @@ export function sqliteStorage(config) {
             const result = stmtPruneInvoices.run(maxAgeSecs);
             return result.changes;
         },
-        pruneStaleRecords(maxAgeMs) {
+        pruneStaleRecords: db.transaction((maxAgeMs) => {
             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;
-        },
+        }),
         close() {
             db.close();
         },

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