# Multi-Tenancy & Cách ly

Synapse là multi-tenant: nhiều người dùng, mỗi người có nhiều mind, hoàn toàn
cách ly với nhau. Trang này giải thích mô hình cách ly.

## Hệ thống 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)
```

## Cấp độ cách ly

### Cấp 1: Cách ly người dùng

Mỗi tài khoản người dùng được cách ly. Alice không thể:

- Xem mind của Bob
- Truy cập bộ nhớ của Bob (ngay cả với JWT của cô ấy)
- Liệt kê thông tin tài khoản của Bob

Thực thi bởi: cột `user_id` trên tất cả bảng, JWT chứa `user_id`, tất cả truy
vấn lọc theo `user_id`.

### Cấp 2: Cách ly mind

Trong một người dùng, mỗi mind được cách ly. Mind A không thể:

- Xem bộ nhớ của Mind B
- Truy cập tác vụ, chat, script của Mind B

Thực thi bởi: cột `mind_id` trên tất cả bảng dữ liệu, Mind Key chứa `mind_id`,
tất cả truy vấn lọc theo `mind_id`.

> [!CRITICAL]
> Cách ly Mind Key là ranh giới bảo mật chính. Một Mind Key bị lộ cấp quyền
> truy cập đầy đủ dữ liệu mind đó — nhưng CHỈ mind đó.

## Token xác thực

| Token | Phạm vi | Có thể truy cập gì |
|-------|-------|-------------------|
| Mind Key | Một mind duy nhất | Chỉ dữ liệu mind đó |
| JWT | Tài khoản người dùng | Quản lý tài khoản (tạo/liệt kê/xóa mind) |
| Computer Token | Một máy tính duy nhất | Lệnh của máy tính đó |

## Truy cập chéo mind

### Trong cùng người dùng

Người dùng có thể truy cập tất cả mind của họ qua JWT (ví dụ `GET /minds` liệt
kê tất cả). Nhưng để đọc/ghi dữ liệu bộ nhớ, họ cần Mind Key cụ thể.

### Giữa người dùng

Người dùng không thể truy cập dữ liệu của nhau — TRỪ KHI họ chia sẻ rõ ràng một
mind qua 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"}'
```

Sau khi chia sẻ, Bob có thể truy cập Mind A qua JWT của anh ấy (chỉ đọc nếu
`role=read`).

## Ranh giới bảo mật

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

## Mẫu multi-tenant phổ biến

### Mẫu 1: Một người dùng, một mind

Phổ biến nhất cho người dùng LLM agent cá nhân.

- 1 tài khoản người dùng
- 1 mind
- 1 Mind Key
- Tất cả bộ nhớ trong một phạm vi

### Mẫu 2: Một người dùng, nhiều mind

Cho người dùng có nhiều ngữ cảnh (công việc, cá nhân, dự án).

- 1 tài khoản người dùng
- N mind (ví dụ "work", "personal", "project-x")
- N Mind Key
- Mỗi phiên LLM sử dụng một Mind Key

### Mẫu 3: Mind chung nhóm

Cho nhóm cộng tác trên một dự án.

- 1 người dùng tạo mind (nhận Mind Key)
- Người tạo chia sẻ với thành viên nhóm qua JWT
- Tất cả thành viên nhóm truy cập qua JWT (hoặc Mind Key chung)

> [!WARNING]
> Chia sẻ Mind Key cấp quyền truy cập đọc/ghi đầy đủ. Cho cộng tác nhóm, ưu
> tiên Sharing API (dựa trên JWT) thay vì chia sẻ Mind Key trực tiếp.

### Mẫu 4: Nhà cung cấp SaaS

Cho ứng dụng nhúng Synapse làm lớp bộ nhớ.

- Mỗi khách hàng = 1 tài khoản người dùng
- Mỗi dự án khách hàng = 1 mind
- Ứng dụng lưu Mind Key cho mỗi khách hàng/dự án
- Cách ly đầy đủ giữa khách hàng

## Xác minh cách ly

### Kiểm tra: Mind Key không thể truy cập mind khác

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

### Kiểm tra: JWT không thể đọc dữ liệu bộ nhớ trực tiếp

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

## Thực hành tốt nhất

> [!TIP]
> - **Sử dụng một mind mỗi dự án/ngữ cảnh** — cách ly là bạn của bạn
> - **Không bao giờ chia sẻ Mind Key** — sử dụng Sharing API thay thế
> - **Xoay vòng Mind Key** nếu bị xâm phạm (xóa mind, tạo mới)
> - **Kiểm toán mind chia sẻ** — xem xét `GET /sharing` định kỳ
> - **Sử dụng JWT cho giao diện con người** — không bao giờ lộ Mind Key cho người dùng cuối

## Bước tiếp theo

- [Xác thực](/docs/getting-started/authentication)
- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt)
- [Kiến trúc](/docs/concepts/architecture)