Settlens

Avalie os requisitos de pagamento x402 V2 em relação a políticas explícitas. Seis ferramentas MCP públicas offline; sem carteira, assinatura ou pagamentos.

GitHub

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Settlens

Evidências de segurança e conformidade para endpoints de pagamento agênticos.

O Settlens inspeciona o handshake HTTP x402 V2, valida os requisitos de pagamento anunciados, detecta mudanças inesperadas no preço ou destinatário, aplica uma política local e pode verificar com segurança que uma autorização intencionalmente inválida não desbloqueia o recurso.

O Settlens usa o parser oficial @x402/core como dependência de runtime fixada. Ele nunca detém fundos, carteiras ou chaves de pagamento e nunca chama /settle. A única chave que utiliza é a chave ed25519 opcional que assina atestações de evidência.

Visão geral do produto e documentação completa: settlens.com (docs, changelog).

Disponibilidade do código-fonte

Este repositório publica um snapshot revisado da implementação do Settlens. O histórico original de desenvolvimento, registros de prospecção comercial e o histórico de operações de produção permanecem em um repositório privado separado. Os hostnames de implantação e exemplos de IP neste snapshot são ilustrativos; configure seu próprio host.

A visibilidade do código-fonte não estabelece uma licença de código aberto. Nenhum pacote npm ou licença geral de código aberto é publicado aqui. O serviço hospedado e os pilotos técnicos acompanhantes permanecem disponíveis em settlens.com.

O que ele verifica

o recurso não autenticado retorna HTTP 402;
PAYMENT-REQUIRED existe e contém JSON codificado em Base64;
o objeto decodificado usa x402 V2 e os campos centrais obrigatórios;
o mesmo objeto é aceito pelo SDK oficial fixado x402 V2;
resource.url vincula o pagamento à URL em teste;
esquema, rede CAIP-2, valor atômico, ativo, destinatário e tempo limite são válidos;
esquemas, redes, destinatários, ativos e preço máximo correspondem a uma política local opcional;
solicitações idênticas não alteram inesperadamente seus termos de pagamento;
endpoints remotos usam HTTPS;
o esquema GET /supported de um facilitador, os metadados do signatário e a cobertura concordam com os requisitos anunciados;
com autorização explícita, uma assinatura de pagamento inválida falha de forma segura, tanto no recurso quanto no endpoint /verify do facilitador;
uma autorização de pagamento capturada pode ser verificada criptograficamente offline.

A implementação segue a especificação central x402 V2 oficial e a especificação de transporte HTTP.

Requisitos

Node.js 20.19 ou mais recente.

Experimente a demonstração local

Instale o lockfile exato e execute o portão de qualidade:

npm ci --ignore-scripts
npm run quality

Inicie o alvo local deliberadamente de qualidade mista:

npm run demo:server

Em outro terminal, escaneie o endpoint em conformidade:

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

Execute a sonda ativa segura:

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

Detecte o bypass de pagamento da demonstração:

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

A CLI grava evidências JSON, HTML e SARIF autocontidas em reports/. Os relatórios JSON contêm um bloco de integridade SHA-256 determinístico. Ela sai com o código 1 quando uma verificação com falha atinge o limite de severidade configurado, e com o código 2 para erros de CLI ou configuração.

Verifique se um relatório JSON não foi alterado:

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

Escaneie um endpoint autorizado real

O modo passivo é o padrão:

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

O Settlens não segue redirecionamentos e não inclui corpos de resposta em seus relatórios. Credenciais de URL e parâmetros de consulta secretos comuns são mascarados. Os valores dos cabeçalhos de solicitação também são omitidos das evidências. Um PAYMENT-SIGNATURE fornecido pelo usuário é rejeitado imediatamente, para que escaneamentos passivos não possam enviar acidentalmente uma autorização de pagamento real.

Use --active --authorized somente após o proprietário do endpoint ter aprovado explicitamente a avaliação, e forneça seu identificador de ticket ou escopo com --authorization-ref. A sonda ativa envia um PAYMENT-SIGNATURE intencionalmente inválido; ela nunca chama o endpoint /settle de um facilitador e não pode mover fundos.

Quando cabeçalhos personalizados são usados, seu destino deve ser permitido de forma independente:

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

Isso impede que uma configuração modificada encaminhe segredos de CI para um host controlado por atacante. A CI também pode definir SETTLENS_ALLOWED_HOSTS como uma lista separada por vírgulas fora da configuração da avaliação.

Verificação independente de assinatura

O Settlens pode verificar criptograficamente uma autorização de pagamento x402 capturada offline — sem carteira, chave privada ou RPC necessário:

npm run settlens -- verify-payment payment.json

