x402 Receipt Verifier

Сверяет собственные логи x402-платежей NEXUS с его собственными логами доставки и выдаёт подписанную квитанцию, подтверждающую, что конкретный платёж коррелирует с реальным успешным вызовом сервиса. Кандидат NEXUS #13 -- ручная сборка, а не сгенерированная FORGE.

• POST /verify-payment-receipt {"asset_name": "...", "payer_address": "0x...", "claimed_amount_usd": 0.01, "claimed_at": "2026-08-22T21:31:34Z"} — тарифицируется $0.02 через x402 (Base Sepolia testnet).

• POST /payer-spend-health {"asset_name": "...", "payer_address": "0x..."} — тарифицируется $0.02 через x402.

• POST /verify-receipt-signature {"receipt": {...}, "signature": "..."} — бесплатно, подтверждает, что ранее выданная квитанция подлинна и не изменена.

• MCP-инструменты verify_payment_receipt / payer_spend_health на /mcp — сейчас бесплатно, см. «Известные ограничения».

• GET /health, GET /.well-known/agent-card.json, GET /openapi.json (содержит x-payment-info).

Что он на самом деле делает (и почему это не просто выгрузка логов)

revenue_events (проведённые x402-платежи) и traffic_events (обслуженные HTTP-запросы) — это две отдельные, некоррелированные таблицы: ни одна вставка не сохраняет общий идентификатор, связывающий конкретный платёж с конкретным запросом, который этим платежом оплачен. Этот ассет выполняет корреляцию, которую сам NEXUS больше нигде не делает: по заявленным (asset_name, payer_address, claimed_amount_usd, claimed_at) он находит реальную соответствующую строку revenue_events (если она есть) в пределах window_seconds, а затем проверяет, пришлась ли успешная (2xx) строка traffic_events для того же ассета сразу после реальной платёжной метки времени. Продукт — вердикт (VERIFIED_DELIVERY / PAYMENT_NO_DELIVERY / PAYMENT_NOT_FOUND) плюс подписанная квитанция, а не сырой доступ к какой-либо из таблиц. Обе таблицы читаются через две RPC-функции Postgres с SECURITY DEFINER (nexus_verify_payment_receipt, nexus_payer_spend_health), которые возвращают только вычисленный объект вердикта и никогда не отдают дамп строк — это согласуется с существующей в этой кодовой базе политикой RLS «только INSERT» на обеих таблицах (см. CLAUDE.md SS5). Миграция: add_x402_payment_receipt_verification_rpcs (проект Supabase ieduhdgfjdeffvzxvihf).

Область охвата намеренно сужена: только собственные уже развёрнутые x402-ассеты NEXUS — то, что реально лежит в наших revenue_events/traffic_events. Аудит платёжных требований третьей стороны против логов третьей стороны был исходной, более широкой идеей (пункт №3 в списке возможностей, «recibo/prueba de ejecucion verificable para pagos entre agentes») и был явно отмечен там как несущий юридический/дискуссионный риск из-за выступления в роли арбитра между двумя другими сторонами. Сужение охвата до нашего собственного уже публичного каталога ассетов полностью обходит это — нет третьей стороны, чьи требования мы разбираем, есть только наши собственные уже проведённые данные.

Related MCP server: address-intel-api

Известные варианты написания 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 — это HMAC-SHA256 (в hex) над канонической JSON-кодировкой receipt, под ключом 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 не хранят общий корреляционный идентификатор в момент вставки, поэтому VERIFIED_DELIVERY означает «успешный запрос к этому ассету попал в окно после этого платежа», а не «именно этот запрос оплачен именно этой транзакцией». На ассете с низким трафиком это практически точной. На гипотетическом высокональном ассете с множеством одновременных вызывающих это было бы неоднозначным — в этом случае candidate_successful_calls (поверх в самой квитанции, см. PaymentReceipt в main.py) показал бы >1. По состоянию на 2026-08-23 ни на одном из охваченных 6 ассетов не было достаточно плотного одновременного трафика, чтобы это имело значение.

