AGA MCP Server

Governança de tempo de execução criptográfica para agentes de IA. 20 ferramentas. Artefatos de política selados, medição contínua, prova à prova de adulteração. Ed25519 + SHA-256.

GitHub

Documentação

AGA - Artefatos de Governança Atestada

Governança criptográfica em tempo de execução para agentes de IA e sistemas autônomos.

Status: publicado no npm; esta versão traz proveniência de build SLSA (verifique: npm audit signatures). As ferramentas do servidor e o aga-proxy emitem o pacote de evidências SEP canônico, verificável offline pela @attested-intelligence/aga-verify publicada e pelo verificador de referência aga-receipt-spec/verify/verify-sep.mjs. Desde 3.2.0 o verificador é ágil em algoritmo e acompanha um perfil pós-quântico: v1 Ed25519-SHA256-JCS (o padrão que o gateway emite) e v2 ML-DSA-65+Ed25519-SHA256-JCS (um compósito NIST FIPS-204 ML-DSA-65 + RFC-8032 Ed25519, ambos devem verificar), selecionado por pacote pelo campo algorithm com uma tricotomia VERIFIED / FAILED / UNSUPPORTED_PROFILE. Versões anteriores a 3.0 (um pacote de cadeia de continuidade legado que não verifica sob o verificador SEP) estão obsoletas; use ^3.0.0. O escopo da alegação e a superfície de ataque residual estão documentados honestamente em THREAT_BOUNDARY.md.

# This package IS the AGA MCP server (TypeScript, runs over stdio). Use it from any MCP client:
npx -y @attested-intelligence/aga-mcp-server

Um SDK complementar em Python (aga-governance) está documentado na seção de SDK Python abaixo.

Verifique você mesmo (não acredite em nossa palavra)

Você não precisa aceitar nada disso por fé. O repositório traz o verificador de referência, os vetores canônicos e pacotes de exemplo, para que você possa verificar um offline agora mesmo, sem rede e sem callback para nós:

git clone https://github.com/attestedintelligence/aga-mcp-server
cd aga-mcp-server
# A canonical SEP bundle verifies; a one-byte-tampered copy is rejected.
node aga-receipt-spec/verify/verify-sep.mjs fixtures/valid_minimal.json   # OVERALL: VERIFIED (integrity only; no key pinned)
node aga-receipt-spec/verify/verify-sep.mjs fixtures/tampered.json        # OVERALL: FAILED

O CLI @attested-intelligence/aga-verify publicado fornece o mesmo veredito, e npm run conformance:cross-stack (primeiro: npm run build && npm --prefix independent-verifier run build) prova seis configurações de verificador v1, abrangendo três toolchains independentes (JavaScript, Go e Python, incluindo uma implementação pura stdlib, sem criptografia de terceiros), que concordam em todos os 57 casos de stack cruzado; npm run conformance:cross-stack-v2 prova que dois oráculos genuinamente de linguagens independentes (@noble/JS e CIRCL/Go) concordam no corpus composto v2. Para uma reprodução completa sem confiança (compile o pacote você mesmo, reproduza o tarball publicado byte a byte, reexecute cada gate), veja o REVIEWER_GUIDE.md (um caminho de autoatendimento comando a comando), REPRODUCIBILITY.md e o passo a passo SKEPTICAL_AUDITOR.md. Esta versão traz proveniência de build SLSA, verificável com npm audit signatures.

O Que Isto Faz

Cada chamada de ferramenta que um agente de IA faz passa pelo gateway AGA. Cada chamada é avaliada contra a política, e a decisão (PERMITIDA ou NEGADA) é registrada como um recibo de governança assinado e vinculado por hash. Os recibos são coletados em pacotes de evidências que qualquer terceiro pode verificar offline usando criptografia padrão.

Registre. Prove. Verifique.

