الأمان والعمليات في NextPDF Connect

لمحة سريعة

يُصادق ⁨NextPDF Connect⁩ وسائط النقل الشبكية باستخدام رمز حامل خاص بمفتاح ⁨API.⁩ ويتعامل مع وسيط النقل المحلي ⁨Model Context Protocol⁩ (⁨MCP⁩) بصفته عملية فرعية موثوقة. ويضع كل أداة عالية الخطورة خلف تأكيد بشري صريح. تشرح هذه الصفحة نموذج المصادقة وأمان النقل ونموذج التهديد.

التثبيت

composer require nextpdf/server

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

للخادم ثلاثة حدود ثقة: حد واحد لكل وسيط نقل.

يعمل وسيط النقل ⁨MCP stdio⁩ كعملية فرعية يطلقها عميل محلي. يقرأ ⁨JSON-RPC⁩ من الدخل القياسي ويكتب الاستجابات إلى الخرج القياسي. لا يملك وسيط النقل هذا أي مستمع شبكي أو مفتاح ⁨API.⁩ ويرث الثقة من حد عملية نظام التشغيل، وهو نموذج الثقة الذي تحدده مواصفة ⁨MCP⁩ لـ ⁨stdio.⁩ تُرسل السجلات إلى الخطأ القياسي، لذا لا تُفسد دفق البروتوكول أبدًا.

أما وسيط النقل ⁨REST⁩ ووسيط النقل ⁨gRPC⁩ فهما شبكيان. ويتطلب كل منهما رمز حامل لمفتاح ⁨API⁩ في كل طلب، باستثناء فحوص السلامة غير المصادَق عليها. ويدعم وسيطا النقل مخزن المفاتيح نفسه، وصيغة المفتاح نفسها، والتحقق ذا الزمن الثابت نفسه. يقرأ وسيط النقل ⁨gRPC⁩ الرمز من بيانات تعريف الاستدعاء. ويقرؤه ⁨REST⁩ من ترويسة Authorization.

تُعد المصادقة غير الصحيحة العطل الذي تسميه قائمة ⁨OWASP⁩ لأهم 10 مخاطر في أمان واجهة برمجة التطبيقات (⁨API⁩) باسم ⁨API2⁩:2023 ⁨Broken Authentication.⁩ تُضعف العيوب في هذا المجال قدرة الـ ⁨API⁩ على تحديد هوية المستدعي، ومن ثم تُضعف أمان الـ ⁨API⁩ إجمالًا (⁨OWASP API Security Top 10⁩، ⁨API2⁩:2023). كما تُذكر الرموز الضعيفة أو القابلة للتنبؤ بوصفها نمطًا مضادًّا يدل على مصادقة معطوبة (المصدر نفسه، قائمة الثغرات). يعالج التصميم أدناه كلا الخطرين.

سطح الـ ⁨API⁩

صيغة مفتاح ⁨API⁩ والتحقق منه

المفتاح هو npk_live_{kid}_{secret}. يمثّل kid معرِّفًا من ثمانية أحرف يُستخدم للبحث عن السجل بزمن ⁨O⁩(1)، ويحمل السر مقدار العشوائية. لا يحتفظ المخزن أبدًا بالمفتاح الخام؛ بل يخزّن ملخص ⁨SHA-256⁩ لكامل مادة المفتاح. في كل طلب، يحسب الخادم تجزئة الرمز المقدَّم ويقارنها بالملخص المخزَّن باستخدام مقارنة ذات زمن ثابت (hash_equals)، فلا يكشف المفتاح الخاطئ أي معلومات عبر التوقيت. يُرفض المفتاح المعطَّل أو منتهي الصلاحية بعد فحص التجزئة، لا قبله.

يشترك متحققا ⁨REST⁩ و⁨gRPC⁩ في هذا المنطق. تقرأ وسيطة ⁨REST⁩ Authorization: Bearer npk_live_…. يقرأ مُصادِق ⁨gRPC⁩ رمز الحامل نفسه من بيانات تعريف الاستدعاء authorization في ⁨gRPC⁩، والتي تُنقل بوصفها ترويسات ⁨HTTP/2.⁩ ويُفشل الاستدعاء بحالة UNAUTHENTICATED في ⁨gRPC.⁩

