# Мультитенантність та ізоляція

Synapse є мультитенантним: кілька користувачів, кожен із кількома mind-ами, повністю
ізольованими один від одного. Ця сторінка пояснює модель ізоляції.

## Ієрархія тенантів

```
Synapse Instance
  │
  ├── User Account 1 (email: alice@example.com)
  │   ├── Mind A (Mind Key mk_aaa...)
  │   │   ├── Memories (only accessible via mk_aaa...)
  │   │   ├── Tasks
  │   │   └── Chat
  │   └── Mind B (Mind Key mk_bbb...)
  │       └── ... (isolated from Mind A)
  │
  ├── User Account 2 (email: bob@example.com)
  │   └── Mind C (Mind Key mk_ccc...)
  │       └── ... (isolated from Alice's minds)
  │
  └── ... (more users)
```

## Рівні ізоляції

### Рівень 1: Ізоляція користувачів

Кожен обліковий запис користувача ізольований. Аліса не може:

- Бачити mind-и Боба
- Доступатися до спогадів Боба (навіть зі своїм JWT)
- Переглядати інформацію про обліковий запис Боба

Забезпечено: колонка `user_id` у всіх таблицях, JWT містить `user_id`, усі
запити фільтруються за `user_id`.

### Рівень 2: Ізоляція mind-ів

У межах користувача кожен mind ізольований. Mind A не може:

- Бачити спогади Mind B
- Доступатися до завдань, чату, скриптів Mind B

Забезпечено: колонка `mind_id` у всіх таблицях даних, Mind Key містить `mind_id`,
усі запити фільтруються за `mind_id`.

> [!CRITICAL]
> Ізоляція Mind Key — це основна межа безпеки. Виточений Mind Key надає повний
> доступ до даних цього mind-у — але ТІЛЬКИ цього mind-у.

## Токени автентифікації

| Токен | Область | Що може доступати |
|-------|-------|-------------------|
| Mind Key | Один mind | Лише дані цього mind-у |
| JWT | Обліковий запис користувача | Керування обліковим записом (створення/список/видалення mind-ів) |
| Computer Token | Один комп'ютер | Команди цього комп'ютера |

## Між-mind доступ

### У межах одного користувача

Користувач може доступатися до всіх своїх mind-ів через JWT (напр. `GET /minds`
виводить усі). Але для читання/запису даних пам'яті потрібен конкретний Mind Key.

### Між користувачами

Користувачі не можуть доступатися до даних одне одного — ЯКЩО тільки явно не
поділяться mind-ом через Sharing API:

```bash
# Аліса ділиться Mind A з Бобом
curl -X POST https://synapse.schaefer.zone/sharing \
  -H "Authorization: Bearer ALICE_JWT" \
  -d '{"mind_id": "m_aaa", "email": "bob@example.com", "role": "read"}'
```

Після цього Боб може доступатися до Mind A через свій JWT (лише читання, якщо
`role=read`).

## Межі безпеки

```
┌─────────────────────────────────────────────────┐
│              Synapse Instance                    │
│  ┌─────────────────────────────────────────┐    │
│  │         User Account Boundary           │    │
│  │  ┌──────────────┐  ┌──────────────┐    │    │
│  │  │  Mind Bound. │  │  Mind Bound. │    │    │
│  │  │  (Mind Key)  │  │  (Mind Key)  │    │    │
│  │  │              │  │              │    │    │
│  │  │  Memories    │  │  Memories    │    │    │
│  │  │  Tasks       │  │  Tasks       │    │    │
│  │  │  Chat        │  │  Chat        │    │    │
│  │  │  Scripts     │  │  Scripts     │    │    │
│  │  └──────────────┘  └──────────────┘    │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘
```

## Типові шаблони мультитенантності

### Шаблон 1: Один користувач, один mind

Найпоширеніший для індивідуальних користувачів LLM-агентів.

- 1 обліковий запис користувача
- 1 mind
- 1 Mind Key
- Усі спогади в одній області

### Шаблон 2: Один користувач, кілька mind-ів

Для користувачів із кількома контекстами (робота, особисте, проєкти).

- 1 обліковий запис користувача
- N mind-ів (напр. «work», «personal», «project-x»)
- N Mind Keys
- Кожна сесія LLM використовує один Mind Key

### Шаблон 3: Командний спільний mind

Для команд, що співпрацюють над проєктом.

- 1 користувач створює mind (отримує Mind Key)
- Творець ділиться з членами команди через JWT
- Усі члени команди доступаються через JWT (або спільний Mind Key)

> [!WARNING]
> Поширення Mind Key дає повний доступ на читання/запис. Для командної
> співпраці віддавайте перевагу Sharing API (на основі JWT), а не прямому
> поширенню Mind Keys.

### Шаблон 4: SaaS-провайдер

Для додатків, що вбудовують Synapse як шар пам'яті.

- Кожен клієнт = 1 обліковий запис користувача
- Кожен проєкт клієнта = 1 mind
- Додаток зберігає Mind Keys для кожного клієнта/проєкту
- Повна ізоляція між клієнтами

## Перевірка ізоляції

### Тест: Mind Key не може доступатися до інших mind-ів

```bash
# Ключ Mind A не може читати спогади Mind B
curl -H "Authorization: Bearer mk_aaa..." \
     "https://synapse.schaefer.zone/memory/search?q=test"
# Returns only Mind A's memories

curl -H "Authorization: Bearer mk_bbb..." \
     "https://synapse.schaefer.zone/memory/search?q=test"
# Returns only Mind B's memories (different results)
```

### Тест: JWT не може читати дані пам'яті напряму

```bash
# JWT може вивести список mind-ів
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds
# Returns: list of minds

# JWT НЕ МОЖЕ читати спогади (потрібен Mind Key)
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/memory/recall
# Returns: 401 Unauthorized
```

## Найкращі практики

> [!TIP]
> - **Один mind на проєкт/контекст** — ізоляція — ваш друг
> - **Ніколи не поширюйте Mind Keys** — використовуйте Sharing API
> - **Ротуйте Mind Keys** у разі компрометації (видаліть mind, створіть новий)
> - **Аудитуйте спільні mind-и** — періодично переглядайте `GET /sharing`
> - **Використовуйте JWT для людського UI** — ніколи не викривайте Mind Keys кінцевим користувачам

## Наступні кроки

- [Автентифікація](/docs/getting-started/authentication)
- [Mind Key проти JWT](/docs/getting-started/mind-key-vs-jwt)
- [Архітектура](/docs/concepts/architecture)