# Multi-Tenancy & Isolation

Synapse ist Multi-Tenant: mehrere Nutzer, jeder mit mehreren Minds, vollständig
voneinander isoliert. Diese Seite erklärt das Isolationsmodell.

## Tenant-Hierarchie

```
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)
```

## Isolations-Level

### Level 1: Nutzer-Isolation

Jedes Nutzerkonto ist isoliert. Alice kann nicht:

- Bobs Minds sehen
- Auf Bobs Memories zugreifen (auch nicht mit ihrem JWT)
- Bobs Konto-Infos auflisten

Erzwungen durch: `user_id`-Spalte auf allen Tabellen, JWT enthält `user_id`,
alle Queries filtern nach `user_id`.

### Level 2: Mind-Isolation

Innerhalb eines Nutzers ist jeder Mind isoliert. Mind A kann nicht:

- Memories von Mind B sehen
- Auf Tasks, Chat, Scripts von Mind B zugreifen

Erzwungen durch: `mind_id`-Spalte auf allen Datentabellen, Mind Key enthält
`mind_id`, alle Queries filtern nach `mind_id`.

> [!CRITICAL]
> Die Mind-Key-Isolation ist die primäre Sicherheitsgrenze. Ein geleakter Mind
> Key gewährt vollen Zugriff auf die Daten dieses Minds — aber NUR auf dieses.

## Authentifizierungs-Tokens

| Token | Scope | Worauf Zugriff |
|-------|-------|----------------|
| Mind Key | Einzelner Mind | Nur Daten dieses Minds |
| JWT | Nutzerkonto | Kontoverwaltung (Minds anlegen/auflisten/löschen) |
| Computer Token | Einzelner Rechner | Commands dieses Rechners |

## Mind-übergreifender Zugriff

### Innerhalb desselben Nutzers

Nutzer können über JWT auf alle ihre Minds zugreifen (z. B. listet `GET /minds`
alle auf). Um Memory-Daten zu lesen/schreiben, benötigen sie aber den
spezifischen Mind Key.

### Nutzerübergreifend

Nutzer können nicht aufeinander Daten zugreifen — AUSSER sie teilen explizit
einen Mind via 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"}'
```

Nach dem Teilen kann Bob via JWT auf Mind A zugreifen (read-only bei
`role=read`).

## Sicherheitsgrenzen

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

## Häufige Multi-Tenancy-Patterns

### Pattern 1: Ein Nutzer, ein Mind

Am häufigsten für einzelne LLM-Agent-Nutzer.

- 1 Nutzerkonto
- 1 Mind
- 1 Mind Key
- Alle Memories in einem Scope

### Pattern 2: Ein Nutzer, mehrere Minds

Für Nutzer mit mehreren Kontexten (Arbeit, persönlich, Projekte).

- 1 Nutzerkonto
- N Minds (z. B. „work", „personal", „project-x")
- N Mind Keys
- Jede LLM-Session verwendet einen Mind Key

### Pattern 3: Team-Shared-Mind

Für Teams, die an einem Projekt zusammenarbeiten.

- 1 Nutzer legt den Mind an (erhält Mind Key)
- Ersteller teilt mit Teammitgliedern via JWT
- Alle Teammitglieder greifen via JWT (oder geteiltem Mind Key) zu

> [!WARNING]
> Das Teilen eines Mind Keys gewährt vollen Lese-/Schreibzugriff. Für
> Team-Kollaboration bevorzuge die Sharing-API (JWT-basiert) gegenüber dem
> direkten Teilen von Mind Keys.

### Pattern 4: SaaS-Provider

Für Apps, die Synapse als Memory-Layer einbetten.

- Jeder Kunde = 1 Nutzerkonto
- Jedes Kundenprojekt = 1 Mind
- App speichert Mind Keys pro Kunde/Projekt
- Volle Isolation zwischen Kunden

## Isolations-Verifikation

### Test: Mind Key kann nicht auf andere Minds zugreifen

```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)
```

### Test: JWT kann Memory-Daten nicht direkt lesen

```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
```

## Best Practices

> [!TIP]
> - **Ein Mind pro Projekt/Kontext** — Isolation ist dein Freund
> - **Mind Keys niemals teilen** — verwende stattdessen die Sharing-API
> - **Mind Keys rotieren**, falls kompromittiert (Mind löschen, neu anlegen)
> - **Geteilte Minds auditieren** — `GET /sharing` regelmäßig prüfen
> - **JWT für Human-UI verwenden** — Mind Keys nie an Endnutzer geben

## Nächste Schritte

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