# Multi-Tenancy y aislamiento

Synapse es multi-tenant: múltiples usuarios, cada uno con múltiples minds,
completamente aislados entre sí. Esta página explica el modelo de aislamiento.

## Jerarquía de tenants

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

## Niveles de aislamiento

### Nivel 1: Aislamiento de usuario

Cada cuenta de usuario está aislada. Alice no puede:

- Ver los minds de Bob
- Acceder a las memorias de Bob (incluso con su JWT)
- Listar la información de la cuenta de Bob

Aplicado por: columna `user_id` en todas las tablas, el JWT contiene `user_id`,
todas las consultas filtran por `user_id`.

### Nivel 2: Aislamiento de mind

Dentro de un usuario, cada mind está aislado. Mind A no puede:

- Ver las memorias de Mind B
- Acceder a tareas, chat, scripts de Mind B

Aplicado por: columna `mind_id` en todas las tablas de datos, el Mind Key
contiene `mind_id`, todas las consultas filtran por `mind_id`.

> [!CRITICAL]
> El aislamiento por Mind Key es el límite de seguridad principal. Un Mind Key
> filtrado otorga acceso completo a los datos de ese mind — pero SOLO a ese
> mind.

## Tokens de autenticación

| Token | Ámbito | A qué puede acceder |
|-------|-------|-------------------|
| Mind Key | Un solo mind | Solo los datos de ese mind |
| JWT | Cuenta de usuario | Gestión de cuenta (crear/listar/eliminar minds) |
| Computer Token | Una sola computadora | Los comandos de esa computadora |

## Acceso entre minds

### Dentro del mismo usuario

El usuario puede acceder a todos sus minds vía JWT (p. ej. `GET /minds` los
lista todos). Pero para leer/escribir datos de memoria, necesita el Mind Key
específico.

### Entre usuarios

Los usuarios no pueden acceder a los datos de los demás — A MENOS que
compartan explícitamente un mind vía la API de Sharing:

```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"}'
```

Tras compartirlo, Bob puede acceder a Mind A vía su JWT (solo lectura si
`role=read`).

## Límites de seguridad

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

## Patrones comunes de multi-tenancy

### Patrón 1: Un usuario, un mind

El más común para usuarios individuales de agentes LLM.

- 1 cuenta de usuario
- 1 mind
- 1 Mind Key
- Todas las memorias en un ámbito

### Patrón 2: Un usuario, múltiples minds

Para usuarios con múltiples contextos (trabajo, personal, proyectos).

- 1 cuenta de usuario
- N minds (p. ej. "trabajo", "personal", "proyecto-x")
- N Mind Keys
- Cada sesión LLM usa un Mind Key

### Patrón 3: Mind compartido en equipo

Para equipos que colaboran en un proyecto.

- 1 usuario crea el mind (obtiene el Mind Key)
- El creador lo comparte con los miembros del equipo vía JWT
- Todos los miembros acceden vía JWT (o Mind Key compartido)

> [!WARNING]
> Compartir un Mind Key otorga acceso completo de lectura/escritura. Para
> colaboración en equipo, prefiera la API de Sharing (basada en JWT) sobre
> compartir Mind Keys directamente.

### Patrón 4: Proveedor SaaS

Para aplicaciones que integran Synapse como su capa de memoria.

- Cada cliente = 1 cuenta de usuario
- Cada proyecto de cliente = 1 mind
- La app almacena los Mind Keys por cliente/proyecto
- Aislamiento completo entre clientes

## Verificación de aislamiento

### Test: Un Mind Key no puede acceder a otros minds

```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: Un JWT no puede leer datos de memoria directamente

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

## Mejores prácticas

> [!TIP]
> - **Use un mind por proyecto/contexto** — el aislamiento es su aliado
> - **Nunca comparta Mind Keys** — use la API de Sharing en su lugar
> - **Rote los Mind Keys** si se comprometen (elimine el mind, cree uno nuevo)
> - **Audite los minds compartidos** — revise `GET /sharing` periódicamente
> - **Use JWT para la interfaz humana** — nunca exponga Mind Keys a usuarios finales

## Próximos pasos

- [Autenticación](/docs/getting-started/authentication)
- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt)
- [Arquitectura](/docs/concepts/architecture)