From 00b68ffc8ffacf64b838bc78cef3c21596729fa6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 10 Jan 2026 00:41:45 +0000 Subject: [PATCH 1/5] feat(tasks): add x402 payment middleware epic Add task documentation for implementing plug-n-play x402 payment protocol middleware for the AIDD server framework. Enables API monetization via HTTP 402 Payment Required with stablecoin payments. Tasks include: - createWithPayment factory middleware - Payment verification via facilitator - 402 response format (x402 spec compliant) - Test utilities for mocking payments - Configuration and documentation updates --- tasks/x402-payment-middleware-epic.md | 107 ++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 tasks/x402-payment-middleware-epic.md diff --git a/tasks/x402-payment-middleware-epic.md b/tasks/x402-payment-middleware-epic.md new file mode 100644 index 0000000..2b79847 --- /dev/null +++ b/tasks/x402-payment-middleware-epic.md @@ -0,0 +1,107 @@ +# x402 Payment Middleware Epic + +**Status**: 📋 PLANNED +**Goal**: Enable plug-n-play API monetization via x402 payment protocol middleware + +## Overview + +AI agents and automated systems need to access paid APIs without human intervention, but current payment flows require accounts, sessions, and manual approval. The x402 protocol enables instant, programmatic stablecoin payments embedded directly into HTTP using the long-dormant 402 Payment Required status code. This epic adds payment middleware to the AIDD server framework, allowing developers to monetize APIs with a single middleware addition to their route stack. + +--- + +## createWithPayment Factory + +Factory function that creates middleware requiring payment before granting access to protected resources. + +**Requirements**: +- Given a request without valid payment proof, should respond with HTTP 402 and PaymentRequired header containing amount, currency, recipient, and supported networks +- Given a request with valid payment proof in X-PAYMENT header, should verify payment via configured facilitator +- Given successful payment verification, should attach payment receipt to `response.locals.payment` and allow request to proceed +- Given failed payment verification, should respond with HTTP 402 and appropriate error details +- Given configuration options, should require `recipient` (wallet address), `amount` (price in smallest unit), and `currency` (e.g., 'USDC') +- Given optional `network` configuration, should default to Base network for lowest fees +- Given optional `facilitator` configuration, should default to Coinbase x402 facilitator +- Given response.locals.payment, should include `payer`, `amount`, `currency`, `network`, `transactionHash`, and `timestamp` + +--- + +## Payment Verification + +Middleware must verify payment proofs through a facilitator service. + +**Requirements**: +- Given a payment proof, should validate signature and payment details against facilitator API +- Given facilitator verification success, should cache proof to avoid re-verification on retries +- Given facilitator verification failure, should return 402 with clear error message (insufficient funds, expired, invalid signature) +- Given facilitator unavailability, should return 503 Service Unavailable with retry-after header +- Given payment verification, should complete within 5 seconds under normal network conditions +- Given sensitive payment data, should sanitize wallet addresses and transaction hashes in error logs (show first/last 4 chars only) + +--- + +## 402 Response Format + +Standardized payment required response following x402 protocol specification. + +**Requirements**: +- Given 402 response, should include `X-PAYMENT-REQUIRED` header with base64-encoded payment requirements +- Given payment requirements, should specify `recipient`, `amount`, `currency`, `network`, and `facilitator` URL +- Given payment requirements, should include `description` field for human-readable payment context +- Given payment requirements, should include `resource` field identifying the requested endpoint +- Given multiple supported networks, should list all in order of preference (lowest fees first) + +--- + +## Test Utilities + +Enable testing payment middleware without real blockchain transactions. + +**Requirements**: +- Given test environment, should support `createMockFacilitator` that returns configurable verification results +- Given mock facilitator, should simulate success, insufficient funds, expired payment, and network errors +- Given test setup, should provide `createPaymentProof` helper to generate valid test proofs +- Given createServer test utility, should extend to support payment header injection + +--- + +## Configuration Integration + +Integrate with existing withConfig middleware for payment settings. + +**Requirements**: +- Given environment variables, should support `PAYMENT_RECIPIENT`, `PAYMENT_FACILITATOR_URL` configuration +- Given missing required payment config, should fail fast with descriptive ConfigurationError +- Given optional `PAYMENT_NETWORK` env var, should override default network selection +- Given production environment, should validate recipient address format before accepting requests + +--- + +## Documentation + +Update server framework documentation with payment middleware usage. + +**Requirements**: +- Given docs/server/README.md, should add createWithPayment to API Reference section +- Given documentation, should include complete example with React/fetch client-side payment flow +- Given documentation, should explain facilitator concept and supported networks +- Given security section, should document payment-specific best practices (recipient validation, amount verification) + +--- + +## Export Updates + +Add payment middleware to server exports. + +**Requirements**: +- Given src/server/middleware/index.js, should export `createWithPayment` +- Given src/server/middleware/index.js, should export `createMockFacilitator` for testing +- Given package.json, should add `@x402/core` as peer dependency + +--- + +## References + +- [x402 Protocol Specification](https://www.x402.org/) +- [x402 GitHub Repository](https://github.com/coinbase/x402) +- [Coinbase x402 Developer Docs](https://docs.cdp.coinbase.com/x402/welcome) +- [x402 Whitepaper](https://www.x402.org/x402-whitepaper.pdf) From 831e201fd8ba12da79aa06ec62de66f9059b2b61 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 10 Jan 2026 00:48:41 +0000 Subject: [PATCH 2/5] refactor(tasks): use named params with env fallbacks for payment middleware Update createWithPayment factory to accept named parameters with default parameter syntax falling back to environment variables: - recipient -> X402_RECIPIENT - facilitatorUrl -> X402_FACILITATOR - paymentNetwork -> X402_PAYMENT_NETWORK --- tasks/x402-payment-middleware-epic.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/tasks/x402-payment-middleware-epic.md b/tasks/x402-payment-middleware-epic.md index 2b79847..f2a64c8 100644 --- a/tasks/x402-payment-middleware-epic.md +++ b/tasks/x402-payment-middleware-epic.md @@ -13,14 +13,29 @@ AI agents and automated systems need to access paid APIs without human intervent Factory function that creates middleware requiring payment before granting access to protected resources. +```js +createWithPayment({ + recipient = process.env.X402_RECIPIENT, + facilitatorUrl = process.env.X402_FACILITATOR, + paymentNetwork = process.env.X402_PAYMENT_NETWORK, + amount, + currency = 'USDC', + description, +}) +``` + **Requirements**: - Given a request without valid payment proof, should respond with HTTP 402 and PaymentRequired header containing amount, currency, recipient, and supported networks - Given a request with valid payment proof in X-PAYMENT header, should verify payment via configured facilitator - Given successful payment verification, should attach payment receipt to `response.locals.payment` and allow request to proceed - Given failed payment verification, should respond with HTTP 402 and appropriate error details -- Given configuration options, should require `recipient` (wallet address), `amount` (price in smallest unit), and `currency` (e.g., 'USDC') -- Given optional `network` configuration, should default to Base network for lowest fees -- Given optional `facilitator` configuration, should default to Coinbase x402 facilitator +- Given named parameters, should accept `{ recipient, facilitatorUrl, paymentNetwork, amount, currency, description }` +- Given `recipient` parameter not provided, should fall back to `process.env.X402_RECIPIENT` via default parameter syntax +- Given `facilitatorUrl` parameter not provided, should fall back to `process.env.X402_FACILITATOR` via default parameter syntax +- Given `paymentNetwork` parameter not provided, should fall back to `process.env.X402_PAYMENT_NETWORK` via default parameter syntax +- Given `paymentNetwork` not configured anywhere, should default to Base network for lowest fees +- Given `amount` parameter, should require explicit value (price in smallest unit) with no env fallback +- Given `currency` parameter not provided, should default to 'USDC' - Given response.locals.payment, should include `payer`, `amount`, `currency`, `network`, `transactionHash`, and `timestamp` --- @@ -69,9 +84,9 @@ Enable testing payment middleware without real blockchain transactions. Integrate with existing withConfig middleware for payment settings. **Requirements**: -- Given environment variables, should support `PAYMENT_RECIPIENT`, `PAYMENT_FACILITATOR_URL` configuration -- Given missing required payment config, should fail fast with descriptive ConfigurationError -- Given optional `PAYMENT_NETWORK` env var, should override default network selection +- Given environment variables, should support `X402_RECIPIENT`, `X402_FACILITATOR`, `X402_PAYMENT_NETWORK` configuration +- Given `recipient` not provided as parameter and `X402_RECIPIENT` not set, should throw descriptive ConfigurationError at middleware creation time +- Given `facilitatorUrl` not provided as parameter and `X402_FACILITATOR` not set, should throw descriptive ConfigurationError at middleware creation time - Given production environment, should validate recipient address format before accepting requests --- From 4f87b333c4cf6bda657476d1241710257b10d512 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 10 Jan 2026 00:51:22 +0000 Subject: [PATCH 3/5] fix(tasks): use canonical x402 header names Update to official x402 protocol header names: - PAYMENT-REQUIRED (402 response) - PAYMENT-SIGNATURE (client payment proof) - PAYMENT-RESPONSE (settlement response) --- tasks/x402-payment-middleware-epic.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tasks/x402-payment-middleware-epic.md b/tasks/x402-payment-middleware-epic.md index f2a64c8..7ab8918 100644 --- a/tasks/x402-payment-middleware-epic.md +++ b/tasks/x402-payment-middleware-epic.md @@ -25,8 +25,8 @@ createWithPayment({ ``` **Requirements**: -- Given a request without valid payment proof, should respond with HTTP 402 and PaymentRequired header containing amount, currency, recipient, and supported networks -- Given a request with valid payment proof in X-PAYMENT header, should verify payment via configured facilitator +- Given a request without valid payment proof, should respond with HTTP 402 and `PAYMENT-REQUIRED` header containing base64-encoded payment requirements +- Given a request with valid payment proof in `PAYMENT-SIGNATURE` header, should verify payment via configured facilitator - Given successful payment verification, should attach payment receipt to `response.locals.payment` and allow request to proceed - Given failed payment verification, should respond with HTTP 402 and appropriate error details - Given named parameters, should accept `{ recipient, facilitatorUrl, paymentNetwork, amount, currency, description }` @@ -59,11 +59,12 @@ Middleware must verify payment proofs through a facilitator service. Standardized payment required response following x402 protocol specification. **Requirements**: -- Given 402 response, should include `X-PAYMENT-REQUIRED` header with base64-encoded payment requirements +- Given 402 response, should include `PAYMENT-REQUIRED` header with base64-encoded payment requirements - Given payment requirements, should specify `recipient`, `amount`, `currency`, `network`, and `facilitator` URL - Given payment requirements, should include `description` field for human-readable payment context - Given payment requirements, should include `resource` field identifying the requested endpoint - Given multiple supported networks, should list all in order of preference (lowest fees first) +- Given successful payment, should include `PAYMENT-RESPONSE` header with base64-encoded settlement response --- From 3f070c220b7216cbd626ebe80edb151d2215918b Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 11 Jan 2026 10:35:29 +0000 Subject: [PATCH 4/5] fix(tasks): add PAYMENT-RESPONSE requirement to factory section Move PAYMENT-RESPONSE header requirement from 402 Response Format section (where it didn't belong) to createWithPayment Factory section with specific fields: transactionHash, network, settledAt. --- tasks/x402-payment-middleware-epic.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tasks/x402-payment-middleware-epic.md b/tasks/x402-payment-middleware-epic.md index 7ab8918..eca3a64 100644 --- a/tasks/x402-payment-middleware-epic.md +++ b/tasks/x402-payment-middleware-epic.md @@ -27,6 +27,7 @@ createWithPayment({ **Requirements**: - Given a request without valid payment proof, should respond with HTTP 402 and `PAYMENT-REQUIRED` header containing base64-encoded payment requirements - Given a request with valid payment proof in `PAYMENT-SIGNATURE` header, should verify payment via configured facilitator +- Given successful payment verification, should set `PAYMENT-RESPONSE` header with base64-encoded settlement response containing `transactionHash`, `network`, and `settledAt` - Given successful payment verification, should attach payment receipt to `response.locals.payment` and allow request to proceed - Given failed payment verification, should respond with HTTP 402 and appropriate error details - Given named parameters, should accept `{ recipient, facilitatorUrl, paymentNetwork, amount, currency, description }` @@ -64,7 +65,6 @@ Standardized payment required response following x402 protocol specification. - Given payment requirements, should include `description` field for human-readable payment context - Given payment requirements, should include `resource` field identifying the requested endpoint - Given multiple supported networks, should list all in order of preference (lowest fees first) -- Given successful payment, should include `PAYMENT-RESPONSE` header with base64-encoded settlement response --- From b6f22895d427e92a70578874b3013d1b9423e74b Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 11 Jan 2026 10:36:19 +0000 Subject: [PATCH 5/5] feat(tasks): add Playwright e2e test requirements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add requirements for Playwright end-to-end tests covering: - Full payment flow (402 → payment → resource access) - PAYMENT-REQUIRED header format verification - Client-side payment signature submission --- tasks/x402-payment-middleware-epic.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tasks/x402-payment-middleware-epic.md b/tasks/x402-payment-middleware-epic.md index eca3a64..03610f9 100644 --- a/tasks/x402-payment-middleware-epic.md +++ b/tasks/x402-payment-middleware-epic.md @@ -77,6 +77,9 @@ Enable testing payment middleware without real blockchain transactions. - Given mock facilitator, should simulate success, insufficient funds, expired payment, and network errors - Given test setup, should provide `createPaymentProof` helper to generate valid test proofs - Given createServer test utility, should extend to support payment header injection +- Given Playwright e2e tests, should verify full payment flow from 402 response through successful payment to resource access +- Given Playwright e2e tests, should verify client receives correct `PAYMENT-REQUIRED` header format on unpaid requests +- Given Playwright e2e tests, should verify client can parse payment requirements and submit valid `PAYMENT-SIGNATURE` ---