@thecryptodonkey/toll-booth 1.0.0

package/dist/storage/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/storage/sqlite.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Core type definitions for toll-booth.
+ *
+ * toll-booth is a generic L402 Lightning payment middleware for gating
+ * any HTTP API behind a Lightning Network paywall.
+ */
+/**
+ * A Lightning invoice returned from a backend after creation.
+ */
+export interface Invoice {
+    /** The BOLT 11 payment request string. */
+    bolt11: string;
+    /** The payment hash that identifies this invoice. */
+    paymentHash: string;
+}
+/**
+ * The current status of a Lightning invoice.
+ */
+export interface InvoiceStatus {
+    /** Whether the invoice has been paid. */
+    paid: boolean;
+    /** The payment preimage, present only if the invoice has been paid. */
+    preimage?: string;
+}
+/**
+ * Abstraction over a Lightning node backend.
+ *
+ * Implement this interface to add support for a new Lightning node type
+ * (e.g. phoenixd, LND, CLN).
+ */
+export interface LightningBackend {
+    /**
+     * Create a new Lightning invoice for the given amount.
+     * @param amountSats - Amount in satoshis.
+     * @param memo - Optional human-readable invoice description.
+     * @returns The created invoice.
+     */
+    createInvoice(amountSats: number, memo?: string): Promise<Invoice>;
+    /**
+     * Check the payment status of an existing invoice.
+     * @param paymentHash - The payment hash of the invoice to check.
+     * @returns The current invoice status.
+     */
+    checkInvoice(paymentHash: string): Promise<InvoiceStatus>;
+}
+/**
+ * Pricing table mapping route patterns to amounts in satoshis.
+ *
+ * Keys are route patterns (e.g. `"/route"`) and values are the
+ * required payment amount in satoshis.
+ */
+export type PricingTable = Record<string, number>;
+/**
+ * A credit tier offering volume discounts.
+ *
+ * The `amountSats` is what the user pays; `creditSats` is what they receive.
+ * When `creditSats > amountSats`, the difference is the volume discount.
+ */
+export interface CreditTier {
+    /** Amount the user pays in satoshis. */
+    amountSats: number;
+    /** Credits received in satoshis (may exceed amountSats for volume discounts). */
+    creditSats: number;
+    /** Human-readable label for this tier. */
+    label: string;
+}
+/**
+ * Configuration for a toll-booth instance.
+ */
+export interface BoothConfig {
+    /**
+     * The Lightning backend to use for invoice creation and status checks.
+     * Optional when using Cashu-only mode (`redeemCashu` provided without a backend).
+     */
+    backend?: LightningBackend;
+    /**
+     * Pricing table mapping route patterns to amounts in satoshis.
+     * Routes not listed here use `defaultInvoiceAmount` if set.
+     */
+    pricing: PricingTable;
+    /** The upstream URL to proxy authorised requests to. */
+    upstream: string;
+    /**
+     * Optional free-tier configuration. Requests matching these criteria
+     * bypass the payment requirement.
+     */
+    freeTier?: {
+        requestsPerDay: number;
+    };
+    /**
+     * Default invoice amount in satoshis. Controls how many credits are
+     * minted per invoice, and is also used as the route cost when
+     * `strictPricing` challenges an unpriced route.
+     */
+    defaultInvoiceAmount?: number;
+    /**
+     * When true, unpriced routes are challenged (402) using `defaultInvoiceAmount`
+     * as the cost, instead of being passed through for free. This prevents
+     * mount-prefix mismatches or typos from silently bypassing billing.
+     */
+    strictPricing?: boolean;
+    /**
+     * Root key used for macaroon generation and verification, as a
+     * hex-encoded 32-byte string.
+     * If omitted, a random key is generated at startup (not recommended for
+     * production use, as tokens will be invalidated on restart).
+     */
+    rootKey?: string;
+    /**
+     * Path to the SQLite database file used for invoice persistence.
+     * Defaults to `./toll-booth.db` in the current working directory.
+     */
+    dbPath?: string;
+    /**
+     * Trust reverse-proxy headers (`X-Forwarded-For` / `X-Real-IP`) for client IP.
+     * Keep disabled unless a trusted proxy overwrites these headers.
+     */
+    trustProxy?: boolean;
+    /**
+     * Custom callback to resolve the client IP for adapters that cannot infer
+     * it directly (for example Deno, Bun, or Cloudflare Workers).
+     * The callback receives the adapter-specific request object.
+     */
+    getClientIp?: (request: unknown) => string;
+    /**
+     * Extra headers to include on every response (e.g. `{ 'X-Coverage': 'GB' }`).
+     * Replaces the previously hardcoded `X-Coverage: GB` header.
+     */
+    responseHeaders?: Record<string, string>;
+    /**
+     * Credit tiers with optional volume discounts.
+     * Used by the payment page tier selector and the `/create-invoice` endpoint.
+     */
+    creditTiers?: CreditTier[];
+    /**
+     * Pay a Lightning invoice via Nostr Wallet Connect.
+     * Accepts NWC URI + bolt11, returns the payment preimage.
+     * When provided, the payment page shows an NWC option.
+     */
+    nwcPayInvoice?: (nwcUri: string, bolt11: string) => Promise<string>;
+    /**
+     * Redeem a Cashu token as payment.
+     * Returns the credited amount in satoshis. Implementations should be
+     * idempotent for the same `paymentHash` if you rely on retry/recovery.
+     * When provided, the payment page shows a Cashu option.
+     */
+    redeemCashu?: (token: string, paymentHash: string) => Promise<number>;
+    /**
+     * Timeout in milliseconds for upstream proxy requests.
+     * Defaults to 30000 (30 seconds).
+     */
+    upstreamTimeout?: number;
+    /**
+     * Maximum age of stored invoices in milliseconds. Invoices older than
+     * this are periodically pruned. Set to 0 to disable pruning.
+     * Default: 86400000 (24 hours).
+     */
+    invoiceMaxAgeMs?: number;
+}
+/**
+ * A record of a payment event stored for audit and idempotency purposes.
+ */
+export interface PaymentEvent {
+    timestamp: string;
+    paymentHash: string;
+    amountSats: number;
+}
+/**
+ * A record of an incoming HTTP request, used for analytics and
+ * free-tier tracking.
+ */
+export interface RequestEvent {
+    timestamp: string;
+    endpoint: string;
+    satsDeducted: number;
+    remainingBalance: number;
+    latencyMs: number;
+    authenticated: boolean;
+    clientIp: string;
+}
+/**
+ * A record of a 402 challenge issued to a client.
+ */
+export interface ChallengeEvent {
+    timestamp: string;
+    endpoint: string;
+    amountSats: number;
+    clientIp: string;
+}
+/**
+ * Optional event handlers for observing toll-booth lifecycle events.
+ */
+export type EventHandler = {
+    onPayment?: (event: PaymentEvent) => void;
+    onRequest?: (event: RequestEvent) => void;
+    onChallenge?: (event: ChallengeEvent) => void;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core type definitions for toll-booth.
+ *
+ * toll-booth is a generic L402 Lightning payment middleware for gating
+ * any HTTP API behind a Lightning Network paywall.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/llms.txt

@@ -0,0 +1,91 @@
+# toll-booth
+
+> APIs gate access through accounts, API keys, and credit cards — mechanisms that assume a human on the other end. Machines and AI agents can't sign up for accounts. toll-booth is L402 payment middleware that lets any HTTP API accept instant payments — Lightning, Cashu ecash, or Nostr Wallet Connect — with no accounts, no API keys, and no PII exchanged.
+
+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, Alby), or you can run in Cashu-only mode with no Lightning node at all — ideal for serverless and edge deployments.
+
+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.
+
+## Getting Started
+
+```bash
+npm install @thecryptodonkey/toll-booth
+```
+
+```typescript
+import express from 'express'
+import { Booth } from '@thecryptodonkey/toll-booth'
+import { phoenixdBackend } from '@thecryptodonkey/toll-booth/backends/phoenixd'
+
+const app = express()
+app.use(express.json())
+
+const booth = new Booth({
+  adapter: 'express',
+  backend: phoenixdBackend({
+    url: 'http://localhost:9740',
+    password: process.env.PHOENIXD_PASSWORD!,
+  }),
+  pricing: { '/api': 10 },
+  upstream: 'http://localhost:8080',
+})
+
+app.get('/invoice-status/:paymentHash', booth.invoiceStatusHandler as any)
+app.post('/create-invoice', booth.createInvoiceHandler as any)
+app.use('/', booth.middleware as any)
+app.listen(3000)
+```
+
+For Cashu-only mode (no Lightning node required):
+
+```typescript
+const booth = new Booth({
+  adapter: 'web-standard',
+  redeemCashu: async (token, paymentHash) => {
+    // Verify and redeem the ecash token with your Cashu mint
+    return amountRedeemed
+  },
+  pricing: { '/api': 5 },
+  upstream: 'http://localhost:8080',
+})
+```
+
+## Key Concepts
+
+- **Booth** — the main facade class. Instantiate with a config object, then wire `.middleware`, `.invoiceStatusHandler`, and `.createInvoiceHandler` into your router.
+- **LightningBackend** — interface with two methods: `createInvoice(amountSats, memo?)` and `checkInvoice(paymentHash)`. Five implementations provided; implement your own for custom backends.
+- **L402 flow** — client requests a priced endpoint, receives HTTP 402 with a Lightning invoice and macaroon, pays the invoice, then sends `Authorization: L402 <macaroon>:<preimage>` to access the API.
+- **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 request allowance (`freeTier: { requestsPerDay: N }`). Requests under the limit bypass payment.
+- **Adapters** — `'express'` for Express 4/5, `'web-standard'` for Deno, Bun, and Cloudflare Workers.
+
+## API Surface
+
+Main entry point: `import { Booth } from '@thecryptodonkey/toll-booth'`
+
+Subpath imports for tree-shaking:
+- `@thecryptodonkey/toll-booth/backends/phoenixd` — Phoenixd backend
+- `@thecryptodonkey/toll-booth/backends/lnd` — LND backend
+- `@thecryptodonkey/toll-booth/backends/cln` — Core Lightning backend
+- `@thecryptodonkey/toll-booth/backends/lnbits` — LNbits backend
+- `@thecryptodonkey/toll-booth/backends/alby` — Alby / NWC backend
+- `@thecryptodonkey/toll-booth/storage/sqlite` — SQLite storage (default)
+- `@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
+
+Booth instance properties:
+- `.middleware` — main request handler (checks auth, proxies upstream)
+- `.invoiceStatusHandler` — GET /invoice-status/:paymentHash
+- `.createInvoiceHandler` — POST /create-invoice
+- `.nwcPayHandler` — POST /nwc-pay (when nwcPayInvoice configured)
+- `.cashuRedeemHandler` — POST /cashu-redeem (when redeemCashu configured)
+- `.resetFreeTier()` — reset daily free-tier counters
+- `.close()` — clean up timers and database connections
+
+## Optional
+
+- [Vision: The Vending Machine Web](docs/vision.md) — why L402 and permissionless machine-to-machine payments matter
+- [Example: Valhalla routing proxy](examples/valhalla-proxy/) — complete Docker Compose deployment gating a routing engine behind Lightning payments
+- [Production checklist](README.md#production-checklist) — deployment best practices

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@thecryptodonkey/toll-booth",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "L402 Lightning payment middleware for any Node.js framework — Express, Deno, Bun",
+  "license": "MIT",
+  "keywords": [
+    "l402", "lightning", "paywall", "micropayments", "middleware",
+    "cashu", "ecash", "nostr", "nwc", "bitcoin",
+    "express", "deno", "bun", "cloudflare-workers", "serverless",
+    "macaroon", "http-402", "api-monetisation", "payment-gateway"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheCryptoDonkey/toll-booth.git"
+  },
+  "homepage": "https://github.com/TheCryptoDonkey/toll-booth#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./backends/phoenixd": {
+      "import": "./dist/backends/phoenixd.js",
+      "types": "./dist/backends/phoenixd.d.ts"
+    },
+    "./backends/lnd": {
+      "import": "./dist/backends/lnd.js",
+      "types": "./dist/backends/lnd.d.ts"
+    },
+    "./backends/cln": {
+      "import": "./dist/backends/cln.js",
+      "types": "./dist/backends/cln.d.ts"
+    },
+    "./backends/alby": {
+      "import": "./dist/backends/alby.js",
+      "types": "./dist/backends/alby.d.ts"
+    },
+    "./backends/lnbits": {
+      "import": "./dist/backends/lnbits.js",
+      "types": "./dist/backends/lnbits.d.ts"
+    },
+    "./storage/sqlite": {
+      "import": "./dist/storage/sqlite.js",
+      "types": "./dist/storage/sqlite.d.ts"
+    },
+    "./storage/memory": {
+      "import": "./dist/storage/memory.js",
+      "types": "./dist/storage/memory.d.ts"
+    },
+    "./adapters/express": {
+      "import": "./dist/adapters/express.js",
+      "types": "./dist/adapters/express.d.ts"
+    },
+    "./adapters/web-standard": {
+      "import": "./dist/adapters/web-standard.js",
+      "types": "./dist/adapters/web-standard.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "test:integration": "bash scripts/test-integration.sh",
+    "test:integration:ln": "bash scripts/test-integration.sh --ln-only",
+    "test:integration:cashu": "bash scripts/test-integration.sh --cashu-only",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.8.0",
+    "macaroon": "^3.0.4",
+    "qrcode": "^1.5.4"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cashu/cashu-ts": "^3.5.0",
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/express": "^5.0.6",
+    "@types/qrcode": "^1.5.6",
+    "@types/ws": "^8.18.1",
+    "express": "^5.2.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "ws": "^8.19.0"
+  }
+}