يطبّق وسيطا النقل أيضًا تقييد معدل مضادًّا للأتمتة على حركة ما قبل المصادقة: تُرصد المحاولات المفرطة من هوية عميل واحدة وتُرفض — 429 Too Many Requests في ⁨REST⁩، والحالة RESOURCE_EXHAUSTED في ⁨gRPC.⁩ يكون هذا الضابط نشطًا افتراضيًّا، لذا يحمي أي نشر لم يُكوِّن مخزن تحديد المعدل على نحو منفصل. ينبغي للعملاء التراجع بدلًا من إعادة المحاولة فورًا.

الاستجابات غير المصرَّح بها

يتلقى طلب ⁨REST⁩ الذي يحتوي على مفتاح مفقود أو مشوَّه أو معطَّل أو منتهي الصلاحية 401 Unauthorized مع نص بتفاصيل المشكلة وترويسة استجابة WWW-Authenticate: Bearer. يطابق هذا متطلب ⁨HTTP⁩ بأن استجابة 401 يجب أن تحمل حقل ترويسة WWW-Authenticate بتحدٍّ واحد على الأقل (⁨RFC 9110⁩ §11.6.1). وينبع هذا المتطلب من القاعدة القائلة بأن الطلب بلا اعتمادات أو باعتمادات غير صالحة ينبغي أن يتلقى 401 مع تحدي WWW-Authenticate (⁨RFC 9110⁩ §11.6).

استحقاق المفتاح

يحمل كل سجل مفتاح حدًّا أقصى لطبقة المنتج. يرفق خط أنابيب ⁨REST⁩ هوية العميل المصادَق عليه وطبقته بالطلب، ليتمكن التفويض اللاحق من فرض سقوف القدرة والحمولة حسب الطبقة. لا يمكن لمفتاح من طبقة ⁨core⁩ تشغيل عملية ⁨Pro⁩ أو ⁨Enterprise⁩، حتى عندما تكون تلك الحزم مثبَّتة.

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

لا يملك وسيط النقل ⁨MCP⁩ أي مفتاح ⁨API.⁩ هذا مقصود وصحيح لعملية فرعية محلية. لا تعرض خادم ⁨MCP⁩ عبر طبقة وسيطة شبكية. إذا احتاج وكيل شبكي إلى الأدوات، فضعه أمام وسيط النقل ⁨REST⁩ أو ⁨gRPC⁩، اللذين يصادقان.
فحوص السلامة مجهولة الهوية عن قصد. يتجاوز /healthz و/readyz المصادقةَ حتى يتمكن المنسِّقون من فحص الحيوية والجاهزية دون اعتمادات. وهما لا يعيدان سوى الحالة، ولا يكشفان أي بيانات أدوات أو بيانات مستندات.
رمز التأكيد وحيد الاستخدام وقصير العمر. تُصدر بوابة التدخل البشري رمزًا مرتبطًا باسم الأداة لمدة 300 ثانية. يُستهلك الرمز عند أول استخدام. وهو ليس اعتمادًا للمصادقة ولا يحل محل مفتاح ⁨API.⁩

الأداء

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

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

بوابة التدخل البشري

تعلن كل أداة مستوى خطورتها. الأدوات في أعلى مستوى، ApprovalRequired، لا تُنفَّذ عند الاستدعاء الأول. تعيد بوابة التأكيد تحديًا يتضمن رمزًا وحيد الاستخدام. وعلى الوكيل أن يُظهر التحدي لإنسان وأن يعيد استدعاء الأداة بالرمز. هذا ضابط متعمَّد عند النقطة التي يُدخل فيها الفعل المؤتمت خطرًا. وهذه هي النقطة التي يحددها ⁨IEC 31010⁩ للتحكم في الخطر المُدخَل عبر الفعل البشري (هنا، الوكيل)، عند نقطة الإدخال أو قربها (⁨IEC 31010⁩:2019). لا يمكن للتكوين أن يضعف البوابة: يمكن لتجاوز التكوين أن يرفع خطورة أداة فقط، ولا يمكنه أبدًا أن يخفض أداة ApprovalRequired. راجِع /⁨connect/hitl-risk-tiers/.⁩

تكوين أمان النقل

