Tingkat risiko HITL NextPDF Connect

Sekilas pandang

Setiap alat mendeklarasikan salah satu dari empat tingkat risiko. Tingkat tertinggi, yang memerlukan persetujuan, tidak dijalankan pada panggilan pertama. Sebagai gantinya, ConfirmationGate mengembalikan token tantangan sekali pakai. Agen harus meneruskan token tersebut kepada manusia, yang kemudian memberi izin untuk pemanggilan ulang.

Pemasangan

composer require nextpdf/server

Tinjauan konseptual

Model risiko memiliki tepat empat tingkat yang berurutan:

Tingkatan	Nilai	Arti	Efek
safe	0	Hanya baca, tanpa efek samping	Eksekusi otomatis
caution	1	Membuat atau mengubah status dalam memori	Eksekusi otomatis, dicatat dalam audit
review	2	Menghasilkan keluaran yang dapat disalahgunakan	Eksekusi otomatis, dicatat dalam audit
approval_required	3	Destruktif, berimplikasi hukum, atau kritis bagi privasi	Memerlukan konfirmasi manusia

Risiko suatu alat berasal dari tepat dua sumber: deklarasi alat itu sendiri dan penggantian konfigurasi operator yang bersifat opsional. Tidak ada sumber ketiga. Model ini menyertakan nomor versi. Respons initialize MCP menampilkan nomor tersebut sehingga klien dapat mendeteksi perubahan yang tidak kompatibel. Pencatatan audit berlaku pada tingkat caution dan di atasnya.

Menahan tindakan otomatis hingga manusia memberi izin menempatkan pengendalian tepat di titik tempat otomatisasi memunculkan risiko. IEC 31010 mengidentifikasi posisi ini sebagai titik untuk mengendalikan risiko yang muncul melalui tindakan manusia, pada atau dekat titik kemunculannya (IEC 31010:2019).

Permukaan API

ConfirmationGate

Saat Anda memanggil alat approval_required tanpa token yang valid, gerbang akan menerbitkan tantangan. Pemeriksaan mengembalikan salah satu dari dua bentuk.

{ "allowed": true }

atau

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

Teks tantangan menyebutkan operasi beserta deskripsinya, dan juga memperingatkan jika berkas tujuan akan ditimpa. Teks ini memberi tahu pemanggil untuk memanggil ulang alat yang sama dengan parameter _confirmation_token yang disetel ke token yang diterbitkan. Token kedaluwarsa dalam 300 detik.

Pengikatan token dirancang secara sengaja: token mengikat nama alat, nonce acak, dan TTL — bukan argumennya. Saat mencoba lagi, klien MCP dapat melakukan serialisasi ulang argumen dengan urutan kunci atau normalisasi yang berbeda, sehingga melakukan hashing pada argumen akan merusak konfirmasi yang sah. Token bersifat sekali pakai. Menggunakannya pada pemanggilan ulang akan mengizinkan panggilan tersebut tepat satu kali.

Kemunculan per transport

Gerbang ini diberlakukan pada setiap transport yang menjalankan alat:

MCP: tantangan dikembalikan secara in-band sebagai respons JSON-RPC yang berhasil, dengan teks tantangan sebagai isinya. Pemanggil memanggil ulang tools/call dengan arguments._confirmation_token.
REST dan gRPC: gerbang yang sama berjalan di eksekutor alat bersama sebelum operasi approval_required. Tantangan muncul dalam respons operasi. Pemanggil mengulangi operasi dengan token tersebut.

Proteksi penurunan tingkat bawaan

Penggantian konfigurasi dapat menaikkan tingkat risiko suatu alat, tetapi tidak pernah dapat menurunkan tingkat alat yang secara rancangan bersifat approval_required. Pemuat konfigurasi memberlakukan kumpulan kritis yang tetap dan melempar kesalahan saat pemuatan jika penggantian mencoba menurunkan tingkat. Server menolak melakukan boot alih-alih berjalan dengan gerbang yang dilemahkan.

Contoh kode — Mulai cepat

Picu tantangan dengan menulis berkas melalui 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

Respons yang diterima adalah tantangan, bukan berkasnya. Panggil ulang dengan token yang diterbitkan:

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

Contoh kode — Produksi

Naikkan tingkat alat yang biasanya bertingkat caution menjadi memerlukan persetujuan untuk penerapan yang diperketat:

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

Penurunan tingkat ditolak saat pemuatan, dan server tidak akan dimulai. Sebagai contoh, menyetel output_pdf di bawah 3 merupakan penurunan tingkat.

Kasus tepi dan jebakan

output_pdf dalam mode base64 tidak melalui gerbang. Menulis ke disk memerlukan persetujuan; mengembalikan PDF sebagai base64 (tanpa file_path) diperlakukan sebagai risiko yang lebih rendah dan berjalan tanpa konfirmasi.
Token bukan kredensial. Token tidak mengautentikasi pemanggil dan tidak menggantikan kunci API pada transport berjaringan. Token hanya melepaskan satu panggilan tertentu yang dibatasi gerbang sebanyak satu kali, dalam waktu 300 detik.
Tantangan baru setiap kali. Gagal meneruskan token, atau membiarkannya kedaluwarsa, tidak memblokir alat secara permanen. Panggilan berikutnya menerbitkan tantangan baru. Token disimpan dalam penyimpanan token sekali pakai dengan pengumpulan sampah berkala.
Audit berlangsung apa pun hasilnya. Penerbitan tantangan, eksekusi yang berhasil, dan eksekusi yang gagal pada tingkat caution dan di atasnya semuanya dicatat dalam audit beserta nama alat dan tingkat risikonya.

Performa

Gerbang ini menambahkan satu pencarian ke penyimpanan token dan, saat tantangan diterbitkan, pembuatan token acak. Biaya tersebut dapat diabaikan dibandingkan operasi yang dibatasi gerbang dan hanya berlaku untuk alat approval_required.

Catatan keamanan

Gerbang ini merupakan kontrol penahanan, bukan kontrol autentikasi. Gerbang ini memastikan manusia mengizinkan tindakan yang destruktif, berimplikasi hukum, atau kritis bagi privasi, bahkan ketika alat dijalankan oleh agen otonom. Untuk operasi seperti ini, server tidak mengklaim beroperasi tanpa pengawasan manusia, dan konfigurasi tidak dapat melemahkan gerbang. Padukan gerbang ini dengan model kunci API pada transport berjaringan dan dengan pembatasan hak akses minimal enabled_tools. Lihat /connect/security-and-operations/.

Kesesuaian

Klaim	Sumber	`reference_id`
Kendalikan risiko pada titik kemunculan (oleh manusia)	IEC 31010:2019

Respons initialize MCP menyertakan versi model risiko sehingga klien dapat mendeteksi perubahan yang tidak kompatibel. Format wire-nya didokumentasikan di /transports/mcp/.

Konteks komersial

Alat Premium mendeklarasikan tingkat risikonya sendiri dengan model empat tingkat yang sama. Operasi Premium yang destruktif, seperti redaksi, menggunakan gerbang yang identik. Gerbang ini merupakan bagian dari server, bukan dari paket Premium.

Lihat juga

/connect/tool-catalog/ — tingkat risiko untuk setiap alat core yang terverifikasi
/connect/configuration/ — penggantian risiko yang hanya bisa menaikkan tingkat
/connect/security-and-operations/ — bagaimana gerbang ini cocok dengan model ancaman
/transports/mcp/ — format wire tantangan secara in-band
/connect/overview/ — di mana gerbang ini berada dalam arsitektur