@ch4p/plugin-x402 0.1.4

package/src/middleware.test.ts

@@ -0,0 +1,335 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { createX402Middleware, pathMatches, decodePaymentHeader } from './middleware.js';
+import type { X402Config, X402PaymentPayload } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function makeReq(
+  url = '/',
+  headers: Record<string, string | undefined> = {},
+  method = 'GET',
+): IncomingMessage {
+  return { url, headers, method } as unknown as IncomingMessage;
+}
+
+interface MockResponse {
+  statusCode: number;
+  headers: Record<string, string | number>;
+  body: string;
+  writeHead: (status: number, h: Record<string, string | number>) => void;
+  end: (data?: string) => void;
+}
+
+function makeRes(): MockResponse {
+  const res: MockResponse = {
+    statusCode: 200,
+    headers: {},
+    body: '',
+    writeHead(status, h) {
+      this.statusCode = status;
+      Object.assign(this.headers, h);
+    },
+    end(data?: string) {
+      if (data) this.body = data;
+    },
+  };
+  return res;
+}
+
+function makePayload(overrides: Partial<X402PaymentPayload> = {}): X402PaymentPayload {
+  return {
+    x402Version: 1,
+    scheme: 'exact',
+    network: 'base',
+    payload: {
+      signature: '0xabc',
+      authorization: {
+        from: '0x1234567890123456789012345678901234567890',
+        to: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        value: '1000000',
+        validAfter: '0',
+        validBefore: '9999999999',
+        nonce: '0xdeadbeef',
+      },
+    },
+    ...overrides,
+  };
+}
+
+function encodePayment(payload: X402PaymentPayload): string {
+  return Buffer.from(JSON.stringify(payload)).toString('base64');
+}
+
+const BASE_CONFIG: X402Config = {
+  enabled: true,
+  server: {
+    payTo: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+    amount: '1000000',
+    network: 'base',
+    protectedPaths: ['/sessions', '/sessions/*', '/webhooks/*'],
+  },
+};
+
+// ---------------------------------------------------------------------------
+// pathMatches
+// ---------------------------------------------------------------------------
+
+describe('pathMatches', () => {
+  it('matches wildcard "*"', () => {
+    expect(pathMatches('/anything', '*')).toBe(true);
+  });
+
+  it('matches "/**"', () => {
+    expect(pathMatches('/foo/bar', '/**')).toBe(true);
+  });
+
+  it('matches prefix wildcard "/sessions/*"', () => {
+    expect(pathMatches('/sessions/abc', '/sessions/*')).toBe(true);
+    expect(pathMatches('/sessions', '/sessions/*')).toBe(true);
+  });
+
+  it('does not prefix-match unrelated paths', () => {
+    expect(pathMatches('/other', '/sessions/*')).toBe(false);
+  });
+
+  it('exact match', () => {
+    expect(pathMatches('/sessions', '/sessions')).toBe(true);
+    expect(pathMatches('/sessions/abc', '/sessions')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// decodePaymentHeader
+// ---------------------------------------------------------------------------
+
+describe('decodePaymentHeader', () => {
+  it('returns null for non-base64 garbage', () => {
+    expect(decodePaymentHeader('!!!not base64!!!')).toBeNull();
+  });
+
+  it('returns null for valid base64 but non-JSON', () => {
+    expect(decodePaymentHeader(Buffer.from('not json').toString('base64'))).toBeNull();
+  });
+
+  it('returns null when x402Version is wrong', () => {
+    const bad = { ...makePayload(), x402Version: 2 };
+    expect(decodePaymentHeader(encodePayment(bad as unknown as X402PaymentPayload))).toBeNull();
+  });
+
+  it('returns null when scheme is missing', () => {
+    const bad = { x402Version: 1, network: 'base', payload: { signature: '0x', authorization: { from: '0x1', to: '0x2', value: '1' } } };
+    expect(decodePaymentHeader(Buffer.from(JSON.stringify(bad)).toString('base64'))).toBeNull();
+  });
+
+  it('parses a valid payload', () => {
+    const payload = makePayload();
+    const result = decodePaymentHeader(encodePayment(payload));
+    expect(result).not.toBeNull();
+    expect(result?.network).toBe('base');
+    expect(result?.payload.authorization.from).toBe(payload.payload.authorization.from);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createX402Middleware — disabled / null cases
+// ---------------------------------------------------------------------------
+
+describe('createX402Middleware — disabled', () => {
+  it('returns null when enabled is false', () => {
+    expect(createX402Middleware({ enabled: false, server: BASE_CONFIG.server })).toBeNull();
+  });
+
+  it('returns null when enabled is missing', () => {
+    expect(createX402Middleware({ server: BASE_CONFIG.server })).toBeNull();
+  });
+
+  it('returns null when server config is missing', () => {
+    expect(createX402Middleware({ enabled: true })).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createX402Middleware — public paths pass through
+// ---------------------------------------------------------------------------
+
+describe('createX402Middleware — public paths', () => {
+  it('passes /health through (returns false)', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const result = await handler(makeReq('/health'), res as unknown as ServerResponse);
+    expect(result).toBe(false);
+    expect(res.statusCode).toBe(200); // no response written
+  });
+
+  it('passes /.well-known/agent.json through', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const result = await handler(makeReq('/.well-known/agent.json'), res as unknown as ServerResponse);
+    expect(result).toBe(false);
+    expect(res.statusCode).toBe(200);
+  });
+
+  it('passes /pair through', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const result = await handler(makeReq('/pair'), res as unknown as ServerResponse);
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createX402Middleware — unprotected paths pass through
+// ---------------------------------------------------------------------------
+
+describe('createX402Middleware — unprotected paths', () => {
+  it('passes through paths not in protectedPaths', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const result = await handler(makeReq('/other'), res as unknown as ServerResponse);
+    expect(result).toBe(false);
+    expect(res.statusCode).toBe(200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createX402Middleware — 402 responses
+// ---------------------------------------------------------------------------
+
+describe('createX402Middleware — 402 responses', () => {
+  it('returns 402 when X-PAYMENT header is absent on a protected path', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const result = await handler(makeReq('/sessions'), res as unknown as ServerResponse);
+    expect(result).toBe(true); // handled
+    expect(res.statusCode).toBe(402);
+    const body = JSON.parse(res.body);
+    expect(body.error).toBe('X402');
+    expect(body.x402Version).toBe(1);
+    expect(body.accepts[0].payTo).toBe(BASE_CONFIG.server!.payTo);
+  });
+
+  it('returns 402 for a sub-path of a wildcard pattern', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const result = await handler(makeReq('/sessions/abc-123'), res as unknown as ServerResponse);
+    expect(result).toBe(true);
+    expect(res.statusCode).toBe(402);
+  });
+
+  it('returns 402 on malformed X-PAYMENT header', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const req = makeReq('/sessions', { 'x-payment': 'not-base64!!!' });
+    const result = await handler(req, res as unknown as ServerResponse);
+    expect(result).toBe(true);
+    expect(res.statusCode).toBe(402);
+  });
+
+  it('returns 402 when payment network does not match', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const payload = makePayload({ network: 'ethereum' });
+    const req = makeReq('/sessions', { 'x-payment': encodePayment(payload) });
+    const result = await handler(req, res as unknown as ServerResponse);
+    expect(result).toBe(true);
+    expect(res.statusCode).toBe(402);
+  });
+
+  it('strips query string before path matching', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const result = await handler(makeReq('/sessions?foo=bar'), res as unknown as ServerResponse);
+    expect(result).toBe(true); // protected path, no payment
+    expect(res.statusCode).toBe(402);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createX402Middleware — valid payment
+// ---------------------------------------------------------------------------
+
+describe('createX402Middleware — valid payment', () => {
+  it('tags req._x402Authenticated and returns false on valid payment', async () => {
+    const handler = createX402Middleware(BASE_CONFIG)!;
+    const res = makeRes();
+    const payload = makePayload();
+    const req = makeReq('/sessions', { 'x-payment': encodePayment(payload) });
+    const result = await handler(req, res as unknown as ServerResponse);
+    expect(result).toBe(false); // not handled — continue routing
+    expect(res.statusCode).toBe(200); // no 402 written
+    expect((req as unknown as Record<string, unknown>)['_x402Authenticated']).toBe(true);
+  });
+
+  it('calls verifyPayment and passes when it returns true', async () => {
+    const verify = vi.fn().mockResolvedValue(true);
+    const cfg: X402Config = {
+      enabled: true,
+      server: { ...BASE_CONFIG.server!, verifyPayment: verify },
+    };
+    const handler = createX402Middleware(cfg)!;
+    const res = makeRes();
+    const payload = makePayload();
+    const req = makeReq('/sessions', { 'x-payment': encodePayment(payload) });
+    const result = await handler(req, res as unknown as ServerResponse);
+    expect(result).toBe(false);
+    expect(verify).toHaveBeenCalledOnce();
+  });
+
+  it('returns 402 when verifyPayment returns false', async () => {
+    const verify = vi.fn().mockResolvedValue(false);
+    const cfg: X402Config = {
+      enabled: true,
+      server: { ...BASE_CONFIG.server!, verifyPayment: verify },
+    };
+    const handler = createX402Middleware(cfg)!;
+    const res = makeRes();
+    const payload = makePayload();
+    const req = makeReq('/sessions', { 'x-payment': encodePayment(payload) });
+    const result = await handler(req, res as unknown as ServerResponse);
+    expect(result).toBe(true);
+    expect(res.statusCode).toBe(402);
+    expect(verify).toHaveBeenCalledOnce();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createX402Middleware — defaults
+// ---------------------------------------------------------------------------
+
+describe('createX402Middleware — defaults', () => {
+  it('uses default /* protection when protectedPaths not specified', async () => {
+    const cfg: X402Config = {
+      enabled: true,
+      server: {
+        payTo: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        amount: '1000000',
+      },
+    };
+    const handler = createX402Middleware(cfg)!;
+    const res = makeRes();
+    // Any non-public path should be protected
+    const result = await handler(makeReq('/anything'), res as unknown as ServerResponse);
+    expect(result).toBe(true);
+    expect(res.statusCode).toBe(402);
+  });
+
+  it('uses USDC on Base as default asset', async () => {
+    const cfg: X402Config = {
+      enabled: true,
+      server: {
+        payTo: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        amount: '500000',
+      },
+    };
+    const handler = createX402Middleware(cfg)!;
+    const res = makeRes();
+    await handler(makeReq('/protected'), res as unknown as ServerResponse);
+    const body = JSON.parse(res.body);
+    expect(body.accepts[0].asset).toBe('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+    expect(body.accepts[0].network).toBe('base');
+    expect(body.accepts[0].maxTimeoutSeconds).toBe(300);
+  });
+});

package/src/middleware.ts

@@ -0,0 +1,188 @@
+/**
+ * x402 gateway middleware — server-side payment enforcement.
+ *
+ * Call createX402Middleware(config) to obtain a pre-handler compatible with
+ * GatewayServer's `preHandler` option. For each incoming request the handler:
+ *
+ *   1. Skips system paths (/health, /.well-known/agent.json, /pair).
+ *   2. Skips paths not matched by `protectedPaths`.
+ *   3. If no X-PAYMENT header: responds 402 with payment requirements and
+ *      returns true (request handled, no further routing).
+ *   4. If X-PAYMENT header present: structurally validates the decoded
+ *      payload and, if a verifyPayment callback is configured, calls it.
+ *      - Invalid or rejected: sends 402 and returns true.
+ *      - Valid: tags `req._x402Authenticated = true` and returns false
+ *        so the request proceeds through normal routing with pairing auth
+ *        bypassed (GatewayServer.checkAuth respects this flag).
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { X402Config, X402PaymentRequirements, X402PaymentPayload } from './types.js';
+
+/** Paths always excluded from payment gating. */
+const PUBLIC_PATHS: ReadonlySet<string> = new Set([
+  '/health',
+  '/.well-known/agent.json',
+  '/pair',
+]);
+
+/** Default USDC on Base contract address. */
+const DEFAULT_ASSET = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+
+/** Default network. */
+const DEFAULT_NETWORK = 'base';
+
+/** Default payment timeout in seconds. */
+const DEFAULT_TIMEOUT = 300;
+
+/**
+ * Returns true if urlPath matches the protection pattern.
+ *
+ * Pattern rules:
+ *   - "*" or "/**": matches every path
+ *   - "/foo/*": prefix match — matches /foo and /foo/bar/baz
+ *   - "/foo": exact match only
+ */
+export function pathMatches(urlPath: string, pattern: string): boolean {
+  if (pattern === '*' || pattern === '/**') return true;
+  if (pattern.endsWith('/*')) {
+    const prefix = pattern.slice(0, -2);
+    return urlPath === prefix || urlPath.startsWith(prefix + '/');
+  }
+  return urlPath === pattern;
+}
+
+/** Strip query string from a URL to get the path only. */
+function extractPath(url: string): string {
+  const qIdx = url.indexOf('?');
+  return qIdx >= 0 ? url.slice(0, qIdx) : url;
+}
+
+/** Send a 402 Payment Required response with the x402 JSON body. */
+function send402(res: ServerResponse, requirements: X402PaymentRequirements): void {
+  const body = JSON.stringify({
+    x402Version: 1,
+    error: 'X402',
+    accepts: [requirements],
+  });
+  res.writeHead(402, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+/**
+ * Decode and structurally validate the X-PAYMENT header value.
+ * Returns null on any parse or structure failure.
+ */
+export function decodePaymentHeader(header: string): X402PaymentPayload | null {
+  try {
+    const json = Buffer.from(header, 'base64').toString('utf-8');
+    const parsed = JSON.parse(json) as unknown;
+    if (typeof parsed !== 'object' || parsed === null) return null;
+
+    const p = parsed as Record<string, unknown>;
+    if (p['x402Version'] !== 1) return null;
+    if (p['scheme'] !== 'exact') return null;
+    if (typeof p['network'] !== 'string') return null;
+
+    const payload = p['payload'];
+    if (typeof payload !== 'object' || payload === null) return null;
+    const pl = payload as Record<string, unknown>;
+    if (typeof pl['signature'] !== 'string') return null;
+
+    const auth = pl['authorization'];
+    if (typeof auth !== 'object' || auth === null) return null;
+    const a = auth as Record<string, unknown>;
+    if (
+      typeof a['from'] !== 'string' ||
+      typeof a['to'] !== 'string' ||
+      typeof a['value'] !== 'string'
+    ) {
+      return null;
+    }
+
+    return parsed as X402PaymentPayload;
+  } catch {
+    return null;
+  }
+}
+
+export type X402PreHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+
+/**
+ * Create an x402 middleware pre-handler for GatewayServer.
+ *
+ * Returns null when x402 is disabled or no server config is provided.
+ *
+ * @param config x402 plugin configuration
+ * @returns Pre-handler function, or null if x402 is not enabled.
+ */
+export function createX402Middleware(config: X402Config): X402PreHandler | null {
+  if (!config.enabled || !config.server) return null;
+
+  const serverCfg = config.server;
+  const asset = serverCfg.asset ?? DEFAULT_ASSET;
+  const network = serverCfg.network ?? DEFAULT_NETWORK;
+  const maxTimeoutSeconds = serverCfg.maxTimeoutSeconds ?? DEFAULT_TIMEOUT;
+  const description =
+    serverCfg.description ?? 'Payment required to access this gateway resource.';
+  const protectedPaths = serverCfg.protectedPaths ?? ['/*'];
+
+  return async (req: IncomingMessage, res: ServerResponse): Promise<boolean> => {
+    const rawUrl = req.url ?? '/';
+    const urlPath = extractPath(rawUrl);
+
+    // Never gate well-known system paths.
+    if (PUBLIC_PATHS.has(urlPath)) return false;
+
+    // Only gate paths listed in protectedPaths.
+    const isProtected = protectedPaths.some((p) => pathMatches(urlPath, p));
+    if (!isProtected) return false;
+
+    const requirements: X402PaymentRequirements = {
+      scheme: 'exact',
+      network,
+      maxAmountRequired: serverCfg.amount,
+      resource: urlPath,
+      description,
+      mimeType: 'application/json',
+      payTo: serverCfg.payTo,
+      maxTimeoutSeconds,
+      asset,
+      extra: {},
+    };
+
+    const paymentHeader = req.headers['x-payment'];
+    if (!paymentHeader || typeof paymentHeader !== 'string') {
+      send402(res, requirements);
+      return true; // handled — no further routing
+    }
+
+    const payment = decodePaymentHeader(paymentHeader);
+    if (!payment) {
+      send402(res, requirements);
+      return true; // handled — malformed header
+    }
+
+    // Network mismatch — reject.
+    if (payment.network !== network) {
+      send402(res, requirements);
+      return true;
+    }
+
+    // Optional on-chain verifier.
+    if (serverCfg.verifyPayment) {
+      const allowed = await serverCfg.verifyPayment(payment, requirements);
+      if (!allowed) {
+        send402(res, requirements);
+        return true;
+      }
+    }
+
+    // Payment accepted — tag the request so checkAuth bypasses pairing.
+    (req as unknown as Record<string, unknown>)['_x402Authenticated'] = true;
+    return false; // continue routing
+  };
+}