NextPDF Connect için güvenlik ve operasyonlar

Bir bakışta

NextPDF Connect, ağ üzerinden çalışan taşımalarda kimlik doğrulamayı bir API anahtarı taşıyıcı belirteciyle yapar. Yerel Model Context Protocol (MCP) taşımasını güvenilir bir alt süreç olarak kabul eder. Yüksek riskli her aracı açık insan onayının arkasına yerleştirir. Bu sayfa kimlik doğrulama modelini, taşıma güvenliğini ve tehdit modelini açıklar.

Kurulum

composer require nextpdf/server

Kavramsal genel bakış

Sunucuda, her taşıma için bir tane olmak üzere üç güven sınırı bulunur.

Bunlardan MCP stdio taşıması, yerel bir istemci tarafından başlatılan bir alt süreçtir. Standart girdiden JSON-RPC iletilerini okur ve yanıtları standart çıktıya yazar. Bu taşımanın ne ağ dinleyicisi ne de API anahtarı vardır. Güven modelini işletim sistemi süreç sınırından devralır; bu, MCP belirtiminin stdio için tanımladığı güven modelidir. Günlükler standart hataya yazılır; böylece protokol akışı hiçbir zaman bozulmaz.

Bunlardan REST taşıması ve gRPC taşıması ise ağ üzerinden çalışır. İkisi de, kimlik doğrulaması yapılmayan sağlık yoklamaları dışında her istekte bir API anahtarı taşıyıcı belirteci gerektirir. Aynı anahtar deposu, anahtar biçimi ve sabit zamanlı doğrulama her iki taşıma için de kullanılır. gRPC taşıması belirteci çağrı meta verilerinden okur. REST taşıması ise onu Authorization başlığından okur.

Hatalı kimlik doğrulama, OWASP Application Programming Interface (API) Security Top 10 tarafından API2:2023 Broken Authentication olarak tanımlanan bir güvenlik açığıdır. Bu alandaki kusurlar, API’nin çağıranı tanıma yeteneğini tehlikeye atar ve dolayısıyla API güvenliğini bir bütün olarak tehlikeye atar (OWASP API Security Top 10, API2:2023). Zayıf veya tahmin edilebilir belirteçler de hatalı kimlik doğrulama anti-deseni olarak belirtilir (aynı kaynak, güvenlik açığı listesi). Aşağıdaki tasarım bu iki riski de ele alır.

API yüzeyi

API anahtarı biçimi ve doğrulaması

Bir anahtar npk_live_{kid}_{secret} biçimindedir. kid, O(1) kayıt aramasında kullanılan sekiz karakterlik bir tanımlayıcıdır; entropi gizli değer tarafından taşınır. Depo ham anahtarı hiçbir zaman saklamaz. Tam anahtar malzemesinin bir SHA-256 özetini saklar. Sunucu her istekte, sunulan belirtecin özetini alır ve sabit zamanlı bir karşılaştırma (hash_equals) kullanarak onu saklanan özetle karşılaştırır; böylece yanlış bir anahtar hakkında zamanlama yoluyla hiçbir bilgi açığa çıkmaz. Devre dışı bırakılmış veya süresi dolmuş bir anahtar, özet denetiminden önce değil sonra reddedilir.

REST ve gRPC doğrulayıcıları bu mantığı paylaşır. REST ara katmanı Authorization: Bearer npk_live_… değerini okur. gRPC kimlik doğrulayıcısı aynı taşıyıcı belirteci HTTP/2 başlıkları olarak taşınan gRPC authorization çağrı meta verilerinden okur. Çağrının gRPC UNAUTHENTICATED durumuyla başarısız olmasını sağlar.

Her iki taşıma, kimlik doğrulama öncesi trafiğe otomasyon karşıtı bir kısıtlama da uygular: tek bir istemci kimliğinden gelen aşırı denemeler hız sınırlamasına tabi tutulur ve reddedilir — REST’te 429 Too Many Requests, gRPC’de ise gRPC RESOURCE_EXHAUSTED durumu. Bu denetim varsayılan olarak etkindir; böylece ayrı bir hız sınırı deposu yapılandırılmamış dağıtımları da korur. İstemciler hemen yeniden denemek yerine beklemelidir.

Yetkisiz yanıtlar

