# Multi-tenancy e isolamento

Synapse è multi-tenant: utenti multipli, ciascuno con menti multiple, completamente
isolati tra loro. Questa pagina spiega il modello di isolamento.

## Gerarchia dei tenant

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

## Livelli di isolamento

### Livello 1: isolamento utente

Ogni account utente è isolato. Alice non può:

- Vedere le menti di Bob
- Accedere alle memorie di Bob (nemmeno con il suo JWT)
- Elencare le informazioni dell'account di Bob

Imposto da: colonna `user_id` su tutte le tabelle, il JWT contiene `user_id`,
tutte le query filtrano per `user_id`.

### Livello 2: isolamento mente

All'interno di un utente, ogni mente è isolata. La Mente A non può:

- Vedere le memorie della Mente B
- Accedere alle attività, chat, script della Mente B

Imposto da: colonna `mind_id` su tutte le tabelle dati, la Mind Key contiene
`mind_id`, tutte le query filtrano per `mind_id`.

> [!CRITICAL]
> L'isolamento tramite Mind Key è il confine di sicurezza primario. Una Mind Key
> leakata concede pieno accesso ai dati di quella mente — ma SOLO a quella mente.

## Token di autenticazione

| Token | Ambito | Cosa può accedere |
|-------|-------|-------------------|
| Mind Key | Singola mente | Solo i dati di quella mente |
| JWT | Account utente | Gestione account (crea/elenca/elimina menti) |
| Computer Token | Singolo computer | I comandi di quel computer |

## Accesso tra menti

### All'interno dello stesso utente

L'utente può accedere a tutte le sue menti tramite JWT (es. `GET /minds` le
elenca tutte). Ma per leggere/scrivere dati di memoria, ha bisogno della Mind
Key specifica.

### Tra utenti

Gli utenti non possono accedere ai dati l'uno dell'altro — A MENO CHE non
condividano esplicitamente una mente tramite la 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"}'
```

Dopo la condivisione, Bob può accedere alla Mente A tramite il suo JWT (sola
lettura se `role=read`).

## Confini di sicurezza

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

## Modelli multi-tenant comuni

### Modello 1: utente singolo, mente singola

Più comune per utenti singoli di agenti LLM.

- 1 account utente
- 1 mente
- 1 Mind Key
- Tutte le memorie in un unico scope

### Modello 2: utente singolo, menti multiple

Per utenti con contesti multipli (lavoro, personale, progetti).

- 1 account utente
- N menti (es. "work", "personal", "project-x")
- N Mind Key
- Ogni sessione LLM usa una Mind Key

### Modello 3: mente condivisa di team

Per team che collaborano a un progetto.

- 1 utente crea la mente (ottiene la Mind Key)
- Il creatore condivide con i membri del team tramite JWT
- Tutti i membri del team accedono tramite JWT (o Mind Key condivisa)

> [!WARNING]
> Condividere una Mind Key dà pieno accesso in lettura/scrittura. Per
> collaborazione di team, preferisca la Sharing API (basata su JWT) rispetto
> alla condivisione diretta di Mind Key.

### Modello 4: provider SaaS

Per app che integrano Synapse come loro layer di memoria.

- Ogni cliente = 1 account utente
- Ogni progetto cliente = 1 mente
- L'app salva le Mind Key per cliente/progetto
- Pieno isolamento tra clienti

## Verifica dell'isolamento

### Test: una Mind Key non può accedere ad altre menti

```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: il JWT non può leggere i dati di memoria direttamente

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

> [!TIP]
> - **Usi una mente per progetto/contesto** — l'isolamento è suo amico
> - **Non condivida mai le Mind Key** — usi la Sharing API invece
> - **Roti le Mind Key** se compromesse (elimini la mente, ne crei una nuova)
> - **Verifichi le menti condivise** — revisioni `GET /sharing` periodicamente
> - **Usi JWT per UI umana** — non esponga mai le Mind Key agli utenti finali

## Prossimi passi

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