Các mức rủi ro HITL của NextPDF Connect

Tổng quan nhanh

Mỗi công cụ khai báo một trong bốn mức rủi ro. Mức cao nhất, yêu cầu phê duyệt, không thực thi ngay trong lần gọi đầu tiên. Thay vào đó, ConfirmationGate trả về một token thử thách dùng một lần. Một agent phải chuyển token đó cho một người để người đó phê duyệt lần gọi lại.

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

Mô hình rủi ro gồm đúng bốn mức, được sắp xếp theo thứ tự:

Mức	Giá trị	Ý nghĩa	Hiệu lực
safe	0	Chỉ đọc, không có tác động phụ	Tự động thực thi
caution	1	Tạo hoặc thay đổi trạng thái trong bộ nhớ	Tự động thực thi và ghi nhật ký kiểm tra
review	2	Tạo kết quả đầu ra có thể bị lạm dụng	Tự động thực thi và ghi nhật ký kiểm tra
approval_required	3	Mang tính phá hủy, pháp lý hoặc trọng yếu về quyền riêng tư	Yêu cầu xác nhận của con người

Rủi ro của một công cụ chỉ đến từ hai nguồn: khai báo của chính công cụ đó và một tùy chỉnh cấu hình tùy chọn do người vận hành đặt. Không có nguồn thứ ba. Mô hình mang theo một số hiệu phiên bản. Phản hồi initialize của MCP công bố số đó để client có thể phát hiện thay đổi không tương thích. Việc ghi nhật ký kiểm tra áp dụng từ mức caution trở lên.

Việc giữ lại một hành động tự động cho đến khi có người cho phép sẽ đặt biện pháp kiểm soát đúng nơi tự động hóa phát sinh rủi ro. IEC 31010 xác định đây là vị trí để kiểm soát rủi ro phát sinh từ hành động của con người, tại hoặc gần điểm phát sinh (IEC 31010:2019).

Bề mặt API

ConfirmationGate

Khi bạn gọi một công cụ approval_required mà không có token hợp lệ, gate sẽ phát ra một thử thách. Phép kiểm tra trả về một trong hai dạng sau.

{ "allowed": true }

hoặc

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

Nội dung thử thách nêu tên thao tác cùng phần mô tả của thao tác đó. Nội dung này cũng cảnh báo khi một tệp đích sắp bị ghi đè. Nó yêu cầu bên gọi gọi lại chính công cụ đó với tham số _confirmation_token được đặt thành token đã cấp. Token hết hạn sau 300 giây.

Việc ràng buộc token là có chủ đích: token ràng buộc tên công cụ, một nonce ngẫu nhiên và TTL — không phải các đối số. Khi thử lại, các client MCP có thể tuần tự hóa lại các đối số với thứ tự khóa hoặc cách chuẩn hóa khác nhau, nên việc băm các đối số sẽ khiến những lần xác nhận hợp lệ bị lỗi. Token chỉ dùng một lần. Khi được dùng trong lần gọi lại, token cho phép thực hiện cuộc gọi đúng một lần.

Hiển thị theo từng transport

Gate được áp dụng trên mọi transport điều khiển công cụ:

MCP: thử thách được trả về in-band dưới dạng một phản hồi JSON-RPC thành công, với nội dung thử thách là phần nội dung của phản hồi. Bên gọi gọi lại tools/call kèm arguments._confirmation_token.
REST và gRPC: cùng một gate chạy trong bộ thực thi công cụ dùng chung trước một thao tác approval_required. Thử thách xuất hiện trong phản hồi của thao tác. Bên gọi lặp lại thao tác kèm token.

Bảo vệ chống hạ cấp tích hợp sẵn

Một tùy chỉnh cấu hình có thể nâng mức rủi ro của một công cụ, nhưng không bao giờ được hạ thấp một công cụ vốn được thiết kế là approval_required. Bộ tải cấu hình áp dụng một tập trọng yếu cố định và phát sinh lỗi ngay khi tải nếu một tùy chỉnh cố hạ cấp. Máy chủ từ chối khởi động thay vì chạy với một gate đã bị làm yếu.

