# المصادقة و Mind Keys

يستخدم Synapse طريقتين للمصادقة، كلٌّ مُحسّنة لحالة استخدام مختلفة.
فهم الفرق أساسي لبناء تكاملات موثوقة.

## طريقتان للمصادقة

| الطريقة | حالة الاستخدام | حد المعدل | الانتهاء |
|--------|----------|------------|--------|
| **Mind Key** | وكلاء LLM، الأدوات المؤتمتة | لا شيء (ترويسة) / 60 دقيقة (استعلام) | أبدًا |
| **JWT** | واجهة الإنسان، عمليات الحساب | لا شيء | 7 أيام |

## Mind Key (للوكلاء)

Mind Key رمز API محدود بمستأجر. يُصادق بيانات عقل واحد
(الذكريات، المهام، الدردشة، السكربتات، إلخ). استخدمه لـ:

- وكلاء LLM الذين يستدعون الـ API
- سكربتات الأتمتة الخلفية
- إعداد خادم MCP
- أي تكامل طويل الأمد

### مصادقة الترويسة (موصى بها)

```bash
curl -H "Authorization: Bearer mk_yourMindKeyHere" \
     https://synapse.schaefer.zone/memory/recall
```

### معامل الاستعلام (للأدوات التي تفتح عناوين URL فقط)

```bash
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
```

> [!WARNING]
> معامل الاستعلام `?key=` محدود بـ **60 طلبًا في الدقيقة**.
> ترويسة Bearer بلا حد معدل. استخدم الترويسة كلما دعم عميلك
> الترويسات المخصصة.

### إنشاء Mind Key

```bash
curl -X POST https://synapse.schaefer.zone/minds \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Work Mind", "description": "Project memories"}'
```

تتضمن الاستجابة `mind_key` — **احفظه فورًا**، يُعرض مرة واحدة فقط.

### سرد عقلك

```bash
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds
```

### حذف عقل (لا يمكن التراجع!)

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds/m_xyz789
```

## JWT (للبشر)

تُصادق JWTs **حساب المستخدم**، لا عقلًا محددًا. استخدمها لـ:

- تسجيل الحساب والدخول
- إنشاء / سرد / حذف العقول
- مشاركة العقول مع مستخدمين آخرين
- إدارة اشتراك Web Push

### تسجيل

```bash
curl -X POST https://synapse.schaefer.zone/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

يُرجع: `{ "jwt": "eyJ...", "user": {...} }`

### تسجيل الدخول

```bash
curl -X POST https://synapse.schaefer.zone/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

يُرجع: `{ "jwt": "eyJ...", "user": {...} }`

### انتهاء JWT

تنتهي JWTs بعد **7 أيام**. عند انتهاء JWT، استدعِ `/login` مرة أخرى للحصول
على واحد جديد. لا تنتهي Mind Key أبدًا، لذا تستمر تكاملات الوكلاء
بالعمل.

## أفضل ممارسات الأمان

> [!CRITICAL]
> - **لا تلتزم Mind Keys في git أبدًا.** استخدم متغيرات البيئة.
> - **لا تسجّل Mind Keys أبدًا.** قنّعها في السجلات (`mk_***...***xyz`).
> - **دوّر المفاتيح** إذا اشتبهت في تسريب (احذف العقل، أنشئ واحدًا جديدًا).
> - **استخدم عقلًا واحدًا لكل مشروع** لتحديد دائرة الضرر إذا تسرب مفتاح.

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

```bash
# .env (لا تلتزم هذا الملف أبدًا)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone
```

```typescript
// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});
```

### إعداد خادم MCP

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}
```

## نمط العقول المتعددة

يستطيع كل مستخدم امتلاك عقول متعددة. أنماط شائعة:

| اسم العقل | الغرض |
|-----------|---------|
| `work` | ذكريات العمل |
| `personal` | التفضيلات الشخصية، العائلة |
| `project-synapse` | سياق مشروع محدد |
| `learning-german` | تقدّم التعلم |
| `assistant-default` | بديل للأغراض العامة |

استخدم Mind Keys مختلفة لجلسات LLM مختلفة للحفاظ على عزل السياقات.

## حدود المعدل

| طريقة المصادقة | الحد | النطاق |
|-------------|-------|-------|
| Mind Key (ترويسة) | لا شيء | لكل عقل |
| Mind Key (?key=) | 60/دقيقة | لكل IP |
| JWT (ترويسة) | لا شيء | لكل مستخدم |
| نقاط النهاية العامة | لا شيء | عام |

تُتضمن ترويسات حد المعدل (`X-RateLimit-Limit`، `X-RateLimit-Remaining`، `Retry-After`)
في الاستجابات عند الاقتضاء.

## الخطوات التالية

- [Mind Key مقابل JWT](/docs/getting-started/mind-key-vs-jwt) — متى تستخدم أيًّا منهما
- [Memory API](/docs/api/memory) — ما تستطيع فعله بـ Mind Key
- [User API](/docs/api/user) — إدارة الحساب بـ JWTs