@emdash-cms/x402 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,144 @@
+import { AstroIntegration } from "astro";
+import { SettleResponse } from "@x402/core/types";
+
+//#region src/types.d.ts
+/** CAIP-2 network identifier (e.g., "eip155:8453" for Base mainnet) */
+type Network = `${string}:${string}`;
+/** Human-readable price: "$0.10", "0.50", or atomic units { amount, asset } */
+type Price = string | number | {
+  amount: string;
+  asset: string;
+  extra?: Record<string, unknown>;
+};
+/**
+ * Configuration for the x402 Astro integration.
+ *
+ * @example
+ * ```ts
+ * import { x402 } from "@emdashcms/x402";
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     x402({
+ *       payTo: "0xYourWallet",
+ *       network: "eip155:8453",
+ *       defaultPrice: "$0.01",
+ *       botOnly: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+interface X402Config {
+  /** Destination wallet address for payments */
+  payTo: string;
+  /** CAIP-2 network identifier */
+  network: Network;
+  /** Default price for content (can be overridden per-page) */
+  defaultPrice?: Price;
+  /** Facilitator URL (defaults to x402.org testnet facilitator) */
+  facilitatorUrl?: string;
+  /** Payment scheme (defaults to "exact") */
+  scheme?: string;
+  /** Maximum timeout for payment signatures in seconds (defaults to 60) */
+  maxTimeoutSeconds?: number;
+  /** Enable EVM chain support (defaults to true) */
+  evm?: boolean;
+  /** Enable Solana chain support (defaults to false) */
+  svm?: boolean;
+  /**
+   * Only enforce payment for bots/agents, not humans.
+   * Uses Cloudflare Bot Management score from request.cf.botManagement.score.
+   * Requires Cloudflare deployment with Bot Management enabled.
+   * When true, requests with a bot score >= botScoreThreshold are treated as
+   * human and enforcement is skipped.
+   */
+  botOnly?: boolean;
+  /**
+   * Bot score threshold. Requests with a score below this are treated as bots.
+   * Only used when botOnly is true. Defaults to 30.
+   * Score range: 1 (almost certainly bot) to 99 (almost certainly human).
+   */
+  botScoreThreshold?: number;
+}
+/**
+ * Options passed to enforce() to override defaults for a specific page.
+ */
+interface EnforceOptions {
+  /** Override the price for this specific request */
+  price?: Price;
+  /** Override the destination wallet */
+  payTo?: string;
+  /** Override the network */
+  network?: Network;
+  /** Override the payment scheme */
+  scheme?: string;
+  /** Resource description for the payment prompt */
+  description?: string;
+  /** MIME type hint for the resource */
+  mimeType?: string;
+}
+/**
+ * Result of a successful payment enforcement check.
+ * Returned when the request should proceed (either paid or skipped).
+ */
+interface EnforceResult {
+  /** Whether payment was required and verified */
+  paid: boolean;
+  /** Whether enforcement was skipped (e.g., human in botOnly mode) */
+  skipped: boolean;
+  /** The payer's wallet address (if paid) */
+  payer?: string;
+  /** Settlement response (if payment was settled) */
+  settlement?: SettleResponse;
+  /** Headers to add to the response (e.g., PAYMENT-RESPONSE) */
+  responseHeaders: Record<string, string>;
+}
+/**
+ * The x402 enforcement interface available on Astro.locals.x402.
+ */
+interface X402Enforcer {
+  /**
+   * Check if the current request includes valid payment.
+   * If not paid, returns a 402 Response that should be returned directly.
+   * If paid (or skipped in botOnly mode), returns an EnforceResult.
+   *
+   * @param request - The incoming Request object
+   * @param options - Optional overrides for this specific enforcement
+   * @returns A 402 Response (return it) or an EnforceResult (proceed with page render)
+   *
+   * @example
+   * ```astro
+   * ---
+   * const { x402 } = Astro.locals;
+   *
+   * const result = await x402.enforce(Astro.request, { price: "$0.01" });
+   * if (result instanceof Response) return result;
+   *
+   * x402.applyHeaders(result, Astro.response);
+   * ---
+   * ```
+   */
+  enforce(request: Request, options?: EnforceOptions): Promise<Response | EnforceResult>;
+  /**
+   * Apply x402 response headers (e.g., PAYMENT-RESPONSE) to the Astro response.
+   * Call this after a successful enforce() to include settlement proof in the response.
+   */
+  applyHeaders(result: EnforceResult, response: {
+    headers: Headers;
+  }): void;
+  /**
+   * Check if a request has a payment signature without verifying it.
+   * Useful for conditional rendering without enforcement.
+   */
+  hasPayment(request: Request): boolean;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Create the x402 Astro integration.
+ */
+declare function x402(config: X402Config): AstroIntegration;
+//#endregion
+export { type EnforceOptions, type EnforceResult, type Network, type Price, type X402Config, type X402Enforcer, x402 };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/index.ts"],"mappings":";;;;AAOA;AAAA,KAAY,OAAA;;KAGA,KAAA;EAGP,MAAA;EAAgB,KAAA;EAAe,KAAA,GAAQ,MAAA;AAAA;;;;;;;;AAqB5C;;;;;;;;;;;;UAAiB,UAAA;EAgBhB;EAdA,KAAA;EA4BA;EA1BA,OAAA,EAAS,OAAA;EA0BQ;EAxBjB,YAAA,GAAe,KAAA;EA8Be;EA5B9B,cAAA;EAkCiB;EAhCjB,MAAA;EA4BQ;EA1BR,iBAAA;EA8BA;EA5BA,GAAA;EA8BA;EA5BA,GAAA;EAgCA;;;AAOD;;;;EA/BC,OAAA;EAmCA;;;;;EA7BA,iBAAA;AAAA;;AAyCD;;UAnCiB,cAAA;EAyDC;EAvDjB,KAAA,GAAQ,KAAA;EAuDqD;EArD7D,KAAA;EAqDqD;EAnDrD,OAAA,GAAU,OAAA;EAyD+C;EAvDzD,MAAA;EA6D2B;EA3D3B,WAAA;EA+CA;EA7CA,QAAA;AAAA;;;;;UAOgB,aAAA;EA4ChB;EA1CA,IAAA;EA0Ca;EAxCb,OAAA;EAwCyD;EAtCzD,KAAA;EA4CA;EA1CA,UAAA,GAAa,cAAA;EA0CF;EAxCX,eAAA,EAAiB,MAAA;AAAA;;;;UAMD,YAAA;EC3DG;;;;;;;;;;;;;;;;;;;;;EDiFnB,OAAA,CAAQ,OAAA,EAAS,OAAA,EAAS,OAAA,GAAU,cAAA,GAAiB,OAAA,CAAQ,QAAA,GAAW,aAAA;;;;;EAMxE,YAAA,CAAa,MAAA,EAAQ,aAAA,EAAe,QAAA;IAAY,OAAA,EAAS,OAAA;EAAA;;;;;EAMzD,UAAA,CAAW,OAAA,EAAS,OAAA;AAAA;;;AArErB;;;AAAA,iBCxBgB,IAAA,CAAK,MAAA,EAAQ,UAAA,GAAa,gBAAA"}

package/dist/index.mjs

@@ -0,0 +1,30 @@
+//#region src/index.ts
+const VIRTUAL_MODULE_ID = "virtual:x402/config";
+const RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID;
+/**
+* Create the x402 Astro integration.
+*/
+function x402(config) {
+	return {
+		name: "@emdashcms/x402",
+		hooks: { "astro:config:setup": ({ addMiddleware, updateConfig }) => {
+			updateConfig({ vite: { plugins: [{
+				name: "x402-virtual-config",
+				resolveId(id) {
+					if (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_MODULE_ID;
+				},
+				load(id) {
+					if (id === RESOLVED_VIRTUAL_MODULE_ID) return `export default ${JSON.stringify(config)}`;
+				}
+			}] } });
+			addMiddleware({
+				entrypoint: "@emdashcms/x402/middleware",
+				order: "pre"
+			});
+		} }
+	};
+}
+
+//#endregion
+export { x402 };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @emdashcms/x402 -- x402 Payment Integration for Astro\n *\n * An Astro integration that provides x402 payment enforcement via\n * Astro.locals.x402. Supports bot-only mode using Cloudflare Bot Management.\n *\n * @example\n * ```ts\n * // astro.config.mjs\n * import { x402 } from \"@emdashcms/x402\";\n *\n * export default defineConfig({\n *   integrations: [\n *     x402({\n *       payTo: \"0xYourWallet\",\n *       network: \"eip155:8453\",\n *       defaultPrice: \"$0.01\",\n *       botOnly: true,\n *     }),\n *   ],\n * });\n * ```\n *\n * ```astro\n * ---\n * const { x402 } = Astro.locals;\n *\n * const result = await x402.enforce(Astro.request, { price: \"$0.05\" });\n * if (result instanceof Response) return result;\n *\n * x402.applyHeaders(result, Astro.response);\n * ---\n * <article>Premium content here</article>\n * ```\n */\n\nimport type { AstroIntegration } from \"astro\";\n\nimport type { X402Config } from \"./types.js\";\n\nconst VIRTUAL_MODULE_ID = \"virtual:x402/config\";\nconst RESOLVED_VIRTUAL_MODULE_ID = \"\\0\" + VIRTUAL_MODULE_ID;\n\n/**\n * Create the x402 Astro integration.\n */\nexport function x402(config: X402Config): AstroIntegration {\n\treturn {\n\t\tname: \"@emdashcms/x402\",\n\t\thooks: {\n\t\t\t\"astro:config:setup\": ({ addMiddleware, updateConfig }) => {\n\t\t\t\t// Inject the virtual module that provides config to the middleware\n\t\t\t\tupdateConfig({\n\t\t\t\t\tvite: {\n\t\t\t\t\t\tplugins: [\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tname: \"x402-virtual-config\",\n\t\t\t\t\t\t\t\tresolveId(id: string) {\n\t\t\t\t\t\t\t\t\tif (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_MODULE_ID;\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\tload(id: string) {\n\t\t\t\t\t\t\t\t\tif (id === RESOLVED_VIRTUAL_MODULE_ID) {\n\t\t\t\t\t\t\t\t\t\treturn `export default ${JSON.stringify(config)}`;\n\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t],\n\t\t\t\t\t},\n\t\t\t\t});\n\n\t\t\t\t// Register the middleware that puts the enforcer on locals\n\t\t\t\taddMiddleware({\n\t\t\t\t\tentrypoint: \"@emdashcms/x402/middleware\",\n\t\t\t\t\torder: \"pre\",\n\t\t\t\t});\n\t\t\t},\n\t\t},\n\t};\n}\n\n// Re-export types for convenience\nexport type {\n\tEnforceOptions,\n\tEnforceResult,\n\tNetwork,\n\tPrice,\n\tX402Config,\n\tX402Enforcer,\n} from \"./types.js\";\n"],"mappings":";AAwCA,MAAM,oBAAoB;AAC1B,MAAM,6BAA6B,OAAO;;;;AAK1C,SAAgB,KAAK,QAAsC;AAC1D,QAAO;EACN,MAAM;EACN,OAAO,EACN,uBAAuB,EAAE,eAAe,mBAAmB;AAE1D,gBAAa,EACZ,MAAM,EACL,SAAS,CACR;IACC,MAAM;IACN,UAAU,IAAY;AACrB,SAAI,OAAO,kBAAmB,QAAO;;IAEtC,KAAK,IAAY;AAChB,SAAI,OAAO,2BACV,QAAO,kBAAkB,KAAK,UAAU,OAAO;;IAGjD,CACD,EACD,EACD,CAAC;AAGF,iBAAc;IACb,YAAY;IACZ,OAAO;IACP,CAAC;KAEH;EACD"}

