الأمان وسياسة CSP

قائمة السماح بالأصول#

يفشل التضمين افتراضيًا (إغلاق عند الفشل) ما لم يكن التضمين مفعَّلًا وكان أصل الصفحة الأم في المتصفح مسموحًا به تمامًا. الأصل (origin) هو scheme://hostname[:port]؛ أما المسارات وسلاسل الاستعلام فليست جزءًا منه.

أضف أصول الإنتاج والمعاينة والتطوير المحلي كلًّا على حدة. لا تضف حرفًا بديلًا (wildcard) لحل خطأ في التثبيت: فبخلاف ذلك يمكن لأي شخص ينسخ المعرّف العام (slug) أن يضمّن الوكيل ويستهلك الرصيد (Credits) الخاص بالموقع.

سياسة أمان المحتوى (CSP)#

يحتاج المحمِّل (loader) إلى إذن للسكربت، وتحتاج أداة الدردشة إلى إذن للإطار، وقد يحتاج طلب المظهر الذي يرسله المحمِّل إلى إذن للاتصال. ادمج هذه المصادر في التوجيهات الحالية لدى الموقع المضيف، ولا تستبدل سياسة مكتملة بهذا المثال المختصر.

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;

إذا كان الموقع يستخدم script-src-elem، فأضف https://makeagent.fast إليه أيضًا. لا يتطلب المحمِّل الخارجي unsafe-inline، لكن إطار العمل الخاص بالموقع المضيف قد تكون له متطلبات مستقلة تخص nonce أو التجزئة (hash). تفيد سياسة «الإبلاغ فقط» (report-only) أثناء الاختبار:

Content-Security-Policy-Report-Only:
  script-src 'self' https://makeagent.fast;
  frame-src https://makeagent.fast;
  connect-src 'self' https://makeagent.fast;

عندما تُبلغ وحدة تحكم المتصفح عن انتهاك لسياسة CSP، عدّل التوجيه المذكور تحديدًا، لا default-src بشكل واسع، ثم أعد اختبار الصفحة العامة.

الميكروفون وأذونات المتصفح#

ينشئ المحمِّل الإطار (iframe) بالسمة allow="microphone; autoplay; clipboard-write". ومع ذلك قد تتجاوز سياسة أذونات (Permissions Policy) أكثر صرامة على مستوى الموقع المضيف هذا الإذن. إذا كان الصوت مفعَّلًا، فاسمح بأصل إطار Make Agent Fast في استجابة الموقع المضيف:

Permissions-Policy: microphone=(self "https://makeagent.fast")

يجب أيضًا أن يمنح الزائر إذن الوصول إلى الميكروفون في المتصفح. اختبر عبر HTTPS؛ إذ تقيّد المتصفحات عادةً الوصول إلى الميكروفون على الأصول العامة غير الآمنة. أما الدردشة النصية فلا تتطلب إذن الميكروفون.

حدود الرسائل والإطار#

يقبل المحمِّل فقط الرسائل maf:ready وmaf:open وmaf:close ورسائل دورة حياة السمة المرتبطة بمعرّف الموقع (slug) الحالي. ويجري التحقق من رسائل الإطار الواردة مقابل https://makeagent.fast. لا تنسخ المحمِّل إلى حزمتك الخاصة ولا تزل التحقق من الأصل هذا.

يجب ألا يحاول الكود في الصفحة المضيفة الوصول إلى DOM الخاص بالإطار. فالإطار عابر للأصول (cross-origin) بالتصميم، وسطح التكامل المدعوم هو المحمِّل وسمات data-* الموثقة له وطرق تعريف الهوية الموضحة أدناه.

الأسرار وهوية الزائر#

معرّف الموقع (slug) ورابط المحمِّل عامّان. أما كل ما عدا ذلك فيجب إبقاؤه خارج مصدر الصفحة:

• لا تضف أبدًا مفتاح MAF API أو رمز OAuth أو مفتاح مزوّد الذكاء الاصطناعي أو رمز موصِّل (Connector) أو سرّ webhook إلى المقتطف.
• لا تضمّن أي سرّ داخل حزمة JavaScript ولا تكشفه عبر NEXT_PUBLIC_* أو VITE_* أو متغيرات بيئة المتصفح المشابهة.
• استخدم تكاملًا مع API من جهة الخادم عندما يحتاج تطبيقك إلى إنشاء مواقع أو تحديث وكلاء أو جلب بيانات مساحة العمل الخاصة.
• لا تضع عناوين البريد الإلكتروني أو معرّفات الحسابات أو أي بيانات أخرى عن الزائر في data-label أو data-locale أو معلمات الاستعلام.

تعريف العملاء المسجَّلين دخولهم#

في الوكيل ← الإجراءات ← العملاء المسجَّلون دخولهم، أنشئ سرًّا وانسخه عند ظهوره. احفظه على خادمك فقط باسم MAF_SECRET_KEY؛ ولا تضعه أبدًا في كود المتصفح أو متغيرات البيئة العامة أو المستودع. هذا السر الخاص بالوكيل منفصل عن مفتاح API الخاص بمساحة العمل. يؤدي تدويره إلى إبطال الرموز القديمة ويغيّر مفتاح التوقيع الخاص بـعمليات البحث (Lookups)؛ أما حذفه فيعطّل هوية العميل الموثّقة وعمليات البحث إلى أن يُهيَّأ سر جديد.