Eksik, bozuk, devre dışı bırakılmış veya süresi dolmuş bir anahtarla gelen REST isteği, bir 401 Unauthorized yanıtıyla birlikte bir problem-details gövdesi ve bir WWW-Authenticate: Bearer yanıt başlığı alır. Bu, 401 yanıtının en az bir meydan okuma içeren bir WWW-Authenticate başlık alanı taşıması GEREKTİĞİ (MUST) yönündeki HTTP gereksinimiyle uyumludur (RFC 9110 §11.6.1). Bu gereksinim, eksik veya geçersiz kimlik bilgileri içeren bir isteğin 401 ile birlikte bir WWW-Authenticate meydan okuması alması gerektiği kuralından gelir (RFC 9110 §11.6).

Anahtar yetkilendirmesi

Her anahtar kaydında izin verilen en yüksek ürün katmanı bulunur. REST işlem hattı, kimliği doğrulanmış istemcinin kimliğini ve katmanını isteğe ekler; böylece sonraki yetkilendirme adımı, yetenek ve yük üst sınırlarını katmana göre uygulayabilir. core katmanındaki bir anahtar, ilgili paketler kurulu olsa bile bir Pro veya Enterprise işlemini çalıştıramaz.

Uç durumlar ve dikkat edilmesi gerekenler

MCP taşımasının API anahtarı yoktur. Bu, yerel bir alt süreç için bilinçli ve doğru bir tercihtir. MCP sunucusunu bir ağ ara katmanı üzerinden açığa çıkarmayın. Ağ üzerinden çalışan bir aracının araçlara erişmesi gerekiyorsa, onu kimlik doğrulayan REST veya gRPC taşımasının önüne yerleştirin.
Sağlık yoklamaları bilerek anonimdir. /healthz ve /readyz kimlik doğrulamasını atlar; böylece düzenleyiciler bir kimlik bilgisi olmadan canlılığı ve hazır olma durumunu yoklayabilir. Yalnızca durum döndürürler. Araç verisini veya belge verisini hiçbir şekilde açığa çıkarmazlar.
Bir onay belirteci tek kullanımlık ve kısa ömürlüdür. İnsan onaylı (human-in-the-loop) kapı, araç adına bağlı, 300 saniyelik ömre sahip bir belirteç çıkarır. Belirteç ilk kullanımda tüketilir. Bu bir kimlik bilgisi değildir ve bir API anahtarının yerini almaz.

Performans

Kimlik doğrulama, istek başına tek bir özet hesaplaması ve sabit zamanlı bir karşılaştırmadan oluşur. Bu maliyet, bir işlemin maliyetiyle karşılaştırıldığında ihmal edilebilir düzeydedir. Sıcak yeniden yüklenen anahtar deposu, anahtar dosyası değiştiğinde dosyayı yeniden okur; böylece anahtar döndürme yeniden başlatma gerektirmez ve istek başına maliyet eklemez.

Güvenlik notları

İnsan onaylı (human-in-the-loop) kapı

Her araç bir risk düzeyi bildirir. En yüksek düzeydeki ApprovalRequired araçları ilk çağrıda çalışmaz. Onay kapısı, tek kullanımlık bir belirteç içeren bir meydan okuma döndürür. Aracı uygulama, meydan okumayı bir insana göstermeli ve aracı belirteçle yeniden çağırmalıdır. Bu, otomatik eylemin risk oluşturduğu noktada uygulanan bilinçli bir denetimdir. Bu, IEC 31010’un insan (burada aracı) eylemiyle getirilen riskin getirildiği noktada veya yakınında denetlenmesine yönelik yaklaşımıyla uyumludur (IEC 31010:2019). Yapılandırma kapıyı zayıflatamaz: bir yapılandırma geçersiz kılması yalnızca bir aracın riskini yükseltebilir; bir ApprovalRequired aracını asla düşüremez. Bkz. /connect/hitl-risk-tiers/.

Taşıma güvenliği yapılandırması

Ağ üzerinden çalışan taşımalar Transport Layer Security (TLS) bağlantısını kendileri sonlandırmaz; TLS, dağıtım düzeyinde ele alınır. Birleşik referans dağıtımı, gRPC taşımasını karşılıklı TLS ile çalıştırır; anahtar, sertifika ve istemci CA’sı dağıtım gizli değerleri olarak sağlanır. Karşılıklı TLS kullanıldığında sunucu bir sertifika sunar ve bir istemci sertifikası gerektirip doğrular. REST taşımasını bir TLS sonlandırıcısının (ters proxy veya hizmet ağı) ardında çalıştırın ve güvenilmeyen bir ağda asla düz metin bir dinleyici açığa çıkarmayın. Yapılandırma ayrıntıları /connect/deployment/ içinde yer alır. Bu, anahtar teslimi bir garanti değil, güvenlik duruşunu açıklayan bir bildirimdir; güvenli taşıma doğru bir dağıtım yapılandırması gerektirir.