package/locals.d.ts

@@ -0,0 +1,11 @@
+import type { X402Enforcer } from "./src/types.js";
+
+declare global {
+	namespace App {
+		interface Locals {
+			x402: X402Enforcer;
+		}
+	}
+}
+
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@emdash-cms/x402",
+  "version": "0.0.1",
+  "description": "x402 payment protocol integration for Astro sites",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudflare/emdash.git",
+    "directory": "packages/x402"
+  },
+  "files": [
+    "dist",
+    "src",
+    "locals.d.ts"
+  ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.mts",
+      "default": "./dist/middleware.mjs"
+    },
+    "./locals": {
+      "types": "./locals.d.ts"
+    }
+  },
+  "dependencies": {
+    "@x402/core": "^2.8.0",
+    "@x402/evm": "^2.8.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "astro": "^6.0.1",
+    "publint": "0.3.17",
+    "tsdown": "0.20.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "astro": ">=6.0.0-beta.0"
+  },
+  "optionalDependencies": {
+    "@x402/svm": "^2.8.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check": "publint && attw --pack --ignore-rules=cjs-resolves-to-esm --ignore-rules=no-resolution",
+    "test": "vitest",
+    "typecheck": "tsgo --noEmit"
+  }
+}

package/src/enforcer.ts

@@ -0,0 +1,231 @@
+/**
+ * x402 Payment Enforcer
+ *
+ * Creates the x402 enforcement interface. Uses the @x402/core SDK
+ * to handle the payment protocol negotiation.
+ */
+
+import {
+	decodePaymentSignatureHeader,
+	encodePaymentRequiredHeader,
+	encodePaymentResponseHeader,
+} from "@x402/core/http";
+import { HTTPFacilitatorClient, x402ResourceServer, type ResourceConfig } from "@x402/core/server";
+
+import type { EnforceOptions, EnforceResult, X402Config, X402Enforcer } from "./types.js";
+
+const PAYMENT_SIGNATURE_HEADER = "payment-signature";
+const PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED";
+const PAYMENT_RESPONSE_HEADER = "PAYMENT-RESPONSE";
+
+const DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
+const DEFAULT_SCHEME = "exact";
+const DEFAULT_MAX_TIMEOUT_SECONDS = 60;
+const DEFAULT_BOT_SCORE_THRESHOLD = 30;
+
+/**
+ * Cached resource server instance.
+ * Initialized once per process, reused across requests.
+ */
+let _resourceServer: x402ResourceServer | null = null;
+let _initPromise: Promise<void> | null = null;
+
+/**
+ * Get or create the x402ResourceServer singleton.
+ */
+async function getResourceServer(config: X402Config): Promise<x402ResourceServer> {
+	if (!_resourceServer) {
+		const facilitatorUrl = config.facilitatorUrl ?? DEFAULT_FACILITATOR_URL;
+		const facilitator = new HTTPFacilitatorClient({ url: facilitatorUrl });
+		const server = new x402ResourceServer(facilitator);
+
+		// Register EVM scheme (default)
+		if (config.evm !== false) {
+			try {
+				const evmMod = await import("@x402/evm/exact/server");
+				const evmScheme = new evmMod.ExactEvmScheme();
+				server.register("eip155:*" as `${string}:${string}`, evmScheme);
+			} catch {
+				// @x402/evm not installed -- skip EVM support
+			}
+		}
+
+		// Register SVM scheme (opt-in)
+		if (config.svm) {
+			try {
+				const svmMod = await import("@x402/svm/exact/server");
+				const svmScheme = new svmMod.ExactSvmScheme();
+				server.register("solana:*" as `${string}:${string}`, svmScheme);
+			} catch {
+				// @x402/svm not installed -- skip Solana support
+			}
+		}
+
+		_resourceServer = server;
+		_initPromise = server.initialize();
+	}
+
+	if (_initPromise) {
+		await _initPromise;
+		_initPromise = null;
+	}
+
+	return _resourceServer;
+}
+
+/**
+ * Check if a request is from a bot using Cloudflare Bot Management.
+ * Returns true if the request is likely from a bot, false otherwise.
+ * When bot management data is unavailable (local dev, non-CF deployment),
+ * returns false (treat as human).
+ */
+function isBot(request: Request, threshold: number): boolean {
+	// Cloudflare Workers expose cf properties on the request
+	const cf = (request as unknown as { cf?: { botManagement?: { score?: number } } }).cf;
+	const score = cf?.botManagement?.score;
+	if (score == null) return false;
+	return score < threshold;
+}
+
+/**
+ * Create an X402Enforcer for the given configuration.
+ * Called once by the middleware, reused across requests.
+ */
+export function createEnforcer(config: X402Config): X402Enforcer {
+	const botScoreThreshold = config.botScoreThreshold ?? DEFAULT_BOT_SCORE_THRESHOLD;
+
+	return {
+		async enforce(request: Request, options?: EnforceOptions): Promise<Response | EnforceResult> {
+			// In botOnly mode, skip enforcement for humans
+			if (config.botOnly && !isBot(request, botScoreThreshold)) {
+				return { paid: false, skipped: true, responseHeaders: {} };
+			}
+
+			const server = await getResourceServer(config);
+
+			const price = options?.price ?? config.defaultPrice;
+			if (price == null) {
+				throw new Error(
+					"x402: No price specified. Pass a price in enforce() options or set defaultPrice in the config.",
+				);
+			}
+
+			const payTo = options?.payTo ?? config.payTo;
+			const network = options?.network ?? config.network;
+			const scheme = options?.scheme ?? config.scheme ?? DEFAULT_SCHEME;
+			const maxTimeoutSeconds = config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+
+			const resourceConfig: ResourceConfig = {
+				scheme,
+				payTo,
+				price: normalizePrice(price),
+				network,
+				maxTimeoutSeconds,
+			};
+
+			const url = new URL(request.url);
+			const resourceInfo = {
+				url: url.pathname,
+				description: options?.description,
+				mimeType: options?.mimeType,
+			};
+
+			// Check for payment signature header
+			const paymentHeader =
+				request.headers.get(PAYMENT_SIGNATURE_HEADER) || request.headers.get("PAYMENT-SIGNATURE");
+
+			if (!paymentHeader) {
+				return make402(server, resourceConfig, resourceInfo, "Payment required");
+			}
+
+			// Payment present -- decode and verify
+			const paymentPayload = decodePaymentSignatureHeader(paymentHeader);
+			const requirements = await server.buildPaymentRequirements(resourceConfig);
+			const matchingReqs = server.findMatchingRequirements(requirements, paymentPayload);
+
+			if (!matchingReqs) {
+				return make402(
+					server,
+					resourceConfig,
+					resourceInfo,
+					"Payment does not match accepted requirements",
+				);
+			}
+
+			// Verify with facilitator
+			const verifyResult = await server.verifyPayment(paymentPayload, matchingReqs);
+
+			if (!verifyResult.isValid) {
+				return make402(
+					server,
+					resourceConfig,
+					resourceInfo,
+					verifyResult.invalidReason ?? "Payment verification failed",
+				);
+			}
+
+			// Settle
+			const settleResult = await server.settlePayment(paymentPayload, matchingReqs);
+
+			const responseHeaders: Record<string, string> = {};
+			if (settleResult) {
+				responseHeaders[PAYMENT_RESPONSE_HEADER] = encodePaymentResponseHeader(settleResult);
+			}
+
+			return {
+				paid: true,
+				skipped: false,
+				payer: verifyResult.payer,
+				settlement: settleResult,
+				responseHeaders,
+			};
+		},
+
+		applyHeaders(result: EnforceResult, response: { headers: Headers }): void {
+			for (const [key, value] of Object.entries(result.responseHeaders)) {
+				response.headers.set(key, value);
+			}
+		},
+
+		hasPayment(request: Request): boolean {
+			return !!(
+				request.headers.get(PAYMENT_SIGNATURE_HEADER) || request.headers.get("PAYMENT-SIGNATURE")
+			);
+		},
+	};
+}
+
+/** Build and return a 402 Response */
+async function make402(
+	server: x402ResourceServer,
+	resourceConfig: ResourceConfig,
+	resourceInfo: { url: string; description?: string; mimeType?: string },
+	error: string,
+): Promise<Response> {
+	const requirements = await server.buildPaymentRequirements(resourceConfig);
+	const paymentRequired = await server.createPaymentRequiredResponse(
+		requirements,
+		resourceInfo,
+		error,
+	);
+
+	return new Response(JSON.stringify(paymentRequired), {
+		status: 402,
+		headers: {
+			"Content-Type": "application/json",
+			[PAYMENT_REQUIRED_HEADER]: encodePaymentRequiredHeader(paymentRequired),
+		},
+	});
+}
+
+/**
+ * Normalize a user-friendly price into the format expected by x402 SDK.
+ */
+function normalizePrice(
+	price: string | number | { amount: string; asset: string; extra?: Record<string, unknown> },
+): string | number | { amount: string; asset: string; extra?: Record<string, unknown> } {
+	if (typeof price === "string" && price.startsWith("$")) {
+		return price.slice(1);
+	}
+	return price;
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * @emdash-cms/x402 -- x402 Payment Integration for Astro
+ *
+ * An Astro integration that provides x402 payment enforcement via
+ * Astro.locals.x402. Supports bot-only mode using Cloudflare Bot Management.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { x402 } from "@emdash-cms/x402";
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     x402({
+ *       payTo: "0xYourWallet",
+ *       network: "eip155:8453",
+ *       defaultPrice: "$0.01",
+ *       botOnly: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * ```astro
+ * ---
+ * const { x402 } = Astro.locals;
+ *
+ * const result = await x402.enforce(Astro.request, { price: "$0.05" });
+ * if (result instanceof Response) return result;
+ *
+ * x402.applyHeaders(result, Astro.response);
+ * ---
+ * <article>Premium content here</article>
+ * ```
+ */
+
+import type { AstroIntegration } from "astro";
+
+import type { X402Config } from "./types.js";
+
+const VIRTUAL_MODULE_ID = "virtual:x402/config";
+const RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID;
+
+/**
+ * Create the x402 Astro integration.
+ */
+export function x402(config: X402Config): AstroIntegration {
+	return {
+		name: "@emdash-cms/x402",
+		hooks: {
+			"astro:config:setup": ({ addMiddleware, updateConfig }) => {
+				// Inject the virtual module that provides config to the middleware
+				updateConfig({
+					vite: {
+						plugins: [
+							{
+								name: "x402-virtual-config",
+								resolveId(id: string) {
+									if (id === VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_MODULE_ID;
+								},
+								load(id: string) {
+									if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+										return `export default ${JSON.stringify(config)}`;
+									}
+								},
+							},
+						],
+					},
+				});
+
+				// Register the middleware that puts the enforcer on locals
+				addMiddleware({
+					entrypoint: "@emdash-cms/x402/middleware",
+					order: "pre",
+				});
+			},
+		},
+	};
+}
+
+// Re-export types for convenience
+export type {
+	EnforceOptions,
+	EnforceResult,
+	Network,
+	Price,
+	X402Config,
+	X402Enforcer,
+} from "./types.js";

package/src/middleware.ts

@@ -0,0 +1,24 @@
+/**
+ * x402 Astro Middleware
+ *
+ * Injected by the x402 integration. Creates the enforcer and
+ * places it on Astro.locals.x402 for use in page frontmatter.
+ *
+ * The config is passed via the virtual module resolved by the integration.
+ */
+
+import { defineMiddleware } from "astro:middleware";
+// The integration injects config via a virtual module.
+// @ts-ignore -- virtual module, resolved at build time
+import x402Config from "virtual:x402/config";
+
+import { createEnforcer } from "./enforcer.js";
+import type { X402Config } from "./types.js";
+
+const config = x402Config as X402Config;
+const enforcer = createEnforcer(config);
+
+export const onRequest = defineMiddleware(async (context, next) => {
+	context.locals.x402 = enforcer;
+	return next();
+});

package/src/types.ts

@@ -0,0 +1,141 @@
+/**
+ * x402 Payment Integration Types
+ */
+
+import type { SettleResponse } from "@x402/core/types";
+
+/** CAIP-2 network identifier (e.g., "eip155:8453" for Base mainnet) */
+export type Network = `${string}:${string}`;
+
+/** Human-readable price: "$0.10", "0.50", or atomic units { amount, asset } */
+export type Price =
+	| string
+	| number
+	| { amount: string; asset: string; extra?: Record<string, unknown> };
+
+/**
+ * Configuration for the x402 Astro integration.
+ *
+ * @example
+ * ```ts
+ * import { x402 } from "@emdash-cms/x402";
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     x402({
+ *       payTo: "0xYourWallet",
+ *       network: "eip155:8453",
+ *       defaultPrice: "$0.01",
+ *       botOnly: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export interface X402Config {
+	/** Destination wallet address for payments */
+	payTo: string;
+	/** CAIP-2 network identifier */
+	network: Network;
+	/** Default price for content (can be overridden per-page) */
+	defaultPrice?: Price;
+	/** Facilitator URL (defaults to x402.org testnet facilitator) */
+	facilitatorUrl?: string;
+	/** Payment scheme (defaults to "exact") */
+	scheme?: string;
+	/** Maximum timeout for payment signatures in seconds (defaults to 60) */
+	maxTimeoutSeconds?: number;
+	/** Enable EVM chain support (defaults to true) */
+	evm?: boolean;
+	/** Enable Solana chain support (defaults to false) */
+	svm?: boolean;
+	/**
+	 * Only enforce payment for bots/agents, not humans.
+	 * Uses Cloudflare Bot Management score from request.cf.botManagement.score.
+	 * Requires Cloudflare deployment with Bot Management enabled.
+	 * When true, requests with a bot score >= botScoreThreshold are treated as
+	 * human and enforcement is skipped.
+	 */
+	botOnly?: boolean;
+	/**
+	 * Bot score threshold. Requests with a score below this are treated as bots.
+	 * Only used when botOnly is true. Defaults to 30.
+	 * Score range: 1 (almost certainly bot) to 99 (almost certainly human).
+	 */
+	botScoreThreshold?: number;
+}
+
+/**
+ * Options passed to enforce() to override defaults for a specific page.
+ */
+export interface EnforceOptions {
+	/** Override the price for this specific request */
+	price?: Price;
+	/** Override the destination wallet */
+	payTo?: string;
+	/** Override the network */
+	network?: Network;
+	/** Override the payment scheme */
+	scheme?: string;
+	/** Resource description for the payment prompt */
+	description?: string;
+	/** MIME type hint for the resource */
+	mimeType?: string;
+}
+
+/**
+ * Result of a successful payment enforcement check.
+ * Returned when the request should proceed (either paid or skipped).
+ */
+export interface EnforceResult {
+	/** Whether payment was required and verified */
+	paid: boolean;
+	/** Whether enforcement was skipped (e.g., human in botOnly mode) */
+	skipped: boolean;
+	/** The payer's wallet address (if paid) */
+	payer?: string;
+	/** Settlement response (if payment was settled) */
+	settlement?: SettleResponse;
+	/** Headers to add to the response (e.g., PAYMENT-RESPONSE) */
+	responseHeaders: Record<string, string>;
+}
+
+/**
+ * The x402 enforcement interface available on Astro.locals.x402.
+ */
+export interface X402Enforcer {
+	/**
+	 * Check if the current request includes valid payment.
+	 * If not paid, returns a 402 Response that should be returned directly.
+	 * If paid (or skipped in botOnly mode), returns an EnforceResult.
+	 *
+	 * @param request - The incoming Request object
+	 * @param options - Optional overrides for this specific enforcement
+	 * @returns A 402 Response (return it) or an EnforceResult (proceed with page render)
+	 *
+	 * @example
+	 * ```astro
+	 * ---
+	 * const { x402 } = Astro.locals;
+	 *
+	 * const result = await x402.enforce(Astro.request, { price: "$0.01" });
+	 * if (result instanceof Response) return result;
+	 *
+	 * x402.applyHeaders(result, Astro.response);
+	 * ---
+	 * ```
+	 */
+	enforce(request: Request, options?: EnforceOptions): Promise<Response | EnforceResult>;
+
+	/**
+	 * Apply x402 response headers (e.g., PAYMENT-RESPONSE) to the Astro response.
+	 * Call this after a successful enforce() to include settlement proof in the response.
+	 */
+	applyHeaders(result: EnforceResult, response: { headers: Headers }): void;
+
+	/**
+	 * Check if a request has a payment signature without verifying it.
+	 * Useful for conditional rendering without enforcement.
+	 */
+	hasPayment(request: Request): boolean;
+}