Settlens

npx add-mcp 'https://settlens.com/mcp'

Settlens

Evidencia de seguridad y conformidad para endpoints de pago agénticos.

Settlens inspecciona el handshake HTTP x402 V2, valida los requisitos de pago anunciados, detecta cambios inesperados en el precio o el destinatario, aplica una política local y puede verificar de forma segura que una autorización intencionalmente inválida no desbloquea el recurso.

Settlens utiliza el parser oficial @x402/core como dependencia de runtime fija. Nunca retiene fondos, billeteras o claves de pago y nunca llama a /settle. La única clave que utiliza es la clave ed25519 opcional que firma las atestaciones de evidencia.

Resumen del producto y documentación completa: settlens.com (docs, changelog).

Disponibilidad del código fuente

Este repositorio publica una instantánea revisada de la implementación de Settlens. El historial de desarrollo original, los registros de prospección comercial y el historial de operaciones de producción permanecen en un repositorio privado separado. Los nombres de host de despliegue y los ejemplos de IP en esta instantánea son ilustrativos; configure su propio host.

La visibilidad del código fuente no establece una licencia de código abierto. No se publica ningún paquete npm ni una licencia general de código abierto aquí. El servicio alojado y los pilotos técnicos acompañantes siguen disponibles en settlens.com.

Qué comprueba

• el recurso no autenticado devuelve HTTP 402;
• PAYMENT-REQUIRED existe y contiene JSON codificado en Base64;
• el objeto decodificado usa x402 V2 y los campos centrales requeridos;
• el mismo objeto es aceptado por el SDK oficial fijo x402 V2;
• resource.url vincula el pago a la URL bajo prueba;
• esquema, red CAIP-2, cantidad atómica, activo, destinatario y tiempo de espera son válidos;
• esquemas, redes, destinatarios, activos y precio máximo coinciden con una política local opcional;
• las solicitudes idénticas no cambian inesperadamente sus términos de pago;
• los endpoints remotos usan HTTPS;
• el esquema GET /supported de un facilitador, los metadatos del firmante y la cobertura coinciden con los requisitos anunciados;
• con autorización explícita, una firma de pago inválida falla de forma cerrada, tanto en el recurso como en el endpoint /verify del facilitador;
• una autorización de pago capturada puede verificarse criptográficamente sin conexión.

La implementación sigue la especificación central x402 V2 oficial y la especificación de transporte HTTP.

Requisitos

• Node.js 20.19 o más reciente.

Pruebe la demostración local

Instale el lockfile exacto y ejecute la puerta de calidad:

npm ci --ignore-scripts
npm run quality

Inicie el objetivo local deliberadamente de calidad mixta:

npm run demo:server

En otra terminal, escanee el endpoint conforme:

npm run settlens -- scan http://127.0.0.1:4402/secure

Ejecute la sonda activa segura:

npm run settlens -- scan http://127.0.0.1:4402/secure \
  --active \
  --authorized \
  --authorization-ref DEMO-APPROVAL-001

Detecte la omisión de pago de demostración:

npm run settlens -- scan http://127.0.0.1:4402/bypass \
  --active \
  --authorized \
  --authorization-ref DEMO-APPROVAL-002

La CLI escribe evidencia JSON, HTML y SARIF autocontenida en reports/. Los informes JSON contienen un bloque de integridad SHA-256 determinista. Sale con el código 1 cuando una comprobación fallida alcanza el umbral de severidad configurado, y con el código 2 para errores de CLI o configuración.

Verifique que un informe JSON no ha cambiado:

npm run settlens -- verify-report reports/settlens-REPORT_ID.json

Escanee un endpoint real autorizado

El modo pasivo es el predeterminado:

npm run settlens -- scan https://merchant.example/api/data \
  --expect-scheme exact \
  --expect-network eip155:8453 \
  --expect-pay-to 0xYourReviewedRecipient \
  --max-amount 10000