Çıktı yolu sınırlaması

Dosyaya yazan araçlar, istenen yolu yapılandırılmış temel dizine göre çözer, kanonikleştirir ve boş baytları, protokol sarmalayıcılarını ve .. geçişini reddeder. Temel dizinin dışına çözümlenen tüm yolları reddederler. Temel dizini, en az ayrıcalıklı dosya sistemi izinlerine sahip ayrılmış bir birimde tutun.

Veri yerleşimi ve PII azaltmaları

Sunucu, belgeleri yalnızca bellek içi belge deposunda, yapılandırılmış yaşam süresi (TTL) (varsayılan 1800 saniye) ve sınırlı sayı (varsayılan 50) boyunca tutar. Açıkça bir dosya çıktısı aracını çağırmadıkça ve yol sınırlama denetimini geçmedikçe belge içeriğini kalıcı olarak diske yazmaz. Sunucu, bir belgeyi işlemek veya incelemek için giden ağ çağrısı yapmaz; bu nedenle bir araç açıkça uzak bir kaynağı getirecek şekilde yapılandırılmadıkça belge baytları dağıtım dışına çıkmaz. Durumsuz, yerleşim açısından duyarlı dağıtımlarda dosya çıktısını devre dışı bırakın (allow_file_output: false) ve enabled_tools değerini asgari kümeyle sınırlandırın.

Güvenli telemetri ve günlük temizleme

Denetim günlüğü, Caution risk düzeyindeki ve üzerindeki araç yürütmelerini ve çıkarılan her onay meydan okumasını kaydeder. Denetim kaydı, araç adını, risk düzeyini ve başarı bayrağını içerir. Araç argümanlarını olası hassas veriler olarak değerlendirin: günlükleri erişim denetimleri olan bir hedefe yönlendirin ve paylaşılan ortamlarda genel günlük düzeyini, argüman yüklerini yankılayacak ayrıntı düzeyine yükseltmeyin. MCP taşıması, günlükleri standart hataya yazar; böylece günlük içeriği standart çıktıdaki protokol akışına asla girmez.

Uygunluk

İddia	Kaynak	`reference_id`
Hatalı kimlik doğrulama API güvenliğini tehlikeye atar	OWASP API Security Top 10, API2:2023
Zayıf/tahmin edilebilir belirteçler hatalı kimlik doğrulama anti-desenidir	OWASP API Security Top 10, API2:2023
`401` yanıtı bir `WWW-Authenticate` meydan okuması taşımalıdır (MUST)	RFC 9110 §11.6.1
Eksik/geçersiz kimlik bilgileri → `401` + meydan okuma	RFC 9110 §11.6
Riski, (insan tarafından) getirildiği noktada denetleyin	IEC 31010:2019

Model Context Protocol stdio güven modeli, resmi MCP belirtiminin 2025-06-18 revizyonunu izler. URL’si /transports/mcp/ üzerinde kayıtlıdır; çünkü MCP belirtimi erişimi kısıtlı standartlar derlemi kapsamında değildir.

Ticari bağlam

İmzalama, redaksiyon, uygunluk ve adli analiz araçları yalnızca nextpdf/premium sunucu paketiyle birlikte kurulduğunda kullanılabilir. Bunların varlığı kimlik doğrulama modelini değiştirmez. Risk katmanları, yıkıcı araçları yine de insan onaylı (human-in-the-loop) kapının arkasında tutar.

Ayrıca bakınız

/connect/hitl-risk-tiers/ — risk modeli ve onay zarfı ayrıntıları
/connect/deployment/ — TLS, karşılıklı TLS, gizli değerler ve çalışma ayarı
/transports/rest/ — REST ara katman işlem hattı ve OpenAPI güvenlik şeması
/transports/grpc/ — gRPC meta veri kimlik doğrulaması ve durum kodları
/connect/configuration/ — enabled_tools, anahtar deposu seçimi ve risk geçersiz kılmaları