الأمان والتشغيل في حزمة NextPDF Laravel

لمحة سريعة

تضبط الحزمة ترويسات استجابة ثابتة لملفات تنسيق المستندات المحمولة (⁨PDF⁩)، وتنقّي أسماء ملفات التنزيل، وتتحقق من مسارات إخراج قوائم الانتظار داخل العملية العاملة، وتوجّه نداءات بروتوكول نقل النص التشعبي (⁨HTTP⁩) إلى سلطة الطوابع الزمنية عبر عميل يراعي مخاطر تزوير الطلبات. تشرح هذه الصفحة نموذج التهديدات وإعدادات النشر التي يتطلبها كل ضابط أمان.

التثبيت

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

نظرة مفاهيمية عامة

تكيّف الحزمة محرك ⁨PDF⁩ للعمل ضمن إطار عمل ويب. يحدّد طلب ⁨HTTP⁩ وناقل قائمة الانتظار حدود الثقة. تغطي ضوابط الأمان هذه معالجة الاستجابة، وحمولات المهام بعد فك تسلسلها، وحركة ⁨HTTP⁩ الصادرة إلى سلطة الطوابع الزمنية.

واجهة ⁨API⁩ — نموذج التهديدات

الأصل	التهديد	ضابط الأمان في هذه الحزمة	إعدادات النشر المطلوبة
استجابة ⁨PDF⁩ عبر ⁨HTTP⁩	استكشاف نوع المحتوى، واختطاف النقر، والفهرسة	مجموعة ترويسات ثابتة في كل مصنع PdfResponse	لا شيء؛ الترويسات غير قابلة للتهيئة
اسم ملف التنزيل	حقن الترويسات، واجتياز المسار في Content-Disposition	منقّي اسم الملف يزيل الفواصل، وأحرف التحكم، والبايتات الفارغة	لا شيء؛ المنقّي يعمل دائمًا
مسار إخراج مهمة قائمة الانتظار	كتابة ملف عشوائي عبر حمولة متسلسلة مُلاعَب بها	يُتحقَّق من المسار في handle() في العملية العاملة	وجّه الإخراج إلى مسار تخزين محكوم
حركة ⁨HTTP⁩ الصادرة إلى سلطة الطوابع الزمنية (⁨TSA⁩)	تزوير الطلبات من جانب الخادم، والتلاعب بالنص الصريح	عميل ⁨HTTP⁩ يراعي مخاطر تزوير الطلبات؛ يُفرَض ⁨HTTPS⁩ ما لم يُخفَّف ذلك صراحةً	أبقِ tsa.allow_insecure_http = false؛ ثبّت معلومات المفتاح العام للموضوع (⁨SPKI⁩)
حالة العملية العاملة المشتركة	تسرّب الحالة بين الطلبات في العمليات العاملة طويلة العمر	سجل خطوط مقفل؛ ذاكرة تخزين مؤقت للصور محدودة؛ مستند مرتبط بالمصنع	اضبط preload_fonts؛ حُدّ الذاكرة على مستوى الحاوية

تقوية الاستجابة

يضبط كل مصنع PdfResponse مجموعة ترويسات ثابتة:

• 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

هذه القيم ثوابت في PdfResponse، وهي غير قابلة للتهيئة. تتحقق مجموعة اختبارات الحزمة من كل ترويسة في كل دالة مصنع، بما في ذلك المتغيرات المتدفقة.

يمرّ اسم ملف التنزيل عبر منقٍّ قبل وصوله إلى ترويسة Content-Disposition. يزيل المنقّي فواصل المسار، وأحرف التحكم، والبايتات الفارغة، ويُصدر معاملًا filename*= وفق طلب التعليقات (⁨RFC⁩) 5987 للأسماء غير المنتمية إلى ⁨ASCII.⁩ يصبح اسم الملف الفارغ document.pdf.

التحقق من حمولة قائمة الانتظار

يسلسل GeneratePdfJob دالة مغلقة على ناقل قائمة الانتظار. تتحقق العملية العاملة من مسار الإخراج داخل handle()، وليس عند الإرسال. يرفض التحقق ما يلي:

