NextPDF Connect — poziomy ryzyka HITL

W skrócie

Każde narzędzie deklaruje jeden z czterech poziomów ryzyka. Dla najwyższego poziomu, wymagającego zatwierdzenia, pierwsze wywołanie nie uruchamia narzędzia. Zamiast tego ConfirmationGate zwraca jednorazowy token wyzwania. Agent musi przekazać ten token człowiekowi, który autoryzuje ponowne wywołanie.

Instalacja

composer require nextpdf/server

Przegląd koncepcyjny

Model ryzyka ma dokładnie cztery uporządkowane poziomy:

Poziom	Wartość	Znaczenie	Efekt
safe	0	Tylko odczyt, bez efektów ubocznych	Automatyczne wykonanie
caution	1	Tworzy lub modyfikuje stan w pamięci	Automatyczne wykonanie, odnotowane w dzienniku audytu
review	2	Generuje dane wyjściowe, które mogą zostać użyte niezgodnie z przeznaczeniem	Automatyczne wykonanie, odnotowane w dzienniku audytu
approval_required	3	Niszczące, prawnie istotne lub krytyczne dla prywatności	Wymaga potwierdzenia przez człowieka

Poziom ryzyka narzędzia pochodzi dokładnie z dwóch źródeł: z własnej deklaracji narzędzia oraz z opcjonalnego nadpisania w konfiguracji przez operatora. Nie istnieje trzecie źródło. Model ma numer wersji. Odpowiedź MCP initialize udostępnia ten numer, dzięki czemu klient może wykryć niezgodną zmianę. Rejestrowanie w dzienniku audytu obowiązuje dla poziomu caution i wyższych.

Wstrzymanie zautomatyzowanego działania do czasu autoryzacji przez człowieka umieszcza kontrolę tam, gdzie automatyzacja wprowadza ryzyko. Norma IEC 31010 wskazuje, że ryzyko wprowadzone przez działanie człowieka należy kontrolować w punkcie jego wprowadzenia lub w jego pobliżu (IEC 31010:2019).

Powierzchnia API

ConfirmationGate

Gdy narzędzie approval_required zostanie wywołane bez ważnego tokenu, brama wystawia wyzwanie. Weryfikacja zwraca jedną z dwóch postaci.

{ "allowed": true }

lub

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

Tekst wyzwania podaje nazwę operacji i jej opis. Ostrzega także, gdy plik docelowy miałby zostać nadpisany. Nakazuje wywołującemu ponowne wywołanie tego samego narzędzia z parametrem _confirmation_token ustawionym na wystawiony token. Token wygasa po 300 sekundach.

Sposób powiązania tokenu jest celowy: token wiąże nazwę narzędzia, losowy nonce oraz TTL — a nie argumenty. Przy ponownej próbie klienci MCP mogą ponownie zserializować argumenty z inną kolejnością kluczy lub normalizacją, więc haszowanie argumentów unieważniałoby prawidłowe potwierdzenia. Token jest jednorazowy. Jego użycie przy ponownym wywołaniu zezwala na wykonanie dokładnie jeden raz.

Ujawnianie w poszczególnych transportach

Brama jest wymuszana w każdym transporcie obsługującym narzędzia:

MCP: wyzwanie jest zwracane w paśmie jako pomyślna odpowiedź JSON-RPC z tekstem wyzwania w treści. Wywołujący ponownie wywołuje tools/call z arguments._confirmation_token.
REST i gRPC: ta sama brama działa we współdzielonym wykonawcy narzędzi przed wykonaniem operacji approval_required. Wyzwanie pojawia się w odpowiedzi z operacji. Wywołujący powtarza operację z tokenem.

Wbudowana ochrona przed obniżeniem poziomu

Nadpisanie w konfiguracji może podnieść poziom ryzyka narzędzia, ale nigdy nie może obniżyć poziomu narzędzia, które z założenia jest approval_required. Moduł ładujący konfigurację wymusza stały zbiór krytyczny i zgłasza błąd podczas ładowania, jeśli nadpisanie próbuje obniżyć poziom. Serwer odmawia uruchomienia, zamiast działać z osłabioną bramą.

