# بيانات الاعتماد والبيئة

> كيف يقرأ mailctl رموز المزوّدين، وأين تذهب بيانات اعتماد صناديق البريد المولّدة.

يعامل mailctl بيانات الاعتماد على أنها أخطر ما يتعامل معه. قاعدتان تشكّلان التصميم:

1.  **لا يُكتب أي شيء حساس على الإخراج القياسي أبدًا.** لا رمز API، ولا رمز وصول، ولا كلمة سر صندوق بريد. تذهب بيانات اعتماد صناديق البريد المولّدة إلى سلسلة مفاتيح macOS، أو إلى ملف بصلاحيات `0600`، أو إلى الخطأ القياسي، ولا مكان غير ذلك. فكلمة السر على الإخراج القياسي تنتهي في أنبوب أو سجل أو تاريخ الطرفية.
    
2.  **لا يُخزَّن أي شيء حساس في ملف الإعداد.** يذكر الإعداد **اسم متغير بيئة**؛ ويقرأ mailctl القيمة من البيئة، أو من سلسلة المفاتيح، لحظة الحاجة إليها.
    

## سلسلة مفاتيح macOS

كل متغير أدناه، وكل `passwordEnv` لصندوق بريد، يُقرأ من البيئة أولًا، ثم من سلسلة مفاتيح تسجيل الدخول: الخدمة `mailctl`، والحساب هو اسم المتغير. الرمز المحفوظ هناك لا يبقى أبدًا في ملف إعداد الصدفة، ويجده خادم MCP دونه.

```console
$ security add-generic-password -U -s mailctl -a CLOUDFLARE_API_TOKEN -w
$ security add-generic-password -U -s mailctl -a PURELYMAIL_API_TOKEN -w
```

حين يأتي `-w` أخيرًا بلا قيمة، يطلب `security` القيمة، فلا تصل أبدًا إلى تاريخ الصدفة. يُظهر `mailctl doctor` مصدر كل بيانات اعتماد: `env` أو `keychain`.

تذهب بيانات الاعتماد المولّدة إلى سلسلة المفاتيح أيضًا، تحت الخدمة نفسها: الحساب هو عنوان صندوق البريد، أو `address (app name)` لبيانات اعتماد تطبيق.

```console
$ security find-generic-password -s mailctl -a contact@example.com -w
$ security find-generic-password -s mailctl -a "contact@example.com (app phone)" -w
```

يكتبها `-secrets-out` في ملف بدلًا من ذلك، وهذا يناسب CI وLinux. ودون سلسلة مفاتيح ودون `-secrets-out`، يُبلَّغ عنها على الخطأ القياسي. وتحت `mailctl mcp`، حيث يذهب الخطأ القياسي إلى الوكيل، تذهب إلى ملف بصلاحيات `0600` تحت `$XDG_STATE_HOME/mailctl` بدلًا من ذلك.

## متغيرات البيئة

  
| المتغير | مطلوب | الغرض |
| --- | --- | --- |
| 
`CLOUDFLARE_API_TOKEN`

 | 

دائمًا

 | 

صلاحية تعديل DNS على المناطق التي تديرها. ويُستخدم أيضًا لـ Email Routing وEmail Sending ونشر Worker حيث تكون مُعَدّة.

 |
| 

`CLOUDFLARE_ACCOUNT_ID`

 | 

غالبًا

 | 

يُشار إليه في الإعداد بـ `${CLOUDFLARE_ACCOUNT_ID}`. تحتاجه واجهات Cloudflare المرتبطة بالحساب.

 |
| 

`PURELYMAIL_API_TOKEN`

 | 

نطاقات purelymail

 | 

الوصول إلى واجهة Purelymail.

 |
| 

`MS365_TENANT_ID`

 | 

نطاقات ms365

 | 

معرّف مستأجر Microsoft Entra.

 |
| 

`MS365_CLIENT_ID`

 | 

نطاقات ms365

 | 

معرّف العميل للتطبيق المسجَّل.

 |
| 

`MS365_CLIENT_SECRET`

 | 

نطاقات ms365

 | 

سر العميل للتطبيق.

 |

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

## تحديد نطاق رمز Cloudflare

امنح الرمز صلاحية تعديل DNS على المناطق المحددة التي يديرها mailctl، لا على كل مناطق الحساب. رمز الكتابة على DNS للحساب كله مريح أثناء الإعداد، وعبء بعده.

## بيانات اعتماد صناديق البريد

يمكن لمدخل صندوق البريد أن يذكر متغير بيئة:

```yaml
mailboxes:
  - address: contact@example.com
    passwordEnv: CONTACT_PASSWORD
```

أو أن يحذفه، وحينها يولّد mailctl واحدًا:

```yaml
mailboxes:
  - address: contact@example.com
```

القيمة المولّدة 24 حرفًا من مصدر عشوائي تشفيري، أي نحو 150 بتًا من الإنتروبيا. ولا تُنتَج إلا حين يضطر mailctl فعلًا إلى إنشاء ذلك الصندوق؛ فلا يُعطى صندوق قائم قيمة جديدة بالخطأ أبدًا.

### يُبلَّغ عنها مرة واحدة فقط

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

```console
$ mailctl apply -secrets-out new-mailboxes.txt
...
Wrote 1 generated credential(s) to new-mailboxes.txt
```

إن فشل التشغيل في منتصفه، لا يُبلَّغ إلا عن قيم الصناديق التي أُنشئت فعلًا. وهذا هو العدد الذي يمكنك الاعتماد عليه.

### ملف المخرجات

يُنشأ بصلاحيات `0600` بإنشاء حصري، فيُرفض المسار الموجود بدل الكتابة فوقه. وإن فشلت الكتابة لأي سبب، يُبلَّغ عن القيم على الخطأ القياسي بدلًا من ذلك؛ فخسارة بيانات اعتماد حية بصمت ليست طريقة فشل مقبولة.

### بعد التسليم

استخرج القيم، واحفظها في مدير كلمات السر، واحذف الملف. وحيث يدعم المزوّد ذلك، يَسِم mailctl كلمة السر المولّدة بأنها يجب أن تُغيَّر عند أول تسجيل دخول، فينتهي المستلم بشيء لم يره أحد غيره.

## إبقاء الملف خارج git

أضف قاعدة التجاهل قبل إنشاء الملف، لا بعده:

```console
$ printf '*.secrets\n' >> .gitignore
```

لا يقرأ mailctl بيانات الاعتماد من ملف الإعداد أبدًا، فالإعداد نفسه آمن للإيداع، لكن افحصه بحثًا عن عناوين حقيقية قبل نشره في أي مكان.