Livelli di rischio HITL di NextPDF Connect

In breve

Ogni strumento dichiara uno dei quattro livelli di rischio. Quando il livello è il più alto, approval-required, lo strumento non viene eseguito alla prima chiamata. Al suo posto, il ConfirmationGate restituisce un token di challenge monouso e un agent deve inoltrarlo a una persona, che autorizza la nuova invocazione.

Installazione

composer require nextpdf/server

Panoramica concettuale

Il modello di rischio ha esattamente quattro livelli ordinati:

Livello	Valore	Significato	Effetto
safe	0	Sola lettura, nessun effetto collaterale	Esecuzione automatica
caution	1	Crea o modifica lo stato in memoria	Esecuzione automatica, registrato nell’audit
review	2	Produce output che potrebbe essere utilizzato in modo improprio	Esecuzione automatica, registrato nell’audit
approval_required	3	Distruttivo, di rilevanza legale o critico per la privacy	Richiesta la conferma di una persona

Il rischio di uno strumento deriva esattamente da due elementi: la dichiarazione dello strumento stesso e un override di configurazione facoltativo dell’operatore. Non esiste una terza origine. Il modello include un numero di versione e la risposta MCP initialize espone tale numero in modo che un client possa rilevare una modifica incompatibile. La registrazione di audit si applica dal livello caution in su.

Sospendere un’azione automatizzata finché una persona non la autorizza colloca il controllo esattamente dove l’automazione introduce il rischio. È la posizione individuata da IEC 31010 per controllare il rischio introdotto tramite l’azione umana, in corrispondenza o in prossimità del punto di introduzione (IEC 31010:2019).

Superficie API

Il ConfirmationGate

Quando uno strumento approval_required viene invocato senza un token valido, il gate emette una challenge. Il controllo restituisce una delle due forme seguenti.

{ "allowed": true }

oppure

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

Il testo della challenge indica l’operazione e la relativa descrizione e avverte quando un file di destinazione verrebbe sovrascritto. Chiede al chiamante di invocare nuovamente lo stesso strumento con un parametro _confirmation_token impostato sul token emesso. Il token scade dopo 300 secondi.

Il binding del token è intenzionale: associa il nome dello strumento, un nonce casuale e il TTL — non gli argomenti. Al nuovo tentativo, i client MCP potrebbero riserializzare gli argomenti con un ordinamento delle chiavi o una normalizzazione diversi, quindi calcolare l’hash degli argomenti invaliderebbe conferme legittime. Il token è monouso; consumarlo alla nuova invocazione consente la chiamata esattamente una volta.

Esposizione per ciascun transport

Il gate viene applicato a ogni transport che gestisce gli strumenti:

MCP: la challenge viene restituita in-band come risposta JSON-RPC riuscita, con il testo della challenge come contenuto. Il chiamante invoca nuovamente tools/call con arguments._confirmation_token.
REST e gRPC: lo stesso gate viene eseguito nell’executor condiviso degli strumenti prima di un’operazione approval_required. La challenge compare nella risposta dell’operazione; il chiamante ripete l’operazione con il token.

Protezione integrata contro il downgrade

Un override di configurazione può aumentare il livello di rischio di uno strumento, ma non può mai abbassare uno strumento che è approval_required per progettazione. Il loader di configurazione applica un set critico fisso e genera un’eccezione in fase di caricamento se un override tenta un downgrade. Il server rifiuta di avviarsi invece di funzionare con un gate indebolito.

Esempio di codice — Avvio rapido

Attivare una challenge tentando di scrivere un file con 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

La risposta contiene la challenge, non il file. Invocare nuovamente con il token emesso:

{"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>"}}}

Esempio di codice — Produzione

Elevare ad approval-required uno strumento normalmente di livello caution per un deployment con sicurezza rafforzata:

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

Un downgrade viene rifiutato in fase di caricamento e il server non si avvia. Per esempio, impostare output_pdf al di sotto di 3 è un downgrade.

Casi limite e insidie

output_pdf in modalità base64 non applica il gate. La scrittura su disco è approval-required; restituire il PDF come base64 (senza file_path) è considerato a rischio inferiore e viene eseguito senza conferma.
Il token non è una credenziale. Non autentica il chiamante e non sostituisce una chiave API sui transport di rete. Sblocca solo una specifica chiamata sottoposta a gate, una sola volta, entro 300 secondi.
Una nuova challenge ogni volta. Omettere l’inoltro di un token, o lasciarlo scadere, non blocca lo strumento in modo permanente; la chiamata successiva emette una nuova challenge. I token sono memorizzati in un token store monouso con garbage collection periodica.
L’audit avviene indipendentemente dall’esito. L’emissione di una challenge, un’esecuzione riuscita e un’esecuzione non riuscita sono tutte registrate nell’audit a partire dal livello caution, con il nome dello strumento e il livello di rischio.

Prestazioni

Il gate aggiunge una ricerca nel token store e, in caso di challenge, la generazione di un token casuale. Il costo è trascurabile rispetto a quello dell’operazione sottoposta a gate ed è sostenuto solo per gli strumenti approval_required.

Note sulla sicurezza

Il gate è un controllo di contenimento, non un controllo di autenticazione. Garantisce che una persona autorizzi le azioni distruttive, di rilevanza legale o critiche per la privacy anche quando è un agent autonomo a gestire lo strumento. Per queste operazioni, il server non dichiara di operare senza supervisione umana e la configurazione non può indebolire il gate. Combinarlo con il modello di chiave API sui transport di rete e con la limitazione ai privilegi minimi tramite enabled_tools. Vedere /connect/security-and-operations/.

Conformità

Dichiarazione	Fonte	`reference_id`
Controllare il rischio nel punto di introduzione (umana)	IEC 31010:2019

La versione del modello di rischio è inclusa nella risposta MCP initialize in modo che i client possano rilevare una modifica incompatibile. Il formato wire è documentato su /transports/mcp/.

Contesto commerciale

Gli strumenti Premium dichiarano il proprio livello di rischio utilizzando lo stesso modello a quattro livelli. Le operazioni Premium distruttive (ad esempio la redazione) sono sottoposte a gate dallo stesso meccanismo. Il gate fa parte del server, non del pacchetto Premium.

Vedere anche

/connect/tool-catalog/ — il livello di rischio di ogni strumento core verificato
/connect/configuration/ — l’override del rischio solo in aumento
/connect/security-and-operations/ — come il gate si inserisce nel modello di minaccia
/transports/mcp/ — il formato wire della challenge in-band
/connect/overview/ — dove si colloca il gate nell’architettura