المفاتيح وCORS
المفتاح القابل للنشر والمفتاح السرّي، وقاعدة المصدر، والتدوير والإلغاء، وCORS الذي يتبع نطاقات موقعك، وطرح المراقبة ثم الإلزام.
كل نداء عام قد يحمل مفتاح واجهة في X-Api-Key. المفاتيح لكل موقع على حدة،
وتُنشأ وتُدوَّر وتُلغى من الإعدادات ← المواقع ← اربط موقعك.
نوعان من المفاتيح
القابل للنشر pk_… | السرّي sk_… | |
|---|---|---|
| أين يعمل | المتصفّح | خادمك أنت (التصيير من الخادم، مهمّة خلفية) |
| سرّي؟ | لا — يُدمج في حزمتك بالتصميم | نعم — يُخزَّن مُجزّأً ويُعرض مرّة واحدة |
| فحص المصدر | نعم: نطاقات موقعك وحدها | لا — نداء الخادم بلا Origin |
| حدود المعدّل | القياسية | خمسة أضعافها |
| فحص الروبوتات | مطلوب على عمليات الكتابة الخمس | متجاوَز |
| ظهوره في النظام | القيمة كاملة في أي وقت | البادئة فقط بعد الإنشاء |
المفتاح القابل للنشر ليس كلمة مرور. قيمته في مكان آخر: يمكنك إلغاؤه، وله حدّ معدّل خاص به، وهو يخبر النظام أي تكامل أطلق النداء. يستطيع أي أحد أن يستخرجه من JavaScript — ولن يعمل معه، لأنه مرفوض من أي مصدر ليس من نطاقاتك.
أما المفتاح السرّي فهو كلمة مرور. يتجاوز فحص المصدر تحديدًا لأن النداء بين
الخوادم لا مصدر فيه ليُفحص، فعامله كاعتماد: احفظه في متغيّر بيئة على الخادم فقط
(لا تسبقه بـ NEXT_PUBLIC_ أبدًا)، ولا تضعه في مستودع، ودوّره فورًا إن ظهر في
حزمة متصفّح أو سجلّ أو لقطة شاشة.
قاعدة المصدر
يُقبل نداء pk_ حين يكون Origin أحد نطاقات الموقع. وخارج الإنتاج يُقبل كذلك
http://localhost وhttp://127.0.0.1، فيعمل التطوير المحلي بالمفتاح الحقيقي. وما
عدا ذلك فهو 403 SITE_KEY_ORIGIN_MISMATCH، وهو الرمز نفسه حين يسمّي المفتاح موقعًا
غير الذي تعرّف عليه الطلب.
لذلك يهمّ تبويب النطاقات مرّتين: فهو يحدّد أي المواقع يعرّفه المضيف، ويحدّد المصادر التي يعمل منها المفتاح القابل للنشر.
التدوير والإلغاء
- التدوير ينشئ مفتاحًا جديدًا ويلغي القديم في خطوة واحدة. انشر القيمة الجديدة، ثم تأكّد أن لا شيء ما زال يستعمل القديمة.
- الإلغاء يقتل المفتاح فورًا. والنداء به يجيب
401 SITE_KEY_REVOKED. - قيمة المفتاح السرّي تُعرض مرّة واحدة في نافذة إنشائه. لا سبيل لقراءتها مجدّدًا؛ وإن ضاعت فدوّره.
- تُسجَّل للمفاتيح لحظة «آخر استخدام»، فتميّز المفتاح الحيّ من المنسيّ قبل إلغائه.
وتدوير المفتاح القابل للنشر عمليّة نشر: المفتاح يعيش داخل بنائك، فلا تصل القيمة الجديدة إلى الزوّار إلا بعد إعادة بناء الموقع. دوّر المفتاح السرّي أولًا إن كنت ستدوّر الاثنين.
CORS
يتبع CORS نطاقات موقعك ولا شيء غيرها. لا يعكس /api/public/* ترويسة Origin إلا
حين تكون:
- نطاقًا مضافًا إلى موقع، أو
- إحدى واجهات المنصّة نفسها المضبوطة في البيئة، أو
localhostخارج الإنتاج.
وكل مصدر آخر يُرفض قبل تشغيل المُعالِج — يبلّغ المتصفّح عن فشل CORS ولا يوجد
جسم استجابة تقرؤه. فإن فشل الجلب في المتصفّح ونجح النداء نفسه من curl، فالمصدر
هو ما يجب فحصه لا المفتاح.
وترويسات الطلب مُدرَجة صراحةً: Content-Type وAuthorization وX-Subdomain
وX-Site وX-Api-Key وX-Turnstile-Token وX-Organization-Id
وX-Simulated-Organization-Id. والترويسة خارج هذه القائمة تُفشل الطلب التمهيدي،
فلا يرسل المتصفّح الطلب أصلًا — وهذا يبدو كعطل في CORS لا كترويسة مرفوضة. لا
تخترع ترويسات من عندك.
الطرح: مراقبة ثم إلزام
تُشغَّل المفاتيح على مرحلتين حتى لا ينكسر موقع قائم عند النشر.
- المراقبة (وهي حال المنصّة اليوم). النداء بلا مفتاح، أو بمفتاح مجهول، أو من مصدر خاطئ، يُخدَم، ويُكتب الرفض في سجلّ الخادم بدلًا من إعادته. فلا يفشل اليوم شيء ممّا تبنيه بسبب غياب مفتاح.
- الإلزام. يُرفض الطلب نفسه:
401 SITE_KEY_REQUIREDأو401 SITE_KEY_REVOKEDأو403 SITE_KEY_ORIGIN_MISMATCH.
ويُعلن التحويل في سجلّ التغييرات قبل حدوثه. أرسل مفاتيحك الآن: في وضع المراقبة لا فرق بين تكامل صحيح وآخر مُلزَم، ويوم التحويل لا يتغيّر عندك شيء.
بعد ذلك
- الحماية من الروبوتات — الرمز الإضافي على خمس عمليات كتابة.
- حدود المعدّل — ماذا تعني «خمسة أضعاف» بالأرقام.