مفاتيح API

يتضمن FORGE نظام إدارة مفاتيح API كامل لمنح التطبيقات والخدمات الخارجية وصولاً آمناً إلى واجهة API الخاصة بك. تدعم المفاتيح صلاحيات دقيقة وتحديد معدل الطلبات والانتهاء والإلغاء.

نظرة عامة

توفر مفاتيح API آلية مصادقة بديلة لجلسات المستخدم. صُممت للتكاملات بين الخوادم والتطبيقات المحمولة وأي نظام خارجي يحتاج لاستدعاء API برمجياً. كل مفتاح له مجموعة صلاحيات وحد معدل خاص به.

مفاتيح التطوير (مُهيأة تلقائياً)

عند إنشاء مشروع FORGE جديد، يتم تهيئة مفاتيح API عاملة تلقائياً لكلا تطبيقي الواجهة الأمامية. هذا يعني أن تسجيل الدخول واستدعاءات API تعمل فوراً دون أي إعداد يدوي.

المفاتيح المُهيأة مسبقاً

التطبيق	المفتاح	الغرض
لوحة الإدارة	forge_sk_admin_panel_default_key_2024	وصول إداري كامل
تطبيق الويب	forge_sk_frontend_web_app_default_key_2024	ميزات الويب العامة

هذه المفاتيح:

1. تُزرع في قاعدة البيانات عبر 07_api_keys.sql أثناء الـ migrations
2. تُهيأ في ملفات .env المُولدة لكل تطبيق واجهة أمامية
3. تُضاف تلقائياً في كل طلبات API عبر رأس X-API-Key

كيف يعمل

إنشاء المشروع
       │
       ├── قاعدة البيانات تزرع مفاتيح API (مُجزأة)
       │
       ├── تطبيق الإدارة يحصل على .env مع:
       │   NEXT_PUBLIC_API_KEY="forge_sk_admin_panel_default_key_2024"
       │
       └── تطبيق الويب يحصل على .env مع:
           NEXT_PUBLIC_API_KEY="forge_sk_frontend_web_app_default_key_2024"

       │
       ▼
عميل API يُضيف رأس X-API-Key تلقائياً لكل الطلبات
       │
       ▼
✅ كل شيء يعمل مباشرة

ملاحظة أمنية

تحذير

مفاتيح التطوير مخصصة للتطوير المحلي فقط. قبل النشر للإنتاج:

1. أنشئ مفاتيح API جديدة من لوحة الإدارة
2. حدّث ملفات .env بالمفاتيح الجديدة
3. فكر في إلغاء مفاتيح التطوير الافتراضية

مفاتيح التطوير لها صلاحيات كاملة (["*"]) لتبسيط التطوير المحلي. مفاتيح الإنتاج يجب أن تكون بصلاحيات محدودة بناءً على مبدأ الحد الأدنى من الصلاحيات.

مخطط قاعدة البيانات

يخزن جدول api_keys جميع المفاتيح المُصدرة:

العمود	النوع	الوصف
id	UUID	المفتاح الأساسي
name	VARCHAR(255)	تسمية قابلة للقراءة (مثل "التطبيق المحمول")
key_hash	VARCHAR(64)	تجزئة SHA-256 للمفتاح الكامل
key_prefix	VARCHAR(8)	أول 8 أحرف للتعريف
permissions	JSONB	مصفوفة الإجراءات المسموحة
rate_limit	INTEGER	الحد الأقصى للطلبات في الدقيقة
last_used_at	TIMESTAMP	آخر وقت استُخدم فيه المفتاح
last_used_ip	VARCHAR(45)	عنوان IP لآخر طلب
request_count	BIGINT	إجمالي عدد الطلبات بهذا المفتاح
expires_at	TIMESTAMP	تاريخ انتهاء المفتاح (nullable لعدم الانتهاء)
revoked_at	TIMESTAMP	وقت إلغاء المفتاح (nullable)
revoked_by	UUID	المستخدم الذي ألغى المفتاح (nullable)
revoked_reason	TEXT	سبب الإلغاء (nullable)
created_by	UUID	المستخدم الذي أنشأ المفتاح
created_at	TIMESTAMP	طابع زمني لإنشاء السجل
updated_at	TIMESTAMP	طابع زمني لآخر تحديث