Mẫu mã — bắt đầu nhanh

Kích hoạt một thử thách bằng cách ghi tệp bằng 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

Phản hồi là thử thách, không phải tệp. Gọi lại với token đã cấp:

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

Mẫu mã — môi trường vận hành

Nâng một công cụ vốn thường ở mức caution lên mức yêu cầu phê duyệt cho một bản triển khai được tăng cường bảo mật:

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

Một cấu hình hạ cấp sẽ bị từ chối ngay khi tải và máy chủ không khởi động. Ví dụ, đặt output_pdf thấp hơn 3 là hạ cấp.

Trường hợp đặc biệt và những điều cần lưu ý

output_pdf ở chế độ base64 không qua gate. Ghi ra đĩa là thao tác yêu cầu phê duyệt; trả về PDF dưới dạng base64 (không có file_path) được coi là rủi ro thấp hơn và chạy mà không cần xác nhận.
Token không phải là một thông tin xác thực. Token không xác thực bên gọi và không thay thế cho một khóa API trên các transport mạng. Nó chỉ cho phép một cuộc gọi đi qua gate cụ thể đúng một lần, trong vòng 300 giây.
Một thử thách mới mỗi lần. Không chuyển được token, hoặc để token hết hạn, không chặn công cụ vĩnh viễn. Cuộc gọi tiếp theo phát ra một thử thách mới. Các token được lưu trong một kho token dùng một lần và được thu gom rác định kỳ.
Việc kiểm tra diễn ra bất kể kết quả ra sao. Việc phát ra thử thách, một lần thực thi thành công và một lần thực thi thất bại ở mức caution trở lên đều được ghi nhật ký kiểm tra kèm tên công cụ và mức rủi ro.

Hiệu năng

Gate bổ sung một lần tra cứu trong kho token và, khi cần thử thách, một lần tạo token ngẫu nhiên. Chi phí này không đáng kể so với thao tác đi qua gate và chỉ áp dụng cho các công cụ approval_required.

Lưu ý về bảo mật

Gate là một biện pháp kiểm soát ngăn chặn, không phải biện pháp kiểm soát xác thực. Nó bảo đảm rằng có người cho phép các hành động mang tính phá hủy, pháp lý hoặc trọng yếu về quyền riêng tư ngay cả khi một agent tự hành điều khiển công cụ. Đối với các thao tác này, máy chủ không tuyên bố có thể vận hành mà không có sự giám sát của con người, và cấu hình không thể làm yếu gate. Hãy kết hợp nó với mô hình khóa API trên các transport mạng và giới hạn phạm vi theo nguyên tắc đặc quyền tối thiểu bằng enabled_tools. Xem /connect/security-and-operations/.

Tuân thủ

Tuyên bố	Nguồn	`reference_id`
Kiểm soát rủi ro tại điểm phát sinh (do con người)	IEC 31010:2019

Phản hồi initialize của MCP mang theo phiên bản mô hình rủi ro để client có thể phát hiện thay đổi không tương thích. Định dạng truyền dữ liệu được ghi lại trong tài liệu tại /transports/mcp/.

Bối cảnh thương mại

Các công cụ Premium khai báo mức rủi ro riêng theo cùng một mô hình bốn cấp. Các thao tác Premium mang tính phá hủy, chẳng hạn như che giấu thông tin, dùng đúng cùng một gate. Gate là một phần của máy chủ, không phải của gói Premium.

Xem thêm

/connect/tool-catalog/ — mức rủi ro đã xác minh cho từng công cụ core
/connect/configuration/ — tùy chỉnh rủi ro chỉ nâng cấp
/connect/security-and-operations/ — cách gate phù hợp với mô hình mối đe dọa
/transports/mcp/ — định dạng truyền dữ liệu cho thử thách in-band
/connect/overview/ — vị trí của gate trong kiến trúc