x402-engineer 0.1.0

package/skills/stellar-dev/zk-proofs.md

@@ -0,0 +1,136 @@
+# Zero-Knowledge Proofs on Stellar (Status-Sensitive)
+
+## When to use this guide
+Use this guide when the user asks for:
+- On-chain ZK proof verification patterns
+- Privacy-preserving smart contract architecture
+- BN254/Poseidon readiness planning
+- Groth16 or PLONK integration strategy
+- Cross-chain proof verification design
+
+This guide is intentionally status-aware. ZK capabilities on Stellar evolve with protocol and SDK releases.
+
+## Source-of-truth checks (required)
+Before implementation, always verify:
+1. CAP status in `stellar/stellar-protocol` (`Accepted`/`Implemented` vs draft/awaiting decision)
+2. Target network protocol/software version
+3. `soroban-sdk` support for required cryptographic host functions
+4. Availability of production examples matching your proving system
+
+Primary references:
+- [CAP-0059](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0059.md) (BLS12-381)
+- [CAP-0074](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0074.md) (BN254 proposal)
+- [CAP-0075](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0075.md) (Poseidon/Poseidon2 proposal)
+- [Stellar protocol/software versions](https://developers.stellar.org/docs/networks/software-versions)
+- [RPC providers](https://developers.stellar.org/docs/data/apis/rpc/providers)
+
+## Capability model
+Treat advanced cryptography as capability-gated:
+- Capability A: proof verification primitive support
+- Capability B: hash primitive support
+- Capability C: SDK ergonomics and bindings
+- Capability D: operational cost envelope
+
+Do not assume all capabilities are present on all networks/environments.
+
+## Architecture patterns
+
+### 1) Verification gateway
+Use a dedicated verifier contract (or module) for cryptographic checks:
+- Normalize and validate inputs
+- Enforce domain separation for statements
+- Verify proof
+- Emit explicit success/failure events
+
+Benefits:
+- Smaller audit surface
+- Easier upgrades/migrations
+- Cleaner operational telemetry
+
+### 2) Policy-and-proof split
+Separate concerns:
+- `Verifier`: cryptographic validity only
+- `Policy`: business/risk/compliance logic
+- `Application`: state transition after verifier + policy pass
+
+Benefits:
+- Better testability
+- Safer upgrades
+- Clearer incident response
+
+### 3) Feature flags and graceful fallback
+Gate advanced paths by environment support:
+- Enable ZK flows only where required primitives are verified available
+- Keep deterministic fallback behavior for unsupported environments
+- Document supported network/protocol matrix in deployment notes
+
+## Integration checklist
+- [ ] Target network supports required primitives
+- [ ] SDK pin supports required APIs
+- [ ] Proof statement includes anti-replay binding (nonce/context)
+- [ ] Full simulation path is covered (proof + policy + state transition)
+- [ ] Negative-path tests exist for malformed/tampered inputs
+- [ ] Resource budget checks are documented for realistic proof sizes
+- [ ] Security review documents all cryptographic assumptions
+
+## Common pitfalls
+
+### Over-trusting proof payload shape
+A payload that parses is not equivalent to a valid statement for your application.
+
+Mitigation:
+- Validate public-input semantics and statement domain explicitly.
+
+### Missing anti-replay controls
+Valid proofs can be replayed without context binding.
+
+Mitigation:
+- Bind proofs to session/nonce/action scope and persist replay guards.
+
+### Monolithic contract design
+Combining verifier, policy, and state logic increases audit complexity.
+
+Mitigation:
+- Keep verifier logic isolated and narrow.
+
+### Hardcoded protocol assumptions
+Assuming primitive availability across all networks causes runtime failures.
+
+Mitigation:
+- Capability-gate and verify at deployment time.
+
+## Testing strategy
+
+### Unit tests
+- Input domain validation
+- Replay protection behavior
+- Event correctness
+
+### Integration tests
+- End-to-end proof submission flow
+- Negative cases: tampered input, stale nonce, unsupported feature path
+- Network-configuration differences (local/testnet/mainnet)
+
+### Operational tests
+- Cost/resource envelope under realistic proof sizes
+- Load behavior on verifier hot paths
+- Upgrade/migration safety tests for verifier changes
+
+## Security review focus
+- Authorization and anti-replay guarantees
+- Statement domain separation
+- Upgrade controls around verifier/policy modules
+- Denial-of-service resistance and bounded workloads
+- Event/log coverage for forensic traceability
+
+## Example starting points
+- [Soroban examples](https://github.com/stellar/soroban-examples)
+- [Groth16 verifier example](https://github.com/stellar/soroban-examples/tree/main/groth16_verifier)
+- [Security guide](security.md)
+- [Advanced patterns](advanced-patterns.md)
+- [Standards reference](standards-reference.md)
+
+## What not to do
+- Do not claim specific primitives are production-ready without checking CAP status and network support.
+- Do not hardcode draft-spec behavior as guaranteed runtime behavior.
+- Do not skip simulation and negative-path testing for verifier flows.

package/skills/x402-add-paywall/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: x402-add-paywall
+description: Wrap an API endpoint with x402 payment protection. Detects endpoints, adds middleware wrapping, and updates route config.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: "[endpoint-path]"
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
+---
+
+# /x402:add-paywall
+
+> Protect an API endpoint with x402 payment middleware. I'll detect your endpoints, let you choose which to protect, and handle the wrapping.
+
+## Step 1 -- Verify x402 is initialized
+
+Use Grep to check if `@x402/core` exists in `package.json` dependencies:
+
+```
+Grep: pattern="@x402/core" in package.json
+```
+
+**If NOT found:** Output exactly:
+
+> "No x402 configuration detected. Run /x402:init first."
+
+Then STOP. Do not proceed.
+
+**If found:** Continue. Use Glob and Grep to locate the project's x402 files:
+
+1. Find the routesConfig file: Use Grep to search for files containing `RoutesConfig` or `routesConfig`:
+   ```
+   Grep: pattern="routesConfig" glob="**/*.{ts,js}" (exclude node_modules)
+   ```
+
+2. Find the server/middleware file: Use Grep to search for files importing `x402ResourceServer` or `paymentMiddleware` or `withPayment`:
+   ```
+   Grep: pattern="withPayment|paymentMiddleware|x402ResourceServer" glob="**/*.{ts,js}" (exclude node_modules)
+   ```
+
+Store both file paths for later use.
+
+## Step 2 -- Detect framework
+
+Read `package.json` and check `dependencies` for the framework:
+
+1. `"next"` in dependencies -> **Next.js App Router**
+2. `"express"` in dependencies -> **Express**
+3. `"fastify"` in dependencies -> **Fastify**
+4. `"hono"` in dependencies -> **Hono**
+
+Priority if multiple detected: Next.js > Express > Fastify > Hono.
+
+If no supported framework found, output:
+
+> "Could not detect framework from package.json. Supported: Next.js, Express, Fastify, Hono."
+
+Then STOP.
+
+## Step 3 -- Discover API endpoints
+
+Read [references/patterns.md](references/patterns.md) for the framework-specific endpoint detection approach.
+
+**Next.js App Router:**
+- Use Glob to find `**/app/api/**/route.{ts,js}` files
+- For each found file, Read it and extract the exported HTTP method handlers (look for `export async function GET`, `export async function POST`, `export const GET`, `export const POST`, etc. for GET, POST, PUT, PATCH, DELETE)
+- Build a list of `"METHOD /path"` entries where the path is derived from the file's directory structure relative to `app/` (e.g., `app/api/content/route.ts` -> `/api/content`)
+
+**Express:**
+- Use Grep to find route registrations: `app.get(`, `app.post(`, `app.put(`, `app.patch(`, `app.delete(`, `router.get(`, `router.post(`, `router.put(`, `router.patch(`, `router.delete(`
+- Extract the path argument (first string argument) from each match
+- Build a list of `"METHOD /path"` entries
+
+**Fastify:**
+- Use Grep to find route registrations: `fastify.get(`, `fastify.post(`, `fastify.put(`, `fastify.patch(`, `fastify.delete(`, `fastify.route(`
+- Extract the path argument from each match
+- Build a list of `"METHOD /path"` entries
+
+**Hono:**
+- Use Grep to find route registrations: `app.get(`, `app.post(`, `app.put(`, `app.patch(`, `app.delete(`, `app.route(`
+- Extract the path argument from each match
+- Build a list of `"METHOD /path"` entries
+
+**If no endpoints found:** Output exactly:
+
+> "No API endpoints found in this project. Create an endpoint first, then run /x402:add-paywall."
+
+Then STOP.
+
+## Step 4 -- Check protection status
+
+For each discovered endpoint, determine if it is already protected:
+
+**Next.js (inline wrap):**
+- Read the route file
+- Check if it contains the `// x402: payment-protected endpoint` comment
+- Check if it imports `withPayment` or `withX402`
+- If either found: mark as **PROTECTED**
+
+**Express / Fastify / Hono (middleware):**
+- Read the routesConfig file found in Step 1
+- Check if `"METHOD /path"` already exists as a key in routesConfig
+- If found: mark as **PROTECTED** and note the current price and network
+
+**All frameworks:**
+- Always check routesConfig for an existing `"METHOD /path"` key regardless of framework
+
+## Step 5 -- Present endpoint list
+
+Output exactly (replacing `{N}` with the count):
+
+> "Found {N} API endpoints. Select which to protect:"
+
+Then display a numbered list showing protection status:
+
+```
+1. [PROTECTED] GET /api/content ($0.001 USDC)
+2. [          ] POST /api/data
+3. [          ] GET /api/users
+```
+
+Protected endpoints show the current price. Unprotected endpoints have empty brackets.
+
+**Argument handling:** If `$ARGUMENTS` provides an endpoint path (e.g., the user ran `/x402:add-paywall /api/data`), auto-select that endpoint instead of presenting the full list. If the argument matches multiple methods for the same path, select all of them.
+
+**If ALL endpoints are already protected:** Output exactly:
+
+> "All selected endpoints are already protected. No changes made."
+
+Then STOP.
+
+## Step 6 -- Wrap selected endpoint(s)
+
+Read [references/patterns.md](references/patterns.md) for the framework-specific wrapping approach.
+
+### Next.js App Router (inline wrap)
+
+For each selected unprotected endpoint:
+
+1. **Read the route file** -- always read before editing (never assume file state)
+2. **Add import** -- if `withPayment` or `withX402` is not already imported, add the import:
+   ```typescript
+   import { withPayment } from "{relative_path_to_server}";
+   ```
+   Use the path to the x402 server file found in Step 1. Preserve existing imports -- do not duplicate.
+3. **Add marker comment** -- add `// x402: payment-protected endpoint` above the handler function
+4. **Wrap the handler** -- wrap the handler's body with `withPayment(req, () => { ... original handler ... })`:
+   ```typescript
+   // x402: payment-protected endpoint
+   export async function GET(req: Request) {
+     return withPayment(req, () => {
+       // ... original handler body ...
+     });
+   }
+   ```
+5. **Use Edit tool** to apply changes to the route file
+
+### Express / Fastify / Hono (middleware)
+
+For middleware-based frameworks, no route file changes are needed -- the middleware intercepts all routes listed in routesConfig.
+
+1. **Check middleware registration** -- Read the app setup file and verify middleware is registered:
+   - Express: `app.use(paymentMiddleware(...))` or `app.use(x402Middleware)`
+   - Fastify: `fastify.register(x402PaymentPlugin, ...)`
+   - Hono: `app.use(paymentMiddleware(...))` or `app.use(x402Middleware)`
+2. **If middleware not registered** -- add it to the app setup file (check first for idempotency)
+
+### All frameworks -- Add routesConfig entry
+
+For EVERY selected unprotected endpoint, regardless of framework:
+
+1. **Read the routesConfig file** found in Step 1
+2. **Add a new entry** using the Edit tool:
+   ```typescript
+   "METHOD /path": {
+     accepts: [
+       {
+         scheme: "exact",
+         price: "$0.001",
+         network: NETWORK,
+         payTo: SERVER_ADDRESS,
+       },
+     ],
+     description: "Description of endpoint",
+     mimeType: "application/json",
+   },
+   ```
+3. **Price default:** Use `"$0.001"` (dollar-sign prefix required) unless the user specifies a different price
+4. **Key format:** `"METHOD /path"` (e.g., `"GET /api/content"`, `"POST /api/data"`)
+
+## Step 7 -- Confirm
+
+For each endpoint that was successfully protected, output exactly (replacing `{path}` with the endpoint path):
+
+> "Protected {path} with x402 paywall. Price: $0.001 USDC per request."
+
+If an endpoint was already protected and skipped, output exactly:
+
+> "Endpoint {path} is already protected (price: {price} {asset}, network: {network}). No changes made."
+
+## Important Rules
+
+- **Idempotency is critical.** Always check for existing protection before making changes. Running this command twice on the same endpoint must produce no changes the second time.
+- **Always read before editing.** Use the Read tool on every file before modifying it. Never assume file contents.
+- **Preserve existing code.** When wrapping Next.js handlers, keep all existing imports, types, and logic intact. Only add the `withPayment` wrapper and marker comment.
+- **For Express/Hono/Fastify:** Only modify routesConfig to add the route entry. Do NOT modify individual route handler files -- the middleware handles interception automatically.
+- **Price format:** Always use dollar-prefixed strings (e.g., `"$0.001"`, not `"0.001"`).
+- **routesConfig key format:** Always use `"METHOD /path"` (e.g., `"GET /api/content"`).
+- **Marker comment:** Use exactly `// x402: payment-protected endpoint` -- this is the idempotency detection marker for Next.js routes.

package/skills/x402-add-paywall/references/patterns.md

@@ -0,0 +1,132 @@
+# x402 Endpoint Wrapping Patterns
+
+Reference for framework-specific x402 payment protection patterns. Read this before modifying any route files or middleware configuration.
+
+## Wrapping Strategy by Framework
+
+### Next.js App Router -- Inline Wrap
+
+Next.js route handlers must be wrapped individually because there is no global middleware interception point in App Router.
+
+**Pattern:** Import `withX402` (or `withPayment`) and wrap the exported handler function.
+
+**Using @x402/next (official):**
+
+```typescript
+import { withX402 } from "../lib/x402/server";
+import { routesConfig, resourceServer } from "../lib/x402/server";
+
+// x402: payment-protected endpoint
+export const GET = withX402(
+  async (req: Request) => {
+    return Response.json({ data: "protected content" });
+  },
+  routesConfig,
+  resourceServer,
+);
+```
+
+**Using custom withPayment (demo pattern):**
+
+```typescript
+import { withPayment } from "@/lib/x402/server";
+
+// x402: payment-protected endpoint
+export async function GET(req: Request) {
+  return withPayment(req, () => {
+    return Response.json({ data: "protected content" });
+  });
+}
+```
+
+**Endpoint detection:** Scan `app/api/` (or `src/app/api/`) recursively for `route.ts` or `route.js` files. Each file may export GET, POST, PUT, PATCH, DELETE handlers.
+
+### Express -- Middleware Registration
+
+Express uses global middleware. No changes to route handler files needed.
+
+**Pattern:** The `paymentMiddleware` from `@x402/express` intercepts all routes defined in `routesConfig`.
+
+```typescript
+// In app setup (e.g., server.ts or app.ts)
+import { paymentMiddleware } from "@x402/express";
+import { routesConfig, resourceServer } from "./lib/x402/server";
+
+app.use(paymentMiddleware(routesConfig, resourceServer));
+```
+
+**Endpoint detection:** Grep for `app.get(`, `app.post(`, `app.put(`, `app.patch(`, `app.delete(`, `router.get(`, `router.post(`, `router.put(`, `router.patch(`, `router.delete(` etc.
+
+### Fastify -- Plugin Registration
+
+Fastify uses a plugin. No changes to route handler files needed.
+
+**Pattern:** The custom `x402PaymentPlugin` intercepts all routes defined in `routesConfig`. Since `@x402/fastify` is not published on npm, use `@x402/core` directly with a custom `FastifyAdapter`.
+
+```typescript
+// In app setup (e.g., server.ts or app.ts)
+import { x402PaymentPlugin } from "./lib/x402/server";
+
+fastify.register(x402PaymentPlugin, { routesConfig, resourceServer });
+```
+
+**Endpoint detection:** Grep for `fastify.get(`, `fastify.post(`, `fastify.put(`, `fastify.patch(`, `fastify.delete(`, `fastify.route(` etc.
+
+### Hono -- Middleware Registration
+
+Hono uses global middleware. No changes to route handler files needed.
+
+**Pattern:** The `paymentMiddleware` from `@x402/hono` intercepts all routes defined in `routesConfig`.
+
+```typescript
+// In app setup (e.g., index.ts or app.ts)
+import { paymentMiddleware } from "@x402/hono";
+import { routesConfig, resourceServer } from "./lib/x402/server";
+
+app.use(paymentMiddleware(routesConfig, resourceServer));
+```
+
+**Endpoint detection:** Grep for `app.get(`, `app.post(`, `app.put(`, `app.patch(`, `app.delete(`, `app.route(` etc.
+
+## routesConfig Entry Format
+
+Every protected endpoint needs an entry in routesConfig:
+
+```typescript
+"METHOD /path": {
+  accepts: [
+    {
+      scheme: "exact",
+      price: "$0.001",
+      network: "stellar:testnet",
+      payTo: SERVER_ADDRESS,
+    },
+  ],
+  description: "Description of what this endpoint does",
+  mimeType: "application/json",
+},
+```
+
+**Key details:**
+- The key format is `"METHOD /path"` (e.g., `"GET /api/content"`, `"POST /api/data"`)
+- `price` must include the dollar-sign prefix (e.g., `"$0.001"`, not `"0.001"`)
+- `network` is `"stellar:testnet"` for development, `"stellar:mainnet"` for production
+- `payTo` is the Stellar public key (G...) that receives USDC payments
+- `scheme` is `"exact"` for fixed-price payments
+
+## Idempotency Detection
+
+Before making any changes, check if an endpoint is already protected.
+
+**For Next.js (inline wrap):**
+- Check if route file contains `// x402: payment-protected endpoint` comment
+- Check if route file imports `withPayment` or `withX402`
+- If either found: endpoint is already protected -- do not wrap again
+
+**For Express/Fastify/Hono (middleware):**
+- Check if routesConfig already contains the `"METHOD /path"` entry
+- If found: endpoint is already protected -- do not add duplicate entry
+
+**For all frameworks:**
+- Check routesConfig for existing `"METHOD /path"` key before adding a new entry
+- If the key exists, report the current price and network, skip with no changes

package/skills/x402-debug/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: x402-debug
+description: Diagnose x402 payment configuration issues. Runs static analysis checks on environment, dependencies, code structure, and framework setup.
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: [Read, Grep, Glob, Bash]
+---
+
+# /x402:debug
+
+> Run a comprehensive diagnostic check on your x402 payment configuration. I'll check everything: env vars, dependencies, code structure, and framework setup.
+
+## Instructions
+
+1. **Read the full checklist** from [references/checklist.md](references/checklist.md) to get all checks with their PASS/FAIL/WARN conditions and fix instructions.
+
+2. **Run EVERY check** in the checklist. No arguments, no scope narrowing, full checklist every time. Do not skip checks.
+
+3. **Static analysis only:** Use Read, Grep, and Glob to inspect files. Do NOT make network calls (no curl, no fetch, no API requests). Do NOT use Write or Edit -- this command is read-only.
+
+4. **Early exit -- no x402 setup detected:** Before running the checklist, check if `@x402/core` exists in `package.json` dependencies. If NOT found, output exactly:
+
+   "No x402 configuration detected. Run /x402:init first."
+
+   Then STOP. Do not run remaining checks.
+
+5. **Environment variable handling:**
+   - Read `.env.local` first. If `.env.local` doesn't exist, fall back to `.env`.
+   - If neither `.env.local` nor `.env` exists, report all env var checks as FAIL with fix instruction to create `.env.local`.
+   - Do NOT output env var values (security). Only report whether each variable is set/not set and whether its format is valid.
+
+6. **Framework detection order:**
+   - Detect framework FIRST (Category 4), then use detected framework for framework-specific checks in other categories.
+   - Detection priority when multiple frameworks found: Next.js > Express > Fastify > Hono.
+
+## Output Format
+
+Group results by category with markdown headers:
+
+### Environment Variables
+
+Report each env var check result on its own line.
+
+### Dependencies
+
+Report each dependency check result on its own line.
+
+### Code Structure
+
+Report each code structure check result on its own line.
+
+### Framework Detection
+
+Report each framework check result on its own line.
+
+**Formatting rules:**
+
+- Each check result on its own line using `[PASS]`, `[FAIL]`, or `[WARN]` prefix
+- FAIL items include `Fix:` on the next line (indented with two spaces) with the exact instruction from the checklist
+- Order within each category: FAIL items first, then WARN, then PASS
+- End with the summary line from the checklist (pass/fail/warning counts or "All checks passed. x402 is ready.")
+
+## Example Output
+
+```
+### Environment Variables
+[FAIL] Environment variable FACILITATOR_API_KEY: Not set
+  Fix: Add FACILITATOR_API_KEY to .env.local (see .env.example). Get a key at: https://channels.openzeppelin.com/testnet/gen
+[PASS] SERVER_STELLAR_ADDRESS
+[PASS] FACILITATOR_URL
+
+### Dependencies
+[PASS] @x402/core: Installed
+[PASS] @x402/stellar: Installed
+[PASS] Framework adapter: @x402/next installed
+[PASS] @x402/core version: 2.9.0
+
+### Code Structure
+[WARN] No protected endpoints in routesConfig
+  Fix: Run /x402:add-paywall to protect an endpoint
+[PASS] Route config: lib/x402/config.ts
+[PASS] Server middleware: lib/x402/server.ts
+[PASS] ExactStellarScheme: Correctly imported from server path
+[PASS] Price format: All prices use $ prefix
+
+### Framework Detection
+[PASS] Framework detected: Next.js
+[PASS] Adapter matches framework: Next.js
+
+### Summary
+10 passed, 1 failed, 1 warning. Fix the FAIL items above to complete your x402 setup.
+```