urukprize/docs/02_security_and_fingerprint.md

بروتوكول الأمان، التشفير، وبصمة الجهاز (Security, Fingerprint & Header Protocol)

Document Version: 1.0.0
Date: September 2026

---

1. تحليل المتطلب الأمني والمصطلحات التقنية

أشار المطلب الصوتي إلى ضرورة إلزام كل طلب صادر من التطبيق باحتواء بيانات التحقق الصارمة:

"أي طلب لازم يكون الـ Header، يعني يكون فيه المستخدم، ومعرف المستخدم ID، والـ Fingerprint، حتى تكون أموره أفضل."

لتحقيق أقصى درجات الحماية ومنع مشاركة الحسابات أو تزوير بطاقات العضوية، تم تصميم بروتوكول أمني متكامل يربط بين:

1. بصمة الجهاز الفيزيائية والرقمية (Device Fingerprint).
2. ترويسة الطلب الأمنية المشفرة (Custom Security Headers).
3. التوقيع الرقمي للطلب (Request HMAC-SHA256 Signing).
4. منع هجمات الإعادة (Anti-Replay Protection) عبر الـ Nonce والـ Timestamp.

---

2. آلية توليد بصمة الجهاز (Device Fingerprint Pipeline)

في تطبيق Flutter، يتم جمع مزيج فريد من خصائص العتاد والنظام لتوليد معرف بصمة رقمية لا يتكرر:

flowchart LR
    A[Hardware IDs: Motherboard / CPU / Model] --> D[Fingerprint Generator]
    B[OS Details: Build Number / Android-iOS ID] --> D
    C[Cryptographic Random Salt in SecureStorage] --> D
    D --> E[SHA-256 Hashing]
    E --> F[Device Fingerprint: 64-Hex String]

خطوات التوليد والتخزين عبر الـ Native MethodChannel:

1. الاستغناء الكامل عن الحزم الخارجية: لا يتم استخدام حزم جاهزة مثل device_info_plus لتفادي البطء والثغرات وكسر التوافقية مع تحديثات النظام.
2. قناة تواصل أصيلة (Native MethodChannel):
   • على نظام Android (بلغة Kotlin):
     • قراءة مباشرة لمعرف النظام المشفر Settings.Secure.ANDROID_ID.
     • دمج مصفوفة خصائص العتاد الصلبة: Build.MANUFACTURER, Build.MODEL, Build.HARDWARE, Build.BOARD, Build.FINGERPRINT.
     • توليد ملح تشفيري في معالج الأمان المادي Android KeyStore لضمان عدم استنساخ البصمة حتى لو تم عمل Root للهاتف.
   • على نظام iOS (بلغة Swift):
     • قراءة المعرف العتادي الموثوق UIDevice.current.identifierForVendor?.uuidString.
     • حفظ واسترجاع الملح التشفيري في Apple Keychain Services تحت معيار الأمان الصارم kSecAttrAccessibleAfterFirstUnlock.
3. يتم دمج هذه البيانات وتشفيرها عبر خوارزمية SHA-256 لإنتاج بصمة رقمية بطول 64 حرفاً (X-Device-Fingerprint).
4. تضمن هذه المعمارية الأصيلة عملاً سلساً وبسرعة أداء فائقة على كافة الأجهزة، وخاصة هواتف هواوي والأجهزة الصينية التي لا تدعم خدمات جوجل.

---

3. مواصفات ترويسة الطلب الأمنية (Security Headers Protocol)

كل استدعاء برمجيات (API Request) من تطبيق Flutter إلى خادم الـ PHP يجب أن يرفق الترويسات التالية:

اسم الترويسة (Header)	النوع	الوصف والأهمية
X-User-Id	Integer / UUID	المعرف الرقمي الفريد للمستخدم في النظام
X-Device-Fingerprint	String (SHA-256)	بصمة الجهاز المعتمدة والمطابقة لسجل الجهاز في السيرفر
X-Timestamp	Unix Timestamp	التوقيت الدقيق لإرسال الطلب (بالثواني)
X-Nonce	UUID v4 String	رمز فريد يُستخدم لمرة واحدة فقط لمنع هجمات إعادة الإرسال
X-Signature	String (HMAC-SHA256)	توقيع مشفر يدمج الرابط، التاريخ، النونس، وجسم الطلب
Authorization	Bearer <Token>	رمز الجلسة المشفر الممنوح للمستخدم بعد تسجيل الدخول

معادلة حساب التوقيع الرقمي (Signature Formula):

Signature_Payload = Method + "\n" + Path + "\n" + Timestamp + "\n" + Nonce + "\n" + Hash(RequestBody)
X-Signature = HMAC_SHA256(Signature_Payload, User_Device_Secret)

---

4. التحقق على خادم الـ Pure PHP (Backend Security Middleware)

تقوم طبقة الـ Middleware في الخادم بالتحقق من الطلب بالخطوات التالية قبل تمريره لأي متحكم (Controller):

1. التحقق من نافذة الوقت (Timestamp Window): التأكد من أن X-Timestamp يقع ضمن نطاق ±60 ثانية من توقيت السيرفر لمنع الطلبات المؤجلة.
2. فحص الـ Nonce: التحقق من أن القيمة لم تُستخدم من قبل (مخزنة في جدول سريع أو كاش الذاكرة لمدة 10 دقائق).
3. مطابقة بصمة الجهاز (Fingerprint Match): مقارنة X-Device-Fingerprint بالبصمة المسجلة لـ X-User-Id في جدول user_security.
4. التحقق من التوقيع (HMAC Validation): إعادة حساب التوقيع باستخدام المفتاح السري للجهاز ومقارنته بـ X-Signature باستخدام دالة hash_equals() المقاومة لهجمات التوقيت (Timing Attacks).

---

5. أمن الهوية الرقمية والـ QR Code الديناميكي

لمنع ظاهرة تداول لقطات الشاشة (Screenshot Sharing) بين غير المشتركين للاستفادة من خصم الـ 50% في المستشفيات والفنادق، تم تصميم الـ QR Code ليكون ديناميكياً وموقعاً تشفيرياً:

sequenceDiagram
    participant UserApp as تطبيق المشترك
    participant Server as خادم أوروك PHP
    participant Scanner as هاتف موظف المستشفى / الفندق

    UserApp->>Server: طلب تحديث كود العضوية (مع الهيدر والبصمة)
    Server-->>UserApp: رمز زمني موقع HMAC (صالح لـ 90 ثانية فقط)
    UserApp->>UserApp: عرض QR Code التفاعلي على الشاشة
    Scanner->>UserApp: مسح الرمز بكاميرا الهاتف
    Scanner->>Server: إرسال الرمز للتحقق (Verify Token)
    Server-->>Scanner: عرض فوري: الاسم، الصورة، صلاحية الخصم 50%، وتسجيل سجل الزيارة

بنية رمز الـ QR المشفر:

{
  "uid": 1042,
  "mem": "URUK-2026-8891",
  "exp": 1792451000,
  "sig": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

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