microdao-daarion/docs/runbook/secrets-rotation.md

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 Підготувати нові секрети

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

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

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

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 Команди перезапуску (приклади)

# 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) Перевірки після ротації

# 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 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 вікно (видалити старий ключ).