x402 Receipt Verifier

Audita los registros de pago x402 de NEXUS contra sus propios registros de entrega y emite un recibo firmado que demuestra que un pago concreto se corresponde con una llamada de servicio real y exitosa. Candidato #13 de NEXUS -- construcción manual, no generada por FORGE.

• POST /verify-payment-receipt {"asset_name": "...", "payer_address": "0x...", "claimed_amount_usd": 0.01, "claimed_at": "2026-08-22T21:31:34Z"} -- se cobra $0.02 mediante x402 (Base Sepolia testnet).

• POST /payer-spend-health {"asset_name": "...", "payer_address": "0x..."} -- se cobra $0.02 mediante x402.

• POST /verify-receipt-signature {"receipt": {...}, "signature": "..."} -- gratuito, confirma que un recibo emitido previamente es auténtico y no ha sido modificado.

• Herramientas MCP verify_payment_receipt / payer_spend_health en /mcp -- actualmente gratuitas, ver "Limitaciones conocidas".

• GET /health, GET /.well-known/agent-card.json, GET /openapi.json (incluye x-payment-info).

Qué hace en realidad (y por qué no es solo un volcado de registros)

revenue_events (pagos x402 liquidados) y traffic_events (peticiones HTTP atendidas) son dos tablas separadas y sin correlación: ninguna de las inserciones guarda un identificador compartido que vincule un pago concreto con la solicitud concreta que pagó. Este activo realiza la correlación que NEXUS no hace en ningún otro lugar: dado un valor reclamado (asset_name, payer_address, claimed_amount_usd, claimed_at), busca la fila real correspondiente en revenue_events (si existe) dentro de window_seconds y luego comprueba si una solicitud correcta (2xx) de traffic_events para ese mismo activo llegó poco después de esa marca de tiempo real de pago. El veredicto (VERIFIED_DELIVERY / PAYMENT_NO_DELIVERY / PAYMENT_NOT_FOUND) junto con un recibo firmado es el producto, no el acceso directo a ninguna de las dos tablas. Ambas tablas se leen a través de dos funciones RPC SECURITY DEFINER de Postgres (nexus_verify_payment_receipt, nexus_payer_spend_health) que solo devuelven el objeto del veredicto calculado, nunca un volcado de filas, en coherencia con la política RLS de solo INSERT ya existente en este repositorio para ambas tablas (ver CLAUDE.md SS5). Migración: add_x402_payment_receipt_verification_rpcs (proyecto de Supabase iedahdgfjdeffvzxvihf).

