Bảo mật và vận hành NextPDF Connect

Tổng quan nhanh

NextPDF Connect xác thực các transport qua mạng bằng bearer token đóng vai trò API key. Với transport Model Context Protocol (MCP) cục bộ, hệ thống xem đó là một subprocess đáng tin cậy. Mọi công cụ rủi ro cao đều bị chặn sau bước xác nhận rõ ràng của con người. Trang này giải thích mô hình xác thực, bảo mật truyền tải và mô hình đe dọa.

Cài đặt

composer require nextpdf/server

Tổng quan khái niệm

Máy chủ có ba ranh giới tin cậy, tương ứng với từng transport.

Transport MCP stdio là một subprocess do client cục bộ khởi chạy. Nó đọc JSON-RPC trên standard input và ghi phản hồi trên standard output. Transport này không có network listener và không có API key. Nó kế thừa độ tin cậy từ ranh giới tiến trình của hệ điều hành, đây là mô hình tin cậy mà đặc tả MCP quy định cho stdio. Log được ghi ra standard error, nên không bao giờ làm hỏng luồng protocol.

Cả transport REST và transport gRPC đều hoạt động qua mạng. Cả hai đều yêu cầu bearer token đóng vai trò API key trên mọi request, ngoại trừ các health probe không cần xác thực. Hai transport dùng chung key store, định dạng khóa và cơ chế xác thực constant-time. Transport gRPC đọc token từ call metadata; REST đọc token từ header Authorization.

Xác thực triển khai sai là lỗi được OWASP Application Programming Interface (API) Security Top 10 xác định là API2:2023 Broken Authentication. Các lỗ hổng trong khu vực này làm suy yếu khả năng nhận diện bên gọi của API, từ đó làm suy yếu bảo mật API nói chung (OWASP API Security Top 10, API2:2023). Token yếu hoặc dễ đoán cũng được nêu là một anti-pattern của broken-auth (cùng nguồn, danh sách lỗ hổng). Thiết kế dưới đây xử lý cả hai rủi ro này.

Bề mặt API

Định dạng và xác thực API key

Một khóa có dạng npk_live_{kid}_{secret}. kid là một định danh tám ký tự dùng để tra cứu bản ghi với độ phức tạp O(1), còn secret là phần mang entropy. Store không bao giờ lưu khóa gốc; nó chỉ lưu một SHA-256 digest của toàn bộ key material. Trên mỗi request, máy chủ băm token được cung cấp và so sánh nó với digest đã lưu bằng phép so sánh constant-time (hash_equals), nên khóa sai không để lộ thông tin qua thời gian xử lý. Khóa bị vô hiệu hóa hoặc đã hết hạn sẽ bị từ chối sau bước kiểm tra hash, không phải trước đó.

Bộ xác thực REST và gRPC dùng chung logic này. Middleware REST đọc Authorization: Bearer npk_live_…. Bộ xác thực gRPC đọc cùng bearer token đó từ call metadata authorization của gRPC, được truyền dưới dạng HTTP/2 header. Khi xác thực không thành công, lệnh gọi thất bại với trạng thái gRPC UNAUTHENTICATED.

Cả hai transport cũng áp dụng anti-automation throttle trước xác thực cho lưu lượng: các lần thử quá mức từ một danh tính client sẽ bị rate-limit và từ chối — 429 Too Many Requests trên REST, và trạng thái gRPC RESOURCE_EXHAUSTED trên gRPC. Kiểm soát này được bật theo mặc định, nên nó bảo vệ cả bản triển khai chưa cấu hình rate-limit store riêng. Client nên chờ và giãn thời gian giữa các lần thử thay vì thử lại ngay lập tức.

Phản hồi không được ủy quyền

