ضوابط الأمان ونوايا الحذف في واجهة API

صُممت TrekMail API لمنع فقدان البيانات عن طريق الخطأ. تتطلب العمليات الخطرة عدة خطوات للتأكيد، وتمنع حدود المعدل الأخطاء الجماعية، ويُسجل كل إجراء.

سلة المحذوفات. يؤدي تأكيد نية حذف صندوق بريد الآن إلى نقل الصندوق إلى سلة محذوفات لمدة 7 أيام (تظهر باسم المحذوفة مؤخرا في لوحة التحكم) بدلا من إتلافه فورا. يمكنك سرد صناديق البريد المحذوفة واستعادة أحدها خلال هذه المدة:

GET  /api/v1/mailboxes?status=trashed        # list the recycle bin
POST /api/v1/mailboxes/{id}:restore          # restore to active (scope mailboxes:delete)

بعد انتهاء مدة الاحتفاظ، تحذف مهمة يومية صناديق البريد الموجودة في السلة نهائيا. تعيد الاستعادة التحقق من حد صناديق البريد لكل نطاق. يستخدم وكلاء MCP أداتي restore_mailbox وlist_trashed_mailboxes؛ أصبحت confirm_delete_intent قابلة للاسترداد وليست عملية غير قابلة للعكس. يؤدي حذف نطاق أو حساب إلى إزالة صناديق بريده نهائيا ولا يستخدم سلة المحذوفات.

الحذف بخطوتين (نوايا الحذف)

يُعد حذف صندوق بريد أو نطاق من أكثر العمليات الخطرة تأثيرا في API. وتستخدم هذه العمليات مسارا من خطوتين:

الخطوة 1: إنشاء نية حذف

POST /api/v1/mailboxes/{id}:delete-intent

ينشئ هذا الإجراء نية محدودة المدة تصف ما سيُحذف. تتضمن الاستجابة:

• علامات المخاطر: تحذيرات بشأن قواعد إعادة التوجيه أو الأسماء المستعارة أو عمليات الترحيل النشطة التي ستتأثر.
• انتهاء الصلاحية: تنتهي صلاحية النية بعد 10 دقائق. وبعد ذلك يجب إنشاء نية جديدة.
• عنوان URL للتأكيد: عنوان URL المطلوب استدعاؤه في الخطوة 2.

لا تُحذف أي بيانات في هذه المرحلة.

الخطوة 2: تأكيد النية

POST /api/v1/delete-intents/{id}:confirm
Headers: X-Confirm-Delete: true

عند تفعيل سلة صناديق البريد في TrekMail، ينقل التأكيد صندوق البريد إلى المحذوفة مؤخرا ويعيد نية مكتملة تحمل status: "executed". يمكن استعادة الصندوق خلال سبعة أيام، بشرط أن يسمح حد النطاق بذلك وقت الاستعادة.

{
  "id": 1,
  "mailbox_id": 4,
  "mailbox_email": "user@acme.test",
  "status": "executed",
  "risk_flags": [],
  "confirmed_at": "2026-05-28T11:22:08+00:00",
  "executed_at": "2026-05-28T11:22:08+00:00"
}

بعد انتهاء فترة الاسترداد، تزيل عملية التنظيف اليومية في TrekMail صندوق البريد نهائيا. استخدم قائمة سلة المحذوفات أو نقطة نهاية الاستعادة قبل ذلك. لا يستخدم حذف نطاق أو حساب مسار استرداد صناديق البريد هذا.

ترويسة X-Confirm-Delete: true مطلوبة في طلب التأكيد كفحص أمان إضافي.

علامات المخاطر

عند إنشاء نية حذف، تتحقق API من الظروف التي قد تشير إلى أنك لا تريد المتابعة:

راجع هذه العلامات قبل التأكيد. لا تمنع API التأكيد بناء على علامات المخاطر. فهي للمعلومات فقط.

حدود المعدل للعمليات الخطرة

للعمليات الخطرة مستويان إضافيان من حدود المعدل إلى جانب حد API القياسي لكل دقيقة:

• حد يومي لكل رمز: يمكن لكل رمز تأكيد عدد محدود من نوايا الحذف يوميا.
• فترة انتظار بين التأكيدات: بعد تأكيد حذف، توجد فترة انتظار قصيرة قبل قبول التأكيد التالي.

عند تفعيل أي منهما، تُعاد 429 Too Many Requests مع ترويسة Retry-After.

تحكم أمان MCP للخوادم المستضافة محليا

