# Безопасность ZBrain

## Модель угроз

**Что защищаем:**
- Содержимое брейнов (особенно TeleraPharma — есть NDA и чувствительная инфраструктурная информация)
- Учётные записи пользователей
- API ключи (OpenAI, Anthropic) — финансовые потери при утечке
- MCP токены — могут давать доступ к чтению/записи брейнов

**От кого защищаем:**
- **Внешний атакующий** через публичный endpoint brain.zetit.ru
- **Скомпрометированный сервер клиента** с украденным MCP токеном
- **Случайная утечка** через копирование токена в git, log файлы, скриншот
- **Внутренний пользователь** с правами viewer, который хочет получить admin

**От чего не защищаемся (нет ресурсов):**
- Физический доступ к VM (предполагаем что гипервизор/датацентр доверенный)
- Скомпрометированный root на самой VM
- 0-day в Postgres, Node.js, библиотеках

## Роли пользователей

| Роль | Управление пользователями | Управление брейнами | Управление источниками | Управление токенами | Просмотр audit | UI |
|------|---------------------------|---------------------|------------------------|--------------------|-----|---|
| **owner** | ✓ Полное | ✓ Полное | ✓ Полное | ✓ Полное | ✓ Все | ✓ |
| **admin** | Только viewer/editor | ✓ Полное | ✓ Полное | ✓ Свои + смотреть чужие | ✓ Все | ✓ |
| **editor** | ✗ | ✗ Создавать нельзя; редактировать содержимое — да | ✓ В назначенных брейнах | ✓ Свои с scope :read и :write | ✓ Свои действия | ✓ |
| **viewer** | ✗ | ✗ | ✗ | ✓ Свои только :read | ✓ Свои действия | ✓ Read-only |
| **agent** (не человек) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ MCP only |

В первой версии у нас один owner — это ты. Остальные роли — для будущего.

## MCP Токены

### Формат

```
brain_pat_<random40chars>
```

Префикс `brain_pat_` (Personal Access Token) — чтобы легко grep'ать в логах и автоматических сканерах секретов.

### Хранение

- Plain text токен **никогда** не хранится
- Хранится `token_hash = SHA-256(token)` и `token_prefix = первые 8 символов после brain_pat_` для UI
- При создании токена UI показывает full token **один раз**, потом только prefix

### Scope формат

```
mcp:<level>:<brain-name>
```

Уровни:
- `mcp:read:<brain>` — query, search, get_page, get_tags, get_links, get_backlinks, get_timeline, get_stats, get_health, get_versions
- `mcp:write:<brain>` — всё из read + put_page, add_tag, remove_tag, add_link, remove_link, add_timeline_entry, sync_brain
- `mcp:admin:<brain>` — всё из write + delete_page, revert_version

Wildcards:
- `mcp:read:*` — read доступ ко всем брейнам (только owner)
- `mcp:*:zetit` — все права на zetit брейн

Один токен может иметь несколько scope, например:
```json
{
  "scopes": ["mcp:read:zetit", "mcp:write:personal"]
}
```

### IP Allowlist

Опционально для каждого токена — список IP/CIDR откуда разрешён доступ.

Для production токенов (на серверах клиентов) — **обязательно** указывать IP клиентского сервера.

### TTL

- По умолчанию: 90 дней
- Опции в UI: 7 дней, 30 дней, 90 дней, 1 год, без срока
- "Без срока" доступен только owner и admin

### Revocation

Soft delete: `revoked_at = now()`.

Кэш в brainhub имеет TTL 30 секунд, поэтому отзыв вступает в силу в течение 30 секунд.

Для немедленного отзыва — `POST /api/admin/cache/invalidate-token`.

### Алгоритм валидации