لا تُنهي وسائط النقل الشبكية ⁨Transport Layer Security⁩ (⁨TLS⁩) بنفسها؛ فـ ⁨TLS⁩ مسؤولية على مستوى النشر. يشغّل النشر المرجعي المدمج وسيط النقل ⁨gRPC⁩ بـ ⁨TLS⁩ متبادل، مع تزويد المفتاح والشهادة وسلطة التصديق للعميل بوصفها أسرار نشر. في ظل ⁨TLS⁩ المتبادل، يقدم الخادم شهادة ويتطلب شهادة عميل ويتحقق منها. شغِّل وسيط النقل ⁨REST⁩ خلف مُنهٍ لـ ⁨TLS⁩ (وكيل عكسي أو شبكة خدمة)، ولا تكشف أبدًا مستمعًا بنص صريح على شبكة غير موثوقة. توجد تفاصيل التكوين المحددة في /⁨connect/deployment/.⁩ هذا بيان وضعية، لا ضمان جاهز، والنقل الآمن يتطلب تكوين نشر صحيحًا.

احتواء مسار الخرج

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

إقامة البيانات وتخفيفات ⁨PII⁩

يحتفظ الخادم بالمستندات في مخزن المستندات في الذاكرة فقط طوال مدة البقاء (⁨TTL⁩) المكوَّنة (الافتراضي 1800 ثانية) وبعدد محدود (الافتراضي 50). وهو لا يُبقي محتوى المستند على القرص ما لم تستدعِ صراحةً أداة خرج ملف ويجتز المسار فحص الاحتواء. لا يُجري الخادم أي استدعاء شبكي صادر لتصيير مستند أو فحصه، لذا لا تغادر بايتات المستند النشرَ ما لم تُكوَّن أداة صراحةً لجلب مورد بعيد. بالنسبة إلى النشرات عديمة الحالة والحساسة لإقامة البيانات، عطِّل خرج الملفات (allow_file_output: false) وقيِّد enabled_tools إلى الحد الأدنى من المجموعة.

القياس عن بُعد الآمن وتنقية السجلات

يسجل التدقيق عمليات تنفيذ الأدوات عند مستوى الخطورة Caution وما فوقه، إضافةً إلى كل تحدي تأكيد مُصدَر. يحمل سجل التدقيق اسم الأداة ومستوى الخطورة وعلامة النجاح. تعامل مع وسائط الأداة على أنها قد تكون حساسة: وجِّه السجلات إلى مصرف ذي ضوابط وصول، ولا ترفع مستوى السجل العام إلى درجة إسهاب تردد حمولات الوسائط في بيئات مشتركة. يكتب وسيط النقل ⁨MCP⁩ السجلات إلى الخطأ القياسي حتى لا يدخل محتوى السجل أبدًا دفق البروتوكول على الخرج القياسي.

المطابقة

الادعاء	المصدر	`reference_id`
المصادقة المعطوبة تُضعف أمان الـ ⁨API⁩	⁨OWASP API Security Top 10⁩، ⁨API2⁩:2023
الرموز الضعيفة/القابلة للتنبؤ نمط مضاد لمصادقة معطوبة	⁨OWASP API Security Top 10⁩، ⁨API2⁩:2023
`401` يجب أن يحمل تحدي `WWW-Authenticate`	⁨RFC 9110⁩ §11.6.1
الاعتمادات المفقودة/غير الصالحة ← `401` + تحدٍّ	⁨RFC 9110⁩ §11.6
التحكم في الخطر عند نقطة الإدخال (البشري)	⁨IEC 31010⁩:2019

يتبع نموذج ثقة ⁨Model Context Protocol stdio⁩ مواصفةَ ⁨MCP⁩ الرسمية، المراجعة 2025-06-18. وعنوان ⁨URL⁩ الخاص بها مسجَّل في /⁨transports/mcp/⁩ لأن مواصفة ⁨MCP⁩ ليست جزءًا من مجموعة المعايير المُبوَّبة.

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

لا توجد أدوات التوقيع والتنقيح والامتثال والطب الشرعي إلا عند تثبيت nextpdf/premium إلى جانب الخادم. وجودها لا يغير نموذج المصادقة. لا تزال طبقة خطورتها تضع الأدوات المدمرة خلف بوابة التدخل البشري.

انظر أيضًا

/⁨connect/hitl-risk-tiers/⁩ — نموذج الخطر ومظروف التأكيد بالتفصيل
/⁨connect/deployment/⁩ — ⁨TLS⁩ و⁨TLS⁩ المتبادل والأسرار وضبط العمال
/⁨transports/rest/⁩ — خط أنابيب وسيطة ⁨REST⁩ ومخطط أمان ⁨OpenAPI⁩
/⁨transports/grpc/⁩ — مصادقة بيانات تعريف ⁨gRPC⁩ ورموز الحالة
/⁨connect/configuration/⁩ — enabled_tools، اختيار مخزن المفاتيح، تجاوزات الخطورة