• Платёж проводится до выполнения Supabase RPC — инфраструктурный сбой после платежа — реальный провал «заплатил и не получил ничего», не раскрытый до этой строки (обнаружен в рамках гейта качества от 2026-08-23, функциональная/пользовательская линза). Если сам вызов nexus_verify_payment_receipt/nexus_payer_spend_health падает (Supabase недоступен, таймаут RPC, повреждённый ответ вышестоящей системы — см. пути 502/503/504 у _nexus_supabase_rpc), покупатель уже заплатил через PaymentMiddlewareASGI и получает ошибку вместо ответа, без какой-либо процедуры возврата. Сейчас это принято только потому, что это Base Sepolia testnet — никакому настоящих средств не под риском. Прежде чем переиспользовать такой же порядок «сначала платёж, потом RPC» на каком-либо мейннет-ассете, добавьте либо проверку доступности Supabase до платежа, либо перейдите на проведение платежа только после успешного результата обработчика.

• Обхода обход с анонимным ключом. Обе RPC-функции Postgres имеют грант на anon (это нужно, чтобы PostgREST вообще мог их выставить) — утёкший SUPABASE_ANON_KEY позволяет вызвать их напрямую по адресу /rest/v1/rpc/nexus_verify_payment_receipt, обходя x402-платление этого ассета. Приемлемо: RPC возвращают только корреляционные вердикты о собственном уже публичном каталоге NEXUS, сам обход ничего чувствительного не раскрывает, снимается только платёжный барьер. Тот же класс риска, что и в любом другом месте этой кодовой базы, где используется anon-ключ Supabase.

• Нет ограничения частоты запросов от вызывающего. Это нормально для одноразового 7-дневного окна измерений.

Гейт качества (развёртывание 2026-08-22, гейт завершён 2026-08-23 после перерыва по лимиту расходов)

Тот же процесс с двумя агентами, что и для кандидатов #3/#4/#6 (линза безопасности, функциональность + качество + покупательский опыт), в этот раз — после деплоя (когда месячный лимит расходов аккаунта прерывает сессию на ночь, ревью всё ещё шло; продолжено и завершено на следующей сессии. Реальные находки применены:

• Безопасность (1 находка, низкая): POST /verify-receipt-signature не имел x402-гейта и ограничений по размеру/глубине, поэтому он хэшировал произвольный словарь receipt, переданный вызывающим, бесплатно — дешевая помеха по стоимости/доступности, но не серьёзная уязвимость. Исправлено: тело размером более >4096 байт или глубже >10 уровней отклоняется с 400/413 до любого хэширования (_validate_receipt_shape, _MAX_RECEIPT_BYTES/_MAX_RECEIPT_DEPTH в main.py).

• Функциональность/пользовательский опыт (1 замечание, средняя): платёж проходит до запуска RPC, поэтому сбой инфраструктуры Supabase после платежа оставляет покупателя уже оплатившим без ответа и без решения — нераскрыто. Исправлено: отражено выше для «Известных ограничений» (без изменений кода; принято для testnet, необходимо пересмотреть перед использованием этого патолога на мейнnet).

• Всё остальное проверенное (класс SSRF из кандидата №3, класс zip-бомб/утечек потоков из кандидата №6, избыточный возврат для anon-RPC, верность HMAC, класс self-payment payTo из кандидата №4, усечение IP, поверхность инъекций) оказалось чистым — подтверждено перепротивившим соответствующие фрагменты кода, а не просто заявлено.

• Две косметические мелочи очень низкой важности сознательно идеально оставлены как есть: неиспользуемый параметр ctx: Context = None MCP-инструмента (та же конвенция неиспользуемых параметров уже есть в agent-verification-api/main.py, это не отклонение, которое стоит здесь исправлять) и молчаливое ограничение window_seconds/lookback_days только на MCP-пути (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).