x402-receipt-verifier

x402 收据验证器

核验 NEXUS 自身的 x402 付款日志与交付日志，并签发带签名的收据，证明特定付款对应一次真实且成功的服务调用。NEXUS 候选项目 #13——手动构建，非 FORGE 生成。

• POST /verify-payment-receipt {"asset_name": "...", "payer_address": "0x...", "claimed_amount_usd": 0.01, "claimed_at": "2026-08-22T21:31:34Z"} ——通过 x402 收取 $0.02（Base 主网，真实 USDC）。
• POST /payer-spend-health {"asset_name": "...", "payer_address": "0x..."} ——通过 x402 收取 $0.02。
• POST /verify-receipt-signature {"receipt": {...}, "signature": "..."} ——免费，确认此前签发的收据真实且未被篡改。
• /mcp 上的 MCP 工具 verify_payment_receipt / payer_spend_health ——目前免费，请参阅“已知限制”。
• GET /health、GET /.well-known/agent-card.json、GET /openapi.json（包含 x-payment-info）。

主网切换（2026-09-03）

最初在 Base Sepolia 测试网上构建并测量。现已切换至 Base 主网：x402 结算改用 CDP 协调器（create_facilitator_config()，同样的替换已应用于 ws/live-entity-verification/erc8004-agent-liveness/onchain-activity-index），收款钱包改用 NEXUS_X402_PAYTO_ADDRESS（缺少环境变量时会快速失败，无占位符默认值，原名为 X402_WALLET_ADDRESS）。部署前，必须在 Cloud Run 中设置 CDP_API_KEY_ID/CDP_API_KEY_SECRET 和 NEXUS_X402_PAYTO_ADDRESS。

实际功能（以及为何它不只是日志转储）

revenue_events（已结算的 x402 付款）和 traffic_events（已处理的 HTTP 请求）是两个独立且未关联的表——两者的插入记录都不包含可将特定付款与其所支付的特定请求关联起来的共享 ID。这个资产实现了 NEXUS 在其他任何地方都未实现的关联功能：给定 (asset_name, payer_address, claimed_amount_usd, claimed_at)，它会在 window_seconds 范围内查找真实匹配的 revenue_events 行（如果有），然后检查同一资产是否在该笔真实付款时间戳之后不久出现了成功（2xx）的 traffic_events 行。判定结果（VERIFIED_DELIVERY / PAYMENT_NO_DELIVERY / PAYMENT_NOT_FOUND）加上带签名的收据就是该产品，而不是对任一数据表的原始访问。两个表都通过两个 Postgres SECURITY DEFINER RPC 函数 （nexus_verify_payment_receipt、nexus_payer_spend_health）读取；这些函数只返回计算所得的判定对象，绝不转储表行——这与该代码库对这两个表现有的仅允许 INSERT 的 RLS 策略一致（见 CLAUDE.md SS5）。迁移：add_x402_payment_receipt_verification_rpcs（Supabase 项目 ieduhdgfjdeffvzxvihf）。

**有意限定范围：**仅涵盖 NEXUS 自身已部署的 x402 资产（即我们自己的 revenue_events/traffic_events 中实际存在的资产）。核验第三方付款声明与第三方日志，是最初更宽泛的构想（机会清单第 #3 项，“面向 Agent 间付款的可验证收据/执行证明”），并且当时已明确指出，充当另外两方之间的仲裁者会带来法律/争议责任风险。将范围缩小到我们自身已公开的资产目录，就完全避开了这一风险——没有第三方的声明需要我们裁定，只有我们自己已结算的数据。

已知的 asset_name 拼写（构建时发现，来自真实数据）

现有目录中的 revenue_events.asset_name 并非始终采用 kebab-case——例如，相似度搜索资产实际存储的值是 "Similarity Search API"（显示名称格式），而不是 similarity-search-api。调用方必须传入与存储值完全一致的字符串，否则 RPC 会正确地（并非错误地）返回 PAYMENT_NOT_FOUND。截至本文撰写时，在 revenue_events 中看到的真实值有：document-conversion-api、 live-entity-verification、agent-verification-api、url-metadata-api、Similarity Search API、ws。

已签名的收据

signature 是对 receipt 的规范 JSON 编码进行 HMAC-SHA256（十六进制）计算得到的签名，密钥为 NEXUS_RECEIPT_SIGNING_KEY。这不是可离线验证的签名（那需要非对称加密和公开的公钥——我们刻意不实现，见“已知限制”）：持有者可通过调用此资源自有的免费 POST /verify-receipt-signature 证明收据真实有效，该接口会在服务端重新验证 HMAC。轮换 NEXUS_RECEIPT_SIGNING_KEY 会使使用旧密钥签发的所有收据失效。

部署目标：Cloud Run

与候选项 #4/#3/#6 使用相同的流水线——参见 skills/infra-deploy-ops。

# 1. First deploy -- PUBLIC_DOMAIN not known yet, every real request 421s until step 2.
./scripts/deploy_cloud_run.sh x402-receipt-verifier manual_assets/x402-receipt-verifier

# 2. Grab the printed *.run.app URL, then (only if it differs from env-vars.deploy.yaml's guess):
gcloud run services update x402-receipt-verifier --region us-central1 --project nexus-505016 \
    --update-env-vars PUBLIC_DOMAIN=<the-real-domain>

已知限制（刻意不修复——CLAUDE.md SS3，没有证据表明需要时不设门槛）

