# Multi-tenancy & isolation

Synapse est multi-tenant : plusieurs utilisateurs, chacun avec plusieurs minds,
entièrement isolés les uns des autres. Cette page explique le modèle d'isolation.

## Hiérarchie des tenants

```
Instance Synapse
  │
  ├── Compte utilisateur 1 (email : alice@example.com)
  │   ├── Mind A (Mind Key mk_aaa...)
  │   │   ├── Memories (accessibles uniquement via mk_aaa...)
  │   │   ├── Tasks
  │   │   └── Chat
  │   └── Mind B (Mind Key mk_bbb...)
  │       └── ... (isolé du Mind A)
  │
  ├── Compte utilisateur 2 (email : bob@example.com)
  │   └── Mind C (Mind Key mk_ccc...)
  │       └── ... (isolé des minds d'Alice)
  │
  └── ... (plus d'utilisateurs)
```

## Niveaux d'isolation

### Niveau 1 : isolation utilisateur

Chaque compte utilisateur est isolé. Alice ne peut pas :

- Voir les minds de Bob
- Accéder aux mémoires de Bob (même avec son JWT)
- Lister les infos de compte de Bob

Appliqué par : colonne `user_id` sur toutes les tables, le JWT contient `user_id`,
toutes les requêtes filtrent par `user_id`.

### Niveau 2 : isolation de mind

Au sein d'un utilisateur, chaque mind est isolé. Le Mind A ne peut pas :

- Voir les mémoires du Mind B
- Accéder aux tâches, chat, scripts du Mind B

Appliqué par : colonne `mind_id` sur toutes les tables de données, la Mind Key
contient `mind_id`, toutes les requêtes filtrent par `mind_id`.

> [!CRITICAL]
> L'isolation par Mind Key est la frontière de sécurité principale. Une Mind Key
> fuite accordant un accès complet aux données de ce mind — mais UNIQUEMENT ce mind.

## Jetons d'authentification

| Jeton | Portée | Ce à quoi il peut accéder |
|-------|-------|-------------------|
| Mind Key | Un seul mind | Données de ce mind uniquement |
| JWT | Compte utilisateur | Gestion de compte (créer/lister/supprimer des minds) |
| Computer Token | Un seul ordinateur | Commandes de cet ordinateur |

## Accès inter-minds

### Au sein du même utilisateur

L'utilisateur peut accéder à tous ses minds via JWT (ex. `GET /minds` les liste tous).
Mais pour lire/écrire des données mémoire, il a besoin de la Mind Key spécifique.

### Entre utilisateurs

Les utilisateurs ne peuvent pas accéder aux données des autres — SAUF s'ils partagent
explicitement un mind via l'API Sharing :

```bash
# Alice partage le Mind A avec 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"}'
```

Après le partage, Bob peut accéder au Mind A via son JWT (en lecture seule si
`role=read`).

## Frontières de sécurité

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

## Schémas multi-tenant courants

### Schéma 1 : utilisateur unique, mind unique

Le plus courant pour les utilisateurs individuels d'agents LLM.

- 1 compte utilisateur
- 1 mind
- 1 Mind Key
- Toutes les mémoires dans un seul scope

### Schéma 2 : utilisateur unique, plusieurs minds

Pour les utilisateurs avec plusieurs contextes (travail, personnel, projets).

- 1 compte utilisateur
- N minds (ex. « work », « personal », « project-x »)
- N Mind Keys
- Chaque session LLM utilise une Mind Key

### Schéma 3 : mind partagé en équipe

Pour les équipes collaborant sur un projet.

- 1 utilisateur crée le mind (obtient la Mind Key)
- Le créateur partage avec les membres de l'équipe via JWT
- Tous les membres y accèdent via JWT (ou Mind Key partagée)

> [!WARNING]
> Partager une Mind Key donne un accès complet en lecture/écriture. Pour la
> collaboration en équipe, préférez l'API Sharing (basée JWT) au partage direct de
> Mind Keys.

### Schéma 4 : fournisseur SaaS

Pour les applications qui intègrent Synapse comme couche mémoire.

- Chaque client = 1 compte utilisateur
- Chaque projet client = 1 mind
- L'application stocke les Mind Keys par client/projet
- Isolation complète entre clients

## Vérification de l'isolation

### Test : une Mind Key ne peut pas accéder à d'autres minds

```bash
# La clé du Mind A ne peut pas lire les mémoires du Mind B
curl -H "Authorization: Bearer mk_aaa..." \
     "https://synapse.schaefer.zone/memory/search?q=test"
# Renvoie uniquement les mémoires du Mind A

curl -H "Authorization: Bearer mk_bbb..." \
     "https://synapse.schaefer.zone/memory/search?q=test"
# Renvoie uniquement les mémoires du Mind B (résultats différents)
```

### Test : un JWT ne peut pas lire directement les données de mémoire

```bash
# Le JWT peut lister les minds
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds
# Renvoie : liste des minds

# Le JWT NE PEUT PAS lire les mémoires (besoin d'une Mind Key)
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/memory/recall
# Renvoie : 401 Unauthorized
```

## Bonnes pratiques

> [!TIP]
> - **Utilisez un mind par projet/contexte** — l'isolation est votre amie
> - **Ne partagez jamais de Mind Keys** — utilisez l'API Sharing à la place
> - **Pivotez les Mind Keys** si compromises (supprimer le mind, en créer un nouveau)
> - **Auditez les minds partagés** — passez en revue `GET /sharing` périodiquement
> - **Utilisez le JWT pour l'interface humaine** — n'exposez jamais les Mind Keys aux utilisateurs finaux

## Prochaines étapes

- [Authentification](/docs/getting-started/authentication)
- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt)
- [Architecture](/docs/concepts/architecture)