```typescript
async function validateToken(token: string, brain: string, requiredScope: 'read'|'write'|'admin'): Promise<TokenInfo> {
  // 1. Проверка формата
  if (!token.startsWith('brain_pat_')) throw new Error('Invalid token format');

  const tokenHash = sha256(token);

  // 2. Проверка в кэше
  const cached = tokenCache.get(tokenHash);
  if (cached) {
    if (cached.error) throw new Error(cached.error);
    return validateScope(cached, brain, requiredScope);
  }

  // 3. DB lookup
  const dbToken = await db.tokens.findByHash(tokenHash);
  if (!dbToken) {
    tokenCache.set(tokenHash, {error: 'Not found'}, 30_000);
    throw new Error('Token not found');
  }

  // 4. Проверки статуса
  if (dbToken.revoked_at) throw new Error('Token revoked');
  if (dbToken.expires_at && dbToken.expires_at < new Date()) throw new Error('Token expired');

  // 5. IP allowlist
  if (dbToken.ip_allowlist?.length > 0) {
    const clientIp = getClientIp();
    if (!isIpInAllowlist(clientIp, dbToken.ip_allowlist)) {
      throw new Error('IP not allowed');
    }
  }

  // 6. Scope check
  validateScope(dbToken, brain, requiredScope);

  // 7. Кэшируем positive result
  tokenCache.set(tokenHash, dbToken, 30_000);

  // 8. Throttled last_used update
  scheduleLastUsedUpdate(dbToken.id);

  return dbToken;
}
```

## Сессии

### Cookie

```
Name: zbrain_session
Value: <jwt-signed session id>
HttpOnly: true
Secure: true (только в production)
SameSite: Lax
Path: /
Domain: brain.zetit.local или brain.zetit.ru
```

JWT внутри cookie - только session id, не данные пользователя. Все данные подтягиваются из БД по session id.

### Refresh tokens

- Access JWT: 15 минут
- Refresh token: 30 дней, ротируется при каждом использовании
- Refresh token хранится в БД как hash (см. таблицу `sessions`)

### Logout

- Удаление cookie
- `sessions.revoked_at = now()` для всех сессий пользователя (если "logout everywhere")

## OAuth

### Поддерживаемые провайдеры

1. **Yandex** (основной)
2. **GitHub** (резервный)
3. **Local email/password** (всегда доступен для owner)

### Привязка к существующему пользователю

Если OAuth возвращает email, который уже есть в users:
- Если у пользователя нет привязки OAuth → требуется подтверждение пароля
- Если есть привязка к другому провайдеру → ошибка ("Already linked to GitHub")
- Если есть привязка к этому же провайдеру → login успешный

### Новые пользователи через OAuth

По умолчанию **отключено** (флаг `OAUTH_AUTO_REGISTER=false`).

В первой версии — только invite-based: owner создаёт пользователя с email, тот логинится через OAuth, происходит match по email.

## 2FA (TOTP)

Опционально, в Sprint 7.

- Секрет генерируется при включении, показывается QR-код для Google Authenticator / Authy
- Сохраняется в `users.totp_secret` зашифрованным
- 8 backup codes генерируются и показываются один раз
- При логине после успешного password check → требуется TOTP код
- Для OAuth-логина 2FA не запрашивается (полагаемся на 2FA провайдера)

## Audit Log

### Что пишем

Категории событий:

**Auth:**
- `user.login.success` / `user.login.failure`
- `user.logout`
- `user.oauth.link` / `user.oauth.unlink`
- `user.totp.enable` / `user.totp.disable`

**User management:**
- `user.create`
- `user.update`
- `user.delete`
- `user.role.change`

**Brain management:**
- `brain.create`
- `brain.update`
- `brain.delete`
- `brain.sync.start` / `brain.sync.complete` / `brain.sync.fail`

**Source management:**
- `source.add`
- `source.update`
- `source.delete`

**Token management:**
- `token.create` (с указанием scopes)
- `token.revoke`

**MCP usage:**
- `mcp.call` (rate-sampled: 1 запись на 10 вызовов на токен в минуту)

**Admin actions:**
- `admin.cache.invalidate`
- `admin.config.update`

### Формат

```typescript
{
  id: bigint,                        // serial
  actor_type: 'user' | 'token',
  actor_id: uuid,                    // user.id или token.id
  action: string,                    // 'brain.create', 'mcp.call', etc.
  resource_type: string?,            // 'brain', 'token', 'source', etc.
  resource_id: string?,              // ID объекта
  payload: jsonb,                    // дополнительные данные
  ip: inet?,
  user_agent: text?,
  created_at: timestamptz
}
```

