NextPDF Connect: níveis de risco para HITL

Visão geral

Cada ferramenta declara um entre quatro níveis de risco. No nível mais alto, que exige aprovação, a ferramenta não é executada na primeira chamada. Em vez disso, o ConfirmationGate retorna um token de desafio de uso único. Um agente deve repassar esse token a um humano, que autoriza a nova invocação.

Instalação

composer require nextpdf/server

Visão conceitual

O modelo de risco tem exatamente quatro níveis, em ordem:

Nível	Valor	Significado	Efeito
safe	0	Somente leitura, sem efeitos colaterais	Execução automática
caution	1	Cria ou modifica estado em memória	Execução automática, registrada no log de auditoria
review	2	Produz saída que poderia ser usada de forma indevida	Execução automática, registrada no log de auditoria
approval_required	3	Destrutiva, com implicações jurídicas ou crítica à privacidade	Confirmação humana obrigatória

O risco de uma ferramenta vem de exatamente dois lugares: a própria declaração da ferramenta e uma substituição opcional na configuração do operador. Não há uma terceira origem. O modelo traz um número de versão. A resposta de initialize do MCP expõe esse número para que um cliente possa detectar uma alteração incompatível. O registro no log de auditoria passa a se aplicar a partir de caution.

Reter uma ação automatizada até que um humano a autorize coloca o controle onde a automação introduz o risco. A IEC 31010 identifica essa posição como o ponto para controlar o risco introduzido por ação humana, no ponto de introdução ou próximo a ele (IEC 31010:2019).

Superfície da API

O ConfirmationGate

Quando você invoca uma ferramenta approval_required sem um token válido, o gate emite um desafio. A verificação retorna um dos dois formatos.

{ "allowed": true }

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

O texto do desafio identifica a operação e sua descrição. Ele também avisa quando um arquivo de destino seria sobrescrito. Ele instrui quem chama a invocar novamente a mesma ferramenta com um parâmetro _confirmation_token definido com o token emitido. O token expira em 300 segundos.

A forma como o token é vinculado é deliberada: o token vincula o nome da ferramenta, um nonce aleatório e o TTL — não os argumentos. Na nova tentativa, os clientes MCP podem reserializar os argumentos com uma ordem de chaves ou normalização diferente, de modo que aplicar hash aos argumentos quebraria confirmações legítimas. O token é de uso único. Ao consumi-lo na nova invocação, a chamada é permitida exatamente uma vez.

Exposição por transporte

O gate é aplicado em todos os transportes que acionam ferramentas:

MCP: o desafio é retornado in-band como uma resposta JSON-RPC bem-sucedida, com o texto do desafio como conteúdo. Quem chama invoca novamente tools/call com arguments._confirmation_token.
REST e gRPC: o mesmo gate é executado no executor de ferramentas compartilhado antes de uma operação approval_required. O desafio aparece na resposta da operação. Quem chama repete a operação com o token.

Proteção integrada contra rebaixamento

Uma substituição na configuração pode elevar o nível de risco de uma ferramenta, mas nunca pode rebaixar uma ferramenta que é approval_required por design. O carregador de configuração impõe um conjunto crítico fixo e lança um erro no momento do carregamento se uma substituição tentar rebaixar. O servidor se recusa a iniciar em vez de operar com o gate enfraquecido.

Exemplo de código — Início rápido

Dispare um desafio gravando um arquivo com output_pdf:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"output_pdf","arguments":{"document_id":"<id>","file_path":"/var/lib/nextpdf/tmp/out.pdf"}}}
EOF

A resposta é o desafio, não o arquivo. Invoque novamente com o token emitido:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"output_pdf","arguments":{"document_id":"<id>","file_path":"/var/lib/nextpdf/tmp/out.pdf","_confirmation_token":"confirm_<nonce>"}}}

Exemplo de código — Produção

Eleve uma ferramenta que normalmente é caution para que ela exija aprovação em uma implantação reforçada:

nextpdf_mcp:
  risk_level_overrides:
    add_image: 3      # require human confirmation for image insertion

Qualquer rebaixamento é rejeitado no momento do carregamento, e o servidor não inicia. Por exemplo, definir output_pdf abaixo de 3 é um rebaixamento.

Casos extremos e armadilhas

output_pdf no modo base64 não passa pelo gate. Gravar em disco exige aprovação; retornar o PDF como base64 (sem file_path) é tratado como um risco menor e executado sem confirmação.
O token não é uma credencial. Ele não autentica quem chama nem substitui uma chave de API em transportes de rede. Ele apenas libera, uma única vez, uma chamada controlada específica dentro de 300 segundos.
Um novo desafio a cada vez. Se você deixar de repassar um token, ou se ele expirar, a ferramenta não será bloqueada permanentemente. A próxima chamada emite um novo desafio. Os tokens são armazenados em um armazenamento de tokens de uso único com coleta de lixo periódica.
A auditoria ocorre independentemente do resultado. A emissão de um desafio, uma execução bem-sucedida e uma execução com falha a partir de caution são todas registradas no log de auditoria com o nome da ferramenta e o nível de risco.

Desempenho

O gate adiciona uma consulta ao armazenamento de tokens e, quando há desafio, a geração de um token aleatório. Esse custo é insignificante em comparação com a operação controlada e se aplica apenas a ferramentas approval_required.

Notas de segurança

O gate é um controle de contenção, não um controle de autenticação. Ele garante que um humano autorize ações destrutivas, com implicações jurídicas ou críticas para a privacidade, mesmo quando um agente autônomo aciona a ferramenta. Para essas operações, o servidor não afirma operar sem supervisão humana, e a configuração não pode enfraquecer o gate. Combine-o com o modelo de chave de API em transportes de rede e com o escopo de privilégio mínimo de enabled_tools. Consulte /connect/security-and-operations/.

Conformidade

Afirmação	Fonte	`reference_id`
Controlar o risco no ponto de introdução (humana)	IEC 31010:2019

A resposta de initialize do MCP carrega a versão do modelo de risco para que os clientes possam detectar uma mudança incompatível. O formato de transmissão está documentado em /transports/mcp/.

Contexto comercial

As ferramentas Premium declaram seu próprio nível de risco com o mesmo modelo de quatro níveis. Operações Premium destrutivas, como a redação, usam o mesmo gate. O gate faz parte do servidor, não do pacote Premium.

Veja também

/connect/tool-catalog/ — níveis de risco de cada ferramenta core verificada
/connect/configuration/ — substituição de risco que só permite elevação
/connect/security-and-operations/ — como o gate se encaixa no modelo de ameaças
/transports/mcp/ — formato de transmissão do desafio in-band
/connect/overview/ — onde o gate se posiciona na arquitetura