Website Intelligence Provider

Independent TypeScript API for deterministic website-intelligence audits. It accepts a URL and produces bilingual English or Spanish findings from bundled fixtures.

API TypeScript independiente para auditorías deterministas de inteligencia web. Recibe una URL y genera hallazgos en inglés o español mediante fixtures incluidos.

No-network default: the service never contacts the submitted URL. Unknown hosts fail closed with FIXTURE_NOT_FOUND. The audit response records network.attempted: false and network.allowed: false.

Red deshabilitada por defecto: el servicio nunca contacta la URL recibida. Los hosts desconocidos fallan de forma segura con FIXTURE_NOT_FOUND.

Public deployment / Despliegue público

• GitHub: https://github.com/CaBsCrypto/website-intelligence-provider

• Stable production deployment: https://website-intelligence-provider.vercel.app

The Vercel project is standalone and uses the functions under api/. vercel.json maps the public routes to those functions. It does not depend on Stellar Bazaar and does not contain Bazaar credentials or deployment hooks.

El proyecto de Vercel es independiente y usa las funciones en api/. No depende de Stellar Bazaar ni contiene credenciales o automatizaciones de Bazaar.

Related MCP server: web-audit-mcp

Requirements / Requisitos

• Node.js 22.18 or newer

• npm 10 or newer

• No production runtime dependencies / Sin dependencias de producción

Local development / Desarrollo local

npm install
npm test
npm start

The server binds to 127.0.0.1:8787 by default. Set PORT to override it.

El servidor escucha en 127.0.0.1:8787 por defecto. Usa PORT para cambiarlo.

curl -s http://127.0.0.1:8787/v1/audits \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com/","language":"es"}'

HTTP API

Request / Solicitud:

{ "url": "https://example.com/", "language": "es" }

language is optional and defaults to en. Supported values are en and es.

x402 Stellar Testnet provider slice

The feature branch exposes one payment-protected resource: POST /v1/x402/audits. It implements the x402 v2 HTTP transport and returns an actual HTTP 402 Payment Required with a base64-encoded PaymentRequired object in PAYMENT-REQUIRED.

La rama de funcionalidad expone un recurso protegido: POST /v1/x402/audits. Implementa el transporte HTTP x402 v2 y devuelve un 402 Payment Required real con PaymentRequired codificado en base64 dentro de PAYMENT-REQUIRED.

Exact-price contract:

• Scheme: exact

• Network: Stellar Testnet, CAIP-2 stellar:testnet

• Asset: SEP-41 Testnet USDC contract CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA

• Amount: 10000 atomic units (0.0010000 USDC at 7 decimals)

• Fees: facilitator-sponsored, advertised as extra.areFeesSponsored: true

• SDK compatibility: pinned Apache-2.0 @x402/core@2.24.0 and @x402/stellar@2.24.0, using ExactStellarScheme

• Settlement: disabled by default

• Recipient: Stellar G- or C-address supplied through X402_STELLAR_PAY_TO

The retry request carries an x402 v2 Stellar PaymentPayload in PAYMENT-SIGNATURE; its payload.transaction is the base64 transaction XDR containing the signed Soroban authorization entries. The provider validates protocol version, exact Stellar requirements, resource URL, method, route, canonical input hash, and Service Card hash before crossing the facilitator boundary. With settlement enabled it first checks /supported for sponsored exact support on stellar:testnet, then calls /verify and /settle. Settlement failure returns 402 and withholds provider output.

Replay protection supports two explicit modes. The authorized local validation profile uses one process-local reservation. A Vercel/multi-instance runtime requires a dedicated Upstash-compatible Redis REST store and uses atomic SET NX reservations plus an atomic Lua commit for the delivery envelope and receipt. Missing or unavailable durable storage fails closed before settlement. The public paid endpoint remains inactive until dedicated provider storage is provisioned, configured and validated; Bazaar storage credentials must not be reused.