Escopo: um pacote verificado prova a integridade dos recibos presentes: cada um é autêntico, corretamente ordenado, incluído no Merkle e (quando uma chave está fixada) vinculado à proveniência. Não prova a não omissão (que toda ação que o agente tomou foi registrada); a completude é limitada pela evidência de adulteração do ponto de interceptação, que está fora do pacote. Veja KNOWN_LIMITATIONS.md para a fronteira honesta completa, e THREAT_BOUNDARY.md para o detalhe por campo.

Uso com Claude Desktop

Adicione à configuração MCP do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "aga": {
      "command": "npx",
      "args": ["-y", "@attested-intelligence/aga-mcp-server"]
    }
  }
}

O Claude pode então selar artefatos, medir integridade, gerar pacotes de evidências e verificar conformidade por meio de linguagem natural.

Persistir a chave de assinatura (faça isto primeiro)

Por padrão, o gateway assina com uma chave efêmera que gira a cada reinício. Isso é aceitável para uma primeira olhada, mas a proveniência do pacote de evidências não pode ser fixada entre reinícios (e o servidor avisa sobre isso no stderr). Defina uma seed Ed25519 estável de 64 hex para que a proveniência permaneça fixável:

# generate a seed once (32 random bytes, hex)
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

Forneça-a via AGA_GATEWAY_KEY, ou AGA_GATEWAY_KEY_FILE (um caminho para a seed). No Claude Desktop, adicione um bloco env:

{
  "mcpServers": {
    "aga": {
      "command": "npx",
      "args": ["-y", "@attested-intelligence/aga-mcp-server"],
      "env": { "AGA_GATEWAY_KEY": "<your-64-hex-seed>" }
    }
  }
}

Mantenha a seed em segredo e fora do controle de versão; consulte DEPLOYMENT.md para o manuseio de chaves.

Ferramentas MCP (15)

Categoria	Ferramentas
Identidade	`get_server_info`, `get_portal_state`
Ciclo de vida	`init_chain`, `attest_subject`, `revoke_artifact`
Medição e decisão	`measure_integrity`, `measure_behavior`, `verify_chain`
Evidência	`generate_evidence_bundle`, `verify_bundle_offline`
Privacidade	`request_claim`, `list_claims`
Delegação	`delegate_to_subagent`
Auditoria	`get_receipts`, `get_chain_events`

measure_behavior é somente detecção por padrão: ele observa padrões de uso de ferramentas e registra uma descoberta de desvio assinada e provável, mas não bloqueia. A aplicação (desvio → quarentena) é opcional via enforce=true e desligada por padrão. Decisões de governança rígidas (PERMITIDA/NEGADA) são tomadas pelo portal/PEP, não pelo monitor comportamental.

Início rápido: verificar um pacote offline

Um pacote que este pacote emite (via a ferramenta MCP generate_evidence_bundle) é um pacote SEP canônico. Verifique-o offline, sem rede e sem callback para nós:

# Published verifier CLI — ships on npm, nothing to clone. Pin the gateway key (from get_server_info) to prove provenance.
npx -y @attested-intelligence/aga-verify evidence-bundle.json --pubkey <gateway-public-key>

# Or, from a clone of this repo, the zero-dep reference verifier (Node 18+) renders the identical verdict:
node aga-receipt-spec/verify/verify-sep.mjs evidence-bundle.json --pubkey <gateway-public-key>

O CLI @attested-intelligence/aga-verify publicado é o caminho distribuído (a versão 1.0.0 mais antiga que pode ser forjada está obsoleta); o verify-sep.mjs de referência fornece o mesmo veredito a partir de um clone do repositório. Sem --pubkey você obtém um resultado somente de integridade (issuerVerified=false); fixe a chave para também provar quem o emitiu. Veja THREAT_BOUNDARY.md §3.7. Um verificador de navegador hospedado está vinculado em Links.

