Keamanan dan operasi untuk paket Laravel NextPDF

Sekilas

Paket ini menetapkan header respons Portable Document Format (PDF) tetap, membersihkan nama berkas unduhan, memvalidasi jalur keluaran antrean pada worker, dan merutekan panggilan Hypertext Transfer Protocol (HTTP) ke otoritas penanda waktu melalui klien yang dirancang untuk menghadapi pemalsuan permintaan. Halaman ini menjelaskan model ancaman serta konfigurasi deployment yang dibutuhkan oleh setiap kontrol.

Pemasangan

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

Tinjauan konseptual

Paket ini mengadaptasi mesin PDF agar dapat digunakan dalam framework web. Permintaan HTTP dan transpor antrean menjadi batas kepercayaan. Kontrol ini mencakup penanganan respons, muatan pekerjaan yang dideserialisasi, dan lalu lintas HTTP keluar ke otoritas penanda waktu.

Permukaan API — model ancaman

Aset	Ancaman	Kontrol dalam paket ini	Konfigurasi deployment yang diperlukan
Respons HTTP PDF	Penebakan tipe konten, clickjacking, pengindeksan	Menetapkan header tetap pada setiap factory PdfResponse	Tidak ada; header tidak dapat dikonfigurasi
Nama berkas unduhan	Injeksi header, path traversal pada Content-Disposition	Pembersih nama berkas menghapus pemisah, karakter kontrol, dan null byte	Tidak ada; pembersih selalu berjalan
Jalur keluaran pekerjaan antrean	Penulisan berkas sembarang melalui muatan terserialisasi yang dirusak	Jalur divalidasi oleh worker di handle()	Rutekan keluaran ke jalur penyimpanan yang terkendali
HTTP otoritas penanda waktu keluar (TSA)	Server-side request forgery, perusakan teks biasa	Klien HTTP yang dirancang untuk menghadapi pemalsuan permintaan; HTTPS diberlakukan kecuali dilonggarkan secara eksplisit	Pertahankan tsa.allow_insecure_http = false; pin Subject Public Key Info (SPKI)
State worker bersama	Kebocoran state antarpermintaan pada worker berumur panjang	Registri fon terkunci; cache gambar terbatas; dokumen terikat factory	Atur preload_fonts; batasi memori di kontainer

Pengerasan respons

Setiap factory PdfResponse menetapkan rangkaian header tetap:

• 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

Nilai-nilai ini berupa konstanta dalam PdfResponse dan tidak dapat dikonfigurasi. Rangkaian pengujian paket memeriksa setiap header pada setiap metode factory, termasuk varian yang dialirkan.

Nama berkas unduhan diproses oleh pembersih sebelum mencapai header Content-Disposition. Pembersih ini menghapus pemisah jalur, karakter kontrol, dan null byte, serta menghasilkan parameter filename*= sesuai Request for Comments (RFC) 5987 untuk nama non-ASCII. Nama berkas kosong menjadi document.pdf.

Validasi muatan antrean

GeneratePdfJob menyerialisasi closure ke transpor antrean. Worker memvalidasi jalur keluaran di dalam handle(), bukan saat dispatch. Validasi menolak:

• null byte dalam jalur,
• skema stream-wrapper (misalnya php://),
• segmen path-traversal ..,
• jalur apa pun yang tidak berakhir dengan .pdf (tanpa membedakan huruf besar-kecil).

Setiap penolakan memunculkan InvalidArgumentException. Validasi berjalan saat worker mengonsumsi pekerjaan. Muatan terserialisasi pada transpor Redis atau basis data dapat dimodifikasi sebelum worker membacanya. Rutekan jalur keluaran ke direktori penyimpanan yang terkendali; jangan membangunnya dari input permintaan yang belum divalidasi.

HTTP keluar ke otoritas penanda waktu

Ketika otoritas penanda waktu dikonfigurasi, paket melakukan binding untuk sebuah Psr\Http\Client\ClientInterface PHP Standard Recommendation (PSR)-18. Klien PSR-18 mengirim permintaan PSR-7 dan mengembalikan respons PSR-7 (PSR-18 §2). Klien yang di-bind membungkus klien berbasis curl dengan lapisan yang dirancang untuk menghadapi pemalsuan permintaan. Klien tersebut memberlakukan HTTPS kecuali tsa.allow_insecure_http secara eksplisit bernilai true.

Otoritas penanda waktu adalah kapabilitas tingkat Premium. Paket Core yang didokumentasikan di sini menyediakan binding klien HTTP dan pengkabelan klien penanda waktu; penandatanganan itu sendiri memerlukan nextpdf/premium. Halaman ini tidak mendokumentasikan perilaku baseline PDF Advanced Electronic Signatures (PAdES) di luar B-B; baseline yang lebih tinggi berada di luar cakupan.

Panduan operasional untuk otoritas penanda waktu:

1. Pertahankan tsa.allow_insecure_http tetap diatur ke false di produksi.
2. Atur tsa.pinned_public_keys ke hash SPKI SHA-256 base64 dari sertifikat otoritas penanda waktu (bentuk RFC 7469).
3. Pertahankan tsa.warn_on_key_rotation tetap diatur ke true agar perubahan SPKI dicatat sebelum sertifikat yang di-pin kedaluwarsa.
4. Ambil tsa.url hanya dari konfigurasi tepercaya. Jika operator dapat mengaturnya dari antarmuka admin, terapkan firewall egress atau kebijakan DNS untuk mengurangi paparan pemalsuan permintaan.

Pencatatan log

Gunakan Psr\Log\LoggerInterface untuk diagnostik. Berikan konteks terstruktur, bukan string yang diinterpolasi. PSR-3 menyerahkan escaping placeholder kepada implementasi logger dan menginstruksikan pemanggil agar tidak meng-escape nilai konteks terlebih dahulu (PSR-3 §1.2). Catat kelas eksepsi, bukan pesan atau trace-nya, untuk mengurangi detail internal dalam log.

Contoh kode — Produksi

resource: config/nextpdf.php (tsa hardening) + src/Laravel/NextPdfServiceProvider.php

<?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
        ],
    ],
];

Kasus tepi & jebakan

• Rangkaian header respons bersifat tetap. Aplikasi yang membutuhkan Content Security Policy (CSP) yang berbeda harus memproses respons setelah factory mengembalikannya.
• Validasi jalur berjalan pada worker. Jalur yang tidak valid lolos dari dispatch() dan baru gagal ketika pekerjaan dijalankan.
• tsa.allow_insecure_http = true menghapus pemberlakuan HTTPS dan melemahkan kepercayaan penanda waktu. Batasi penggunaannya untuk pengembangan lokal.
• Registri fon dikunci setelah pemanasan; secara desain, paket menolak upaya mendaftarkan fon saat runtime di worker berumur panjang.

Performa

Kontrol keamanan menggunakan operasi string dan array waktu-konstan dan tidak menambah biaya per permintaan yang terukur. Penguraian fon pada penggunaan pertama adalah biaya operasional yang dominan; pramuat fon saat worker boot untuk menghindari latensi permintaan pertama.

Catatan keamanan

Halaman ini adalah rujukan model ancaman untuk paket tersebut. Kode sumber memberlakukan kontrol ini, dan rangkaian pengujian menegaskannya. Tabel model ancaman dan langkah-langkah otoritas penanda waktu menyoroti konfigurasi deployment yang harus disediakan operator.

Kesesuaian

Klaim	Sumber	Klausa	reference_id
Klien PSR-18 mengirim permintaan PSR-7, mengembalikan respons PSR-7	PSR-18 HTTP Client	§2
Pemanggil meneruskan konteks log terstruktur yang tidak di-escape	PSR-3 Logger	§1.2

Pinning SPKI RFC 7469 memberi nama pada bentuk yang digunakan oleh kunci konfigurasi tsa.pinned_public_keys. Paket mengonsumsi nilai pin yang disediakan operator dan tidak mengimplementasikan RFC itu sendiri.

Konteks komersial

Penandatanganan PAdES B-B dan integrasi otoritas penanda waktu memerlukan nextpdf/premium. Kapabilitas Enterprise opsional ini tidak memerlukan perubahan kode pada paket Core yang didokumentasikan di sini. Lihat https://nextpdf.dev/get-license/?intent=laravel-signing.

Lihat juga

• /integrations/laravel/configuration/ — setiap kunci TSA, tanda tangan, dan antrean
• /integrations/laravel/production-usage/ — pola dependency injection (DI) dan penanganan kesalahan
• /integrations/laravel/troubleshooting/ — alasan pemeriksaan jalur menolak input
• /integrations/laravel/boot-and-discovery/ — masa hidup binding pada worker berumur panjang