### Хранение

- Хранятся **навсегда** в первой версии (для compliance)
- В будущем — архив старее года в отдельную холодную БД
- Индексы: `(actor_type, actor_id, created_at DESC)`, `(resource_type, resource_id, created_at DESC)`

### Batch insert

MCP-запросов будет много (тысячи в день). Не делаем INSERT на каждый запрос:

```typescript
const auditQueue: AuditEntry[] = [];

// API endpoint:
function logAudit(entry: AuditEntry) {
  auditQueue.push(entry);
  // не ждём insert
}

// Worker раз в секунду:
setInterval(async () => {
  if (auditQueue.length === 0) return;
  const batch = auditQueue.splice(0, 1000);
  await db.audit_log.insertMany(batch);
}, 1000);

// graceful shutdown:
process.on('SIGTERM', async () => {
  if (auditQueue.length > 0) {
    await db.audit_log.insertMany(auditQueue);
  }
});
```

## Сетевая безопасность

### Внутренний контур (brain.zetit.local)

- Доступ только из сети ZETIT или через VPN
- Plain HTTP допустим (доверенная сеть)
- Postgres слушает только localhost (127.0.0.1)
- UFW: открыты только 22 (SSH), 80, 443

### Публичный контур (brain.zetit.ru)

- Только HTTPS, TLS 1.2+ с safe ciphers
- Rate limiting на nginx уровне:
  - 30 r/s per IP (защита от подбора токенов)
  - 100 r/s per token (защита от runaway script)
- Доступны только `/mcp/*`, `/oauth/*`, `/health`
- Любой другой path → 404 без подсказок

### SSH

- Только ключи, password auth отключён
- `PermitRootLogin no`
- Fail2ban на /var/log/auth.log

## Защита секретов

### В коде

- НИКОГДА не коммитим `.env`, `*.key`, `*.pem`
- `.gitignore` строгий
- Pre-commit hook с git-secrets или talisman (опционально)

### На VM

- `/etc/zbrain/.env` — права 600, owner zbrain
- Postgres пароли каждого брейна — в `/var/lib/zbrain/brains/<name>/config.json` (600, owner zbrain)
- API ключи OpenAI/Anthropic — в .env, не в коде
- TLS приватные ключи в `/etc/letsencrypt/live/` — стандартные права Let's Encrypt

### В БД

- Пароли пользователей — bcrypt с cost=12
- MCP токены — SHA-256 hash (HMAC не нужен, потому что коллизии не критичны)
- TOTP secrets — AES-128-GCM с ключом из TOKEN_ENCRYPTION_KEY
- OAuth subjects — открытым текстом (это не секрет)

### Backup

- Полный бэкап шифруется age (или GPG) перед сохранением
- Публичный ключ для шифрования — на VM в /etc/zbrain/backup.age.pub
- Приватный ключ для расшифровки — **НЕ на VM**, хранится отдельно (KeePass / safe / другая машина)

## Чек-лист безопасности перед production

- [ ] Все пароли Postgres сильные (≥24 символа, generated)
- [ ] `/etc/zbrain/.env` с правами 600
- [ ] UFW активен, открыты только нужные порты
- [ ] Fail2ban настроен для SSH и nginx
- [ ] TLS сертификат валиден (A+ rating на ssllabs.com)
- [ ] Postgres listen_addresses = 'localhost'
- [ ] Создан age ключ для бэкапов, приватная часть НЕ на этой VM
- [ ] Скрипт backup.sh в cron, протестирован restore
- [ ] OAuth приложения зарегистрированы, callback URL'ы правильные
- [ ] Owner аккаунт создан, password сильный, 2FA включена (после Sprint 7)
- [ ] INITIAL_OWNER_PASSWORD сменён после первого логина
- [ ] Audit log пишется и читается через UI
- [ ] Test: попытка доступа к /api/* через brain.zetit.ru → 404
- [ ] Test: запрос с revoked токеном → 401 в течение 30 секунд
- [ ] Test: запрос с неверным scope → 403