O algoritmo de referência §6 é implementado em três linguagens: JavaScript (aga-receipt-spec/verify/verify-sep.mjs), Go (verify.go, stdlib crypto/ed25519) e Python (verify.py, RFC-8032 Ed25519 puro stdlib). Uma estrutura de teste de stack cruzado (npm run conformance:cross-stack; primeiro: npm run build && npm --prefix independent-verifier run build) prova que os três, além do motor no servidor e aga-verify, fornecem vereditos idênticos nos vetores canônicos (válidos, adversariais e cada falsificação de pequena ordem). O perfil composto v2 (ML-DSA-65+Ed25519-SHA256-JCS) é mantido no mesmo padrão por uma segunda estrutura (npm run conformance:cross-stack-v2): um motor @noble/JavaScript e um oráculo CIRCL/Go, duas toolchains genuinamente independentes, fornecem vereditos idênticos no corpus v2 fixado, e o verificador de referência v1 (verify-sep.mjs/verify.py/verify.go) retorna UNSUPPORTED_PROFILE (código de saída 3) em um pacote v2, sinalizando "perfil não implementado" em vez de um "inválido" enganoso. (O CLI aga-verify publicado não implementa esta tricotomia de perfil: em um pacote v2 ele retorna FALHA (código de saída 1). Use o código de saída 3 como o sinal de perfil não suportado apenas com os verificadores de referência.)

Mapeamento de nomes de verificação entre implementações

O verificador de referência JS e o SDK Python (aga-governance) decompõem a mesma verificação de sete checagens de forma diferente. Os vereditos gerais e os códigos de saída concordam em todos os casos do corpus de conformidade (reprovado em 2026-07-01: 10/10 células em pacotes intactos/adulterados com chaves não fixadas, corretas e erradas); a sub-checagem que relata uma determinada adulteração pode diferir:

Verificação de referência JS	Campo de resultado Python	O que cobre
`structural`	`algorithm_valid` + partes de `bundle_consistent`	id do algoritmo, boa formação da chave, contagens de recibo/prova
`receipt_signatures`	`receipt_signatures_valid`	Ed25519 sobre bytes canônicos de recibo
`chain_and_ordering`	`chain_integrity_valid`	ligação de folha anterior, ids e timestamps monotônicos
`merkle_and_bijection`	`merkle_proofs_valid`	recálculo de folhas, caminhada de raiz única, bijeção de índices
`signed_checkpoint`	`checkpoint_valid`	vinculação de raiz assinada pelo gateway + contagem + cabeça de cadeia
`envelope_consistency`	`envelope_consistent`	metadados de envelope vs. conteúdo assinado
`gateway_key_match` (com `--pubkey`)	`gateway_key_match` / `provenance`	chave do emissor fixada

Diferença conhecida de decomposição: a referência JS recalcula cada folha Merkle a partir do conteúdo completo do recibo, então uma adulteração de assinatura de recibo também falha merkle_and_bijection; o verificador Python supera a mesma adulteração em receipt_signatures_valid, chain_integrity_valid e bundle_consistent, enquanto seu merkle_proofs_valid pode permanecer verdadeiro. Nenhum é mais frouxo: o pacote falha em ambas as pilhas, código de saída 1. Uma diferença deliberada de tratamento de entrada: um pin --pubkey malformado é um erro de uso (código de saída 2) no SDK Python, enquanto a referência JS trata um pin malformado como não fixado; o comportamento Python é estritamente mais rígido.

Como Funciona

AI Agent                  AGA Gateway                    Verifier
   |                          |                              |
   |-- tools/call ----------->|                              |
   |                    [Evaluate Policy]                    |
   |                    [Sign Receipt]                       |
   |                    [Chain to Previous]                  |
   |<-- PERMITTED/DENIED -----|                              |
   |                          |                              |
   |                    [Export Bundle]                       |
   |                          |--------- evidence.json ----->|
   |                          |                  [Verify Signatures]
   |                          |                  [Verify Chain + Order]
   |                          |                  [Verify Merkle Tree]
   |                          |                  [Verify Signed Checkpoint]
   |                          |                  [PASS / FAIL]

Proxy de Governança MCP