Một REST request thiếu khóa, có khóa sai định dạng, bị vô hiệu hóa hoặc đã hết hạn sẽ nhận 401 Unauthorized với một problem-details body và một response header WWW-Authenticate: Bearer. Điều này phù hợp với yêu cầu HTTP rằng phản hồi 401 PHẢI mang một header field WWW-Authenticate với ít nhất một challenge (RFC 9110 §11.6.1). Yêu cầu đó xuất phát từ quy tắc rằng request bỏ qua credential hoặc dùng credential không hợp lệ nên nhận 401 kèm theo một challenge WWW-Authenticate (RFC 9110 §11.6).

Quyền hạn của khóa

Mỗi bản ghi khóa mang product tier tối đa. Pipeline REST gắn danh tính và tier của client đã được xác thực vào request, để khâu authorization phía sau có thể áp đặt giới hạn năng lực và payload theo tier. Khóa ở core-tier không thể chạy một thao tác Pro hoặc Enterprise, ngay cả khi các package đó đã được cài đặt.

Trường hợp đặc biệt và lưu ý

Transport MCP không có API key. Đây là thiết kế có chủ ý và phù hợp với một subprocess cục bộ. Không phơi bày máy chủ MCP qua một network shim. Nếu một agent truy cập qua mạng cần các công cụ này, hãy đặt nó trước transport REST hoặc gRPC, vốn có xác thực.
Các health probe ẩn danh là có chủ ý. /healthz và /readyz bỏ qua xác thực để các orchestrator có thể kiểm tra liveness và readiness mà không cần credential. Chúng chỉ trả về trạng thái. Chúng không để lộ bất kỳ dữ liệu công cụ hoặc dữ liệu tài liệu nào.
Confirmation token chỉ dùng một lần và có thời hạn ngắn. Cổng human-in-the-loop cấp một token gắn với tên công cụ và có thời gian sống 300 giây. Token bị tiêu thụ ngay ở lần dùng đầu tiên. Nó không phải là một credential xác thực và không thay thế cho API key.

Hiệu năng

Xác thực là một phép băm cộng với một phép so sánh constant-time cho mỗi request. Chi phí này không đáng kể so với chi phí của một lần kết xuất. Cơ chế hot-reloading của key store đọc lại tệp khóa khi nó thay đổi, nên việc xoay vòng khóa không cần khởi động lại và không thêm chi phí cho mỗi request.

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

Cổng human-in-the-loop

Mỗi công cụ khai báo một mức rủi ro. Các công cụ thuộc mức cao nhất, ApprovalRequired, không chạy ngay trong lần gọi đầu tiên. Cổng xác nhận trả về một challenge chứa token dùng một lần. Agent phải hiển thị challenge cho một con người và gọi lại công cụ kèm theo token. Đây là một kiểm soát có chủ ý, đặt ngay tại điểm mà hành động tự động đưa rủi ro vào hệ thống. Đây cũng là điểm mà IEC 31010 xác định để kiểm soát rủi ro phát sinh từ hành động của con người (ở đây là agent), tại hoặc gần điểm phát sinh (IEC 31010:2019). Cấu hình không thể làm suy yếu cổng này: một config override chỉ có thể nâng mức rủi ro của một công cụ, không bao giờ hạ mức của một công cụ ApprovalRequired. Xem /connect/hitl-risk-tiers/.

Cấu hình bảo mật truyền tải

Các transport qua mạng không tự kết thúc Transport Layer Security (TLS); TLS thuộc về khâu triển khai. Bản triển khai tích hợp tham chiếu chạy transport gRPC với mutual TLS, trong đó khóa, certificate và client CA được cung cấp dưới dạng deployment secret. Với mutual TLS, máy chủ xuất trình certificate, đồng thời yêu cầu và xác minh client certificate. Hãy chạy transport REST phía sau một TLS terminator (reverse proxy hoặc service mesh), và không bao giờ phơi bày listener plaintext trên một mạng không tin cậy. Chi tiết cấu hình có trong /connect/deployment/. Đây là một tuyên bố về tư thế bảo mật, không phải một bảo đảm sẵn dùng, và truyền tải an toàn đòi hỏi cấu hình triển khai đúng đắn.

