first commit
This commit is contained in:
Hamza-Ayed
258
docs/SMART_OTP_GATEWAY.md
Normal file
258
docs/SMART_OTP_GATEWAY.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# دليل تصميم وهندسة نظام بوابة التحقق الذكي (Smart OTP Gateway)
|
||||
|
||||
<div dir="rtl" align="right">
|
||||
يوفر هذا المستند تقييماً تفصيلياً وتصميماً هندسياً لبوابة التحقق الذكية المقترحة لدمج قنوات وتساب وتيليجرام، مع الحفاظ على أنظمة مكالمات الفلاش والرسائل النصية كقنوات بديلة.
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## ١. تقييم المفهوم: تجربة المستخدم البشرية ضد أنظمة كشف الروبوتات
|
||||
|
||||
<div dir="rtl" align="right">
|
||||
يعد تحقيق التوازن بين تجربة المستخدم (UX) وفلاتر الحماية التلقائية (خصوصاً فلاتر حظر الأرقام وأنظمة التعرف البصري على النصوص في وتساب) أحد أكبر التحديات في أنظمة التحقق.
|
||||
- المبالغة في الحماية (مثل الصور المشوهة جداً) تزيد من صعوبة الاستخدام ونسبة إلغاء العملية من المستخدم.
|
||||
- تسهيل العملية بشكل مبالغ فيه (مثل إرسال الرمز كنص عادي) يزيد من نسب اكتشاف الرسائل كرسائل ترويجية أو سبام وحظر أرقام الإرسال.
|
||||
|
||||
الحل الهندسي يكمن في تطبيق "واجهة تحقق متعددة الطبقات" مدعومة بـ "شبكة تحقق ديناميكية متكيفة".
|
||||
</div>
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ OTP Delivery Message │
|
||||
│ │
|
||||
│ ┌───────────────────────┐ │
|
||||
│ │ IMAGE LAYER │ <-- 80% Anti-Detection Entropy │
|
||||
│ │ [ 5 4 1 2 ] │ (Dynamic Generation/Reveal) │
|
||||
│ └───────────────────────┘ │
|
||||
│ │
|
||||
│ Click the button below to verify instantly: │
|
||||
│ [ Verify Now (Deep Link) ] <-- 100% Seamless UX │
|
||||
│ │
|
||||
│ *Hidden metadata container* <-- 20% OCR Noise │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
<div dir="rtl" align="right">
|
||||
الركائز الأساسية لواجهة التحقق متعددة الطبقات:
|
||||
١. طبقة العرض المرئي الأساسي (الصور والوسائط الديناميكية): يعرض رمز التحقق داخل صورة يتم توليدها ديناميكياً مع خطوط تشويش خفيفة.
|
||||
٢. البيانات الخفية المصاحبة للرسالة: تحتوي الرسالة على الرمز مشفراً أو مخفياً باستخدام علامات ترميز يونيكود مخفية (مثل المسافات الصفرية أو علامات الاتجاه) لقراءتها تلقائياً بواسطة التطبيق دون أن تثير انتباه العين البشرية أو الروبوتات.
|
||||
٣. روابط التحقق الفورية (الروابط العميقة): تحتوي الرسالة على رابط عميق آمن يقوم بفتح التطبيق وتأكيد العملية تلقائياً عند النقر عليه دون الحاجة لكتابة أو نسخ أي رمز.
|
||||
٤. التوجيه الديناميكي المتكيف مع المخاطر: يقوم النظام بتغيير طريقة التحقق تلقائياً بناءً على مستوى خطورة الطلب.
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## ٢. البنية التحتية الحالية للنظام
|
||||
|
||||
<div dir="rtl" align="right">
|
||||
يتكون النظام الحالي لمكالمات الفلاش من ثلاثة أجزاء رئيسية:
|
||||
١. خادم الخلفية (PHP API): يتولى إنشاء الرموز، وإدارة الأجهزة المتصلة، وتسجيل المهام، والتحقق من الرموز.
|
||||
٢. تطبيق الاتصال (Android Caller App): يعمل على هواتف أندرويد حقيقية متصلة بالإنترنت وتحتوي على شرائح اتصال نشطة، حيث يقوم بطلب المهام المعلقة وتنفيذ المكالمات والرسائل النصية تلقائياً.
|
||||
٣. تطبيق الاستقبال (Flutter Receiver App): يثبت لدى المستخدم النهائي، ويقوم بالتحقق التلقائي في أندرويد عبر قراءة سجل المكالمات للتعرف على مكالمة الفلاش الفائتة، بينما يتيح التعبئة التلقائية للرسائل النصية في آيفون.
|
||||
</div>
|
||||
|
||||
### ٢.١ مخطط سير العمل الحالي في أندرويد (مكالمة الفلاش)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor User as User Device (Android)
|
||||
participant App as Flutter Receiver App
|
||||
participant BE as PHP Backend API
|
||||
participant DB as Database / Redis
|
||||
participant Caller as Android Caller Node
|
||||
|
||||
User->>App: Input Phone Number & Submit
|
||||
App->>BE: POST /api/request-otp (phone, device_type: "android")
|
||||
BE->>BE: Generate 4-digit OTP (e.g., 4829)
|
||||
BE->>DB: Store OTP in Redis (TTL: 120s)
|
||||
BE->>DB: Assign Task (round-robin) to Active Caller Node
|
||||
BE->>BE: Format Caller ID Prefix + 2 Random Digits + OTP (e.g., +96279XX4829)
|
||||
BE-->>App: JSON Response (otp_id, expires_in, method: "flash_call")
|
||||
App->>App: Request READ_CALL_LOG permission & Start Polling
|
||||
|
||||
loop Polling Tasks (Every 3s)
|
||||
Caller->>BE: GET /api/pending-call?device_id=X
|
||||
BE-->>Caller: JSON (pending call: phone + dynamic Caller ID)
|
||||
end
|
||||
|
||||
Caller->>User: Initiates Voice Call (displays +96279XX4829)
|
||||
Caller->>Caller: Wait 2.5s & Programmatically Terminate Call (Missed Call)
|
||||
Caller->>BE: POST /api/call-done (status: "success")
|
||||
|
||||
App->>App: Detects Missed Call in Call Log
|
||||
App->>App: Extracts last 4 digits of Caller ID (4829)
|
||||
App->>BE: POST /api/verify-otp (phone, otp)
|
||||
BE->>DB: Verify OTP in Redis & Update DB Status
|
||||
BE-->>App: {"success": true, "message": "verified"}
|
||||
App->>User: Display Success Screen
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ٣. بنية بوابة التحقق الذكي المقترحة
|
||||
|
||||
<div dir="rtl" align="right">
|
||||
تقوم البوابة الذكية بفحص توفر حساب للرقم على وتساب وتيليجرام أولاً لتحديد قناة الإرسال المثالية بدلاً من الاعتماد الكلي على نظام تشغيل الهاتف فقط.
|
||||
</div>
|
||||
|
||||
### مخطط اتخاذ القرار وقنوات التوجيه
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Start: Request OTP] --> B{Check WhatsApp Availability}
|
||||
B -- Exists --> C[Determine Risk Level]
|
||||
C -- Low Risk --> D1[Send Obfuscated Text OTP]
|
||||
C -- Medium Risk --> D2[Send Dynamic OTP Image + Deep Link]
|
||||
C -- High Risk --> D3[Send Short APNG/MP4 + Deep Link]
|
||||
|
||||
B -- Does Not Exist --> F{Check Telegram Availability}
|
||||
F -- Exists --> G[Send OTP via Telegram Bot/Client]
|
||||
|
||||
F -- Does Not Exist --> H{Check Device OS}
|
||||
H -- Android --> I[Trigger Flash Call via Caller Node]
|
||||
H -- iOS --> J[Trigger SMS via Caller Node]
|
||||
|
||||
D1 --> K[End: Await Verification]
|
||||
D2 --> K
|
||||
D3 --> K
|
||||
G --> K
|
||||
I --> K
|
||||
J --> K
|
||||
```
|
||||
|
||||
### ٣.١ تصنيف مستويات المخاطر الديناميكية
|
||||
|
||||
| مستوى الخطورة | القناة والمحتوى | مستوى الأمان | مستوى صعوبة تجربة المستخدم | حالات الاستخدام المستهدفة |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **المستوى الأول (منخفض)** | رمز نصي عادي (مع علامات يونيكود مخفية) | منخفض | منخفض جداً (تعبئة تلقائية) | عناوين إنترنت موثوقة، مستخدمون متكررون |
|
||||
| **المستوى الثاني (متوسط)** | صورة ديناميكية ثابتة + رابط تحقق فوري | متوسط | منخفض (التحقق بنقرة واحدة) | التسجيلات القياسية، التوجيه الافتراضي |
|
||||
| **المستوى الثالث (مرتفع)** | صورة متحركة APNG/MP4 تظهر تدريجياً + رابط تحقق | مرتفع | منخفض (التحقق بنقرة واحدة) | عناوين إنترنت مشبوهة، طلبات متكررة بكثافة |
|
||||
| **المستوى الرابع (مشبوه)** | مكالمة فلاش خارجية / رمز صوتي | أقصى حد | متوسط (إدخال يدوي وتحدي) | تخطي حدود المحاولات المسموحة |
|
||||
|
||||
---
|
||||
|
||||
## ٤. المواصفات البرمجية للتكامل
|
||||
|
||||
### ٤.١ بوابة وتساب (Node.js Baileys Gateway)
|
||||
|
||||
#### أ. إضافة واجهة التحقق من الأرقام في خادم الويب
|
||||
في ملف `server.js`:
|
||||
|
||||
```javascript
|
||||
app.post('/api/contacts/check', async (req, res) => {
|
||||
const { session_key, phone } = req.body;
|
||||
if (!session_key || !phone) {
|
||||
return res.status(400).json({ error: 'Missing session_key or phone' });
|
||||
}
|
||||
try {
|
||||
const result = await checkWhatsApp(session_key, phone);
|
||||
res.json({ status: 'success', data: result });
|
||||
} catch (err) {
|
||||
res.status(500).json({ error: err.message || 'Failed to check contact' });
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### ب. توليد صورة رمز التحقق ورابط التحقق التلقائي (PHP Backend)
|
||||
|
||||
```php
|
||||
function generateWhatsAppOtpPayload($otp, $phone, $riskLevel) {
|
||||
// Generate Deep Link Token
|
||||
$token = bin2hex(random_bytes(16));
|
||||
|
||||
// Store deep link token in Redis mapped to phone & OTP (expires in 120s)
|
||||
$redis = RedisClient::getInstance();
|
||||
$redis->setex("verify_token:{$token}", 120, json_encode([
|
||||
'phone' => $phone,
|
||||
'otp' => $otp
|
||||
]));
|
||||
|
||||
$deepLink = "https://verify.nabeh.app/otp?token=" . $token;
|
||||
|
||||
if ($riskLevel === 'level_1') {
|
||||
// Obfuscate OTP text using zero-width joiners (ZWJ) or LTR/RTL control characters
|
||||
$obfuscatedOtp = "\u{202D}" . implode("\u{200B}", str_split($otp)) . "\u{202C}";
|
||||
return [
|
||||
'type' => 'text',
|
||||
'message' => "رمز التحقق الخاص بك هو: " . $obfuscatedOtp . "\n\nأو اضغط للتحقق الفوري:\n" . $deepLink
|
||||
];
|
||||
}
|
||||
|
||||
// Create base64 dynamic image for Level 2 & 3
|
||||
$imageBase64 = generateOtpImageBase64($otp);
|
||||
|
||||
return [
|
||||
'type' => 'image',
|
||||
'image' => $imageBase64,
|
||||
'message' => "اضغط على الرابط أدناه لتأكيد هويتك تلقائيًا دون نسخ الرمز:\n\n" . $deepLink
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ٥. أتمتة التحقق في تطبيق الهاتف (Flutter Client)
|
||||
|
||||
<div dir="rtl" align="right">
|
||||
لتحقيق واجهة مستخدم بدون كتابة أو تعبئة يدوية للرموز، يتم تطبيق آليتين أساسيتين في تطبيق فلاتر:
|
||||
</div>
|
||||
|
||||
### ٥.١ معالجة الروابط العميقة (Deep Links)
|
||||
<div dir="rtl" align="right">
|
||||
يقوم التطبيق بتسجيل الدومين الخاص به. عند النقر على الرابط من داخل محادثة وتساب أو تيليجرام:
|
||||
١. يكتشف نظام التشغيل الرابط ويفتح تطبيق الهاتف تلقائياً.
|
||||
٢. يقوم التطبيق باستخراج التوكين وإرساله مباشرة للخلفية.
|
||||
٣. تكتمل عملية التحقق بنجاح وينتقل المستخدم للشاشة التالية فوراُ.
|
||||
</div>
|
||||
|
||||
### ٥.٢ قارئ الإشعارات التلقائي (Notification Listener - Android)
|
||||
<div dir="rtl" align="right">
|
||||
بالنسبة لهواتف أندرويد، يمكن الاستماع للإشعارات الواردة برمجياً لقراءة الرسائل وتمرير التوكين أو الرمز المخفي دون الحاجة لفتح وتساب:
|
||||
</div>
|
||||
|
||||
```dart
|
||||
void onNotificationReceived(NotificationEvent event) {
|
||||
if (event.packageName == "com.whatsapp" && event.title == "Nabeh") {
|
||||
final body = event.text ?? "";
|
||||
final tokenRegex = RegExp(r"token=([a-f0-9]+)");
|
||||
if (tokenRegex.hasMatch(body)) {
|
||||
final token = tokenRegex.firstMatch(body)!.group(1);
|
||||
_verifyToken(token!);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ٦. تعديلات قاعدة البيانات
|
||||
|
||||
```sql
|
||||
ALTER TABLE otp_requests
|
||||
ADD COLUMN channel ENUM('flash_call', 'sms', 'whatsapp', 'telegram') NOT NULL DEFAULT 'flash_call' AFTER method,
|
||||
ADD COLUMN risk_level ENUM('level_1', 'level_2', 'level_3', 'level_4') NOT NULL DEFAULT 'level_2' AFTER channel,
|
||||
ADD COLUMN deep_link_token VARCHAR(64) NULL DEFAULT NULL AFTER risk_level;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ٧. خطة التطوير والتشغيل
|
||||
|
||||
### المرحلة الأولى: تهيئة قنوات الفحص والروابط العميقة
|
||||
<div dir="rtl" align="right">
|
||||
١. كتابة وتفعيل منطق الروابط العميقة (Deep Links) في خادم PHP وتطبيق فلاتر.
|
||||
٢. ربط النطاقات المرتبطة (Associated Domains) في آبل وجوجل.
|
||||
</div>
|
||||
|
||||
### المرحلة الثانية: تحديثات وتساب (Baileys Node.js)
|
||||
<div dir="rtl" align="right">
|
||||
١. إضافة واجهة التحقق من وجود الرقم على خادم وتساب.
|
||||
٢. تفعيل مكتبة توليد الصور برمجياً في خادم PHP لإرسال الصور التلقائية عبر وتساب.
|
||||
</div>
|
||||
|
||||
### المرحلة الثالثة: أتمتة تطبيق الهاتف والبدائل
|
||||
<div dir="rtl" align="right">
|
||||
١. دمج قارئ الإشعارات في فلاتر وتجربة الأتمتة الكاملة.
|
||||
٢. ربط قنوات الاتصال الفائت والرسائل النصية كقنوات بديلة نهائية في حال عدم نجاح التحقق عبر وتساب أو تيليجرام.
|
||||
</div>
|
||||
Reference in New Issue
Block a user