# Multi-tenancy и изоляция

Synapse — multi-tenant-система: несколько пользователей, у каждого — несколько
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: изоляция пользователей

Каждый аккаунт пользователя изолирован. Alice не может:

- Видеть mind пользователя Bob
- Получать доступ к воспоминаниям Bob (даже со своим JWT)
- Просматривать данные аккаунта Bob

Обеспечивается: колонкой `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
# Alice shares Mind A with Bob
curl -X POST https://synapse.schaefer.zone/sharing \
  -H "Authorization: Bearer ALICE_JWT" \
  -d '{"mind_id": "m_aaa", "email": "bob@example.com", "role": "read"}'
```

После этого Bob может получить доступ к 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     │    │    │
│  │  └──────────────┘  └──────────────┘    │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘
```

## Типовые паттерны multi-tenancy

### Паттерн 1: один пользователь, один mind

Наиболее распространён у индивидуальных пользователей LLM-агентов.

- 1 аккаунт пользователя
- 1 mind
- 1 Mind Key
- Все воспоминания в одной области

### Паттерн 2: один пользователь, несколько mind

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

- 1 аккаунт пользователя
- N mind (например, «work», «personal», «project-x»)
- N Mind Key
- Каждая LLM-сессия использует один Mind Key

### Паттерн 3: командный общий mind

Для команд, сотрудничающих над проектом.

- 1 пользователь создаёт mind (получает Mind Key)
- Создатель делится с участниками команды через JWT
- Все участники получают доступ через JWT (или общий Mind Key)

> [!WARNING]
> Передача Mind Key даёт полный доступ на чтение/запись. Для командной работы
> предпочтительнее Sharing API (на основе JWT), а не прямой обмен Mind Key.

### Паттерн 4: SaaS-провайдер

Для приложений, встраивающих Synapse как слой памяти.

- Каждый клиент = 1 аккаунт пользователя
- Каждый проект клиента = 1 mind
- Приложение хранит Mind Key по каждому клиенту/проекту
- Полная изоляция между клиентами

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

### Тест: Mind Key не может получить доступ к другим mind

```bash
# Mind A's key cannot read Mind B's memories
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 can list minds
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds
# Returns: list of minds

# JWT CANNOT read memories (need Mind Key)
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/memory/recall
# Returns: 401 Unauthorized
```

## Лучшие практики

> [!TIP]
> - **Используйте один mind на проект/контекст** — изоляция вам помогает
> - **Никогда не передавайте Mind Key** — используйте Sharing API
> - **Ротируйте Mind Key** при компрометации (удалите mind, создайте новый)
> - **Аудит общих mind** — периодически проверяйте `GET /sharing`
> - **Используйте JWT для человеко-ориентированного UI** — никогда не показывайте Mind Key конечным пользователям

## Следующие шаги

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