Przykład kodu — szybki start

Aby wywołać wyzwanie, zapisz plik za pomocą 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

W odpowiedzi pojawia się wyzwanie, a nie plik. Wywołaj ponownie z wystawionym tokenem:

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

Przykład kodu — produkcja

W przypadku wzmocnionego wdrożenia podnieś narzędzie zwykle ustawione na caution do poziomu wymagającego zatwierdzenia:

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

Obniżenie poziomu jest odrzucane podczas ładowania, a serwer nie uruchamia się. Na przykład ustawienie output_pdf poniżej 3 jest obniżeniem poziomu.

Przypadki brzegowe i pułapki

output_pdf w trybie base64 nie podlega bramie. Zapis na dysk wymaga zatwierdzenia; zwrócenie pliku PDF jako base64 (bez file_path) jest traktowane jako niższe ryzyko i odbywa się bez potwierdzenia.
Token nie jest poświadczeniem. Nie uwierzytelnia wywołującego i nie zastępuje klucza API w transportach sieciowych. Odblokowuje tylko jedno konkretne wywołanie objęte bramą, jednorazowo, w ciągu 300 sekund.
Za każdym razem nowe wyzwanie. Nieprzekazanie tokenu lub dopuszczenie do jego wygaśnięcia nie blokuje narzędzia na stałe. Następne wywołanie wystawia nowe wyzwanie. Tokeny są przechowywane w magazynie tokenów jednorazowych z okresowym odśmiecaniem pamięci.
Audyt odbywa się niezależnie od wyniku. Dla poziomu caution i wyższych w dzienniku audytu zapisywane są wystawienie wyzwania, pomyślne wykonanie oraz nieudane wykonanie wraz z nazwą narzędzia i poziomem ryzyka.

Wydajność

Brama dodaje odczyt z magazynu tokenów oraz, przy wyzwaniu, generowanie losowego tokenu. Ten koszt jest pomijalny w porównaniu z operacją objętą bramą i dotyczy tylko narzędzi approval_required.

Uwagi dotyczące bezpieczeństwa

Brama jest mechanizmem ograniczającym ryzyko, a nie mechanizmem uwierzytelniania. Zapewnia, że człowiek autoryzuje działania niszczące, prawnie istotne lub krytyczne dla prywatności, nawet gdy narzędziem steruje autonomiczny agent. W przypadku tych operacji serwer nie deklaruje działania bez nadzoru człowieka, a konfiguracja nie może osłabić bramy. Połącz ją z modelem klucza API w transportach sieciowych oraz z ograniczaniem uprawnień do minimum za pomocą enabled_tools. Zobacz /connect/security-and-operations/.

Zgodność

Twierdzenie	Źródło	`reference_id`
Kontrola ryzyka w punkcie jego (ludzkiego) wprowadzenia	IEC 31010:2019

Odpowiedź MCP initialize zawiera wersję modelu ryzyka, dzięki czemu klienci mogą wykryć niezgodną zmianę. Format przesyłany w warstwie transmisyjnej jest udokumentowany na stronie /transports/mcp/.

Kontekst komercyjny

Narzędzia Premium deklarują własny poziom ryzyka przy użyciu tego samego czteropoziomowego modelu. Niszczące operacje Premium, takie jak redakcja, korzystają z identycznej bramy. Brama jest częścią serwera, a nie pakietu Premium.

Zobacz także

/connect/tool-catalog/ — poziomy ryzyka dla każdego zweryfikowanego narzędzia podstawowego
/connect/configuration/ — nadpisanie ryzyka działające wyłącznie w górę
/connect/security-and-operations/ — jak brama wpisuje się w model zagrożeń
/transports/mcp/ — format wyzwania przesyłanego w paśmie
/connect/overview/ — gdzie brama znajduje się w architekturze