Settlens no sigue redirecciones y no incluye cuerpos de respuesta en sus informes. Las credenciales de URL y los parámetros de consulta secretos comunes se redactan. Los valores de los encabezados de solicitud también se omiten de la evidencia. Un PAYMENT-SIGNATURE proporcionado por el usuario se rechaza de plano para que los escaneos pasivos no puedan enviar accidentalmente una autorización de pago real.

Solo use --active --authorized después de que el propietario del endpoint haya aprobado explícitamente la evaluación, y proporcione su ticket o identificador de alcance con --authorization-ref. La sonda activa envía un PAYMENT-SIGNATURE intencionalmente inválido; nunca llama al endpoint /settle de un facilitador y no puede mover fondos.

Cuando se usan encabezados personalizados, su destino debe estar en la lista blanca de forma independiente:

npm run settlens -- scan https://merchant.example/paid \
  --header "Authorization: Bearer ${ASSESSMENT_TOKEN}" \
  --allow-host merchant.example

Esto evita que una configuración modificada reenvíe secretos de CI a un host controlado por un atacante. CI también puede establecer SETTLENS_ALLOWED_HOSTS como una lista separada por comas fuera de la configuración de evaluación.

Verificación de firma independiente

Settlens puede verificar criptográficamente una autorización de pago x402 capturada sin conexión: sin billetera, clave privada o RPC requeridos:

npm run settlens -- verify-payment payment.json

El archivo contiene { "requirement": { … }, "payload": { … } }. Para el esquema EVM exact, Settlens recupera el firmante EIP-3009 / EIP-712 y comprueba que coincide con el from autorizado, que la transferencia está vinculada al destinatario y la cantidad anunciados, y que el tiempo de comprobación está estrictamente dentro de la ventana de autorización (validAfter < now < validBefore, como requiere EIP-3009). El tiempo de comprobación es el reloj actual, o --now <unix-seconds|ISO-8601> para comprobar una captura en el momento en que se usó. El dominio EIP-712 se reconstruye a partir del requisito de pago en sí, por lo que no se necesita ninguna llamada en cadena.

Para Solana, comprueba cada ranura de firmante de la transacción contra su clave de cuenta con ed25519. Una ranura vacía se informa como pendiente: una carga útil de cliente x402 está parcialmente firmada, y el facilitador agrega la firma del pagador de tarifas en el asentamiento. La transacción se verifica cuando al menos una firma está presente, cada firma presente es válida y el número de ranuras coincide con el encabezado del mensaje. Si no se proporcionan términos de pago (asset, amount, payTo, maxTimeoutSeconds, extra), esto es explícitamente un resultado solo de firmas: los términos de pago no se comprueban. Proporcionar asset, amount, payTo y extra.feePayer también requiere el perfil SPL TransferChecked sin conexión compatible para vincular el mint, la cantidad atómica y el destinatario. Los términos de pago parciales son un error de uso. Este perfil estático no establece la ejecución o el asentamiento en tiempo de ejecución; las instrucciones no compatibles, las tablas de búsqueda y las extensiones de token permanecen sin verificar.

El comando sale con 0 cuando la verificación solicitada tiene éxito, 1 cuando las firmas o el perfil de pago solicitado fallan, y 2 para entrada o uso inválido.

Monitoreo continuo

Una vez que un endpoint está en vivo, settlens monitor convierte los escaneos puntuales en aseguramiento continuo. Cada ejecución compara el escaneo pasivo actual con la ejecución anterior y genera una alerta para cada cambio para peor: una comprobación que cae de aprobado a advertencia o fallo, una nueva comprobación fallida o de advertencia, o una comprobación que desapareció (removed: cobertura perdida). La deriva se detecta en la primera ejecución programada después de que un endpoint comienza a comportarse de manera diferente:

settlens monitor --config settlens.config.json --state settlens.state.json

