Keamanan dan operasi NextPDF Connect

Sekilas

NextPDF Connect mengautentikasi transport jaringan menggunakan token bearer API key. Connect memperlakukan transport lokal Model Context Protocol (MCP) sebagai subproses tepercaya. Connect menempatkan setiap alat berisiko tinggi di balik konfirmasi manusia yang eksplisit. Halaman ini menjelaskan model autentikasi, keamanan transport, dan model ancaman.

Pemasangan

composer require nextpdf/server

Gambaran konseptual

Server memiliki tiga batas kepercayaan, masing-masing untuk satu transport.

Transport stdio MCP adalah subproses yang dijalankan oleh klien lokal. Transport ini membaca JSON-RPC dari standard input dan menulis respons ke standard output. Transport ini tidak memiliki listener jaringan dan tidak memiliki API key. Transport ini mewarisi kepercayaan dari batas proses sistem operasi, yaitu model kepercayaan yang ditetapkan oleh spesifikasi MCP untuk stdio. Pencatatan log diarahkan ke standard error, sehingga tidak pernah mengganggu aliran protokol.

Transport REST dan transport gRPC terhubung ke jaringan. Keduanya memerlukan token bearer API key pada setiap permintaan, kecuali untuk pemeriksaan kesehatan tanpa autentikasi. Key store, format kunci, dan validasi waktu-konstan yang sama mendukung kedua transport tersebut. Transport gRPC membaca token dari metadata panggilan. REST membacanya dari header Authorization.

Autentikasi yang keliru adalah kegagalan yang diidentifikasi oleh OWASP Application Programming Interface (API) Security Top 10 sebagai API2:2023 Broken Authentication. Cacat di area ini melemahkan kemampuan API untuk mengidentifikasi pemanggil, sehingga melemahkan keamanan API secara keseluruhan (OWASP API Security Top 10, API2:2023). Token yang lemah atau mudah ditebak juga disebut sebagai anti-pola broken-auth (sumber yang sama, daftar kerentanan). Desain di bawah ini menangani kedua risiko tersebut.

Permukaan API

Format dan validasi API key

Kunci berbentuk npk_live_{kid}_{secret}. kid adalah pengidentifikasi delapan karakter yang digunakan untuk pencarian rekaman O(1), sedangkan secret memuat entropinya. Store tidak pernah menyimpan kunci mentah. Store menyimpan digest SHA-256 dari seluruh materi kunci. Pada setiap permintaan, server melakukan hash terhadap token yang diberikan dan membandingkannya dengan digest yang tersimpan menggunakan perbandingan waktu-konstan (hash_equals), sehingga kunci yang salah tidak mengungkap apa pun melalui timing. Kunci yang dinonaktifkan atau kedaluwarsa ditolak setelah pemeriksaan hash, bukan sebelumnya.

Validator REST dan gRPC berbagi logika ini. Middleware REST membaca Authorization: Bearer npk_live_…. Autentikator gRPC membaca token bearer yang sama dari metadata panggilan authorization gRPC, yang dibawa sebagai header HTTP/2. Autentikator menggagalkan panggilan dengan status UNAUTHENTICATED gRPC.

Kedua transport juga menerapkan throttle anti-otomasi pada lalu lintas pra-autentikasi: percobaan berlebih dari satu identitas klien dibatasi lajunya dan ditolak — 429 Too Many Requests pada REST, dan status RESOURCE_EXHAUSTED gRPC pada gRPC. Kontrol ini aktif secara baku, sehingga melindungi penerapan yang belum mengonfigurasi store pembatasan laju secara terpisah. Klien sebaiknya menunggu sebelum mencoba ulang, bukan langsung mengulanginya.

Respons tidak terotorisasi

Permintaan REST dengan kunci yang hilang, salah bentuk, dinonaktifkan, atau kedaluwarsa menerima 401 Unauthorized dengan body problem-details dan header respons WWW-Authenticate: Bearer. Ini sesuai dengan persyaratan HTTP bahwa respons 401 WAJIB membawa field header WWW-Authenticate dengan setidaknya satu challenge (RFC 9110 §11.6.1). Persyaratan itu sejalan dengan aturan bahwa permintaan dengan kredensial yang dihilangkan atau tidak valid seharusnya menerima 401 beserta challenge WWW-Authenticate (RFC 9110 §11.6).

Hak akses kunci

Setiap rekaman kunci memuat tingkatan produk maksimum. Pipeline REST melampirkan identitas dan tingkatan klien yang terautentikasi ke permintaan, sehingga otorisasi hilir dapat menegakkan batas kemampuan dan batas payload menurut tingkatan. Kunci tingkatan core tidak dapat menjalankan operasi Pro atau Enterprise, meskipun paket-paket tersebut terpasang.

Kasus tepi dan jebakan

Transport MCP tidak memiliki API key. Ini disengaja dan tepat untuk subproses lokal. Jangan mengekspos server MCP melalui shim jaringan. Jika agen berjaringan memerlukan alat-alat tersebut, tempatkan di depan transport REST atau gRPC, yang melakukan autentikasi.
Pemeriksaan kesehatan sengaja bersifat anonim. /healthz dan /readyz melewati autentikasi sehingga orkestrator dapat memeriksa liveness dan readiness tanpa kredensial. Keduanya hanya mengembalikan status. Keduanya tidak mengekspos data alat maupun data dokumen.
Token konfirmasi bersifat sekali pakai dan berumur pendek. Gerbang human-in-the-loop menerbitkan token yang terikat pada nama alat dengan masa berlaku 300 detik. Token dikonsumsi saat pertama kali digunakan. Token ini bukan kredensial autentikasi dan tidak menggantikan API key.

