# Multi-tenancy e isolamento

O Synapse é multi-tenant: múltiplos usuários, cada um com múltiplos minds,
totalmente isolados entre si. Esta página explica o modelo de isolamento.

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

## Níveis de isolamento

### Nível 1: isolamento de usuário

Cada conta de usuário é isolada. Alice não pode:

- Ver os minds do Bob
- Acessar as memórias do Bob (mesmo com o JWT dela)
- Listar informações da conta do Bob

Aplicado por: coluna `user_id` em todas as tabelas, JWT contém `user_id`,
todas as consultas filtram por `user_id`.

### Nível 2: isolamento de mind

Dentro de um usuário, cada mind é isolado. Mind A não pode:

- Ver as memórias do Mind B
- Acessar tarefas, chat, scripts do Mind B

Aplicado por: coluna `mind_id` em todas as tabelas de dados, Mind Key contém
`mind_id`, todas as consultas filtram por `mind_id`.

> [!CRITICAL]
> O isolamento por Mind Key é a fronteira de segurança primária. Uma Mind Key
> vazada concede acesso total aos dados daquele mind — mas SOMENTE àquele mind.

## Tokens de autenticação

| Token | Escopo | O que pode acessar |
|-------|--------|---------------------|
| Mind Key | Mind único | Apenas dados daquele mind |
| JWT | Conta de usuário | Gerenciamento de conta (criar/listar/excluir minds) |
| Computer Token | Computador único | Comandos daquele computador |

## Acesso cross-mind

### Dentro do mesmo usuário

O usuário pode acessar todos os seus minds via JWT (ex.: `GET /minds` lista
todos). Mas para ler/escrever dados de memória, ele precisa da Mind Key
específica.

### Entre usuários

Usuários não podem acessar dados um do outro — A MENOS que compartilhem
explicitamente um mind via API de Compartilhamento:

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

Após compartilhar, Bob pode acessar o Mind A via seu JWT (somente leitura se
`role=read`).

## Fronteiras de segurança

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

## Padrões comuns de multi-tenancy

### Padrão 1: usuário único, mind único

Mais comum para usuários individuais de agentes LLM.

- 1 conta de usuário
- 1 mind
- 1 Mind Key
- Todas as memórias em um escopo

### Padrão 2: usuário único, múltiplos minds

Para usuários com múltiplos contextos (trabalho, pessoal, projetos).

- 1 conta de usuário
- N minds (ex.: "work", "personal", "project-x")
- N Mind Keys
- Cada sessão LLM usa uma Mind Key

### Padrão 3: mind compartilhado em equipe

Para equipes colaborando em um projeto.

- 1 usuário cria o mind (recebe a Mind Key)
- O criador compartilha com membros da equipe via JWT
- Todos os membros acessam via JWT (ou Mind Key compartilhada)

> [!WARNING]
> Compartilhar uma Mind Key concede acesso total de leitura/escrita. Para
> colaboração em equipe, prefira a API de Compartilhamento (baseada em JWT)
> em vez de compartilhar Mind Keys diretamente.

### Padrão 4: provedor SaaS

Para apps que incorporam o Synapse como sua camada de memória.

- Cada cliente = 1 conta de usuário
- Cada projeto do cliente = 1 mind
- O app armazena Mind Keys por cliente/projeto
- Isolamento total entre clientes

## Verificação de isolamento

### Teste: Mind Key não pode acessar outros 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)
```

### Teste: JWT não pode ler dados de memória diretamente

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

## Melhores práticas

> [!TIP]
> - **Use um mind por projeto/contexto** — isolamento é seu amigo
> - **Nunca compartilhe Mind Keys** — use a API de Compartilhamento
> - **Faça rotação de Mind Keys** se comprometidas (exclua o mind, crie um novo)
> - **Audite minds compartilhados** — revise `GET /sharing` periodicamente
> - **Use JWT para interface humana** — nunca exponha Mind Keys a usuários finais

## Próximos passos

- [Autenticação](/docs/getting-started/authentication)
- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt)
- [Arquitetura](/docs/concepts/architecture)