Execute o AGA como um proxy transparente entre qualquer cliente MCP e qualquer servidor MCP. Cada chamada de ferramenta é avaliada contra a política e produz um recibo assinado.

# Start the proxy (the `aga-proxy` bin) in front of an upstream MCP server.
# stdio upstream = the hardened default (the upstream is a child process, not network-reachable).
npx -p @attested-intelligence/aga-mcp-server aga-proxy start \
  --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp/test" --profile standard

Exportando o pacote de evidências de um proxy em execução

O proxy registra recibos em seu próprio processo e mantém o ledger SEP na memória. Para tornar esse ledger ativo acessível a partir de um shell separado, aga-proxy start abre um canal de controle somente loopback — um ouvinte HTTP vinculado a 127.0.0.1 (nunca uma interface roteável), em sua própria porta (padrão 18801, sobrescreva com --control-port), distinta da porta do proxy voltada ao agente (18800). Ele expõe apenas rotas de leitura (/export, /status, /receipts); nada nele muta política ou estado, e é inacessível fora do host por construção (o vínculo loopback é a garantia). O proxy escreve a porta de controle escolhida em ~/.aga-proxy/control.json juntamente com proxy.pid.

Uma invocação separada de aga-proxy export lê esse arquivo e busca o mesmo pacote assinado que o proxy em execução emitiria:

# Terminal A — start the proxy in front of an upstream MCP server
npx -p @attested-intelligence/aga-mcp-server aga-proxy start \
  --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp/test" --profile standard

# Terminal B — export the live ledger from a different shell, then verify it offline
npx -p @attested-intelligence/aga-mcp-server aga-proxy export -o evidence.json
npx -y @attested-intelligence/aga-verify evidence.json --pubkey <gateway-public-key>

Se nenhum proxy estiver em execução, aga-proxy export imprime no running proxy found; start it first, or export from within the session e sai com código não zero — nunca emite um pacote vazio ou de espaço reservado. Dentro da sessão do servidor MCP, você também pode chamar a ferramenta generate_evidence_bundle e salvar o JSON retornado.

Ledger em memória: o pacote exportado é o registro criptográfico durável, mas a cadeia viva em processo não sobrevive a um reinício do proxy. Este fluxo torna o ledger ativo acessível a partir de outro processo; ele não adiciona persistência entre reinícios, que precisa do backend persistente (SQLite) e permanece no roadmap (veja KNOWN_LIMITATIONS.md).

O proxy intercepta solicitações tools/call, avalia-as contra uma política selada e gera um recibo SEP assinado para cada decisão. Chamadas permitidas são encaminhadas ao servidor downstream; chamadas negadas retornam um erro MCP e nunca o alcançam. Cada decisão é vinculada por hash e vinculada a checkpoints em um pacote à prova de adulteração. (Métodos diferentes de tools/call não são avaliados por política, mas os não benignos são registrados como recibos passthrough assinados para auditabilidade, e uma lista de bloqueio opcional pode rejeitá-los; consulte THREAT_BOUNDARY.md §3.2.)

Três perfis de política integrados:

permissivo - registra tudo, bloqueia nada (padrão)
padrão - limites de frequência + bloqueia operações destrutivas
restritivo - lista de permissões explícita de ferramentas, todas as ferramentas desconhecidas negadas

Verificação (SEP 3.0 canônico; algoritmo normativo §6 em `aga-receipt-spec/verify/verify-sep.mjs`)

Piso estrutural - O pacote declara Ed25519-SHA256-JCS, chave pública bem formada (todas as codificações de pequena ordem + y ≥ p não canônico rejeitado), receipts.length > 0, contagem de provas = contagem de recibos
Assinaturas de Recibo - Ed25519 sobre JSON canônico de perfil JCS, chaves ordenadas (campo de assinatura excluído)
Cadeia + ordenação - O previous_receipt_hash de cada recibo = folha do recibo anterior; timestamps não decrescentes
Provas Merkle - Recalcule cada folha a partir do conteúdo do recibo, percorra irmãos/direções até uma raiz, índices de folha formam a bijeção completa de 0..N-1
Checkpoint assinado - Verifique o checkpoint assinado pelo gateway vinculando merkle_root, leaf_count e cabeça de cadeia (isso torna a construção sem prefixo à prova de truncamento)
Proveniência (quando uma chave está fixada) - public_key == expected key; caso contrário, somente integridade é relatada