Kinerja

Autentikasi terdiri dari satu hash ditambah satu perbandingan waktu-konstan per permintaan. Biaya itu dapat diabaikan dibandingkan dengan biaya proses render. Key store dengan hot-reloading membaca ulang berkas kunci saat berubah, sehingga rotasi tidak memerlukan restart dan tidak menambah biaya per permintaan.

Catatan keamanan

Gerbang human-in-the-loop

Setiap alat menyatakan tingkat risiko. Alat pada tingkat tertinggi, ApprovalRequired, tidak berjalan pada pemanggilan pertama. Gerbang konfirmasi mengembalikan challenge yang berisi token sekali pakai. Agen harus menampilkan challenge kepada manusia dan memanggil alat tersebut kembali dengan token itu. Ini adalah kontrol yang disengaja pada titik ketika tindakan otomatis memperkenalkan risiko. Titik ini selaras dengan titik yang diidentifikasi IEC 31010 untuk mengendalikan risiko yang diperkenalkan melalui tindakan manusia (di sini, agen), pada atau di dekat titik perkenalannya (IEC 31010:2019). Konfigurasi tidak dapat melemahkan gerbang ini: penggantian konfigurasi hanya boleh menaikkan risiko alat, tidak pernah menurunkan alat ApprovalRequired. Lihat /connect/hitl-risk-tiers/.

Konfigurasi keamanan transport

Transport berjaringan tidak melakukan terminasi Transport Layer Security (TLS) sendiri; TLS adalah urusan penerapan. Penerapan gabungan rujukan menjalankan transport gRPC dengan mutual TLS, dengan kunci, sertifikat, dan CA klien yang disediakan sebagai secret penerapan. Di bawah mutual TLS, server menyajikan sertifikat serta mewajibkan dan memverifikasi sertifikat klien. Jalankan transport REST di belakang terminator TLS (reverse proxy atau service mesh), dan jangan pernah mengekspos listener teks-polos pada jaringan yang tidak tepercaya. Rincian konfigurasi tersedia di /connect/deployment/. Ini adalah pernyataan postur keamanan, bukan jaminan siap pakai, dan transport yang aman memerlukan konfigurasi penerapan yang benar.

Pembatasan jalur keluaran

Alat penulis berkas menyelesaikan jalur yang diminta terhadap direktori basis yang dikonfigurasi, mengkanonikalisasinya, dan menolak null byte, pembungkus protokol, serta traversal ... Alat menolak setiap jalur yang terselesaikan ke luar basis. Simpan direktori basis pada volume khusus dengan izin sistem berkas berprinsip hak istimewa terkecil.

Residensi data dan mitigasi PII

Server menyimpan dokumen hanya di document store dalam memori selama time to live (TTL) yang dikonfigurasi (baku 1800 detik) dan dengan jumlah terbatas (baku 50). Server tidak menyimpan konten dokumen ke disk kecuali Anda secara eksplisit memanggil alat keluaran berkas dan jalurnya lolos pembatasan. Server tidak melakukan panggilan jaringan keluar untuk merender atau memeriksa dokumen, sehingga byte dokumen tidak meninggalkan penerapan kecuali sebuah alat dikonfigurasi secara eksplisit untuk mengambil sumber daya jarak jauh. Untuk penerapan stateless yang sensitif terhadap residensi, nonaktifkan keluaran berkas (allow_file_output: false) dan batasi enabled_tools ke kumpulan minimum yang diperlukan.

Telemetri aman dan pembersihan log

Pencatatan audit merekam eksekusi alat pada tingkat risiko Caution dan di atasnya, serta setiap challenge konfirmasi yang diterbitkan. Rekaman audit memuat nama alat, tingkat risiko, dan flag keberhasilan. Perlakukan argumen alat sebagai data yang berpotensi sensitif: arahkan log ke sink dengan kontrol akses, dan jangan menaikkan level log global ke tingkat verbositas yang menggemakan payload argumen di lingkungan bersama. Transport MCP menulis log ke standard error sehingga konten log tidak pernah masuk ke aliran protokol pada standard output.

Kesesuaian

Klaim	Sumber	`reference_id`
Autentikasi yang rusak melemahkan keamanan API	OWASP API Security Top 10, API2:2023
Token yang lemah/mudah ditebak adalah anti-pola broken-auth	OWASP API Security Top 10, API2:2023
`401` WAJIB membawa challenge `WWW-Authenticate`	RFC 9110 §11.6.1
Kredensial hilang/tidak valid → `401` + challenge	RFC 9110 §11.6
Kendalikan risiko pada titik perkenalan (manusia)	IEC 31010:2019

Model kepercayaan stdio Model Context Protocol mengikuti spesifikasi MCP resmi, revisi 2025-06-18. URL-nya tercatat di /transports/mcp/ karena spesifikasi MCP bukan bagian dari korpus standar yang dikurasi.

Konteks komersial

Alat penandatanganan, redaksi, kepatuhan, dan forensik hanya tersedia ketika nextpdf/premium terpasang bersama server. Keberadaan alat-alat tersebut tidak mengubah model autentikasi. Tingkatan risikonya tetap menempatkan alat yang bersifat destruktif di balik gerbang human-in-the-loop.

Lihat juga

/connect/hitl-risk-tiers/ — model risiko dan amplop konfirmasi secara rinci
/connect/deployment/ — TLS, mutual TLS, secret, dan penyetelan worker
/transports/rest/ — pipeline middleware REST dan skema keamanan OpenAPI
/transports/grpc/ — autentikasi metadata gRPC dan kode status
/connect/configuration/ — enabled_tools, pemilihan key store, penggantian risiko