El reintento envía PaymentPayload en PAYMENT-SIGNATURE. El proveedor valida versión, requisitos exactos de Stellar, recurso y binding SHA-256 antes de invocar el adaptador; el facilitador valida en el XDR firmado el activo, destinatario, monto y autorizaciones Soroban. Si la liquidación falla, retiene el resultado y devuelve 402.

Successful responses include:

• x402 SettlementResponse in the PAYMENT-RESPONSE header;

• the deterministic audit in data;

• a provider receipt containing request hash, output hash, exact payment terms, payer and transaction;

• a reconciliation contract that detects receipt or request/output tampering.

Durable buyer-owned recovery

A buyer may opt into recovery before authorizing payment by generating a random 256-bit token locally. The paid request sends only SHA-256(token) in X-BAZAAR-RECOVERY-PROOF plus a 32-hex request identifier in X-BAZAAR-REQUEST-ID. The provider atomically stores the proof together with the immutable result and receipt, and returns a public recoveryId.

The token remains buyer-owned and must be treated like a password. It is never placed in a URL, Service Card, receipt, logs, Git, MCP output or provider response. Recovery uses a POST body containing version, recoveryId, requestId and the token. A successful recovery returns the original result and receipt without calling /verify, /settle or the buyer signer again. Invalid, missing, expired or mismatched capabilities fail closed. The current retention window is 24 hours.

El comprador puede generar localmente un token aleatorio de 256 bits antes de autorizar. El proveedor recibe únicamente su hash, guarda de forma atómica la entrega inmutable y permite recuperarla mediante POST. El token se trata como contraseña y nunca aparece en URLs, recibos, logs o respuestas. Recuperar una entrega no vuelve a cobrar ni invoca al facilitador.

Recovery covers a lost HTTP response after the durable delivery commit. It cannot make the external Stellar settlement and Redis commit atomic. If the process or store fails after settlement but before commit, the endpoint fails closed with DELIVERY_PERSISTENCE_UNAVAILABLE; operators must reconcile the ledger evidence and restore the immutable record, and the buyer must not authorize another payment. Automated pre-commit crash recovery remains a separate operational milestone.

Buyer-harness environment

Copy .env.example to the ignored .env.local file. npm start loads that file automatically on Node.js 22.18+. Required values:

X402_PUBLIC_BASE_URL=https://provider.example
X402_ALLOWED_PUBLIC_BASE_URLS=https://provider.example
X402_STELLAR_PAY_TO=GYourStellarTestnetRecipientAddress
STELLAR_X402_FACILITATOR_URL=https://channels.openzeppelin.com/x402/testnet
X402_SETTLEMENT_ENABLED=false
X402_MANUAL_SINGLE_PROCESS_TESTNET=false
STELLAR_X402_FACILITATOR_API_KEY=

X402_PUBLIC_BASE_URL must be an explicit canonical HTTPS origin and must also appear exactly in X402_ALLOWED_PUBLIC_BASE_URLS; localhost, HTTP, credentials, paths, queries and fragments fail closed. X402_STELLAR_PAY_TO must be a valid Stellar G- or C-address controlled by the Testnet recipient and able to receive the configured USDC asset. The default facilitator is OpenZeppelin Channels for Stellar Testnet; it requires STELLAR_X402_FACILITATOR_API_KEY as a server-only secret for its supported, verify, and settle calls. On Vercel, WEBSITE_INTELLIGENCE_REDIS_REST_URL and WEBSITE_INTELLIGENCE_REDIS_REST_TOKEN are additionally required. The dynamic Service Card keeps payment.enabled: false until the applicable profile is complete. No NEXT_PUBLIC or browser-visible variable is used.

X402_MANUAL_SINGLE_PROCESS_TESTNET=true is only for an explicitly authorized local Testnet E2E in one controlled Node process. It never enables a Vercel/Lambda runtime. Multi-instance settlement requires the dedicated durable variables instead.

Verified Testnet evidence / Evidencia verificada

The first reconciled external-provider purchase completed on Stellar Testnet for exactly 0.001 USDC (10000 atomic units). Transaction 48d2a2cc92b9433cca611c778b605c759613278c074557ffc6f7c57307d9356f, ledger 4416660, transferred from the shortened test payer GCHU7I…MHQQRW to the shortened test seller GAHOZF…J3WCSM. The provider returned the deterministic result only after reconciling the transaction operation, SAC asset, payer, recipient, amount and ledger. This is Testnet POC evidence, not Mainnet, production readiness or an audit claim.

La primera compra reconciliada se completó en Stellar Testnet por 0.001 USDC. El resultado se entregó únicamente después de reconciliar la evidencia on-chain. Es evidencia de POC en Testnet, no una afirmación de producción, Mainnet o auditoría.

The buyer harness—not this provider—must use @x402/stellar client support and a Stellar Testnet signer capable of signing Soroban authorization entries. It must preserve the website-intelligence/request-binding extension from the challenge in its PaymentPayload. Provider configuration never accepts a Stellar secret key.

Keep X402_SETTLEMENT_ENABLED=false while running protocol, binding and negative tests. Change it to true only for an explicitly authorized Testnet settlement run after npm run check passes. The API key must remain only in ignored local environment configuration. No private key is required or accepted by this provider.

Mantén X402_SETTLEMENT_ENABLED=false durante las pruebas. Cámbialo a true únicamente para una liquidación Testnet autorizada después de superar npm run check. No se requiere ni se acepta una clave privada.

MCP-shaped stdio contract / Contrato MCP por stdio

npm run mcp

The process reads one JSON-RPC message per line. It supports initialize, tools/list, and tools/call. The audit_website tool accepts the same url and optional language, returning both MCP text content and structuredContent.

El proceso lee un mensaje JSON-RPC por línea. Admite initialize, tools/list y tools/call. La herramienta audit_website usa el mismo input y devuelve texto MCP y structuredContent.

Fixtures and determinism / Fixtures y determinismo

Bundled hosts:

• example.com

• www.example.com

• stellar.local

• demo.stellar.local

The same provider version and normalized input always produce the same audit score and findings. Audit output excludes timestamps, DNS state, live HTTP state, environment-derived content, and secrets. The protected endpoint adds an x402 settlement receipt around that deterministic output.

La misma versión e input normalizado siempre generan la misma puntuación y hallazgos. El endpoint protegido agrega un recibo x402 alrededor de esa salida determinista.

Deploying a separate Vercel project / Desplegar como proyecto separado

With an authenticated Vercel CLI:

vercel --yes
vercel --prod --yes

Vercel builds the TypeScript serverless functions in api/ using the explicit routes in vercel.json. No build directory is committed. .vercelignore excludes local caches, work files, build output, credentials, and environment files from deployment uploads.

Vercel detecta automáticamente las funciones TypeScript en api/. No se versiona ningún directorio de build.

Versioning

The HTTP API, Service Card and output schema use major version v1 / 1.0. SERVICE_CARD.v2.json is a checked-in fail-closed snapshot kept synchronized with the dynamic runtime card; despite its historical filename, its content follows the canonical v1 contract. SERVICE_CARD.v1.json remains historical evidence.

Security and scope / Seguridad y alcance

• No outbound HTTP client exists in the audit path.

• URL credentials and non-HTTP(S) protocols are rejected.

• Unknown hosts are never fetched.

• No private keys, custody, wallet signing, Mainnet configuration, or payment secrets are stored.

• Facilitator network calls are impossible unless X402_SETTLEMENT_ENABLED=true and X402_STELLAR_PAY_TO is valid.

• Payment activation additionally requires the server-only OpenZeppelin Channels API key; missing configuration fails closed without naming or echoing secret values.

• Successful receipts bind request/output, network, asset, amount, payTo and transaction. The provider independently reads the confirmed Stellar transaction, requires a positive ledger and withholds delivery when the on-chain operation does not reconcile.

• .env, .env.*, build output, caches, and local Vercel metadata are ignored; .env.example contains names only.

• This project is independent: it does not publish to or modify Stellar Bazaar or any other provider.

License

Apache-2.0. See LICENSE.