Ejecútelo en un horario (cron o CI). Una alerta bloquea cuando la severidad de su comprobación está en o por encima de --fail-on (predeterminado high); por debajo de eso se imprime como una nota. El comando sale con 1 en una alerta bloqueante y puede publicar las alertas con --webhook <url>. El archivo de estado está claveado por método y URL. El monitoreo es completamente pasivo y nunca envía un pago.

Atestaciones de evidencia compartibles

Cada informe lleva un digest SHA-256 determinista. Una atestación de evidencia vincula ese digest a una identidad de firma ed25519 y una marca de tiempo, para que un cliente, socio o auditor pueda verificar el resultado sin conexión:

settlens evidence keygen --out settlens-evidence.key
settlens evidence attest reports/settlens-REPORT_ID.json \
  --key settlens-evidence.key --out attestation.json
settlens evidence verify attestation.json --report reports/settlens-REPORT_ID.json

verify comprueba la firma ed25519 y que el informe está intacto y coincide con la atestación. Agregue --expect-key <file> (una clave pública PEM ed25519, o la clave hex 0x impresa por keygen) para también rechazar una atestación firmada por cualquier otra clave: la clave pública dentro de una atestación solo prueba que alguna clave la firmó. keygen --out se niega a sobrescribir un archivo existente y crea la clave legible solo por su propietario (modo 0600). La firma usa node:crypto solamente; no se requiere HSM ni red.

Agentes de IA (MCP)

settlens mcp ejecuta un servidor de Protocolo de Contexto de Modelo sobre stdio para que Claude Desktop, Claude Code o cualquier cliente MCP puedan comprobar una solicitud de pago x402 antes de pagar:

claude mcp add settlens -- node /absolute/path/to/settlens/src/cli.js mcp

En cada HTTP 402, el agente llama a evaluate_payment_requirements con el encabezado PAYMENT-REQUIRED, la URL solicitada y su política de gasto, y obtiene pay, review o do_not_pay con las razones. Las herramientas sin conexión también verifican firmas de pago, transacciones de Solana, informes y atestaciones; las herramientas de red (scan_endpoint, scan_facilitator) son solo pasivas. Ninguna herramienta paga, firma o necesita una clave.

La decisión es pay solo cuando cada comprobación de protocolo pasa, al menos una opción de pago anunciada satisface la política, y la política establece los cuatro de pay_to, assets, networks y max_amount. Una política que deja cualquiera de ellos abierto obtiene review. El agente entonces paga solo con una opción listada en acceptable.

Las mismas herramientas se sirven sobre MCP Streamable HTTP en https://settlens.com/mcp: las herramientas sin conexión son públicas, las herramientas de red necesitan un token de API. Consulte docs/MCP.md para el endpoint remoto, recursos, el prompt x402_preflight, las entradas y salidas de cada herramienta, y el modelo de seguridad.

Configuración y CI

Copie el ejemplo:

cp settlens.config.example.json settlens.config.json
npm run settlens -- check --config settlens.config.json

Los valores de configuración pueden hacer referencia a variables de entorno:

{
  "headers": {
    "Authorization": "Bearer ${ASSESSMENT_TOKEN}"
  }
}

El valor se expande en tiempo de ejecución y nunca se escribe en el informe. Consulte action.yml y examples/github-workflow.yml para la acción compuesta de GitHub local. Los resultados SARIF están anclados en la línea 1 del archivo de configuración, para que el escaneo de código de GitHub pueda mostrarlos (el escaneo de código en repositorios privados requiere GitHub Code Security).

El CI del repositorio prueba Node.js 20, 22 y 24, aplica umbrales de cobertura, audita dependencias, produce un SBOM CycloneDX, sube SARIF, prueba la detección de omisiones y construye el contenedor no root fijo:

docker build -t settlens:local .
docker run --rm settlens:local --version

Para un despliegue aislado en un host Plesk, compose.plesk.yml proporciona un servicio deshabilitado de red predeterminado y un perfil scan separado habilitado para red. Ningún servicio publica un puerto de entrada.

