إدارة الأسرار ومتغيرات البيئة

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

في مشاريع Vite، لا تُضمّن في حزمة العميل إلا المتغيرات التي تبدأ بالبادئة VITE_. ويمكن الوصول إلى VITE_PUBLIC_API_URL=https://api.example.com في شيفرة المتصفح عبر import.meta.env.VITE_PUBLIC_API_URL. أما جميع المتغيرات الأخرى فتُزال من الحزمة وقت البناء وتظل مقتصرة على الخادم.

في Next.js، تكشف البادئة NEXT_PUBLIC_ المتغير لشفرة JavaScript في المتصفح. ويُضمّن NEXT_PUBLIC_ANALYTICS_ID=UA-123 في حزمة العميل. أما المتغيرات التي لا تحمل هذه البادئة (مثل DATABASE_URL) فلا يمكن الوصول إليها إلا في الشيفرة من جانب الخادم (مكونات الخادم ومسارات API وإجراءات الخادم)، ولا تُرسل مطلقًا إلى المتصفح.

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

يجب ألا تظهر العناصر التالية مطلقًا في حزمة العميل: سلاسل اتصال قواعد البيانات وكلمات المرور، ومفاتيح API السرية التابعة لجهات خارجية (مفتاح Stripe السري ومفتاح OpenAI API)، ومفاتيح RSA/EC الخاصة، وأسرار توقيع JWT، ورموز مصادقة الخدمات الداخلية. إذا احتجت إلى أي منها لإجراء استدعاء API، فمرّر ذلك الاستدعاء عبر وكيل في نقطة نهاية على الخادم.

يضع نمط Backend for Frontend (BFF) طبقة خادم رقيقة بين تطبيق React والخدمات الخارجية الحساسة. يستدعي العميل /api/stripe/charge، فيضيف خادم BFF مفتاح Stripe السري ويستدعي Stripe API، ثم يعيد BFF بيانات الاستجابة الضرورية فقط. وتبقى الأسرار على الخادم بشكل دائم.

يشفّر dotenv-vault ملف .env ويسمح بمشاركته ونشره بأمان عبر البيئات المختلفة، من دون إيداع الأسرار بنص واضح في نظام التحكم في الإصدارات. وتشمل البدائل المخصصة للإنتاج HashiCorp Vault (للمؤسسات) وAWS Parameter Store (SSM) وGCP Secret Manager؛ إذ توفر جميعها استرداد الأسرار عبر API وقت التشغيل بدلًا من وقت البناء.

توفر منصات CI/CD (مثل GitHub Actions وGitLab CI) تخزينًا مشفّرًا للأسرار يمكن الوصول إليه كمتغيرات بيئة أثناء عمليات البناء. خزّن الأسرار في GitHub Secrets، وأشر إليها في مسارات العمل باستخدام ${{ secrets.STRIPE_SECRET_KEY }}. تُخفى الأسرار في السجلات ولا تُضمّن مطلقًا في الأثر البرمجي الناتج عن البناء.

يدعم Next.js وVite عدة ملفات .env: .env (جميع البيئات)، و.env.local (تجاوزات محلية، مستثناة من Git)، و.env.development، و.env.production. يتجاوز الملف المحلي القيم الواردة من الملف المشترك، مما يتيح تهيئة خاصة بكل مطوّر دون التأثير في البيئات الأخرى.

بعد البناء، دقّق في حزمة JavaScript بحثًا عن الأسرار التي كُشف عنها عن طريق الخطأ. شغّل grep -r "password|secret|api_key" dist/ أو استخدم أداة مخصصة مثل تحليل strings على الملفات الناتجة عن البناء. ويمكن التعرّف بوضوح إلى بعض الأسرار، إذا أُدرجت عن طريق الخطأ، من خلال تنسيقها (مثل UUID أو سلاسل base64 أو بادئات المفاتيح مثل sk_live_).

يجب ألا يملك كلٌّ من كل بيئة وكل خدمة وصولًا إلا إلى الأسرار التي تحتاج إليها. لا يحتاج عميل React إلى أي أسرار على الإطلاق؛ بل ينبغي أن يتلقى المعرّفات العامة فقط. ولا يحتاج خادم BFF إلا إلى الأسرار المطلوبة لواجهات API التي يستدعيها. وينبغي أن تستخدم بيئات التطوير مفاتيح API غير مخصصة للإنتاج، ذات صلاحيات محدودة وحدود قصوى للإنفاق.

ماذا يحدث لمتغير بيئة في Next.js يحمل البادئة NEXT_PUBLIC_؟

يستخدم Vite البادئة VITE_ ويستخدم Next.js البادئة NEXT_PUBLIC_ لكشف المتغيرات لحزمة المتصفح. أما جميع المتغيرات الأخرى فمقتصرة على جانب الخادم. لا تُضمّن كلمات مرور قواعد البيانات أو مفاتيح API السرية أو أسرار توقيع JWT في شيفرة العميل مطلقًا. استخدم نمط BFF لتمرير استدعاءات API الحساسة عبر وكيل. واستخدم dotenv-vault أو AWS Parameter Store أو GitHub Secrets لإدارة أسرار الإنتاج. ودقّق في الحزم الناتجة عن البناء بحثًا عن الأسرار التي كُشف عنها عن طريق الخطأ.