AlphaAssay

alphaassay-tools

Ferramentas de cliente open-source para o serviço de validação AlphaAssay: um verificador de certificados offline (Python) e um proxy MCP de stdio para remoto (Node), além de exemplos executáveis e o manifesto de registro para o servidor hospedado.

Componente	Linguagem	Caminho	O que faz
alphaassay_verify	Python ≥3.10	alphaassay_verify/	Verifica certificados offline: assinaturas Ed25519, serialização canônica, histórico assinado de chaves/revogação. Sem acesso à rede.
Proxy MCP	Node ≥18	server/	Faz a ponte entre um cliente MCP stdio local e o endpoint remoto streamable-HTTP.
Exemplos	—	examples/	Pares de requisição/resposta com resultados conhecidos que você pode executar no endpoint de demonstração gratuito.
server.json	—	server.json	Artefato secundário: o manifesto que o registro MCP lê para descrever o servidor hospedado. Não é necessário para usar o código acima.

O mecanismo de validação em si é um serviço hospedado e não faz parte deste repositório.

Instalação

Verificador Python, a partir do código-fonte:

pip install .
# or, for development
pip install -e ".[dev]"

Proxy Node:

npm install

Uso

Verificar um certificado offline

A confiança total da plataforma exige três entradas locais: o certificado com sua assinatura, um pacote assinado de histórico de chaves/revogação versão 2 e pelo menos uma impressão digital raiz SHA-256 obtida externamente. O verificador não realiza acesso à rede ou a banco de dados.

python -m alphaassay_verify verify \
  --certificate cert.json \
  --trust-bundle trust-bundle.json \
  --root-fingerprint <64-hex-digest>

Evidência somente com assinatura, quando você deliberadamente não deseja estabelecer confiança total da plataforma:

python -m alphaassay_verify signature-only \
  --certificate cert.json \
  --public-key key.pem

O código de saída 0 significa verificado; um código de saída diferente de zero e um motivo legível por máquina significam que não foi verificado. Consulte SPEC.md para o formato canônico de bytes e as regras de confiança que a implementação segue.

Executar o proxy MCP

node server/index.mjs

O proxy fala stdio com seu cliente MCP e encaminha para o endpoint remoto. A lista de ferramentas que ele expõe está em server/tools.json.

Executar os exemplos

Cada exemplo é um payload de requisição, a resposta esperada e um script de shell que o envia para o endpoint de demonstração gratuito:

cd examples && ./golden_lookahead.sh

As respostas esperadas são versionadas no repositório, então funcionam também como fixtures para testes de integração no seu próprio código.

Testes

python -m pytest tests/     # verifier: unit tests and canonical vectors
npm test                    # proxy: contract and behaviour tests

Os vetores de teste estão em tests/canonical_vectors.json e tests/fixtures/; são os mesmos vetores usados no desenvolvimento da implementação.

Contribuição

Issues e pull requests são bem-vindos. Por favor:

• mantenha as mudanças focadas e inclua testes para alterações de comportamento;
• execute python -m pytest tests/ e npm test antes de abrir um PR;
• para o verificador, não adicione acesso à rede ou a banco de dados — a operação offline é uma restrição de design, não um detalhe de implementação;
• relate problemas de segurança de forma privada conforme descrito em SECURITY.md, em vez de em uma issue pública.

Licença

Apache-2.0. Consulte LICENSE.