Documentos de aseguramiento

• docs/METHODOLOGY.md define qué prueba cada resultado;
• docs/THREAT_MODEL.md documenta los límites de confianza, controles y riesgos residuales;
• docs/PILOT_ACCEPTANCE.md es la lista de verificación objetiva de aprobación/no aprobación para un piloto de cliente;
• docs/READINESS.md es la instantánea histórica de preparación 0.2.0 (puertas verificadas y abiertas en esa versión, sin autocertificación);
• docs/EVIDENCE.md proporciona comandos de prueba reproducibles;
• SECURITY.md define la política de reporte de vulnerabilidades.

Límite actual

Settlens ahora verifica de forma independiente y criptográfica las autorizaciones de pago (consulte Verificación de firma independiente arriba), y su sonda activa autorizada llama al endpoint /verify de un facilitador para confirmar que una firma inválida falla de forma cerrada. Todavía no:

• llama al /settle del facilitador;
• envía, reproduce o transmite transacciones reales;
• retiene billeteras o claves de pago, firma pagos o toma custodia de fondos;
• prueba la seguridad completa de la aplicación o el cumplimiento normativo.

Esas exclusiones son intencionales: Settlens produce evidencia útil y reproducible sin retener nunca billeteras o claves de pago, mover fondos o tomar custodia.

Settlens informa el comportamiento de protocolo observado. No es una prueba de seguridad completa de la aplicación, una certificación o asesoramiento legal.

Monitoreo persistente y espacio de trabajo privado

El monitoreo ahora compara las huellas de los términos de pago entre ejecuciones incluso cuando los estados de las comprobaciones permanecen sin cambios. Use monitor --history .settlens/monitor.json para un diario atómico y acotado y history --history .settlens/monitor.json --format html para una exportación. El /dashboard privado opcional admite configuración de destino, programación e historial; usa una credencial dedicada, no el token de API de escaneo. Las notificaciones SMTP pueden enviar solicitudes piloto ([Settlens][PILOTE]) y cambios bloqueantes ([Settlens][ALERTE]) a contact@settlens.com. Consulte configuración de monitoreo. Para integración con agentes, src/client.js proporciona un cliente MCP HTTP sin dependencias. examples/preflight-client.mjs demuestra una solicitud seguida de una verificación de política. También está disponible una verificación CLI sin conexión:

node src/cli.js preflight payment-required.txt --policy examples/agent-policy.json --resource-url https://merchant.example/paid

La política de ejemplo son datos ilustrativos de Base Sepolia; revisa y reemplaza su destinatario, activo, red y monto. La salida 0 significa pay; tanto review como do_not_pay salen con 1. Estas herramientas nunca pagan ni firman, y no verifican el estado en cadena.

Referencias aprobadas y ciclo de vida de incidentes

El modo de diario ahora separa las observaciones de los términos de pago explícitamente aprobados, realiza un seguimiento de incidentes abiertos/reconocidos/resueltos y pone en cola alertas por correo electrónico/webhook del propietario de forma atómica con las observaciones. Los incidentes persistentes bloquean CLI/CI hasta la recuperación; el reconocimiento pausa los recordatorios. El panel privado admite edición de políticas de endpoints, aprobación revisada, comentarios, filtros de gravedad y reintentos de entrega. Consulta comportamiento y límites de monitoreo, verificaciones operativas y recuperación cifrada y el primer protocolo de aceptación piloto.

Ejecuta npm run conformance para el corpus sintético determinista y las verificaciones de compatibilidad del SDK fijadas. Sus resultados medidos se aplican solo a ese corpus; consulta metodología de referencia. Los requisitos de Solana también pueden verificarse sin conexión contra el perfil estático compatible de SPL TransferChecked; esto no puede establecer saldos en cadena, resultados de CPI, transferencias netas de Token-2022 ni liquidación.