- الوصول إلى API: من قد يتصل بـ GOWA. هذه هي مصادقة HTTP الأساسية.
- إقران WhatsApp: ربط حساب WhatsApp بفتحة الجهاز، كما أنك ستربط Web.
الوصول إلى API: المصادقة الأساسية
المصادقة الأساسية هي طريقة المصادقة API الوحيدة. لا توجد مفاتيح API أو JWT لمكالمات REST. تعيين واحد أو أكثر من أزواجuser:password، مفصولة بفواصل:
APP_HOST=0.0.0.0، يرفض البدء بدون بيانات اعتماد كاملة. من أجل التنمية المحلية بدون مصادقة، يربط APP_HOST=127.0.0.1.
إذا قام الوكيل العكسي بالمصادقة على كل متصل، فإن APP_ALLOW_UNAUTHENTICATED=true أو --allow-unauthenticated=true يسمح صراحة للمستمع غير المصدق بدون مصادقة أساسية. تقييد الوصول المباشر إلى ذلك المستمع.
إرسال بيانات الاعتماد عند كل طلب:
401 Unauthorized.
ما ليس وراء المصادقة الأساسية
كل شيء آخر، بما في ذلك لوحة التحكم في
/، /mcp و /ws، يتطلب المصادقة الأساسية عند تكوينها.
WebSocket
لا يمكن للمتصفحات تعيين رؤوس على اتصالات WebSocket، لذا فإن/ws يأخذ بيانات الاعتماد في سلسلة الاستعلام:
authorization هو base64(user:password). استخدم TLS (wss://) و احرر سلسلة الاستعلام في سجلات البروكسي. يقوم WebSocket بالتحقق من مصدر المتصفح مقابل نفس الأصول الموثوقة المستخدمة لطلبات HTTP المتغيرة للدولة. يقوم مركز WebSocket الحالي ببث الأحداث على جميع المقابس المتصلة. الاستعلام device_id يحدد سياق الجهاز للاتصال ولكنه لا يعزل تسليم الحدث. استخدم معرفات الجهاز للحدث لتصفية عرض لوحة التحكم، ومنح API الوصول فقط إلى المتصلين الموثوق بهم مع جميع الأجهزة.
راجع مرجع WebSocket المرجع لرموز الأحداث ، الحمولات ، و مثال العميل.
CORS
يسمح CORS بأي أصل افتراضيًا. قيّده باستخدامAPP_CORS_ALLOWED_ORIGINS=https://ui.example.com (مع الفصل بفواصل). ترويسات الطلبات المسموح بها هي Origin وContent-Type وAccept وAuthorization وX-Device-Id.
تُجرى فحوص CORS وفحوص مصدر المتصفح بشكل منفصل. لا يسمح استخدام حرف بدل لمصدر CORS بطلبات تغيّر الحالة أو باتصالات WebSocket. يثق GOWA بمضيف الطلب نفسه، ومصادر CORS المحددة، وAPP_TRUSTED_ORIGINS، والمصادر المضبوطة لجهة إصدار OAuth وعنوان URL لاستدعاء Chatwoot الراجع. إذا كانت لوحة التحكم مستضافة بشكل منفصل، فاضبط مصدرها بدقة:
403 CROSS_SITE_REQUEST_BLOCKED. وهذا أيضا يشمل مسارات GET التي تقوم بتسجيل الدخول أو تسجيل الخروج أو إعادة الاتصال أو إعادة تعيين رابط الدعوة. العملاء مثل الكول الذين لا يرسلون ترويسات منشأ المتصفح لا يزالون يعملون.
لا يُوثَق أبدًا بالأصل null. قدّم gowa-ui.html عبر HTTP أو HTTPS بدلًا من فتحه بعنوان URL من نوع file://. عند العمل خلف وكيل عكسي، حافظ على Host، أو اضبط الوكلاء الموثوقين مع X-Forwarded-Host، أو أدرج الأصل العام في APP_TRUSTED_ORIGINS.
إقران واتساب
كل حساب في WhatsApp يعيش في فتحة الجهاز. قم بإنشاء الفتحة أولاً، ثم إقرانها. المسارات تحت/devices/{device_id} تأخذ الجهاز من المسار. المسارات المعادلة /app/* تستخدم رأس X-Device-Id.
QR code
qr_link و قم بفحصه من الهاتف: إعدادات → الأجهزة المرتبطة → رابط الجهاز. طلب رمز جديد بعد qr_duration ثواني. لوحة التحكم في / تظهر QR مباشرة وتحدث مباشرة عبر WebSocket.
Pairing code
results.pair_code، وهو رمز من 8 محارف. على الهاتف، اختر الربط برقم الهاتف بدلًا من ذلك وأدخله. يجب أن يكون phone رقم الحساب المراد ربطه، مع رمز البلد.
كلمة المرور
إذا طلب الهاتف التحقق من مفتاح المرور أثناء تسجيل الدخول QR ، تقوم GOWA بتخزين تحدي WebAuthn وبثPASSKEY_REQUEST على WebSocket. لوحة التحكم تتعامل مع هذا التدفق. لقيادته بنفسك:
GET /app/passkeyيرجع التحدي المعلق.- يقدم
POST /app/passkey/responseتأكيد WebAuthn (تنسيقPublicKeyCredential.toJSON(). - انتظر
PASSKEY_CONFIRMATION. عندما يكونresult.skip_handoff_uxصحيحاً، فإن تدفق QR النشط يرسل التأكيد تلقائياً. وإلا قارنresult.codeمع التعليمات البرمجية على الهاتف، ثم اتصل بـPOST /app/passkey/confirm.
X-Device-Id على المكالمات الثلاث.
تحقق من النتيجة
results.is_connected و results.is_logged_in كلاهما true بمجرد ربط الحساب. تستمر الجلسات في storages/، لذلك لا تتطلب إعادة التشغيل الاقتران مرة أخرى.
تسجيل الخروج والإزالة
يتم تسجيل خروج حساب غير مرتبط من الهاتف (الأجهزة المرتبطة > تسجيل الخروج) بنفس الطريقة: تبقى الخانة وتحتاج إلى الاقتران مرة أخرى.
قائمة التحقق من الأمان
- تعيين
APP_BASIC_AUTHدائماً مع كلمات مرور قوية على أي شيء يمكن الوصول إليه من شبكة. - إنهاء TLS في وكيل عكسي؛ أوراق اعتماد Auth الأساسية هي فقط أساس 64-مرمز.
- تقييد
APP_CORS_ALLOWED_ORIGINSعند اتصال واجهة المستخدم في المتصفح بـ API. - أنشئ قيمة ثابتة لـ
WHATSAPP_WEBHOOK_SECRETباستخدامopenssl rand -hex 32. تُستبدل القيم الفارغة أو القيم السرية المنشورة ضمن الأمثلة بمفتاح عشوائي خاص بكل عملية يتغير عند إعادة التشغيل. - تعامل مع
storages/باعتباره مجلدًا حساسًا. فهو يحتوي على مفاتيح جلسات جميع الحسابات المرتبطة. تستخدم ملفات SQLite الجديدة أذونات تقتصر على المالك، وتستخدم المجلدات المُنشأة لها الأذونات0700. احمِ النسخ الاحتياطية بالعناية نفسها.