• البايتات الفارغة في المسار،
• مخططات مغلّفات الدفق (على سبيل المثال php://)،
• مقاطع اجتياز المسار ..،
• أي مسار لا ينتهي بـ .pdf (غير حساس لحالة الأحرف).

يطلق كل رفض InvalidArgumentException. يجري التحقق عندما تستهلك العملية العاملة المهمة. يمكن تغيير حمولة متسلسلة على ناقل ⁨Redis⁩ أو في قاعدة بيانات قبل أن تقرأها العملية العاملة. وجّه مسار الإخراج إلى دليل تخزين محكوم؛ لا تشتقّه من مدخلات طلب غير مُتحقَّق منها.

حركة ⁨HTTP⁩ الصادرة إلى سلطة طوابع زمنية

عند تهيئة سلطة طوابع زمنية، تربط الحزمة Psr\Http\Client\ClientInterface وفق توصية معيار ⁨PHP⁩ (⁨PSR⁩)-18. يرسل عميل ⁨PSR-18⁩ طلب ⁨PSR-7⁩ ويعيد استجابة ⁨PSR-7⁩ (⁨PSR-18⁩ §2). يغلّف العميل المربوط عميلًا قائمًا على ⁨curl⁩ بطبقة تراعي مخاطر تزوير الطلبات. يفرض ⁨HTTPS⁩ ما لم تكن tsa.allow_insecure_http صحيحة صراحةً.

سلطة الطوابع الزمنية قدرة من مستوى ⁨Premium.⁩ تربط حزمة ⁨Core⁩ الموثّقة هنا عميل ⁨HTTP⁩ وتوصيلة عميل الطوابع الزمنية؛ أما التوقيع نفسه فيتطلب nextpdf/premium. لا توثّق هذه الصفحة سلوك التوقيعات الإلكترونية المتقدمة لـ ⁨PDF⁩ (⁨PAdES⁩) الأساسي بعد ⁨B-B⁩؛ فالمستويات الأساسية الأعلى خارج النطاق.

إرشادات تشغيلية لسلطة الطوابع الزمنية:

1. أبقِ tsa.allow_insecure_http مضبوطة على false في بيئة الإنتاج.
2. اضبط tsa.pinned_public_keys على تجزئات ⁨SPKI⁩ من نوع ⁨SHA-256⁩ المُرمَّزة بـ ⁨base64⁩ لشهادة سلطة الطوابع الزمنية (صيغة ⁨RFC 7469⁩).
3. أبقِ tsa.warn_on_key_rotation مضبوطة على true حتى يُسجَّل أي تغيّر في ⁨SPKI⁩ قبل انتهاء صلاحية الشهادة المثبَّتة.
4. احصل على tsa.url من إعدادات موثوقة فقط. إذا كان بإمكان مشغّل ضبطها من واجهة إدارية، فطبّق جدار حماية للحركة الصادرة أو سياسة ⁨DNS⁩ للحد من التعرّض لتزوير الطلبات.

التسجيل

استخدم Psr\Log\LoggerInterface للتشخيص. مرّر سياقًا منظَّمًا، وليس سلاسل نصية مُدمَجة بالاستيفاء. يترك ⁨PSR-3⁩ تهريب العناصر النائبة لتنفيذ المُسجِّل ويوجّه المستدعين إلى عدم تهريب قيم السياق مسبقًا (⁨PSR-3⁩ §1.2). سجّل فئة الاستثناء، لا الرسالة أو التتبّع، للحد من ظهور التفاصيل الداخلية في السجلات.

عيّنة كود — بيئة الإنتاج

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

الحالات الحدّية والمزالق

• مجموعة ترويسات الاستجابة ثابتة. يجب على التطبيقات التي تحتاج سياسة أمان محتوى (⁨CSP⁩) مختلفة أن تعالج الاستجابة لاحقًا بعد أن يعيدها المصنع.
• يجري التحقق من المسار في العملية العاملة. يمرّ المسار السيئ عبر dispatch() ويفشل فقط عند تنفيذ المهمة.
• tsa.allow_insecure_http = true تزيل فرض ⁨HTTPS⁩ وتُضعف الثقة في الطوابع الزمنية. اقصرها على التطوير المحلي.
• يُقفَل سجل الخطوط بعد التهيئة المسبقة؛ ترفض الحزمة بحكم التصميم محاولات تسجيل خط في وقت التشغيل داخل عملية عاملة طويلة العمر.

الأداء

تستخدم ضوابط الأمان عمليات على السلاسل والمصفوفات بزمن ثابت، ولا تضيف أي تكلفة قابلة للقياس لكل طلب. تحليل الخطوط عند الاستخدام الأول هو التكلفة التشغيلية المهيمنة؛ حمّل الخطوط مسبقًا عند إقلاع العملية العاملة لتجنّب زمن استجابة الطلب الأول.

ملاحظات أمنية

هذه الصفحة هي مرجع نموذج التهديدات للحزمة. يفرض الكود المصدري هذه الضوابط، وتؤكدها مجموعة الاختبارات. يُبرِز جدول نموذج التهديدات وخطوات سلطة الطوابع الزمنية إعدادات النشر التي يجب على المشغّل توفيرها.

المطابقة

الادعاء	المصدر	البند	⁨reference_id⁩
يرسل عميل ⁨PSR-18⁩ طلب ⁨PSR-7⁩، ويعيد استجابة ⁨PSR-7⁩	عميل ⁨HTTP⁩ وفق ⁨PSR-18⁩	§2
يمرّر المستدعي سياق سجل منظَّمًا غير مُهرَّب	مُسجِّل وفق ⁨PSR-3⁩	§1.2

يحدّد تثبيت ⁨SPKI⁩ وفق ⁨RFC 7469⁩ الصيغة التي يستخدمها مفتاح الإعدادات tsa.pinned_public_keys. تستهلك الحزمة قيم التثبيت التي يوفّرها المشغّل ولا تنفّذ ⁨RFC⁩ نفسه.

السياق التجاري

يتطلب التوقيع وفق ⁨PAdES B-B⁩ والتكامل مع سلطة الطوابع الزمنية ⁨nextpdf/premium.⁩ لا تتطلب قدرة ⁨Enterprise⁩ الاختيارية هذه أي تغيير في الكود ضمن حزمة ⁨Core⁩ الموثّقة هنا. راجع https://nextpdf.dev/get-license/?intent=laravel-signing.

انظر أيضًا

• /⁨integrations/laravel/configuration/⁩ — جميع مفاتيح ⁨TSA⁩ والتوقيع وقائمة الانتظار
• /⁨integrations/laravel/production-usage/⁩ — أنماط حقن التبعيات (⁨DI⁩) ومعالجة الأخطاء
• /⁨integrations/laravel/troubleshooting/⁩ — لماذا ترفض فحوص المسار المدخلات
• /⁨integrations/laravel/boot-and-discovery/⁩ — أعمار الربط في العمليات العاملة طويلة العمر