Giới hạn đường dẫn đầu ra

Các công cụ ghi tệp phân giải đường dẫn được yêu cầu tương đối với thư mục gốc đã cấu hình, chuẩn hóa đường dẫn đó, và từ chối null byte, protocol wrapper, cùng lối đi vòng ... Chúng từ chối bất kỳ đường dẫn nào phân giải ra ngoài thư mục gốc. Hãy đặt thư mục gốc trên một volume riêng với quyền hệ thống tệp ở mức least-privilege.

Nơi lưu trữ dữ liệu và biện pháp giảm thiểu rủi ro PII

Máy chủ chỉ giữ tài liệu trong document store nằm trong bộ nhớ, theo thời gian sống (TTL) đã cấu hình (mặc định 1.800 giây) và giới hạn số lượng (mặc định 50). Nó không lưu nội dung tài liệu xuống đĩa trừ khi bạn gọi rõ ràng một công cụ file-output và đường dẫn vượt qua kiểm tra giới hạn. Máy chủ không thực hiện cuộc gọi mạng ra ngoài để kết xuất hay kiểm tra tài liệu, nên các byte tài liệu không rời khỏi bản triển khai trừ khi một công cụ được cấu hình rõ ràng để lấy một tài nguyên từ xa. Với các bản triển khai stateless nhạy cảm về nơi lưu trữ dữ liệu, hãy tắt file output (allow_file_output: false) và giới hạn enabled_tools ở mức tối thiểu.

Telemetry an toàn và làm sạch log

Audit logging ghi lại các lần thực thi công cụ ở mức rủi ro Caution trở lên, cùng với mọi confirmation challenge đã được cấp. Bản ghi audit mang tên công cụ, mức rủi ro và cờ thành công. Hãy coi đối số của công cụ là dữ liệu có thể nhạy cảm: định tuyến log đến một sink có kiểm soát truy cập, và không nâng mức log toàn cục lên độ chi tiết khiến payload đối số bị ghi lại trong các môi trường dùng chung. Transport MCP ghi log vào standard error nên nội dung log không bao giờ đi vào luồng protocol trên standard output.

Tính tuân thủ

Tuyên bố	Nguồn	`reference_id`
Broken authentication làm suy yếu bảo mật API	OWASP API Security Top 10, API2:2023
Token yếu/dễ đoán là một anti-pattern của broken-auth	OWASP API Security Top 10, API2:2023
`401` PHẢI mang một `WWW-Authenticate` challenge	RFC 9110 §11.6.1
Credential bị thiếu/không hợp lệ → `401` + challenge	RFC 9110 §11.6
Kiểm soát rủi ro tại điểm phát sinh (do con người)	IEC 31010:2019

Mô hình tin cậy stdio của Model Context Protocol tuân theo đặc tả MCP chính thức, bản sửa đổi 2025-06-18. URL của nó được ghi lại trên /transports/mcp/ vì đặc tả MCP không nằm trong kho tiêu chuẩn được kiểm soát.

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

Các công cụ ký, biên tập che (redaction), tuân thủ và pháp y chỉ có khi nextpdf/premium được cài đặt cùng với máy chủ. Việc chúng hiện diện không thay đổi mô hình xác thực. Risk tier của chúng vẫn đặt các công cụ có tính hủy hoại phía sau cổng human-in-the-loop.

Xem thêm

/connect/hitl-risk-tiers/ — mô hình rủi ro và confirmation envelope chi tiết
/connect/deployment/ — TLS, mutual TLS, secret và tinh chỉnh worker
/transports/rest/ — pipeline middleware REST và security scheme của OpenAPI
/transports/grpc/ — xác thực qua metadata gRPC và các status code
/connect/configuration/ — enabled_tools, lựa chọn key store, ghi đè rủi ro