Alcance, a propósito: solo cubre los activos x402 ya desplegados del propio NEXUS (lo que realmente haya en nuestro revenue_events/traffic_events). Auditar las reclamaciones de pago de un tercero contra los registros de un tercero era la idea original más amplia (elemento #3 de la lista de oportunidades, "recibo/prueba de ejecucion verificable para pagos entre agentes") y se marcó explícitamente como riesgo de responsabilidad legal/disputas al actuar como árbitro entre dos partes. Reducir el alcance a nuestro propio catálogo ya público evita en gran parte ese riesgo: no hay ningún tercero cuya reclamación estemos juzgando; solo nuestros propios datos ya liquidados.

Related MCP server: address-intel-api

Grafías conocidas del campo asset_name (descubiertas al construir esto; datos reales)

revenue_events.asset_name no es uniformemente kebab-case dentro del catálogo: p.ej., el valor real almacenado del activo de búsqueda por similitud es "Similarity Search API" (en formato de pantalla), no similarity-search-api. Los llamadores deben pasar la cadena exacta tal como está guardado; si no, la RPC devuelve correctamente (no es un error) PAYMENT_NOT_FOUND. Hasta la fecha, los valores reales vistos en revenue_events son: document-conversion-api, live-entity-verification, agent-verification-api, url-metadata-api, Similarity Search API, ws.

El recibo firmado

signature es un HMAC-SHA256 (en hexadecimal) sobre la codificación JSON canónica de receipt, firmado con la clave NEXUS_RECEIPT_SIGNING_KEY. No es una firma que se pueda verificar fuera de línea (eso requeriría criptografía asimétrica y una clave pública publicada, algo dejado a propósito fuera; ver "Limitaciones conocidas"): un poseedor demuestra que un recibo es auténtico llamando al servidor de este activo mediante POST /verify-receipt-signature, que vuelve a comprobar el HMAC en el backend. Rotar NEXUS_RECEIPT_SIGNING_KEY invalida todo recibo emitido con la clave anterior.

Destino de implementación: Cloud Run

Mismo pipeline que los candidatos #4/#3/#6: ver 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>

Limitaciones conocidas (dejadas sin corregir a propósito -- CLAUDE.md SS3, sin barrera de control sin evidencia de que se necesite)

• Las llamadas a las herramientas MCP no se cobran. Mismo patrón de llamada dentro del proceso que el resto de activos manuales de este repositorio (url-metadata-api, agent-verification-api, document-conversion-api).

• La firma del recibo requiere verificación en línea, no una verificación asimétrica fuera de línea (ver más arriba).

• La correlación es una heurística de ventana de tiempo, no un vínculo rígido. Ni revenue_events ni traffic_events incluyen un identificador de correlación compartido en el insert, por lo que VERIFIED_DELIVERY significa "una llamada original con éxito a este activo llego dentro de la ventana después de este pago", no "este pago pagó exactamente por dicha solicitud". En un activo con poco tráfico, es prácticamente exacto; en un activo hipotéticamente de alto tráfico con muchas llamadas concurrentes sería ambiguo; en ese caso, candidate_successful_calls (que aparece directamente en el receipt por el tipo PaymentReceipt de main.py) mostraría varios valores mayores que 1. Ninguno de los 6 activos analizados hasta ahora tenía un tráfico concurrente tan denso como para que esto importe (2026-08-23).

• El pago se liquida antes de que se ejecute la RPC de Supabase: un fallo de infraestructura posterior al pago es una brecha real de "pagar por nada", no documentada hasta esta línea (encontrado durante la evaluación de calidad del 2026-08-23, perspectiva funcional / experiencia del comprador). Si nexus_verify_payment_receipt/nexus_payer_spend_health falla (Supabase caído, demanda agotada, respuesta descendente con mal formato; rutas 502/503/504 de _nexus_supabase_rpc), el comprador ya ha pagado mediante PaymentMiddlewareASGI y recibe a cambio un error, no una respuesta, sin posibilidad de reintegrar. Aceptado temporalmente solo por ser esta una testnet de Base Sepolia, sin fondos reales en riesgo: antes de reutilizar este mismo esquema de "pago => RPC" en un activo de mainnet, hay que añadir una comprobación de accesibilidad a Supabase antes del pago o modificar la secuencia para que el pago solo se liquide después de obtener un resultado exitoso en el handler.

• Bypass de la clave anónima RPC. Las dos funciones RPC de Postgres están asignadas a anon (requisito para que PostgREST las exponga en absoluto); una filtración de SUPABASE_ANON_KEY permitiría llamarlas de forma directa en /rest/v1/rpc/nexus_verify_payment_receipt, eludiendo el cargo x402 de este activo. Aceptado: las RPC solo devuelven veredictos de correlación sobre el catálogo público ya del propio NEXUS; el bypass no expone nada sensible, pasa el pago por la puerta, nada más. Está en la misma categoría de riesgo que cualquier otro uso de la clave anónima de Supabase en este proyecto.

• No hay límite de tasa por llamador. Correcto para una ventana de medición desechable de 7 días.

Evaluación de calidad (despliegue 2026-08-22; evaluación terminada el 2026-08-23 después de una interrupción por límite de gasto)

Mismo proceso de 2 agentes que los candidatos #3/#4/#6 (perspectiva de seguridad; perspectiva funcional/calidad/experiencia del comprador), pero esta vez ejecutado después del despliegue; la revisión aún seguía en curso cuando el límite de gasto mensual de la cuenta interrumpió la sesión durante la noche, y se reanudó y finalizó en la siguiente sesión. Hallazgos reales, aplicados:

• Seguridad (1 hallazgo; prioridad baja): POST /verify-receipt-signature no tenía compuerta x402 ni delimitación de tamaño/profundidad, por lo que generaba un hash del diccionario receipt que enviaba el usuario, de forma gratuita; era una mejora de coste/disponibilidad, no una vulnerabilidad crítica. Corregido: rechaza con 400/413 los cuerpos > 4096 bytes o de profundidad >10 niveles antes de ningún cálculo hash (_validate_receipt_shape, _MAX_RECEIPT_BYTES/_MAX_RECEIPT_DEPTH en main.py).

• Funcional / experiencia del comprador (un hallazgo medio): el pago se liquida antes de la ejecución de las RPC; si la infraestructura Supabase falla después del pago, el comprador paga y solo recibe error, sin opción de reembolso no documentada. Corregido: se documenta en "Limitaciones conocidas" (sin cambio de código; aceptado en testnet, debe analizarse de nuevo en cualquier reaprovechamiento en mainnet). Todo lo demás comprobado (aspecto SSRF del candidato #3, aspecto de zip-bomb/escape de hilos del candidato #6, exceso de devolución de la RPC con by-pass, correctez del HMAC, aspecto de autopago con payTo del candidato #4, truncación de IP, superficie de inyección) salió limpio, confirmado mediante relectura de los recorridos relevantes del código y no por suposición. Dos elementos de pura estética fueron dejados intactos a propósito: un parámetro no utilizado ctx: Context = None en una herramienta MCP (coherente con la convención de parámetros no utilizados en agent-verification-api/main.py) y la limitación silenciosa de window_seconds/lookback_days en la ruta solo de MCP (el REST ya rechaza fuera de rango mediante Pydantic; el MCP devuelve el valor ajustado en el receipt, capaz de descubrirse, aunque no con un explicito error) -- sin pruebas de que necesite un candado.

Medición (candidato #13; ventana 7 días)

Ventana de 7 días desde el primer despliegue real (2026-08-23 => punto de decisión 2026-08-30). Fuente de verdad: traffic_events/revenue_events/mcp_call_events (asset_name = 'x402-receipt-verifier'), no los logs de Cloud Run. Día 7: si el tráfico real es cero excluyendo bugs de rastreo (crawler), pausar/eliminar el servicio de Cloud Run (gcloud run services delete x402-receipt-verifier --region us-central1 --project nexus-505016).