feat: add x402 payment-gated proxy template

A transparent proxy template with payment-gated routes using the x402
protocol and stateless JWT cookie authentication. Includes built-in
test endpoints for health checks and payment flow demonstration.

Author: edevil

playwright-tests/utils/template-server.ts

@@ -27,6 +27,7 @@ export interface Template {
 	port: number;
 	devCommand: string;
 	framework: "vite" | "next" | "astro" | "remix" | "wrangler" | "react-router";
+	healthCheckPath?: string; // Optional custom path for server readiness check
 }
 
 export class TemplateServerManager {
@@ -131,12 +132,16 @@ export class TemplateServerManager {
 			port = 5173;
 		}
 
+		// Check for custom health check path in cloudflare config
+		const healthCheckPath = packageJson.cloudflare?.healthCheckPath;
+
 		return {
 			name,
 			path,
 			port,
 			devCommand: scripts.dev,
 			framework,
+			healthCheckPath,
 		};
 	}
 
@@ -173,7 +178,10 @@ export class TemplateServerManager {
 
 		// Wait for server to be ready
 		const baseUrl = `http://localhost:${template.port}`;
-		await this.waitForServer(baseUrl, 30000); // 30 second timeout
+		const healthCheckUrl = template.healthCheckPath
+			? `${baseUrl}${template.healthCheckPath}`
+			: baseUrl;
+		await this.waitForServer(healthCheckUrl, 30000); // 30 second timeout
 
 		console.log(`Server for ${template.name} ready at ${baseUrl}`);
 		return baseUrl;

playwright-tests/x402-proxy-template.spec.ts

@@ -0,0 +1,72 @@
+import { test, expect } from "./fixtures";
+
+test.describe("x402 Payment-Gated Proxy Template", () => {
+	test("health endpoint is accessible without payment", async ({
+		page,
+		templateUrl,
+	}) => {
+		const response = await page.goto(`${templateUrl}/__x402/health`);
+		expect(response?.status()).toBe(200);
+
+		const body = await page.textContent("body");
+		expect(body).toContain("ok");
+		expect(body).toContain("x402-proxy");
+		expect(body).toContain("This endpoint is always public");
+	});
+
+	test("health endpoint returns valid JSON", async ({ page, templateUrl }) => {
+		await page.goto(`${templateUrl}/__x402/health`);
+		const content = await page.textContent("body");
+		const json = JSON.parse(content || "{}");
+
+		expect(json.status).toBe("ok");
+		expect(json.proxy).toBe("x402-proxy");
+		expect(json.message).toBe("This endpoint is always public");
+		expect(json.timestamp).toBeGreaterThan(0);
+	});
+
+	test("protected endpoint returns 402 payment required", async ({
+		page,
+		templateUrl,
+	}) => {
+		const response = await page.goto(`${templateUrl}/__x402/protected`);
+		expect(response?.status()).toBe(402);
+	});
+
+	test("402 response includes payment configuration details", async ({
+		page,
+		templateUrl,
+	}) => {
+		await page.goto(`${templateUrl}/__x402/protected`);
+		const body = await page.textContent("body");
+
+		// Verify response contains payment-related information
+		expect(body).toContain("X-PAYMENT");
+		expect(body).toContain("base-sepolia");
+		expect(body).toContain("10000"); // Payment amount in smallest unit
+	});
+
+	test("402 response includes proper payment structure", async ({
+		page,
+		templateUrl,
+	}) => {
+		// Use page.request to get raw JSON response (avoids browser rendering)
+		const response = await page.request.get(`${templateUrl}/__x402/protected`);
+		expect(response.status()).toBe(402);
+
+		const json = await response.json();
+
+		// Verify x402 payment structure
+		expect(json.error).toBe("X-PAYMENT header is required");
+		expect(json.accepts).toBeDefined();
+		expect(Array.isArray(json.accepts)).toBe(true);
+		expect(json.accepts.length).toBeGreaterThan(0);
+		expect(json.x402Version).toBe(1);
+
+		// Verify payment details
+		const paymentOption = json.accepts[0];
+		expect(paymentOption.network).toBe("base-sepolia");
+		expect(paymentOption.resource).toContain("/__x402/protected");
+		expect(paymentOption.description).toContain("Access to premium content");
+	});
+});