x402-lite 0.1.0

package/README.md

@@ -0,0 +1,167 @@
+# x402-lite
+
+Lightweight x402 payment middleware for Express. **Zero crypto dependencies.**
+
+The official `x402-express` package pulls in viem, Solana SDK, and CDP SDK (~100MB+ of node_modules). This package does the same job with **zero dependencies** by delegating verification and settlement to the [x402 facilitator](https://x402.org).
+
+Perfect for Raspberry Pi, edge devices, serverless functions, and anywhere you want x402 payments without the dependency bloat.
+
+## Install
+
+```bash
+npm install x402-lite express
+```
+
+## Quick Start
+
+```js
+const express = require("express");
+const { paymentMiddleware } = require("x402-lite");
+
+const app = express();
+app.use(express.json());
+
+// Health check (free)
+app.get("/health", (req, res) => res.json({ status: "ok" }));
+
+// Protect routes with x402 payments
+app.use(paymentMiddleware("0xYourWalletAddress", {
+  "GET /api/data": {
+    price: "$0.01",
+    network: "base",
+    config: {
+      description: "Get some data",
+    },
+  },
+}));
+
+app.get("/api/data", (req, res) => {
+  res.json({ data: "You paid $0.01 for this!" });
+});
+
+app.listen(3000);
+```
+
+Test it:
+
+```bash
+# Should return 402 with payment requirements
+curl -i http://localhost:3000/api/data
+
+# Health check (free)
+curl http://localhost:3000/health
+```
+
+## Why x402-lite?
+
+| | x402-express | x402-lite |
+|---|---|---|
+| Dependencies | viem, @solana/kit, @coinbase/cdp-sdk, ... | **none** |
+| node_modules size | ~100MB+ | **0 bytes** |
+| Install time | minutes | **instant** |
+| Works on Pi/edge | OOM kills likely | **yes** |
+| EVM support | ✓ | ✓ |
+| Solana support | ✓ | ✗ (EVM only) |
+| Local verification | ✓ | ✗ (facilitator only) |
+
+**Trade-off:** x402-lite requires network access to the facilitator for verification/settlement. If you need offline verification or Solana support, use the official package.
+
+## API
+
+### `paymentMiddleware(payTo, routes, options?)`
+
+Creates Express middleware that enforces x402 payments.
+
+**Parameters:**
+
+| Param | Type | Description |
+|---|---|---|
+| `payTo` | `string` | Ethereum address to receive USDC payments |
+| `routes` | `object` | Route config (see below) |
+| `options.facilitatorUrl` | `string?` | Custom facilitator (default: `https://x402.org/facilitator`) |
+
+**Route config:**
+
+```js
+{
+  // Simple — just a price (defaults to base network)
+  "GET /api/cheap": "$0.001",
+
+  // Full config
+  "POST /api/query": {
+    price: "$0.05",
+    network: "base",          // "base" or "base-sepolia"
+    config: {
+      description: "What this endpoint does",
+      inputSchema: {
+        bodyType: "json",
+        bodyFields: {
+          query: { type: "string", description: "Search query" },
+        },
+      },
+      outputSchema: {
+        type: "object",
+        properties: {
+          result: { type: "string" },
+        },
+      },
+    },
+  },
+
+  // Wildcard — protects all routes under /api/
+  "GET /api/*": "$0.01",
+}
+```
+
+### Route Matching
+
+- `"GET /path"` — matches specific method + path
+- `"/path"` — matches any method
+- `"/path/*"` — wildcard, matches anything under `/path/`
+- `"GET /users/:id"` — parameter matching
+
+### Exported Utilities
+
+```js
+const { priceToAtomic, matchRoute, USDC_CONFIG } = require("x402-lite");
+
+priceToAtomic("$0.01");  // "10000" (USDC has 6 decimals)
+USDC_CONFIG["base"];      // { chainId: 8453, address: "0x833...", decimals: 6 }
+```
+
+## How It Works
+
+1. Client hits a protected endpoint without `X-PAYMENT` header
+2. Server returns **HTTP 402** with payment requirements in `X-PAYMENT-REQUIRED` header and JSON body
+3. Client signs a USDC payment and retries with `X-PAYMENT` header (base64 JSON)
+4. Server forwards payment to the **facilitator** (`x402.org/facilitator`) for verification
+5. If valid, server processes the request and calls facilitator to settle
+6. Settlement response returned in `X-PAYMENT-RESPONSE` header
+
+All crypto operations happen at the facilitator — your server never touches private keys or blockchain RPCs.
+
+## Networks
+
+| Network | Chain ID | USDC Address |
+|---|---|---|
+| `base` | 8453 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
+| `base-sepolia` | 84532 | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
+
+## Testing
+
+```bash
+node test.js
+```
+
+## Pricing Guidelines
+
+| Use Case | Suggested Price |
+|---|---|
+| Simple data lookup | $0.001 – $0.01 |
+| API proxy / enrichment | $0.01 – $0.10 |
+| Compute-heavy query | $0.10 – $0.50 |
+| AI inference | $0.05 – $1.00 |
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,270 @@
+/**
+ * x402-lite — Lightweight x402 payment middleware for Express
+ * 
+ * Zero crypto dependencies. Delegates all verification and settlement
+ * to the x402 facilitator service. Works on Raspberry Pi, edge devices,
+ * and resource-constrained environments.
+ * 
+ * Usage:
+ *   const { paymentMiddleware } = require("x402-lite");
+ *   app.use(paymentMiddleware("0xYourAddress", {
+ *     "POST /api/data": { price: "$0.01", network: "base" }
+ *   }));
+ */
+
+const DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
+
+// USDC contract addresses per chain
+const USDC_CONFIG = {
+  "base": {
+    chainId: 8453,
+    address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    name: "USD Coin",
+    decimals: 6,
+  },
+  "base-sepolia": {
+    chainId: 84532,
+    address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    name: "USDC",
+    decimals: 6,
+  },
+};
+
+/**
+ * Parse a price string like "$0.01" or "0.01" into atomic USDC units (6 decimals)
+ */
+function priceToAtomic(price) {
+  if (typeof price === "number") return String(Math.round(price * 1e6));
+  const str = String(price).replace(/^\$/, "").trim();
+  const num = parseFloat(str);
+  if (isNaN(num)) throw new Error(`Invalid price: ${price}`);
+  return String(Math.round(num * 1e6));
+}
+
+/**
+ * Match a request to a route pattern
+ * Supports: "GET /path", "POST /path", "/path" (any method), "/path/*" (wildcard)
+ */
+function matchRoute(routes, method, path) {
+  for (const [pattern, config] of Object.entries(routes)) {
+    const parts = pattern.trim().split(/\s+/);
+    let routeMethod = null;
+    let routePath;
+
+    if (parts.length === 2) {
+      routeMethod = parts[0].toUpperCase();
+      routePath = parts[1];
+    } else {
+      routePath = parts[0];
+    }
+
+    // Check method
+    if (routeMethod && routeMethod !== method.toUpperCase()) continue;
+
+    // Check path (simple glob: * matches anything)
+    if (routePath === path) return config;
+    if (routePath.endsWith("/*")) {
+      const prefix = routePath.slice(0, -2);
+      if (path === prefix || path.startsWith(prefix + "/")) return config;
+    }
+
+    // Express-style :param matching
+    const routeSegments = routePath.split("/");
+    const pathSegments = path.split("/");
+    if (routeSegments.length === pathSegments.length) {
+      const match = routeSegments.every((seg, i) =>
+        seg.startsWith(":") || seg === pathSegments[i]
+      );
+      if (match) return config;
+    }
+  }
+  return null;
+}
+
+/**
+ * Normalize route config — accepts string price or full config object
+ */
+function normalizeConfig(config) {
+  if (typeof config === "string") {
+    return { price: config, network: "base" };
+  }
+  return config;
+}
+
+/**
+ * Build PaymentRequirements for a route
+ */
+function buildPaymentRequirements(payTo, routeConfig, req) {
+  const { price, network = "base", config: meta = {} } = normalizeConfig(routeConfig);
+  const usdc = USDC_CONFIG[network];
+  if (!usdc) throw new Error(`Unsupported network: ${network}`);
+
+  const maxAmountRequired = priceToAtomic(price);
+  const resource = `${req.protocol}://${req.headers.host}${req.path}`;
+
+  return {
+    scheme: "exact",
+    network,
+    maxAmountRequired,
+    resource,
+    description: meta.description || "",
+    mimeType: meta.mimeType || "",
+    payTo,
+    maxTimeoutSeconds: meta.maxTimeoutSeconds || 60,
+    asset: usdc.address,
+    outputSchema: {
+      input: {
+        type: "http",
+        method: req.method.toUpperCase(),
+        discoverable: meta.discoverable !== false,
+        ...(meta.inputSchema || {}),
+      },
+      output: meta.outputSchema || undefined,
+    },
+    extra: undefined,
+  };
+}
+
+/**
+ * Call the facilitator's verify endpoint
+ */
+async function verifyPayment(facilitatorUrl, paymentPayload, paymentRequirements) {
+  const res = await fetch(`${facilitatorUrl}/verify`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      x402Version: paymentPayload.x402Version || 1,
+      paymentPayload,
+      paymentRequirements,
+    }),
+  });
+
+  const data = await res.json();
+  if (res.status !== 200 || !data.isValid) {
+    return { valid: false, error: data };
+  }
+  return { valid: true, data };
+}
+
+/**
+ * Call the facilitator's settle endpoint
+ */
+async function settlePayment(facilitatorUrl, paymentPayload, paymentRequirements) {
+  try {
+    const res = await fetch(`${facilitatorUrl}/settle`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        x402Version: paymentPayload.x402Version || 1,
+        paymentPayload,
+        paymentRequirements,
+      }),
+    });
+    const data = await res.json();
+    return data;
+  } catch (err) {
+    // Settlement failure shouldn't block the response — log it
+    console.error("[x402-lite] Settlement error:", err.message);
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * Creates Express middleware that enforces x402 payments.
+ * 
+ * @param {string} payTo - Ethereum address to receive payments
+ * @param {object} routes - Route config: { "METHOD /path": { price, network, config } }
+ * @param {object} [options] - Optional settings
+ * @param {string} [options.facilitatorUrl] - Custom facilitator URL (default: x402.org)
+ * @returns {function} Express middleware
+ * 
+ * @example
+ * const { paymentMiddleware } = require("x402-lite");
+ * 
+ * app.use(paymentMiddleware("0x1234...", {
+ *   "GET /api/data": { price: "$0.01", network: "base" },
+ *   "POST /api/query": {
+ *     price: "$0.05",
+ *     network: "base",
+ *     config: {
+ *       description: "Query the database",
+ *       inputSchema: { bodyType: "json", bodyFields: { q: { type: "string" } } },
+ *       outputSchema: { type: "object", properties: { result: { type: "string" } } },
+ *     }
+ *   }
+ * }));
+ */
+function paymentMiddleware(payTo, routes, options = {}) {
+  const facilitatorUrl = options.facilitatorUrl || DEFAULT_FACILITATOR_URL;
+
+  return async function x402Middleware(req, res, next) {
+    // Find matching route
+    const routeConfig = matchRoute(routes, req.method, req.path);
+    if (!routeConfig) return next(); // No payment required for this route
+
+    const paymentRequirements = buildPaymentRequirements(payTo, routeConfig, req);
+
+    // Check for payment header
+    const paymentHeader = req.headers["x-payment"];
+
+    if (!paymentHeader) {
+      // No payment — return 402
+      const encoded = Buffer.from(JSON.stringify([paymentRequirements])).toString("base64");
+      res.setHeader("X-PAYMENT-REQUIRED", encoded);
+      return res.status(402).json({
+        x402Version: 1,
+        error: "X-PAYMENT header is required",
+        accepts: [paymentRequirements],
+      });
+    }
+
+    // Parse payment payload
+    let paymentPayload;
+    try {
+      paymentPayload = JSON.parse(Buffer.from(paymentHeader, "base64").toString("utf8"));
+    } catch {
+      return res.status(400).json({ error: "Invalid X-PAYMENT header (not valid base64 JSON)" });
+    }
+
+    // Verify with facilitator
+    const verification = await verifyPayment(facilitatorUrl, paymentPayload, paymentRequirements);
+    if (!verification.valid) {
+      return res.status(402).json({
+        x402Version: 1,
+        error: "Payment verification failed",
+        details: verification.error,
+        accepts: [paymentRequirements],
+      });
+    }
+
+    // Payment verified — intercept the response to settle after
+    const originalJson = res.json.bind(res);
+    const originalSend = res.send.bind(res);
+
+    let settled = false;
+    const doSettle = async () => {
+      if (settled) return;
+      settled = true;
+      const settlement = await settlePayment(facilitatorUrl, paymentPayload, paymentRequirements);
+      if (settlement.transaction) {
+        // Add settlement info to response header
+        const encoded = Buffer.from(JSON.stringify(settlement)).toString("base64");
+        res.setHeader("X-PAYMENT-RESPONSE", encoded);
+      }
+    };
+
+    res.json = async function (body) {
+      await doSettle();
+      return originalJson(body);
+    };
+
+    res.send = async function (body) {
+      await doSettle();
+      return originalSend(body);
+    };
+
+    next();
+  };
+}
+
+module.exports = { paymentMiddleware, priceToAtomic, matchRoute, USDC_CONFIG };

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "x402-lite",
+  "version": "0.1.0",
+  "description": "Lightweight x402 payment middleware for Express. Zero crypto dependencies — delegates verification and settlement to the facilitator. Perfect for Raspberry Pi, edge, and resource-constrained environments.",
+  "main": "index.js",
+  "keywords": ["x402", "payment", "middleware", "express", "lightweight", "edge", "raspberry-pi"],
+  "author": "Nexus <nexus@nexusagentorg.github.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NexusAgentOrg/x402-lite"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/test.js

@@ -0,0 +1,105 @@
+/**
+ * x402-lite test suite — no external dependencies
+ */
+
+const { paymentMiddleware, priceToAtomic, matchRoute, USDC_CONFIG } = require("./index.js");
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, name) {
+  if (condition) {
+    console.log(`✓ ${name}`);
+    passed++;
+  } else {
+    console.log(`✗ ${name}`);
+    failed++;
+  }
+}
+
+// --- Unit tests ---
+
+// priceToAtomic
+assert(priceToAtomic("$0.01") === "10000", "priceToAtomic: $0.01 = 10000");
+assert(priceToAtomic("$1.00") === "1000000", "priceToAtomic: $1.00 = 1000000");
+assert(priceToAtomic("$0.001") === "1000", "priceToAtomic: $0.001 = 1000");
+assert(priceToAtomic(0.05) === "50000", "priceToAtomic: 0.05 = 50000");
+assert(priceToAtomic("0.10") === "100000", "priceToAtomic: 0.10 = 100000");
+
+// matchRoute
+const routes = {
+  "GET /api/data": { price: "$0.01" },
+  "POST /api/query": { price: "$0.05" },
+  "/api/any": { price: "$0.02" },
+  "GET /api/wild/*": { price: "$0.03" },
+};
+
+assert(matchRoute(routes, "GET", "/api/data") !== null, "matchRoute: exact GET match");
+assert(matchRoute(routes, "POST", "/api/data") === null, "matchRoute: wrong method returns null");
+assert(matchRoute(routes, "POST", "/api/query") !== null, "matchRoute: POST match");
+assert(matchRoute(routes, "GET", "/api/any") !== null, "matchRoute: any method GET");
+assert(matchRoute(routes, "DELETE", "/api/any") !== null, "matchRoute: any method DELETE");
+assert(matchRoute(routes, "GET", "/api/wild/foo") !== null, "matchRoute: wildcard match");
+assert(matchRoute(routes, "GET", "/api/wild/foo/bar") !== null, "matchRoute: deep wildcard");
+assert(matchRoute(routes, "GET", "/unmatched") === null, "matchRoute: unmatched returns null");
+
+// USDC_CONFIG
+assert(USDC_CONFIG["base"].chainId === 8453, "USDC_CONFIG: base chainId");
+assert(USDC_CONFIG["base"].decimals === 6, "USDC_CONFIG: base decimals");
+assert(USDC_CONFIG["base-sepolia"].chainId === 84532, "USDC_CONFIG: base-sepolia chainId");
+
+// --- Middleware integration test (mock) ---
+
+function mockReq(method, path, headers = {}) {
+  return {
+    method,
+    path,
+    protocol: "https",
+    headers: { host: "example.com", ...headers },
+    header(name) { return this.headers[name.toLowerCase()]; },
+  };
+}
+
+function mockRes() {
+  const res = {
+    statusCode: null,
+    headers: {},
+    body: null,
+    status(code) { res.statusCode = code; return res; },
+    json(data) { res.body = data; return res; },
+    send(data) { res.body = data; return res; },
+    setHeader(k, v) { res.headers[k] = v; },
+  };
+  return res;
+}
+
+// Test: no payment → 402
+(async () => {
+  const mw = paymentMiddleware("0x1234567890abcdef1234567890abcdef12345678", {
+    "GET /api/test": { price: "$0.01", network: "base" },
+  });
+
+  const req = mockReq("GET", "/api/test");
+  const res = mockRes();
+  let nextCalled = false;
+
+  await mw(req, res, () => { nextCalled = true; });
+
+  assert(res.statusCode === 402, "middleware: returns 402 without payment");
+  assert(!nextCalled, "middleware: does not call next without payment");
+  assert(res.body && res.body.accepts, "middleware: 402 body includes accepts");
+  assert(res.body.accepts[0].scheme === "exact", "middleware: accepts scheme is exact");
+  assert(res.body.accepts[0].maxAmountRequired === "10000", "middleware: amount is 10000");
+  assert(res.headers["X-PAYMENT-REQUIRED"], "middleware: X-PAYMENT-REQUIRED header set");
+
+  // Test: unprotected route → next()
+  const req2 = mockReq("GET", "/health");
+  const res2 = mockRes();
+  let next2Called = false;
+  await mw(req2, res2, () => { next2Called = true; });
+  assert(next2Called, "middleware: unprotected route calls next()");
+
+  // Summary
+  console.log(`\n📊 Results: ${passed} passed, ${failed} failed`);
+  process.exit(failed > 0 ? 1 : 0);
+})();