Documentação

MCP Fusion/Security and governance/Contratos e lockfile

Contratos e lockfile

Pergunte à IA sobre a Vinkius

O contrato comportamental de um conector: digests SHA-256 canônicos da superfície, mcpfusion.lock, veredictos de diff de contratos no CI, permissões de raio de impacto e atestação HMAC.

Um conector de IA é uma API pública cujo consumidor é um modelo de linguagem. Descrições, campos obrigatórios e formatos de erro são comportamento. O MCP Fusion transforma esse comportamento em um contrato materializado, faz hash, compara e bloqueia esse contrato, para que uma mudança seja um evento revisável e não uma divergência silenciosa. Governança é o workflow; esta página é a maquinaria.

Materializando o contrato

Para cada tool, o framework compila um ToolContract com quatro seções:

SeçãoConteúdo
surfacedescrição, ações, digest do schema de entrada
behaviordigest do schema de saída, fingerprint das regras do sistema, ações destrutivas e somente leitura, cadeia de middleware, topologia de affordances, guardrails cognitivos
token economicsrisco de inflação, contagem de campos do schema, flag de coleção sem limite
entitlementssistema de arquivos, rede, subprocesso, criptografia, avaliação de código

As permissões não são declaradas por você. EntitlementScanner lê o código-fonte do handler, seu texto de função, e detecta capacidades com famílias de regex: fs.* e chamadas de stream, fetch e clientes HTTP, child_process e workers, assinatura e cifras criptográficas e avaliação de código. Heurísticas de evasão capturam os casos interessantes: (0, eval), acesso global computado, require não literal, reconstrução com String.fromCharCode, blobs em base64, densidade de sequências de escape acima de aproximadamente 15% e alta entropia de Shannon em literais longos. Uma ação somente leitura que grava arquivos ou cria um processo é uma violação, não um aviso.

O lockfile

bash
mcpfusion lock
mcpfusion lock --check

Cada seção é canonicalizada como JSON com chaves ordenadas e recebe hash SHA-256. Os quatro hashes de seção compõem um digest por tool, e os digests ordenados por tool compõem o digest do servidor. O resultado é mcpfusion.lock:

json
{
  "lockfileVersion": 1,
  "serverName": "billing",
  "mcpfusionVersion": "...",
  "generatedAt": "...",
  "integrityDigest": "sha256:...",
  "capabilities": {
    "tools": {
      "billing": {
        "integrityDigest": "sha256:...",
        "surface": { "description": "...", "actions": [], "inputSchemaDigest": "..." },
        "behavior": { "egressSchemaDigest": "...", "systemRulesFingerprint": "...", "middlewareChain": [], "affordanceTopology": [] },
        "tokenEconomics": { "inflationRisk": "low", "schemaFieldCount": 8, "unboundedCollection": false },
        "entitlements": { "filesystem": false, "network": true, "subprocess": false, "crypto": false, "codeEvaluation": false }
      }
    }
  }
}

A serialização é determinística, com chaves ordenadas, indentação de dois espaços e newline final, então o arquivo pode ser comparado em revisão. --check recalcula e sai com código diferente de zero quando algo divergiu: esse código de saída é o gate do CI.

Diffing: que tipo de mudança foi essa

diffContracts(before, after) classifica cada diferença, e a classificação é a política de revisão:

VeredictoExemplos das regras
BREAKINGtool renomeada, digest do schema de entrada alterado, ação removida, flag destrutiva ou somente leitura alterada, novo campo obrigatório, Presenter removido, digest de saída alterado, regras do sistema alteradas, risco de inflação elevado, handler ganhou uma permissão
RISKYflag de idempotência alterada, schema por ação alterado, Presenter trocado, guardrail removido, cadeia de middleware alterada, fingerprint de sincronização de estado ou concorrência alterado, presenters incorporados alterados, coleção tornou-se ilimitada
SAFEação adicionada, campo obrigatório removido, tags removidas, guardrail apertado, risco de inflação reduzido, coleção limitada, permissão perdida
COSMETICdescrição alterada, tags adicionadas

Uma permissão perdida é SAFE porque o raio de impacto diminuiu. Uma permissão adicionada é BREAKING porque um revisor precisa vê-la. Essa assimetria é deliberada.

Attestation

O hashing prova que dois artefatos diferem; a atestação prova que o artefato em execução é aquele que você aprovou. attestServerDigest(digest, { signer: 'hmac', secret }) assina o digest do servidor com HMAC-SHA256, com segredos menores que 32 caracteres rejeitados em produção, e na inicialização o servidor recalcula seu digest e compara: em caso de divergência, recusa-se a iniciar com AttestationError. Signatários podem ser substituídos por um KMS ou log de transparência, e a comparação usa tempo constante. A capacidade de confiança também é exposta aos clientes como mcpfusionTrust.

Probes semânticos

Descrições também são comportamento, e a divergência de descrição é invisível para diffs estruturais. Uma probe semântica reproduz entradas conhecidas, envia as saídas baseline e atual para um judge com o contrato da tool e calcula similaridade: 0,95 ou mais significa ausência de divergência, 0,75 é baixa, 0,5 é média e abaixo disso é alta. Probes que falham degradam para uma pontuação média neutra em vez de bloquear, e o módulo nunca chama a rede por conta própria: você injeta o adapter do judge.

Autocorreção no caminho de erro

Quando um contrato muda sob um agente em execução, a falha não é um mistério: com selfHealing configurado, erros de validação incorporam um bloco <contract_awareness> com as diferenças BREAKING e RISKY da ação que falhou, limitado a cinco por padrão, além da instrução para se adaptar. O agente aprende o novo contrato no mesmo turno em que violou o antigo. Consulte Erros.

Próximos passos