# Runbook: Secrets Rotation (Sofiia Stack)

Ціль: безпечно ротувати секрети для `sofiia-console`/router/gateway/memory без простою або з мінімальним вікном деградації.

## 1) Інвентар секретів (класи)

- Telegram bot tokens (`TELEGRAM_BOT_TOKEN`, агентні токени).
- LLM/model provider keys (`OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`, інші provider keys).
- Redis auth (`SOFIIA_REDIS_URL` з паролем, якщо увімкнено auth).
- DB encryption / signing keys (якщо використовується шифрування або signing).
- JWT/session signing keys (якщо застосовуються в BFF/API).
- Internal service tokens (`SUPERVISOR_API_KEY`, `ROUTER_API_KEY`, внутрішні service-to-service ключі).

## 2) Де вони живуть

- `.env` / docker compose env blocks.
- systemd/launchd env (для процесів поза Docker).
- Цільовий стан: централізований secrets manager (Vault/1Password/GitHub Encrypted Secrets) + мінімум секретів у файлах.

## 3) Процедура ротації (порядок і команди)

### 3.1 Підготувати нові секрети

```bash
# Приклад генерації (локально, не комітити)
openssl rand -hex 32
```

Зафіксувати у change-log: які ключі, коли, хто, який rollout order.

### 3.2 Внести нові значення у runtime env (без друку значень)

```bash
cd /path/to/microdao-daarion
# оновити .env/.env.node* або secrets manager
```

### 3.3 Dual-accept / dual-write (де можливо)

- Якщо сервіс підтримує два ключі: додати `NEW`, залишити `OLD` на перехідний період.
- Якщо не підтримує: ротувати покроково з перевірками після кожного restart.

### 3.4 Rollout порядок по нодах

Рекомендований порядок для цього стеку:

1. **NODA2 (control-plane) — precheck**
   - Переконатися, що нові env підхоплюються локально.
2. **NODA1 (production runtime)**
   - Оновити env, перезапустити критичні сервіси по черзі.
3. **NODA2 (control-plane) — finalize**
   - Перезапустити `sofiia-console`, підтвердити керування нодами.

### 3.5 Команди перезапуску (приклади)

```bash
# NODA1 (remote)
ssh root@144.76.224.179 "cd /opt/microdao-daarion && docker compose -f docker-compose.node1.yml up -d router gateway memory-service"

# NODA2 (local control plane)
cd /Users/apple/github-projects/microdao-daarion
docker compose -f docker-compose.node2-sofiia.yml up -d sofiia-console router
```

## 4) Перевірки після ротації

```bash
# 1) статус API
curl -fsS http://127.0.0.1:8002/api/status/full > /dev/null

# 2) дашборд нод
curl -fsS http://127.0.0.1:8002/api/nodes/dashboard > /dev/null

# 3) метрики живі
curl -fsS http://127.0.0.1:8002/metrics | rg "sofiia_"

# 4) distributed idempotency smoke (A/B)
bash ops/redis_idempotency_smoke.sh
```

Паралельно виконати preflight:

```bash
bash ops/preflight_sofiia_console.sh
STRICT=1 bash ops/preflight_sofiia_console.sh
```

## 5) Rollback

1. Повернути попередні значення секретів (із безпечного backup/manager).
2. Перезапустити сервіси в зворотному порядку:
   - NODA2 control-plane -> NODA1 runtime (або за вашим SOP).
3. Повторити перевірки з розділу 4.
4. Зафіксувати інцидент/rollback у операційному журналі.

## 6) Операційні правила

- Ніколи не комітити реальні секрети в git.
- Логувати лише факт наявності/відсутності секрету, не значення.
- Після ротації закривати перехідний dual-accept вікно (видалити старий ключ).