قواعد الأمان للإضافات والمساهمين

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

للإبلاغ عن ثغرة، راسل security@maktaba.dev (التفاصيل في آخر هذه الصفحة). ولا تستخدم مسألة عامة أبدًا.

الإضافات

الحالة: مُخطَّط (لم يُبنَ بعد). نظام الإضافات موصوف في الملحمة 54 ولم يُبنَ بعد. كل قاعدة في هذا القسم متطلب مُخطَّط من تلك المواصفة؛ وقد تتغيّر التفاصيل قبل إطلاقه. الطريقة الوحيدة اليوم لتوسيع مكتبة هي امتداد بايثون من الفريق الأساسي داخل خط المعالجة، وهو غير مفتوح لأطراف خارجية.

الإضافة حزمة واحدة موقَّعة (.mkplugin) تضم مكوّن WebAssembly واحدًا، وبيانًا، ونصوصها بالإنجليزية والعربية، وأيقونة، وواجهة تصريحية اختيارية. تضيف مراحل إلى طابور المهام، وتعمل عبر واجهة برمجية للإضافات ضيقة ومرقَّمة الإصدارات.

لا إنترنت (مُخطَّط)

• لا تستطيع الإضافة فتح مقبس، ولا تحليل اسم نطاق، ولا إرسال طلب HTTP. لا يربط المضيف أي وظائف شبكية بالمكوّن أصلًا، فلا يوجد ما يُستدعى. ولا توجد قدرة network، تحت أي إذن.
• التكاملات التي تحتاج إلى الإنترنت تبقى شيفرة من الفريق الأساسي، لا إضافات.
• يثبت التكامل المستمر ذلك على macOS وLinux وWindows باختبارات تحاول الوصول إلى الشبكة ويجب أن تفشل.

العزل (مُخطَّط)

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

وصول إلى الواجهة البرمجية بالمنح فقط (مُخطَّط)

• تعلن الإضافة القدرات التي تحتاج إليها في بيانها (مثل library.read وtranscript.read وmedia.frames وtags.write). ويمنحها المشرف عند التثبيت، كأذونات تطبيقات الهاتف.
• تتحقق الواجهة البرمجية من كل استدعاء في الخادم. الاستدعاء دون منح يُجاب بـ 403 plugin_capability؛ والاستدعاء خارج موضوع المهمة أو المكتبات الممنوحة يُجاب بـ 403 plugin_scope. ويُسجَّل الاثنان.
• لا تحصل الإضافات أبدًا على صلاحيات المشرف، ولا بيانات اعتماد المستخدمين، ولا الأسرار، ولا بيانات إضافة أخرى، ما لم تصدّرها تلك الإضافة ويُمنح الوصول إليها.
• لا تكتب الإضافات إلا في الحقول المدرجة في قائمة السماح؛ وكل كتابة تُنسب إلى الإضافة وإصدارها، لكي يمكن سردها والتراجع عنها.
• التحديث الذي يطلب قدرات جديدة يعود إلى المراجعة البشرية في المتجر.

حزم موقَّعة (مُخطَّط)

• تحمل كل حزمة بصمة لكل ملف وتوقيعين من نوع Ed25519: توقيع المطوّر، وتوقيع متجر مكتبة المضاد الذي يُضاف بعد الفحوص الآلية والمراجعة.
• يتحقق منزل مكتبة من التوقيعات ويفحص قائمة إبطال موقَّعة قبل تثبيت أي إضافة أو تشغيلها، ويستطيع إيقاف إضافة مُبطَلة مثبّتة سلفًا.
• الحزمة غير الموقَّعة أو الموقَّعة من المطوّر وحده لا تُثبَّت إلا بموافقة صريحة من المشرف، وتُعلَّم بعبارة "غير مُراجَعة" في كل مكان. والعزل نفسه في الحالتين.
• يحفظ المطوّرون مفتاح التوقيع سرًّا. ويجب الإبلاغ فورًا عن أي مفتاح مُسرَّب لكي تُبطَل حزمه.

المساهمون

تنطبق هذه القواعد على كل تغيير في المستودع اليوم.

لا أسرار ولا بيانات اعتماد

• لا تودِع أبدًا أسرارًا أو كلمات مرور أو مفاتيح واجهات برمجية أو رموزًا (tokens) أو مفاتيح خاصة أو مواد توقيع، في الشيفرة أو الاختبارات أو بيانات الاختبار أو الوثائق أو الأمثلة أو ملفات التكامل المستمر.
• اقرأ الإعدادات من البيئة أو من ملفات خارج المستودع. ملفات الأمثلة (مثل .env.example) لا تحمل إلا الأسماء والقيم الافتراضية المحلية الآمنة.
• تنشئ الاختبارات مفاتيح مؤقتة وتستخدم قيمًا وهمية واضحة. لا تلصق أبدًا رمزًا حقيقيًّا في اختبار، ولو لوقت قصير؛ فكل ما يُدفع يبقى في السجل.
• إذا أُودِع سرّ، فعامِله على أنه مُسرَّب: غيّره أولًا، ثم أزِله.

لا تفاصيل شخصية أو خاصة في الوثائق

• لا مسارات منزلية شخصية، ولا أسماء مستخدمين في المسارات، ولا عناوين شبكات خاصة، ولا أسماء مضيفين داخلية، ولا أسماء أجهزة شخصية. استخدم عناصر نائبة عامة مثل localhost أو <data-dir> أو example.com.
• لا لقطات شاشة تُظهر حسابات أو مكتبات أو رموزًا أو عناوين حقيقية.

تحقّق من المدخلات

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

التحقق من الأدوار في الخادم

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

نظافة الاعتماديات

• لا تضف اعتمادية إلا حين تستحق مكانها؛ وفضّل المكتبة القياسية والمكتبات المستخدمة أصلًا.
• ثبّت الإصدارات عبر ملفات القفل (go.sum وuv.lock وpnpm-lock.yaml) وأودِعها مع التغيير؛ ويفشل make lockfile-check عند الانحراف.
• استخدم حزمًا مصونة وواسعة الاستخدام من السجلات الرسمية. ولا تضمّن أبدًا شيفرة من مصدر مجهول.
• تعامل سريعًا مع تنبيهات الأمان الخاصة بالاعتماديات، واجعل الترقيات في تغييرات مستقلة ومركّزة.
• يُشغَّل فحص الشيفرة CodeQL على طلبات الدمج؛ أصلح التنبيهات الجديدة عالية الخطورة قبل الدمج.

الإبلاغ عن الثغرات

• راسل security@maktaba.dev بما وجدته، وكيفية إعادة إنتاجه، والإصدار أو الإيداع، والأثر الذي تتوقعه.
• لا تبلغ أبدًا عن ثغرة في مسألة عامة أو طلب دمج أو نقاش أو محادثة. ولا تنشر التفاصيل حتى يُشحن إصلاح ويُتفق على الإفصاح.
• السياسة الكاملة، بما فيها النطاق وأزمنة الاستجابة، موجودة في maktaba.dev/security/policy.

راجع أيضًا أعراف المساهمين ودليل طلبات الدمج.

اعرض مصدر هذه الصفحة على GitHub