Primitivas Criptográficas

Primitiva	Finalidade
Ed25519	Assinaturas de recibos
SHA-256	Encadeamento de hash, árvores de Merkle, cálculo de folhas
Perfil JCS (JSON canônico com chaves ordenadas)	Assinatura determinística (canon é compatível em nível de bytes com o verificador de referência)
Árvores de Merkle	Vinculando todos os recibos a uma única raiz verificável

Gateway ao Vivo

Um gateway de demonstração está implantado no Cloudflare Workers (uma implantação separada que pode acompanhar sua própria versão; trate-o como um espelho de conveniência e sempre verifique o que ele retorna offline contra uma chave fixada, não como o artefato canônico):

# Check status
curl https://aga-mcp-gateway.attested-intelligence.workers.dev/health

# Export evidence bundle
curl https://aga-mcp-gateway.attested-intelligence.workers.dev/bundle -o evidence-bundle.json

Python SDK

pip install aga-governance

from aga import AgentSession

with AgentSession(gateway_id="my-gateway") as session:
    session.record_tool_call(
        tool_name="search_web",
        decision="PERMITTED",
        reason="tool in allowlist",
        request_id="req-1",
    )
    bundle = session.export_bundle()
    result = session.verify()
    assert result["overall_valid"]

Suíte de Testes

Testes automatizados em TypeScript e Python, além de um corpus de conformidade:

Servidor MCP TypeScript: 384 testes automatizados (vitest), incluindo regressões de negação comprovável e monitor comportamental
Corpus de conformidade SEP: npm run test:conformance (válidos → VERIFIED, negativos → FAILED)
SDK complementar Python: o pacote PyPI aga-governance publicado separadamente (instalação + verificação rápida aqui; sua suíte pytest completa é executada a partir da árvore de origem)

npm test                              # TypeScript tests (vitest)
npm run test:conformance              # SEP conformance corpus
pip install aga-governance && python -c "import aga; print(aga.__version__)"   # Python SDK smoke check

Benchmarks

O determinismo do formato de recibo é reproduzível aqui: npm test executa os vetores entre linguagens, e npm run conformance:cross-stack (primeiro: npm run build && npm --prefix independent-verifier run build) mostra que as seis configurações do verificador v1 (em três toolchains independentes: JS, Go, Python) concordam no corpus canônico de 57 casos, enquanto npm run conformance:cross-stack-v2 mostra que os dois oráculos v2 em linguagens independentes concordam no corpus composto.

Estrutura do Projeto

src/
  sep/                 # Canonical SEP evidence engine: single source of truth (canon, merkle, receipt, checkpoint, bundle, verify)
  core/                # Governance primitives (portal, artifact, attestation, disclosure, delegation, behavioral) + internal continuity-chain profile
  crypto/              # Internal continuity-chain crypto: Ed25519 (node:crypto), SHA-256/blake2b, salt
  proxy/               # MCP governance proxy (transparent interception + policy enforcement; emits SEP bundles)
  middleware/          # Governance PEP wrapper (records a signed PERMITTED/DENIED receipt per governed call)
independent-verifier/  # @attested-intelligence/aga-verify: standalone SEP verifier, zero AGA imports
scenarios/             # Demo scenarios (SCADA, autonomous vehicle, AI agent) that emit SEP bundles
tests/                 # TypeScript test suite (384 automated tests)

Segurança

Consulte SECURITY.md para relatar vulnerabilidades.

Contribuição

Consulte CONTRIBUTING.md para configuração de desenvolvimento e diretrizes.

Licença

MIT

Attested Intelligence Holdings LLC