واجهة نزال البرمجية (API)

العقد هو openapi.yaml. المسار الأساسي /api/v1.

المصادقة

• المتصفح: يعيد GET /api/v1/auth/oidc/login أو /auth/saml/login التوجيه إلى مزوّد الهوية. ويضبط رد النداء (callback) ملف تعريف الارتباط (cookie) nezal_session.
• CLI: يفتح nezal login لوحة التحكم. وتستدعي لوحة التحكم POST /auth/cli/token وتسلّم رمزًا صالحًا لمدة 30 يومًا إلى رد النداء المحلي (localhost) الخاص بـ CLI. أرسله في الترويسة Authorization: Bearer.
• التشغيل الأول: يعمل NEZAL_BOOTSTRAP_TOKEN بصلاحيات المشرف إلى أن يُضبط SSO.
• الحسابات المحلية: POST /auth/password/login بالبريد الإلكتروني وكلمة المرور. ويجيب بـ ok أو mfa_required أو mfa_enrol_required. عشر محاولات فاشلة على حساب واحد خلال خمس عشرة دقيقة تقفله لخمس عشرة دقيقة. وستون محاولة من عنوان واحد تحجب العنوان.

أمور يجب أن يلتزم بها العميل

CSRF. يجب أن يحمل أي طلب مصادَق بملف تعريف ارتباط ويغيّر أي شيء ترويسة Origin أو Referer تتعرّف عليها الواجهة. ولا يتأثر بذلك العملاء الذين يستخدمون رموز Bearer.

طلبات GET ذات الآثار الجانبية ترفض ملف تعريف الارتباط تمامًا (الطرفية وتصدير سجل التدقيق والسجلات). فالمتصفح يرسل هذه الطلبات من أصول أخرى (cross-origin). ولو قُبل ملف تعريف الارتباط فيها لأمكن استغلاله من أي صفحة. استخدم رمز Bearer أو أنشئ تذكرة تُستخدم مرة واحدة وتسري 60 ثانية عبر POST /auth/ticket ومرّرها معاملَ استعلام (query parameter).

الجلسات قابلة للإلغاء. يحمل كل رمز معرّف jti يُطابَق مع جدول الجلسات في كل طلب. لذلك يسري الإلغاء فورًا ولا ينتظر انتهاء صلاحية الرمز. ونقاط النهاية هي GET /me/sessions و DELETE /me/sessions/{jti} وPOST /me/sessions/revoke-all (الذي يستثني الجلسة المستدعية).

القوائم الفارغة تُعاد [] ولا تُعاد null أبدًا. وأي قائمة فارغة على غير ذلك خلل.

الأخطاء

{"code": "nezal.env.quota.perUser", "params": {"owner": "amr", "current": "3", "max": "3"}}

تحمل حالات رفض القبول (admission) الحقل causes[] بمدخل واحد لكل قاعدة. ولكل مدخل field و code وparams. اعرض النصوص بالإنجليزية والعربية من api/pkg/i18n (Render(lang, code, params)).

الترخيص

يثبّت PUT /licence {"key": "NZL2...."} مفتاحًا. وما تزال مفاتيح NZL1. مقبولة. الحالات: valid وgrace وexpired وinvalid وmissing. أصدر المفاتيح بالأمر nezal-licence issue (للمورّد فقط).

يرفض الترخيص المنتهي أو المفقود إنشاء البيئات وتمديدها ومزامنتها. ولا يرفض شيئًا غير ذلك: فالإيقاظ والمعاينات وتسجيل الدخول وسجل التدقيق كلها تستمر في العمل. والميزة المرخّصة غير المتوفرة تجيب بـ 402 مع اسم الميزة في params. وينبغي للعميل أن يعرضها بعبارة "غير مشمولة في خطتك" لا بوصفها خطأ. يعيد GET /licence/usage-report تقريرًا موقَّعًا بالمقاعد النشطة شهريًا.

التدقيق

• GET /audit (للمشرف)
• GET /audit/verify
• GET /audit/export (حزمة أدلة موقَّعة)
• PUT /settings/siem للإرسال عبر syslog أو HTTP

المدخلات مسلسلة بالتجزئة (hash-chained) ولا يمكن تعديلها أو حذفها أبدًا.