O arquivo contém { "requirement": { … }, "payload": { … } }. Para o esquema EVM exact, o Settlens recupera o signatário EIP-3009 / EIP-712 e verifica se ele corresponde ao from autorizado, se a transferência está vinculada ao destinatário e valor anunciados, e se o horário da verificação está estritamente dentro da janela de autorização (validAfter < now < validBefore, como o EIP-3009 exige). O horário da verificação é o relógio atual, ou --now <unix-seconds|ISO-8601> para verificar uma captura no momento em que foi usada. O domínio EIP-712 é reconstruído a partir do próprio requisito de pagamento, portanto, nenhuma chamada on-chain é necessária.

Para Solana, ele verifica cada slot de signatário da transação contra sua chave de conta com ed25519. Um slot vazio é relatado como pendente: uma carga útil de cliente x402 é parcialmente assinada, e o facilitador adiciona a assinatura do pagador de taxas no liquidação. A transação é verificada quando pelo menos uma assinatura está presente, cada assinatura presente é válida e a contagem de slots corresponde ao cabeçalho da mensagem. Se nenhum termo de pagamento (asset, amount, payTo, maxTimeoutSeconds, extra) for fornecido, isso é explicitamente um resultado somente de assinaturas: os termos de pagamento não são verificados. Fornecer asset, amount, payTo e extra.feePayer também exige que o perfil offline suportado de Transferência Verificada SPL vincule o mint, o valor atômico e o destinatário. Termos de pagamento parciais são um erro de uso. Este perfil estático não estabelece execução de runtime ou liquidação; instruções não suportadas, tabelas de consulta e extensões de token permanecem não verificadas.

O comando sai com 0 quando a verificação solicitada é bem-sucedida, 1 quando assinaturas ou o perfil de pagamento solicitado falham, e 2 para entrada ou uso inválido.

Monitoramento contínuo

Uma vez que um endpoint está ativo, settlens monitor transforma escaneamentos pontuais em garantia contínua. Cada execução compara o escaneamento passivo atual com a execução anterior e gera um alerta para cada mudança para pior: uma verificação que cai de aprovação para aviso ou falha, uma nova verificação com falha ou aviso, ou uma verificação que desapareceu (removed: cobertura perdida). A deriva é detectada na primeira execução agendada após um endpoint começar a se comportar de forma diferente:

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

Execute-o em um agendamento (cron ou CI). Um alerta bloqueia quando a severidade de sua verificação está em ou acima de --fail-on (padrão high); abaixo disso, é impresso como uma nota. O comando sai com 1 em um alerta bloqueante e pode POSTAR os alertas com --webhook <url>. O arquivo de estado é chaveado por método e URL. O monitoramento é totalmente passivo e nunca envia um pagamento.

Atestações de evidência compartilháveis

Cada relatório carrega um digest SHA-256 determinístico. Uma atestação de evidência vincula esse digest a uma identidade de assinatura ed25519 e um timestamp, para que um cliente, parceiro ou auditor possa verificar o resultado offline:

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 verifica a assinatura ed25519 e que o relatório está intacto e corresponde à atestação. Adicione --expect-key <file> (uma chave pública PEM ed25519, ou a chave hex 0x impressa por keygen) para também rejeitar uma atestação assinada por qualquer outra chave: a chave pública dentro de uma atestação apenas prova que alguma chave a assinou. keygen --out se recusa a sobrescrever um arquivo existente e cria a chave legível apenas pelo seu proprietário (modo 0600). A assinatura usa node:crypto apenas; nenhum HSM ou rede é necessário.

Agentes de IA (MCP)

settlens mcp executa um servidor Model Context Protocol sobre stdio, para que o Claude Desktop, Claude Code ou qualquer cliente MCP possa verificar uma solicitação de pagamento x402 antes de pagar:

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

Em cada HTTP 402, o agente chama evaluate_payment_requirements com o cabeçalho PAYMENT-REQUIRED, a URL solicitada e sua política de gastos, e obtém pay, review ou do_not_pay com os motivos. As ferramentas offline também verificam assinaturas de pagamento, transações Solana, relatórios e atestações; as ferramentas de rede (scan_endpoint, scan_facilitator) são apenas passivas. Nenhuma ferramenta paga, assina ou precisa de uma chave.

A decisão é pay somente quando todas as verificações de protocolo passam, pelo menos uma opção de pagamento anunciada satisfaz a política, e a política define todos os quatro de pay_to, assets, networks e max_amount. Uma política que deixa qualquer um deles aberto obtém review. O agente então paga apenas com uma opção listada em acceptable.

As mesmas ferramentas são servidas via MCP Streamable HTTP em https://settlens.com/mcp: as ferramentas offline são públicas, as ferramentas de rede precisam de um token de API. Veja docs/MCP.md para o endpoint remoto, recursos, o prompt x402_preflight, as entradas e saídas de cada ferramenta, e o modelo de segurança.