استخدم رابط المحمِّل المحدَّث https://makeagent.fast/embed.js?v=20261022-open في المقتطف الحالي لديك. قد تبقى الروابط القديمة ذات الإصدارات مخزَّنة مؤقتًا لمدة عام ولا توفّر هذا الـSDK. حافظ على قائمة السماح بالأصول وعلى حمايات CSP.

ينبغي لخادمك الموثَّق إصدار الرمز اعتمادًا على العميل من جلسته الخاصة. لا تقبل أبدًا معرّف عميل عشوائيًا قادمًا من المتصفح ليكون الهوية التي تُوقَّع. تعمل هذه الدالة المساعدة على الخادم فقط:

import { createHmac } from "node:crypto";

export function signCustomerIdentity(customer) {
  const secret = process.env.MAF_SECRET_KEY;
  if (!secret) throw new Error("MAF_SECRET_KEY is required");
  const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
  const now = Math.floor(Date.now() / 1000);
  const header = encode({ alg: "HS256", typ: "JWT" });
  const payload = encode({
    sub: customer.id,
    email: customer.email,
    name: customer.name,
    iat: now,
    exp: now + 3600,
  });
  const body = `${header}.${payload}`;
  const signature = createHmac("sha256", secret).update(body).digest("base64url");
  return `${body}.${signature}`;
}

يجب أن يتضمن الترويس alg: "HS256" وtyp: "JWT". والحقل sub سلسلة نصية ثابتة غير فارغة بطول لا يتجاوز 128 حرفًا؛ وexp طابع زمني Unix صحيح بالثواني، في المستقبل وبما لا يتجاوز 24 ساعة من الآن. أما iat الاختياري فيجب أن يكون عددًا صحيحًا؛ وemail الاختياري يجب أن يكون صالحًا وبطول لا يتجاوز 160 حرفًا؛ وname الاختياري بطول لا يتجاوز 120 حرفًا. ويجب أن يتسع الرمز الكامل ضمن 2,048 حرفًا. احذف المطالبات الاختيارية التي لا تحتاج إليها. حمولات JWT موقَّعة وليست مشفَّرة.

أعد الرمز فقط إلى جلسة المتصفح الموثَّقة تلك عبر HTTPS، مع Cache-Control: no-store. لا تسجّله في السجلات ولا تضفه إلى الروابط ولا تخزّنه في localStorage. بعد تحميل embed.js، مرّر رمز الاستجابة هذا إلى الأداة:

window.MakeAgentFast.identify(token);

للتهيئة قبل تشغيل المحمِّل، اضبط window.MakeAgentFastSettings = { identityToken: token } في مرحلة إقلاع تطبيقك بدلًا من ذلك. يحتفظ المحمِّل بأحدث رمز في الذاكرة ويمرّره عندما يكون الإطار جاهزًا. جدّد الرمز من خادمك الموثَّق قبل انتهاء صلاحيته واستدعِ identify مرة أخرى. يتضمنه كل طلب دردشة؛ وتستخدم طلبات المحادثة الترويس x-maf-identity. ولا تعتمد هوية المضيف الموثّقة أبدًا على ملف تعريف الارتباط af_xid.

عند تسجيل الخروج من تطبيقك، استدعِ ما يلي قبل عرض دردشة حساب آخر، وامسح أي رمز إقلاع احتفظ به تطبيقك:

window.MakeAgentFast.logout();

يعيد هذا ضبط هوية الأداة وذاكرة المحادثات المحلية المؤقتة؛ لكنه لا يسجّل خروج العميل من تطبيقك ولا يلغي رمزًا جرى نسخه. كما أن sub لعميل مختلف يمسح ذاكرة الأداة المؤقتة أيضًا. لا يمكن للرموز غير الصالحة أو المنتهية أو الخاصة بوكيل آخر الوصول إلى سجل ذلك العميل المسجَّل دخوله، وتعود إلى مسار الزائر العادي. استخدم مدد صلاحية قصيرة وأبقِ سر كل وكيل منفصلًا. تتجاهل تجربة المالك (Owner rehearsal) رموز الهوية؛ لذا تحقق من العزل على التضمين الفعلي باستخدام حسابَي اختبار منفصلَين.

الموافقة والخصوصية والاحتفاظ بالبيانات#

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

أخبر الزوار عندما تستخدم التجربة الذكاء الاصطناعي أو تسجيل الميكروفون أو التقاط بيانات العملاء المحتملين (Leads) أو التحليلات أو مزوّد مراسلة خارجيًا، وفق ما تقتضيه سياستك والقانون المعمول به. تأكد من سير عمل الاحتفاظ بالمحادثات وحذفها في موقعك قبل الإطلاق؛ فقطع الاتصال أو إزالة التضمين لا يحذف المحادثات الموجودة بحد ذاته.

قائمة التحقق الأمنية قبل الإطلاق#

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