docs: facilitator deployment + SDK x402 integration#98
docs: facilitator deployment + SDK x402 integration#98
Conversation
Adds two operations docs alongside the audit/P0 work, written and verified by parallel research agents against the actual repo state. ## docs/deployment/facilitator-deployment.md (694 lines) End-to-end deployment guide for the x402 facilitator service in `packages/x402-facilitator-node/`. Covers RPC selection, env config, Docker / systemd / managed-platform options, DNS + TLS, on-chain whitelist registration (deferred to P0-12b), HMAC challenge usage, health monitoring, and emergency rollback. Verified locally: - pnpm install / typecheck / build all pass - node dist/index.js boots; well-known and root endpoints respond - /health returns 503 on a public Sepolia RPC that no longer accepts requests (recommend Alchemy in production) - Found pre-existing bug in middleware/hmac-challenge.ts: hmacChallengeInjector only injects X-Challenge on status === 402, but the facilitator never returns 402, so clients can never obtain a challenge. Documented as a pre-launch fix item; not in scope for this docs PR. Docker build was not exercised because no container runtime is available on the audit machine; documented as an open verification. ## docs/integration/sdk-x402-integration.md (583 lines) Integration manual for `@aastar/x402`, `@aastar/channel`, `@aastar/cli`, and `@aastar/core`'s x402 actions, plus how all of them sit on top of the facilitator service and SuperPaymaster's on-chain settle paths. Includes three integration scenarios (server SDK, wallet auto-settle, agent micropayments), full EIP-3009 typed data, HMAC client implementation, and a Sepolia integration checklist. Verified by reading SDK source at /Users/jason/Dev/aastar/aastar-sdk: - @aastar/x402: 37/37 vitest pass - @aastar/channel: 11/11 pass - @aastar/cli: 1/1 pass - packages/x402-facilitator-node has no tests (recommended in TODO) Notable findings flagged in the doc: - ABI sync gap: P0-13 (a90c4ac in fix/p0-wave2-funds-price) added x402NonceKey to SuperPaymaster but ABI is not yet synced to aastar-sdk; SDK still queries x402SettlementNonces with single-key, which will silently return false after P0-13 lands on main. - Schema mismatch: facilitator-node uses {payment, scheme} flat fields; SDK FacilitatorClient sends x402 v2 spec {x402Version, paymentPayload, paymentRequirements}. Need spec alignment before SDK can drive our own facilitator end-to-end. - HMAC is implemented as a hono middleware pair, not a separate /verify-then-/settle round trip; doc reflects actual behavior. ## Cross-references - Audit baseline: docs/security/2026-04-26-p0-prelaunch.md (audit branch) - Decision history: docs/security/2026-04-26-decision-records.md (D4) - Threat model: docs/security/2026-04-26-threat-model.md - Pending P0 dependencies (Wave 2): P0-12a / P0-12b for on-chain approvedFacilitators whitelist + isXPNTs check; P0-13 (already on fix/p0-wave2-funds-price) for nonce key change ## Why a separate PR - Docs are independent of any single P0 fix; reviewable on their own - Stage 1 P0 PRs stay focused on contract changes + tests - SDK team can begin integration work against this doc in parallel with Wave 2 contract reviews
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ff6101b9fb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| pnpm install --prod | ||
| pnpm build |
There was a problem hiding this comment.
The systemd setup installs with pnpm install --prod and immediately runs pnpm build; in this package, build is tsc, which is only in devDependencies. On a clean server this sequence fails because the TypeScript compiler is not installed, so Option B deployment cannot complete as written.
Useful? React with 👍 / 👎.
| const trigger = await fetch('https://facilitator.example.com/some-paid-endpoint'); | ||
| const challenge = trigger.headers.get('X-Challenge'); | ||
| if (!challenge) throw new Error('Facilitator did not issue challenge'); |
There was a problem hiding this comment.
This snippet fetches https://facilitator.example.com/some-paid-endpoint to obtain X-Challenge, but facilitator-node does not expose a paid endpoint that returns 402, so this call returns 404/no challenge and the subsequent HMAC /settle flow cannot proceed. The challenge needs to come from an endpoint that actually emits a 402 response (or a dedicated challenge route).
Useful? React with 👍 / 👎.
代码审查警告 — 需修复后合并 必须修复（合并前） H1 — 文档中硬编码了开发者本地绝对路径 H2 — 建议修复 M1 — facilitator-node ↔ SDK schema 不兼容优先级标注不足 M2 — L1 — docker-compose.yml 示例中的废弃 |
…tator docs H1: Replace all /Users/jason/Dev/aastar/... absolute paths in sdk-x402-integration.md and facilitator-deployment.md with environment variable placeholders ($SUPERPAYMASTER_ROOT, $AASTAR_SDK_ROOT) so the docs are portable across developer machines. H2: Resolve contradiction between facilitator-deployment.md §8.2 and §8.4. Add a prominent warning block in §8.2 explaining that hmacChallengeInjector only fires on HTTP 402 responses while /verify returns 200/400, so X-Challenge is never injected in practice. The client flow steps are updated to reflect this current behavior while preserving the design intent. Closes #98
修复说明本次 commit 修复了两类问题： H1：硬编码绝对路径
文档顶部建议开发者在环境中设置这两个变量（e.g. H2：§8.2 与 §8.4 HMAC 流程矛盾
修复：在 |
…cker-compose version field
|
已处理剩余三条 reviewer 建议： M1 — P1 → P0（schema 不兼容） M2 — verify.ts nonce 查询需改为三元组哈希 L1 — 移除废弃的 docker-compose version 字段 请 re-review，谢谢 🙏 |
2 participants
Summary
为 SuperPaymaster x402 体系新增两份运营级文档，独立于 Stage 1 P0 修复 PR：
packages/x402-facilitator-node/）的端到端部署指南@aastar/x402/@aastar/channel/@aastar/cli的集成手册 + Sepolia 联调清单两份文档由并行 agent 写成，并对实际仓库状态做了验证（不是凭印象写）。
验证摘要
facilitator-deployment.md
pnpm install/typecheck/build全过node dist/index.js可启动；/、/.well-known/x-payment-info200/health在公共 Sepolia RPC 上 503（不是服务 bug，公共 RPC 已停服 —— 已写入 §3.2 推荐 Alchemy）middleware/hmac-challenge.ts:102只在status === 402注入 X-Challenge，但 facilitator 没路径返回 402 → settle 永远拿不到 challenge。已写入文档 §8.4 + §11.2，标为生产前必修（不在本 PR 范围）sdk-x402-integration.md
@aastar/x40237/37 vitest 通过@aastar/channel11/11 通过@aastar/cli1/1 通过packages/x402-facilitator-node没有任何测试，已写入 SDK TODOfix/p0-wave2-funds-price）给 SuperPaymaster 加了x402NonceKey，但 SDK ABI 未同步。P0-13 合入 main 后，SDK 现有的x402SettlementNonces({nonce})单参数查询会永远返回 false（旧 key 没人写）—— 必须配合更新{payment, scheme}平面字段；SDK FacilitatorClient 发 x402 v2 spec{x402Version, paymentPayload, paymentRequirements}。当前 SDK 不能直接驱动我们自家 facilitator，需要 facilitator 升级到 v2 spec 或 SDK 提供专用 client/verify→/settleround trip，文档已按源码改正后续动作（不在本 PR 范围）
依赖项：
approvedFacilitators+ isXPNTs 白名单 → facilitator 链上注册路径才完整可用hmac-challenge.ts:102注入条件关联
security/audit-2026-04-25分支）Test plan