Configuração e CI

Copie o exemplo:

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

Os valores de configuração podem referenciar variáveis de ambiente:

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

O valor é expandido em runtime e nunca é escrito no relatório. Veja action.yml e examples/github-workflow.yml para a ação composta local do GitHub. Os resultados SARIF são ancorados na linha 1 do arquivo de configuração, para que a varredura de código do GitHub possa exibi-los (a varredura de código em repositórios privados requer o GitHub Code Security).

A CI do repositório testa Node.js 20, 22 e 24, aplica limites de cobertura, audita dependências, produz um SBOM CycloneDX, envia SARIF, prova a detecção de bypass e constrói o contêiner não-root fixado:

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

Para uma implantação isolada em host Plesk, compose.plesk.yml fornece um serviço padrão com rede desabilitada e um perfil scan separado com rede habilitada. Nenhum serviço publica uma porta de entrada.

Documentos de garantia

docs/METHODOLOGY.md define o que cada resultado prova;
docs/THREAT_MODEL.md documenta limites de confiança, controles e riscos residuais;
docs/PILOT_ACCEPTANCE.md é a lista de verificação objetiva de aprovação/reprovação para um piloto de cliente;
docs/READINESS.md é o snapshot histórico de prontidão 0.2.0 (portões verificados e abertos naquela versão, sem autocertificação);
docs/EVIDENCE.md fornece comandos de prova reproduzíveis;
SECURITY.md define a política de relato de vulnerabilidades.

Limite atual

O Settlens agora verifica de forma independente e criptográfica as autorizações de pagamento (veja Verificação independente de assinatura acima), e sua sonda ativa autorizada chama o endpoint /verify de um facilitador para confirmar que uma assinatura inválida falha de forma segura. Ele ainda não:

chama /settle do facilitador;
submete, reproduz ou transmite transações reais;
detém carteiras ou chaves de pagamento, assina pagamentos ou assume custódia de fundos;
prova segurança completa do aplicativo ou conformidade regulatória.

Essas exclusões são intencionais: o Settlens produz evidências úteis e reproduzíveis sem nunca deter carteiras ou chaves de pagamento, mover fundos ou assumir custódia.

O Settlens relata o comportamento observado do protocolo. Não é uma prova de segurança completa do aplicativo, uma certificação ou aconselhamento jurídico.

Monitoramento persistente e espaço de trabalho privado

O monitoramento agora compara impressões digitais de termos de pagamento entre execuções, mesmo quando os status das verificações permanecem inalterados. Use monitor --history .settlens/monitor.json para um diário atômico e limitado e history --history .settlens/monitor.json --format html para uma exportação. O /dashboard privado opcional suporta configuração de alvo, agendamento e histórico; ele usa uma credencial dedicada, não o token de API de escaneamento. Notificações SMTP podem enviar solicitações de piloto ([Settlens][PILOTE]) e mudanças bloqueantes ([Settlens][ALERTE]) para contact@settlens.com. Veja configuração de monitoramento. Para integração com agentes, o src/client.js fornece um cliente MCP HTTP sem dependências. O examples/preflight-client.mjs demonstra uma solicitação seguida de uma verificação de política. Uma verificação CLI offline também está disponível:

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

A política de exemplo são dados ilustrativos da Base Sepolia; revise e substitua o destinatário, o ativo, a rede e o valor. Saída 0 significa pay; tanto review quanto do_not_pay retornam saída 1. Essas ferramentas nunca pagam ou assinam, e não verificam o estado on-chain.

Referências aprovadas e ciclo de vida de incidentes

O modo de diário agora separa observações de termos de pagamento explicitamente aprovados, rastreia incidentes abertos/reconhecidos/resolvidos e enfileira alertas por e-mail/webhook do proprietário atomicamente com as observações. Incidentes persistentes bloqueiam CLI/CI até a recuperação; o reconhecimento pausa lembretes. O painel privado suporta edição de políticas de endpoint, aprovação revisada, comentários, filtros de severidade e novas tentativas de entrega. Consulte comportamento e limites de monitoramento, verificações operacionais e recuperação criptografada e o primeiro protocolo de aceitação piloto.

Execute npm run conformance para o corpus sintético determinístico e verificações de compatibilidade de SDK fixadas. Seus resultados medidos se aplicam apenas a esse corpus; consulte metodologia de benchmark. Requisitos da Solana podem adicionalmente ser verificados offline contra o perfil estático suportado de TransferChecked da SPL; isso não pode estabelecer saldos on-chain, resultados de CPI, transferências líquidas do Token-2022 ou liquidação.