NextPDF Laravel paketi güvenlik ve operasyonları

Bir bakışta

Paket; sabit PDF yanıt başlıkları ayarlar, indirme dosya adlarını arındırır, kuyruk çıktı yollarını işçi üzerinde doğrular ve zaman damgası yetkilisine giden HTTP çağrılarını istek sahtekârlığını dikkate alan bir istemci üzerinden yönlendirir. Bu sayfa, tehdit modelini ve her denetim için gereken dağıtım yapılandırmasını açıklar.

Kurulum

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Kavramsal genel bakış

Paket, bir PDF motorunu bir web çerçevesine uyarlar. HTTP isteği ile kuyruk aktarımı güven sınırını tanımlar. Bu denetimler; yanıt işlemeyi, seri durumdan çıkarılan iş yüklerini ve zaman damgası yetkilisine giden dışa dönük HTTP çağrılarını kapsar.

API yüzeyi — tehdit modeli

Varlık	Tehdit	Bu paketteki denetim	Gerekli dağıtım yapılandırması
PDF HTTP yanıtı	İçerik türü koklama, tıklama hırsızlığı, dizine ekleme	Her `PdfResponse` fabrikasında ayarlanan sabit başlık kümesi	Yok; başlıklar yapılandırılabilir değildir
İndirme dosya adı	Başlık enjeksiyonu, yol geçişi: `Content-Disposition`	Dosya adı arındırıcısı; ayırıcıları, denetim karakterlerini ve null baytları kaldırır	Yok; arındırıcı her zaman çalışır
Kuyruk işi çıktı yolu	Kurcalanmış seri durumdaki yük üzerinden rastgele dosya yazma	İşçi üzerinde `handle()` içinde doğrulanan yol	Çıktıyı denetimli bir depolama yoluna yönlendirin
Dışa dönük zaman damgası yetkilisi (TSA) HTTP	Sunucu taraflı istek sahtekârlığı, düz metin kurcalama	İstek sahtekârlığını dikkate alan HTTP istemcisi; açıkça gevşetilmediği sürece HTTPS zorunlu kılınır	Şu ayarı koruyun: `tsa.allow_insecure_http = false`; SPKI’yi sabitleyin
Paylaşılan işçi durumu	Uzun ömürlü işçilerde istekler arası durum sızıntısı	Kilitli yazı tipi kayıt defteri; sınırlı görüntü önbelleği; fabrikaya bağlı belge	Şunu ayarlayın: `preload_fonts`; kapsayıcı düzeyinde belleği sınırlayın

Yanıt sıkılaştırma

Her PdfResponse fabrikası, sabit bir başlık kümesi ayarlar:

Cache-Control: private, max-age=0, must-revalidate
Pragma: public
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Content-Security-Policy: default-src 'none'
X-Robots-Tag: noindex, nofollow
Referrer-Policy: no-referrer

Bu değerler PdfResponse içinde sabittir. Yapılandırılabilir değildir. Paketin test paketi, akışlı türevler dâhil olmak üzere her fabrika yönteminde her başlığı denetler.

İndirme dosya adı, Content-Disposition başlığına ulaşmadan önce arındırıcıdan geçirilir. Arındırıcı; yol ayırıcılarını, denetim karakterlerini ve null baytları kaldırır ve ASCII olmayan adlar için RFC 5987 filename*= parametresi üretir. Boş dosya adı document.pdf olarak kullanılır.

Kuyruk yükü doğrulaması

GeneratePdfJob, seri duruma getirilmiş bir closure’ı kuyruk aktarımına yazar. İşçi, çıktı yolunu gönderim sırasında değil, handle() içinde doğrular. Doğrulama şunları reddeder:

yoldaki null baytları,
akış sarmalayıcı şemalarını (örneğin php://),
.. yol geçişi parçalarını,
sonu .pdf ile bitmeyen tüm yolları (büyük/küçük harfe duyarsız).

Her ret InvalidArgumentException oluşturur. Doğrulama, işçi işi tükettiğinde çalışır. Redis veya veritabanı aktarımındaki seri durumdaki bir yük, işçi onu okumadan önce değiştirilebilir. Çıktı yolunu denetimli bir depolama dizinine yönlendirin; bunu doğrulanmamış istek girdisinden türetmeyin.

Zaman damgası yetkilisine giden dışa dönük HTTP

Paket, zaman damgası yetkilisi yapılandırıldığında bir PSR-18 Psr\Http\Client\ClientInterface bağlar. Bir PSR-18 istemcisi, bir PSR-7 isteği gönderir ve bir PSR-7 yanıtı döndürür (PSR-18 §2). Bağlanan istemci, curl tabanlı bir istemciyi istek sahtekârlığını dikkate alan bir katmanla sarar. tsa.allow_insecure_http açıkça true olarak ayarlanmadığı sürece HTTPS zorunlu kılınır.

Zaman damgası yetkilisi Premium katmanında sunulan bir yetenektir. Burada belgelenen Core paketi, HTTP istemcisini ve zaman damgası istemcisi bağlamasını kaydeder; imzalamanın kendisi nextpdf/premium gerektirir. Bu sayfa, PAdES ötesinde PDF Gelişmiş Elektronik İmzaların (B-B) temel davranışını belgelemez; daha yüksek temel profiller kapsam dışıdır.

Zaman damgası yetkilisi için operasyonel yönergeler:

Üretimde tsa.allow_insecure_http değerini false olarak koruyun.
Yapılandırma anahtarı tsa.pinned_public_keys değerini zaman damgası yetkilisi sertifikasının base64 SHA-256 SPKI karmalarına ayarlayın (RFC 7469 biçimi).
SPKI değiştiğinde bu durum sabitlenen sertifika sona ermeden önce günlüğe kaydedilsin diye tsa.warn_on_key_rotation değerini true olarak koruyun.
Yalnızca güvenilir yapılandırmadan tsa.url değerini alın. Bir operatör bunu yönetici yüzeyinden ayarlayabiliyorsa, istek sahtekârlığına maruz kalmayı azaltmak için bir çıkış güvenlik duvarı veya DNS politikası uygulayın.

Günlük kaydı

Tanılama için Psr\Log\LoggerInterface kullanın. Kaçış uygulanmış dizeler yerine yapılandırılmış bağlam geçirin. PSR-3, yer tutucu kaçışını günlükleyici uygulamasına bırakır ve çağıranlara bağlam değerlerine önceden kaçış uygulamamaları gerektiğini belirtir (PSR-3 §1.2). Günlüklerdeki dâhilî ayrıntıyı azaltmak için istisna iletisini veya izini değil, istisna sınıfını günlüğe kaydedin.

Kod örneği — üretim

<?php

declare(strict_types=1);

// .env — production timestamp-authority hardening
// NEXTPDF_TSA_URL=https://tsa.example.test
// NEXTPDF_TSA_ALLOW_INSECURE_HTTP=false
// NEXTPDF_TSA_WARN_ROTATION=true

return [
    'tsa' => [
        'url'                 => env('NEXTPDF_TSA_URL'),
        'allow_insecure_http' => env('NEXTPDF_TSA_ALLOW_INSECURE_HTTP', false),
        'warn_on_key_rotation' => env('NEXTPDF_TSA_WARN_ROTATION', true),
        'pinned_public_keys'  => [
            // base64 SHA-256 SPKI hashes of the TSA certificate
        ],
    ],
];

Uç durumlar & tuzaklar

Yanıt başlığı kümesi sabittir. Farklı bir Content Security Policy’ye (CSP) ihtiyaç duyan uygulamalar, fabrika yanıtı döndürdükten sonra yanıtı sonradan işlemelidir.
Yol doğrulaması işçi üzerinde çalışır. Hatalı bir yol dispatch() aşamasını geçer ve yalnızca iş yürütüldüğünde başarısız olur.
tsa.allow_insecure_http = true, HTTPS zorunluluğunu kaldırır ve zaman damgası güvenini zayıflatır. Bunu yerel geliştirmeyle sınırlı tutun.
Yazı tipi kayıt defteri ısınmadan sonra kilitlenir; paket, uzun ömürlü bir işçide çalışma zamanında yazı tipi kaydetme girişimlerini tasarım gereği reddeder.

Performans

Güvenlik denetimleri, sabit zamanlı dize ve dizi işlemleri kullanır ve istek başına ölçülebilir bir maliyet eklemez. İlk kullanımda baskın operasyonel maliyet yazı tipi ayrıştırmadır; ilk istek gecikmesinden kaçınmak için yazı tiplerini işçi önyüklemesinde önceden yükleyin.

Güvenlik notları

Bu sayfa, paket için tehdit modeli referansıdır. Kaynak kod bu denetimleri zorunlu kılar ve test paketi bunları doğrular. Tehdit modeli tablosu ve zaman damgası yetkilisi adımları, operatörün sağlaması gereken dağıtım yapılandırmasını belirtir.

Uygunluk

İddia	Kaynak	Madde	reference_id
PSR-18 istemcisi, PSR-7 isteği gönderir, PSR-7 yanıtı döndürür	PSR-18 HTTP Client	§2
Çağıran, kaçış uygulanmamış yapılandırılmış günlük bağlamı geçirir	PSR-3 Logger	§1.2

RFC 7469 SPKI sabitlemesi, tsa.pinned_public_keys yapılandırma anahtarının kullandığı biçimi adlandırır. Paket, operatörün sağladığı sabitleme değerlerini kullanır ve RFC’nin kendisini uygulamaz.

Ticari bağlam

PAdES B-B imzalama ve zaman damgası yetkilisi entegrasyonu nextpdf/premium paketini gerektirir. Bu isteğe bağlı Enterprise yeteneği, burada belgelenen Core paketinde herhangi bir kod değişikliği gerektirmez. Bkz. https://nextpdf.dev/get-license/?intent=laravel-signing.

Ayrıca bkz.

/integrations/laravel/configuration/ — tüm TSA, imza ve kuyruk anahtarları
/integrations/laravel/production-usage/ — bağımlılık enjeksiyonu (DI) ve hata işleme kalıpları
/integrations/laravel/troubleshooting/ — yol denetimlerinin girdiyi neden reddettiği
/integrations/laravel/boot-and-discovery/ — uzun ömürlü işçilerde bağlama ömürleri