• MCP 工具调用不收费。 与此代码库中其他所有手动资源采用相同的进程内调用模式（url-metadata-api、agent-verification-api、document-conversion-api）。
• 收据签名需要在线检查，不能离线进行非对称验证——见上文。
• 关联匹配采用时间窗口启发式，而非硬性关联。 revenue_events 和 traffic_events 在插入时都不会存储共享的关联 ID，因此 VERIFIED_DELIVERY 表示“此资源收到了一次成功请求，且该请求发生在付款后的窗口期内”，而非“这次确切的请求由这笔确切的交易支付”。对于低流量资源，这实际上等同于精确关联；对于假设中的高流量资源，如果有许多并发调用者，就会产生歧义——此时 candidate_successful_calls（直接显示在 receipt 上，见 main.py 中的 PaymentReceipt）会大于 1。截至 2026-08-23，涵盖的 6 个资源都没有密集到足以造成此问题的并发流量。
• 付款会在 Supabase RPC 运行前结算…… 已于 2026-08-31 更正：这是误报，见下文。 2026-08-23 的质量门禁声称，即使 Supabase 失败，付款仍会结算；但此前没人真正阅读过 x402（固定版本 2.15.0）的 PaymentMiddlewareASGI 源码。它已实现“验证→执行→仅在状态码为 2xx 时结算”：verify_payment（不转移资金）会在处理程序执行前通过 call_next(request) 运行；当处理程序返回 ≥400 或抛出异常时（此处 Supabase 失败时，_verify_payment_receipt_core 会将 _NexusRpcError 重新抛为 HTTPException(502/503/504)），中间件会调用 dispatcher.cancel()，绝不会调用 process_settlement()——不会收费。已通过实测确认（真实应用 + 真实 PaymentMiddlewareASGI + 模拟 facilitator，强制触发 HTTPException(504)）：失败时 settle()/on_after_settle 调用次数为 0，返回 200 时为 1。无需更改代码——架构本来就是正确的。
• 匿名密钥 RPC 绕过。 两个 Postgres RPC 函数都已授权给 anon（这是 PostgREST 能公开这些函数的必要条件）——如果 SUPABASE_ANON_KEY 泄露，有人就能直接通过 /rest/v1/rpc/nexus_verify_payment_receipt 调用这些函数，绕过此资源的 x402 收费。我们接受此风险：这些 RPC 只会返回关于 NEXUS 自有且已公开资源目录的关联判断；绕过本身不会泄露敏感信息，只会绕过付费墙。这与此代码库中其他所有 Supabase 匿名密钥的使用属于同一风险类别。
• 没有针对每个调用者的速率限制。 对于为期 7 天的一次性测量窗口，这样做没有问题。

质量门禁（2026-08-22 部署，2026-08-23 因支出限额中断后完成门禁检查）

采用与候选项目 #3/#4/#6 相同的双 Agent 流程（安全视角；功能、质量和买家体验视角）， 这次在部署后运行审核——账户的月度支出限额在夜间中断了仍在进行中的审核，下一次会话中恢复并完成。发现了真实问题，并已处理：

• 安全（1 项发现，低风险）： POST /verify-receipt-signature 没有 x402 门禁，也没有大小或深度限制， 因此调用方可以免费提交任意 receipt 字典并让服务对其进行哈希处理——这是低成本的成本/可用性困扰，不是严重漏洞。已修复：在进行任何哈希处理前，拒绝超过 4096 字节或深度超过 10 层的请求体，返回 400/413 （main.py 中的 _validate_receipt_shape、_MAX_RECEIPT_BYTES/_MAX_RECEIPT_DEPTH）。
• 功能/买家体验（1 项发现，中风险）——2026-08-31 撤回： 最初报告的问题是 “RPC 执行前就已结算付款，因此 Supabase 故障会导致买家已付款却无从补救。” 这是对 PaymentMiddlewareASGI 的误读，并非实际 bug——实证证明见上文“已知限制”。无需更改代码。
• 检查的其他所有方面（候选项目 #3 中的 SSRF 类问题、候选项目 #6 中的压缩包炸弹/线程泄漏类问题、 匿名密钥 RPC 返回过多数据、HMAC 正确性、候选项目 #4 中的自付费 payTo 类问题、IP 截断、 注入面）均未发现问题——这些结论是通过重新阅读相关代码路径确认的，而非仅仅声称。
• 两项非常低风险的外观问题有意保留原样：未使用的 ctx: Context = None MCP 工具参数 （与 agent-verification-api/main.py 中已有的同类未使用参数惯例一致，不值得在此处特意修正）以及仅在 MCP 路径上对 window_seconds/lookback_days 静默限幅 （REST 已通过 Pydantic 拒绝超范围值；MCP 路径会在回执中回显替换后的值，因此可以发现，只是没有明确报错——目前没有证据表明这需要设置门禁）。

测量（候选项目 #13，7 天窗口）

从首次实际部署起的 7 天窗口（2026-08-23 -> 2026-08-30 决策点）。事实来源： traffic_events/revenue_events/mcp_call_events（asset_name = 'x402-receipt-verifier'），而非 Cloud Run 日志。第 7 天：如果没有实际流量（过滤爬虫后），暂停/删除 Cloud Run 服务 （gcloud run services delete x402-receipt-verifier --region us-central1 --project nexus-505016）。