إذا شغلت خادم stdio MCP بنفسك، فيمكن لمسؤوله اشتراط TREKMAIL_ALLOW_DESTRUCTIVE=true قبل إتاحة أدوات الحذف. هذا تحكم أمان محلي وليس مفتاحا لإحدى ميزات منتج TrekMail. يستخدم MCP المستضاف الأذونات الموافق عليها أثناء OAuth.

تظل أدوات القراءة متاحة ضمن النطاقات الممنوحة. راجع مهمة الوكيل ونطاقاته قبل السماح بإجراءات الحذف.

عدم التكرار

توضح نقاط نهاية الكتابة التي تتطلب Idempotency-Key ذلك في جدول نقطة النهاية ومواصفات OpenAPI. استخدم مفتاحا جديدا لكل عملية منطقية قبل إعادة محاولة الطلب:

Idempotency-Key: create-mailbox-alice-2024

• يعيد المفتاح نفسه مع المحتوى نفسه الاستجابة الأصلية دون تكرار العملية.
• يعيد المفتاح نفسه مع محتوى مختلف 409 Conflict.
• تستخدم الرموز المختلفة مساحات مفاتيح مستقلة.

ينشئ خادم MCP مفاتيح عدم تكرار آمنة لإعادة المحاولة لاستدعاءات الأدوات، فلا تكرر إعادة المحاولة عملية مكتملة بالفعل.

بوابات أمان الإرسال

يملك إرسال البريد عبر خادم MCP تصميم أمان خاصا ببوابتين، يشبه بوابة العمليات الخطرة ولكنه يعتمد فحصين مستقلين:

البوابة 1: تحكم الخادم المحلي

بالنسبة إلى خادم MCP مستضاف محليا، اضبط TREKMAIL_ALLOW_SENDING=true للسماح بأداة send_message. يستخدم MCP المستضاف الأذونات الموافق عليها أثناء OAuth.

البوابة 2: التأكيد لكل استدعاء

حتى مع تفعيل بوابة البيئة، يجب أن يتضمن كل استدعاء لـ send_message المعلمة confirm_send=true. من دونها، تعيد الأداة خطأ يطلب من الوكيل التأكيد.

لماذا توجد بوابتان؟

يضبط المسؤول الذي يهيئ خادم MCP التحكم المحلي مرة واحدة. أما التحكم لكل استدعاء فيتطلب من الوكيل اتخاذ قرار نشط بإرسال كل رسالة. لا يكفي أي من التحكمين منفردا؛ يجب اجتياز كليهما قبل خروج أي رسالة من الخادم.

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

بوابات أمان الترحيل

لترحيل البريد عبر خادم MCP بوابات أمان خاصة به، تشبه بوابات الإرسال والعمليات الخطرة.

تحكم الخادم المحلي في الترحيل

بالنسبة إلى خادم MCP مستضاف محليا، اضبط TREKMAIL_ALLOW_MIGRATION=true للسماح بأدوات كتابة الترحيل (start_migration وretry_migration وdelete_migration). يستخدم MCP المستضاف الأذونات الموافق عليها أثناء OAuth.

تظل cancel_migration متاحة دائما بغض النظر عن هذا الإعداد. فهي عملية أمان يجب أن تبقى متاحة لإيقاف عملية ترحيل خارجة عن السيطرة.

تعمل أدوات الترحيل المخصصة للقراءة فقط (list_migrations وget_migration) من دون أي بوابات. تتطلب test_migration_connection القيمة TREKMAIL_ALLOW_MIGRATION=true لأنها تنشئ اتصالات IMAP صادرة.

تأكيد كل استدعاء ترحيل

تتطلب كل أداة كتابة للترحيل معلمة تأكيد:

• تتطلب start_migration القيمة confirm_start=true
• تتطلب cancel_migration القيمة confirm_cancel=true
• تتطلب retry_migration القيمة confirm_retry=true

من دون معلمة التأكيد، تعيد الأداة خطأ يطلب من الوكيل التأكيد.

حد التزامن على مستوى الخادم

تفرض API حدا عاما لعمليات الترحيل المتزامنة (الافتراضي: 20). عند بلوغ الحد، تعيد طلبات الترحيل الجديدة 503 مع migration_capacity_reached وretryable: true. يحمي ذلك موارد الخادم عند ترحيل حسابات كثيرة في الوقت نفسه.

تسجيل التدقيق

يُسجل كل إجراء API يعدّل البيانات في سجل التدقيق، الظاهر ضمن وكلاء الذكاء الاصطناعي وAPI → سجل التدقيق في لوحة التحكم. تشمل الأحداث:

• إنشاء رمز أو إلغاؤه: من أنشأ رمز عمليات أو ألغاه ومتى.
• إنشاء رمز رسائل أو إلغاؤه: من أنشأ رمز رسائل أو ألغاه.
• إنشاء نية: أُنشئت نية حذف لصندوق بريد محدد.
• تأكيد نية: قُبل طلب الحذف.
• تنفيذ حذف: نُقل صندوق البريد إلى المحذوفة مؤخرا وبدأت فترة استرداده.
• انتهاء نية: انتهت نية غير مؤكدة بعد 10 دقائق.
• إنشاء صندوق بريد: جرى توفير صندوق بريد جديد عبر API.
• إنشاء دعوة: أُرسلت دعوة لإعداد صندوق بريد.
• تحديث إعادة التوجيه: تغيرت قواعد إعادة التوجيه لصندوق بريد.
• تشغيل إعادة فحص DNS: طُلب التحقق من DNS لنطاق.
• بدء ترحيل: بدأت عملية ترحيل بريد عبر API.
• إلغاء ترحيل: أُلغيت عملية ترحيل جارية.
• إعادة محاولة ترحيل: أُعيدت محاولة عملية ترحيل فاشلة أو ملغاة.
• حذف ترحيل: حُذف سجل ترحيل.
• قراءة رسالة: سُردت رسائل أو قُرئت عبر Message API.
• إرسال رسالة: أُرسل بريد إلكتروني عبر Message API.
• فشل إرسال رسالة: فشلت محاولة إرسال بريد إلكتروني.
• تحديث علامات رسالة: تغيرت علامات الرسالة (مقروءة/غير مقروءة، مميزة بنجمة).
• حذف رسالة: حُذفت رسالة من مجلد صندوق بريد.
• نقل رسالة: نُقلت رسالة بين المجلدات.
• إنشاء نطاق: أُضيف نطاق عبر API.
• حذف نطاق: أُزيل نطاق عبر API.
• إنشاء تذكرة: فُتحت تذكرة دعم عبر API.
• الرد على تذكرة: نُشر رد في تذكرة.
• إغلاق تذكرة: أُغلقت تذكرة.
• تهيئة SMTP: حُدثت إعدادات SMTP.
• حذف اتصال SMTP: أُزيل اتصال SMTP مخصص.
• إضافة اختبار SMTP إلى قائمة الانتظار: بدأ اختبار اتصال SMTP.
• حذف رمز Cloudflare: أُزيل رمز Cloudflare مخزن عبر API.

تُسجل جميع أحداث Message API بالكامل، بما فيها القراءة والإرسال وتحديث العلامات والحذف والنقل. يُحتفظ بسجلات التدقيق لمدة 90 يوما.

يسجل كل حدث الرمز المستخدم والمورد المتأثر وعنوان IP ومعرّف الطلب.

صفّ سجل التدقيق حسب نوع الحدث أو الرمز أو نطاق التاريخ للتحقيق في نشاط معين.

إصلاحات سريعة

• انتهت النية قبل التأكيد: أنشئ نية حذف جديدة. تنتهي النوايا بعد 10 دقائق.
• "Missing confirm header": أضف الترويسة X-Confirm-Delete: true إلى طلب التأكيد.
• 429 عند تأكيد الحذف: بلغت الحد اليومي أو فترة الانتظار. انتظر المدة المحددة في Retry-After.
• يفيد وكيل MCP مستضاف ذاتيا بأن أدوات الحذف معطلة: يمكن لمسؤوله المحلي ضبط TREKMAIL_ALLOW_DESTRUCTIVE=true في بيئة عملية MCP تلك.
• يفيد وكيل MCP مستضاف ذاتيا بأن "Sending is disabled": يمكن لمسؤوله المحلي ضبط TREKMAIL_ALLOW_SENDING=true في بيئة عملية MCP تلك.
• يفيد وكيل MCP بأن "Send not confirmed": يجب على الوكيل تمرير confirm_send=true كمعلمة في كل استدعاء لـ send_message.
• يفيد وكيل MCP مستضاف ذاتيا بأن أدوات الترحيل معطلة: يمكن لمسؤوله المحلي ضبط TREKMAIL_ALLOW_MIGRATION=true في بيئة عملية MCP تلك.
• 503 "migration_capacity_reached": توجد عمليات ترحيل كثيرة قيد التشغيل على مستوى الخادم. انتظر بضع دقائق ثم حاول مجددا.
• 409 "active migration running": ألغ عملية الترحيل الحالية أو انتظر اكتمالها قبل بدء عملية جديدة.