feat: add x402 payment-gated proxy template

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");
+	});
+});

pnpm-lock.yaml

@@ -77,6 +77,9 @@
     },
     "react-router-postgres-ssr-template": {
       "package_json_hash": "77ba35e81ddae51a6e8a6a7406e0a1f022de4069"
+    },
+    "x402-proxy-template": {
+      "package_json_hash": "5f786630dea32450178ac9c92a0ea350f9b75b14"
     }
   }
 }

templates.json

@@ -0,0 +1,7 @@
+# Environment variables for local development
+# Copy this file to .dev.vars and fill in your values
+
+# JWT secret for signing authentication tokens
+# Generate a secure random secret with:
+# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+JWT_SECRET=your-secret-key-here

x402-proxy-template/.dev.vars.example

@@ -0,0 +1,37 @@
+# prod
+dist/
+
+# dev
+.yarn/
+!.yarn/releases
+.vscode/*
+!.vscode/launch.json
+!.vscode/*.code-snippets
+.idea/workspace.xml
+.idea/usage.statistics.xml
+.idea/shelf
+
+# deps
+node_modules/
+.wrangler
+
+# env
+.env
+.env.production
+.dev.vars
+
+# logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# misc
+.DS_Store
+
+.dev.vars*
+!.dev.vars.example
+!.env.example

x402-proxy-template/.gitignore

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/

x402-proxy-template/.npmrc

@@ -0,0 +1,19 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+.wrangler/
+
+# Generated files
+worker-configuration.d.ts
+
+# Logs
+*.log
+
+# Environment files
+.env
+.dev.vars
+
+# Lock files
+package-lock.json

x402-proxy-template/.prettierignore

@@ -0,0 +1,8 @@
+{
+	"semi": true,
+	"singleQuote": false,
+	"tabWidth": 2,
+	"trailingComma": "es5",
+	"printWidth": 80,
+	"arrowParens": "always"
+}