نموذج الأمان

تتبع مفاتيح API نموذج أمان للكتابة مرة واحدة:

مسار إنشاء المفتاح
─────────────────
1. المسؤول ينشئ مفتاح       → المفتاح الكامل يُرجع مرة واحدة
2. المفتاح يُجزّأ (SHA-256)  → فقط التجزئة تُخزّن
3. بادئة المفتاح تُحفظ       → أول 8 أحرف للعرض
4. المسؤول ينسخ المفتاح     → المفتاح لا يُعرض مجدداً

مسار التحقق من المفتاح
───────────────────
1. العميل يرسل رأس X-API-Key
2. الخادم يُجزّئ المفتاح المستلم
3. التجزئة تُقارن مع key_hash المُخزّن
4. الصلاحيات والانتهاء يُفحصان

تحذير

مفتاح API الكامل يُعرض مرة واحدة فقط عند الإنشاء. لا يمكن استرجاعه لاحقاً. إذا فُقد المفتاح، يجب إلغاؤه وإنشاء مفتاح جديد.

مصفوفة الصلاحيات

يخزن عمود permissions من نوع JSONB مصفوفة الإجراءات المسموحة:

["contents:read", "contents:write", "menus:read", "lookups:read"]

أنماط الصلاحيات الشائعة:

الصلاحية	الوصف
contents:read	قراءة صفحات المحتوى
contents:write	إنشاء وتحديث المحتوى
users:read	قراءة بيانات المستخدمين
users:write	إنشاء وتحديث المستخدمين
menus:read	قراءة بنية القوائم
lookups:read	قراءة قيم البحث
*	وصول كامل (كل الصلاحيات)

المصادقة

تُرسل مفاتيح API عبر رأس HTTP X-API-Key:

curl -X GET /api/contents \
  -H "X-API-Key: fk_a1b2c3d4e5f6g7h8i9j0..."

يتحقق الوسيط من المفتاح في كل طلب:

1. استخراج المفتاح من رأس X-API-Key
2. حساب تجزئة SHA-256
3. البحث عن التجزئة في جدول api_keys
4. التحقق من أن المفتاح غير منتهي (expires_at)
5. التحقق من أن المفتاح غير مُلغى (revoked_at)
6. التحقق من أن الإجراء المطلوب في مصفوفة permissions
7. تطبيق rate_limit
8. تحديث last_used_at و last_used_ip و request_count

نصيحة

مصادقة مفتاح API ومصادقة جلسة المستخدم متنافية حصرياً في طلب واحد. إذا قُدم كلاهما، يأخذ مفتاح API الأولوية.

تحديد المعدل

كل مفتاح API له rate_limit خاص (طلبات في الدقيقة). عند تجاوز الحد، يُرجع API:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800

واجهة الإدارة

توفر لوحة الإدارة إدارة دورة حياة كاملة لمفاتيح API:

• إنشاء مفتاح -- تعيين الاسم والصلاحيات وحد المعدل والانتهاء الاختياري. المفتاح الكامل يُعرض مرة واحدة في مربع حوار سهل النسخ.
• عرض المفاتيح -- قائمة بكل المفاتيح تُظهر الاسم والبادئة والحالة وتاريخ آخر استخدام وعدد الطلبات.
• إلغاء مفتاح -- تعطيل مفتاح فوراً مع سبب اختياري. المفاتيح المُلغاة لا يمكن إعادة تفعيلها.

حالات المفتاح

الحالة	الشرط	قابل للاستخدام؟
نشط	غير منتهي، غير مُلغى	نعم
منتهي	expires_at في الماضي	لا
مُلغى	revoked_at مُعيّن	لا

تحذير

إلغاء المفتاح دائم ويسري فوراً. أي تكاملات تستخدم المفتاح المُلغى ستبدأ بتلقي استجابات 401 Unauthorized. نسّق مع المستهلكين الخارجيين قبل الإلغاء.

مسار التدقيق

جميع إجراءات مفاتيح API تُسجّل في سجل المراجعة. عند تقديم طلب بمفتاح API، يُملأ حقل api_key_id في سجل المراجعة، مما يوفر تتبعاً كاملاً لإجراءات الأطراف الثالثة.