protect-mcp

Portão de política Cedar fail-closed mais recibos assinados para chamadas de ferramentas de agentes de IA.

protect-mcp é um portão que fica à frente das chamadas de ferramentas de um agente de IA. Ele avalia cada chamada contra uma política Cedar, bloqueia o que viola as regras antes de ser executado, e assina um recibo Ed25519 verificável offline de cada decisão. O gateway configurado é executado localmente e não envia telemetria de decisões. O adaptador de coordenação separado conecta-se ao serviço de colaboração hospedado da ScopeBlind; suas requisições e registros retornados têm o caminho de dados descrito abaixo. Ambos são licenciados sob MIT.

Para trabalho em repositório compartilhado, use projetos de cliente: as pessoas concordam com o briefing e os limites, os agentes preparam revisões, e ambas as pessoas aprovam uma versão exata antes que o receptor do proprietário possa alterar o repositório. O fluxo de trabalho de repositório abaixo inclui a configuração e as cinco ferramentas de agente limitadas.

Por que é diferente

• Fail-closed por padrão. Em qualquer erro de política, ausência de engine, ou falha de avaliação, a decisão é DENY. O portão nunca permite silenciosamente. Existe um modo de observação para implantação em sombra, mas mesmo nele uma chamada que seria bloqueada é sinalizada com would_deny: true, então uma falha nunca é silenciosa.
• Ele prova sua própria contenção. serve --enforce e doctor executam um autoteste de inicialização e se recusam a armar o portão a menos que possam demonstrar que uma ação conhecidamente proibida é de fato negada. Um portão que não consegue provar que nega não inicia.
• Cada decisão é um recibo que qualquer um pode verificar. As decisões são assinadas com Ed25519 e verificáveis offline com @veritasacta/verify. A verificação de assinatura não requer consulta de rede. Afirmações sobre execução ainda dependem do operador do portão identificado.

Início rápido: da instalação à primeira prova útil

# 1. Generate an Ed25519 keypair, config template, and sample policy.
npx protect-mcp init

# 2. Print a shadow-mode client configuration, then apply it in your MCP host.
#    This command prints configuration and exits; it does not launch the server.
npx protect-mcp wrap -- node your-mcp-server.js

# 3. Reopen the host and use its tools, then inspect the local-only dashboard.
npx protect-mcp dashboard --open

# 4. Draft a reviewable policy from observed calls.
npx protect-mcp recommend --write

# 5. When reviewed, restart the wrapper in enforce mode with that policy.
npx protect-mcp --policy protect-mcp.recommended.json --enforce -- node your-mcp-server.js

Para o Claude Desktop, execute primeiro um patch de configuração em modo dry-run e depois aplique-o:

npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

O dashboard é vinculado a 127.0.0.1, lê apenas arquivos locais de log/recibo e não envia nada. Use npx protect-mcp connect apenas se você quiser explicitamente um dashboard ScopeBlind hospedado.

O gate como um servidor MCP

Se você preferir chamar o gate como ferramentas em vez de configurar os hooks do Claude Code, execute-o como um servidor MCP:

npx protect-mcp mcp

Ele fala MCP sobre stdio e expõe quatro ferramentas somente leitura, todo o ciclo:

• evaluate_action: decide uma chamada de ferramenta proposta contra uma política Cedar inline, fail-closed (qualquer erro de política é DENY). Retorna { allowed, decision, reason, policy_digest }.
• sign_decision: transforma uma decisão em um recibo assinado com Ed25519 (uma negação assina um gateway_restraint, uma permissão um decision_receipt). Retorna o recibo e sua chave pública; gera uma chave efêmera se você não fornecer uma.
• verify_receipt: verifica um recibo assinado offline contra uma chave pública. Retorna { valid, error, type, kid, issuer }.
• self_test: prova isso, sem entradas. Uma ação conhecidamente proibida é negada, então um recibo assinado faz round-trip e uma cópia adulterada falha.

Aponte qualquer host MCP para ele, por exemplo Claude Desktop:

{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

Os recibos são compatíveis byte a byte com os que o gate assina em tempo de execução, pelo que um recibo emitido aqui usa o mesmo envelope Acta. As capacidades de verificação e a compatibilidade de canonicalização dependem da versão do verificador; use a API verifyReceipt do gateway para o comportamento de conformidade descrito abaixo.

Compatibilidade de canonicalização de recibos

Esta árvore de código corrige o defeito de ordenação de chaves inteiras presente até à 0.14.0: as assinaturas e os hashes de cadeia usam agora a emissão direta de membros JCS, mantendo o perfil de chaves de objeto ASCII do gateway. Chaves com aparência numérica como "10" precedem "2", incluindo dentro de objetos aninhados. Valores não-JSON e Unicode inválido são rejeitados.

Os recibos JSON comuns cujas codificações não foram alteradas continuam a verificar-se. Os recibos históricos assinados com a antiga ordem de chaves numéricas são reportados como legacy_non_jcs_signature; a verificação estrita não os considera JCS válidos. Para uma verificação explícita de compatibilidade histórica, use verifyReceipt(receipt, publicKey, { allowLegacyNumericKeys: true }) e inspecione os campos canonicalization e warning. O seu hash é então o hash histórico original. Preserve os recibos originais e as ligações da cadeia: recalcular um recibo antigo de chaves numéricas com receiptHash produz agora o seu hash JCS e pode quebrar a cadeia histórica. Estas alterações estão incluídas na 0.15.0.

Comece com o seu agente, depois autorize cada tarefa

A versão 0.25.0 inclui um perfil de agente reutilizável. Abra Comece através do seu agente para o comando de configuração com a chave de autoridade apresentada pelo serviço. Verifique essa chave contra uma fonte fidedigna antes de se ligar. Por exemplo:

npx --yes [email protected] coordination agent setup \
  --client claude-code \
  --profile ~/.scopeblind/agent.json \
  --endpoint https://scopeblind.com/api/coordination \
  --authority-key PINNED_64_HEX_AUTHORITY_KEY

Use --client codex ou --client json para essas instruções de registro. A configuração imprime a configuração; aplique-a no seu cliente e, em seguida, reabra esse cliente. O perfil privado contém uma chave de agente e conexões com escopo separado, com permissões de arquivo 600. A configuração não concede permissões de tarefa e não copia nenhuma chave de navegador humana. O servidor registrado executa coordination agent --profile FILE.

Peça ao seu agente para preparar uma tarefa de fatura compartilhada para sua revisão. O fluxo da ferramenta é: