gendesign/docs/Secrets_Rotation_Policy.md

# Secrets Rotation Policy & Procedure

**Issue:** #78 (B6-4) · **Owner:** `devops-engineer` · **Created:** 2026-06-13

Версионированная (in-repo) копия политики ротации секретов. Источник истины по
**значениям** секретов — Obsidian vault `meta/00_credentials.md` (вне репозитория,
владелец — Anton). Этот документ описывает **классы** секретов (имена, расположение,
процедуру ротации, downtime-эффект, периодичность) — **без значений**.

> ⚠️ Этот файл НЕ содержит и не должен содержать значений секретов. Только имена
> переменных, их расположение и процедуры. PR-ревью отклоняет любой diff с
> literal-секретом (`.claude/rules/git-pr.md` → security tripwire).

---

## 0. Модель хранения секретов

| Хранилище | Что лежит | В git? | Кто читает |
|---|---|---|---|
| **Forgejo repo secrets** (`lekss361/gendesign` → Settings → Actions → Secrets) | CI/CD: deploy SSH key, GHCR PAT, bot-токены, DSN, прод API-ключи прокидываемые в `.env.runtime` | ❌ нет | Forgejo Actions runner |
| **Forgejo repo variables** (`vars.*`) | non-sensitive toggles (`LLM_ENABLED`, `OWN_DEVELOPER_IDS`) | ❌ нет | Forgejo Actions runner |
| **GitHub repo secrets** (зеркало для `.github/workflows/`) | deploy SSH key (obsidian-стек) | ❌ нет | GitHub Actions (только obsidian deploy) |
| **`/opt/gendesign/.env`** (VPS, root-only, chmod 600) | DB creds, GlitchTip infra-secrets, FDW/reader passwords, прокси, COMPOSE_PROFILES | ❌ `.gitignore` | docker compose (main + obsidian + tradein стеки) |
| **`/opt/gendesign/backend/.env.runtime`** (VPS, chmod 600) | runtime overlay: `SENTRY_RELEASE`, `GLITCHTIP_DSN`, `OBJECTIVE_API_KEY`, `OPENAI_API_KEY`, `OWN_DEVELOPER_IDS`, `GENDESIGN_FDW_PASSWORD`, `COUCHDB_*` | ❌ `.gitignore` | backend/worker/beat/couchdb |
| **`/opt/gendesign/tradein-mvp/backend/.env.runtime`** (VPS, chmod 600) | tradein DB creds, Yandex/DaData ключи, прокси-URL, Cian-логин, reader password | ❌ `.gitignore` | tradein стек |
| **`caddy/users.caddy.snippet`** (in git) | bcrypt-хеши basic_auth пилотных юзеров | ✅ да (хеши, не plaintext) | Caddy |
| **Obsidian vault `meta/00_credentials.md`** | реестр **значений** всех секретов + audit-log ротаций | ❌ (вне репо) | Anton |

**Правило редактирования `.env` / `.env.runtime`:** только in-place (`sed`/append).
Полная перезапись файла затрёт user-managed секреты, которых нет в репо. См.
`.claude/rules/deploy.md` → «Полностью перезаписывать `.env.runtime` — только `sed`».

**Правило применения изменений:** `docker compose restart` НЕ перечитывает `env_file:`.
После правки env — `docker compose -p <project> -f <file> up -d --force-recreate --no-deps <svc>`.

---

## 1. Реестр классов секретов

Сгруппировано по классу. Колонка «Ротация» ссылается на процедуру в §2.

### 1.1 CI/CD (Forgejo / GitHub repo secrets)

| Имя | Где живёт | Назначение | Класс ротации |
|---|---|---|---|
| `DEPLOY_SSH_KEY` | Forgejo secrets + GitHub secrets | Приватный SSH-ключ для `appleboy/ssh-action` → VPS deploy. **Используется в** `deploy.yml`, `deploy-tradein.yml`, `deploy-obsidian.yml` | **A** (SSH key) |
| `DEPLOY_HOST` / `DEPLOY_USER` / `DEPLOY_PORT` | Forgejo + GitHub secrets | Адрес/юзер/порт VPS. Не «секрет» в строгом смысле, но хранится как secret | **A** |
| `GHCR_PAT` | Forgejo secrets | GitHub Container Registry PAT (`docker login ghcr.io -u lekss361`). Push образов + pull на VPS | **B** (PAT) |
| `FORGEJO_BOT_QA_TOKEN` | Forgejo secrets | bot-qa PAT (`write:issue`) для `stale-claims.yml` / `scripts/cleanup-stale-claims.sh` | **B** |
| `GLITCHTIP_BACKEND_DSN` | Forgejo secrets | Backend Sentry DSN → пишется в `.env.runtime` на deploy | **C** (DSN) |
| `GLITCHTIP_FRONTEND_DSN` | Forgejo secrets | Build-arg `NEXT_PUBLIC_GLITCHTIP_DSN` для frontend образа | **C** |
| `OBJECTIVE_API_KEY` | Forgejo secrets | Объектив live-scraper (`sync_all_groups`, #307). Пустой = no-op | **D** (3rd-party API key) |
| `OPENAI_API_KEY` | Forgejo secrets | LLM-чат (#960/#957). UNSET по умолчанию → фича dormant | **D** |

> Дополнительно во вне-репозиторном `FORGEJO_TOKEN` (личный PAT Anton) живёт доступ
> к Forgejo API из CLI/скриптов. Класс **B**.

### 1.2 Прод runtime — main стек (`/opt/gendesign/.env` + `backend/.env.runtime`)

| Имя | Файл | Назначение | Класс ротации |
|---|---|---|---|
| `POSTGRES_PASSWORD` | `.env` | Пароль роли `gendesign` (PostGIS 16) | **E** (DB password) |
| `POSTGRES_USER` / `POSTGRES_DB` | `.env` | Имя роли / БД (не секрет, но в `.env`) | **E** |
| `GENDESIGN_FDW_PASSWORD` | `backend/.env.runtime` | Пароль роли `tradein_fdw_reader` (FDW из main → tradein). Применяется через `ops/db-bootstrap/set_tradein_fdw_password.sql` | **E** |
| `COUCHDB_PASSWORD` / `COUCHDB_USER` | `backend/.env.runtime` | CouchDB (Obsidian LiveSync, `obsidian.gendsgn.ru`) | **E** |
| `GLITCHTIP_DSN` | `backend/.env.runtime` | Backend GlitchTip DSN (перезаписывается deploy из `GLITCHTIP_BACKEND_DSN`) | **C** |
| `GLITCHTIP_DB_PASS` | `.env` | Пароль БД GlitchTip-стека | **E** |
| `GLITCHTIP_SECRET` | `.env` | Django `SECRET_KEY` GlitchTip | **F** (app secret) |
| `OBJECTIVE_API_KEY` | `backend/.env.runtime` | Зеркало CI-секрета на VPS | **D** |
| `OPENAI_API_KEY` | `backend/.env.runtime` | Зеркало CI-секрета (только если non-empty) | **D** |
| `SCRAPE_ADMIN_TOKEN` | `backend/.env` | **DEPRECATED** (PR #436): app-level admin auth удалён, заменён Caddy basic_auth. Поле оставлено в `core/deps.py` для быстрого rollback | **F** (legacy, см. §3) |

### 1.3 Прод runtime — tradein стек (`/opt/gendesign/tradein-mvp/backend/.env.runtime`)

| Имя | Назначение | Класс ротации |
|---|---|---|
| `TRADEIN_POSTGRES_PASSWORD` / `TRADEIN_POSTGRES_USER` | Пароль/юзер БД `tradein` | **E** |
| `TRADEIN_READER_PASSWORD` | Пароль роли `gendesign_reader` (ETL #976, `ops/db-bootstrap/set_gendesign_reader_password.sql`) | **E** |
| `YANDEX_GEOCODER_API_KEY` | Yandex Geocoder (25k req/day) | **D** |
| `DADATA_API_TOKEN` / `DADATA_API_SECRET` | DaData `/clean/address` enrichment | **D** |
| `SCRAPER_PROXY_URL` (+ legacy `AVITO_PROXY_URL`, `CIAN_PROXY_URL`, `YANDEX_PROXY_URL` и их `*_ROTATE_URL`) | Мобильный прокси для скраперов (содержит user:pass в URL) | **G** (proxy creds) |
| `CIAN_LOGIN_EMAIL` / `CIAN_LOGIN_PASSWORD` | Cian browser auto-login (#639, Variant B) | **D** |
| `COOKIE_ENCRYPTION_KEY` | Шифрование cookie-стейта браузера | **F** |

### 1.4 Proxy / basic_auth (Caddy)

| Артефакт | Где | Назначение | Класс ротации |
|---|---|---|---|
| `caddy/users.caddy.snippet` | **in git** | bcrypt-хеши пилотных юзеров (basic_auth gate, realm `GenDesign Pilot`) | **H** (basic_auth) |

bcrypt-хеши — односторонние, не plaintext-секреты, поэтому намеренно живут в репо.
Ротация полностью описана в `docs/runbooks/basic_auth_management.md`.

---

## 2. Процедуры ротации по классам

Общие принципы:
- Любая ротация = vault entry в `meta/00_credentials.md` (audit-log: что, когда, кто).
- Меняем `.env`/`.env.runtime` **только** `sed`/append, не перезаписываем файл целиком.
- После правки runtime-env прод-сервис поднимаем через `up -d --force-recreate --no-deps <svc>`
  (compose project: `gendesign` / `gendesign-tradein` / `gendesign-obsidian`).

### Класс A — Deploy SSH key (`DEPLOY_SSH_KEY` + host/user/port)

**Downtime:** нет (ключ используется только во время CI deploy-шага).

1. На VPS под deploy-юзером сгенерировать новую keypair:
   `ssh-keygen -t ed25519 -C "forgejo-deploy-$(date +%Y%m%d)" -f ~/.ssh/forgejo_deploy_new`.
2. Добавить **новый публичный** ключ в `~/.ssh/authorized_keys` на VPS (рядом со старым — оба валидны на время cutover).
3. Обновить secret `DEPLOY_SSH_KEY` (приватная часть) в **обоих** местах: Forgejo repo secrets **и** GitHub repo secrets (obsidian-стек использует GitHub Actions).
4. Прогнать `workflow_dispatch` на `deploy.yml` — убедиться, что deploy зелёный с новым ключом.
5. Удалить **старый** публичный ключ из `authorized_keys`.
6. Vault entry.

> ⚠️ **КРИТИЧНО (исторический инцидент):** файл `sshkey.txt` был закоммичен и удалён
> в PR #391 (commit `6f37240`), но **остаётся в git-истории** — этот deploy-ключ
> следует считать **скомпрометированным** и ротировать по процедуре выше как
> приоритетную задачу (если ещё не сделано). Удаление файла из tree НЕ убирает
> blob из истории; чистка истории (`git filter-repo`) — отдельная операция, но
> ротация ключа важнее (после ротации старый blob бесполезен).

### Класс B — PAT (`GHCR_PAT`, `FORGEJO_BOT_QA_TOKEN`, `FORGEJO_TOKEN`)

**Downtime:** нет (если новый PAT выпущен до отзыва старого).

1. Выпустить новый PAT в соответствующем сервисе:
   - `GHCR_PAT`: GitHub → Settings → Developer settings → Tokens (classic) с `write:packages`, `read:packages`.
   - `FORGEJO_BOT_QA_TOKEN`: войти под bot-qa в Forgejo → Settings → Applications → minimum `write:issue`.
   - `FORGEJO_TOKEN`: личный PAT Anton (Forgejo → Applications).
2. Обновить значение в Forgejo repo secrets (для CI) / в keychain (для CLI).
3. Триггернуть зависимый workflow (`deploy.yml` для GHCR, `stale-claims.yml` для bot-qa) — проверить зелёный.
4. Отозвать старый PAT в сервисе.
5. Vault entry.

> `deploy.yml`/`deploy-tradein.yml` делают `docker login ghcr.io` повторно на каждом
> deploy, так что ротация `GHCR_PAT` подхватывается со следующим деплоем без ручного
> вмешательства на VPS.

### Класс C — GlitchTip DSN (`GLITCHTIP_BACKEND_DSN`, `GLITCHTIP_FRONTEND_DSN`, `GLITCHTIP_DSN`)

**Downtime:** нет (пустой DSN = SDK no-op, события просто не шлются в окно ротации).

1. В GlitchTip UI (`errors.gendsgn.ru`) → Project Settings → Client Keys (DSN) → revoke + create new.
2. Backend: обновить `GLITCHTIP_BACKEND_DSN` в Forgejo secrets → deploy пропишет его в `.env.runtime` через `sed` и `--force-recreate` backend/worker/beat.
3. Frontend: обновить `GLITCHTIP_FRONTEND_DSN` (build-arg `NEXT_PUBLIC_GLITCHTIP_DSN`) → требует **rebuild frontend образа** (запекается на build-time) → `workflow_dispatch` или push в `frontend/**`.
4. Vault entry.

### Класс D — 3rd-party API keys (`OBJECTIVE_API_KEY`, `OPENAI_API_KEY`, `YANDEX_GEOCODER_API_KEY`, `DADATA_*`, `CIAN_LOGIN_*`)

**Downtime:** нет (фичи gracefully degrade при пустом ключе — см. config-комментарии).

1. Перевыпустить/ротировать ключ в кабинете провайдера (Объектив / OpenAI / Yandex Cloud / DaData / Cian-аккаунт).
2. Где живёт:
   - `OBJECTIVE_API_KEY`, `OPENAI_API_KEY` — Forgejo secret → deploy пишет в main `.env.runtime`.
   - `YANDEX_GEOCODER_API_KEY`, `DADATA_*`, `CIAN_LOGIN_*` — tradein `.env.runtime` (правится **на VPS вручную**, не из CI).
3. Обновить значение `sed`-ом (НЕ перезапись файла) и `up -d --force-recreate --no-deps backend worker beat` (main) / `... backend scraper` (tradein).
4. Vault entry.

### Класс E — DB passwords (`POSTGRES_PASSWORD`, `TRADEIN_POSTGRES_PASSWORD`, `*_FDW_PASSWORD`, `*_READER_PASSWORD`, `COUCHDB_PASSWORD`, `GLITCHTIP_DB_PASS`)

**Downtime:** короткий — backend переподключается после смены (несколько секунд).

Главная роль (`gendesign` / `tradein`):
1. Сгенерировать пароль: `openssl rand -base64 24 | tr -d '/+' | head -c 24`.
2. `ALTER ROLE <role> WITH PASSWORD '<new>';` внутри контейнера postgres
   (`docker compose -p <project> exec postgres psql -U <user> -d <db> -c "ALTER ROLE ..."`).
3. Обновить пароль в `.env` (`POSTGRES_PASSWORD`) / `.env.runtime` `sed`-ом.
4. `up -d --force-recreate --no-deps backend worker beat` (и `caddy`/`frontend` если завязаны).
5. Vault entry.

Bootstrap-роли (`tradein_fdw_reader`, `gendesign_reader`):
- Пароль живёт ТОЛЬКО в `.env.runtime`; роль создаётся passwordless SQL-миграцией.
- Меняем переменную (`GENDESIGN_FDW_PASSWORD` / `TRADEIN_READER_PASSWORD`) в `.env.runtime`,
  затем повторно прогоняем idempotent-скрипт `ops/db-bootstrap/set_*_password.sql`
  (deploy.yml/deploy-tradein.yml делают это автоматически на следующем деплое).

`COUCHDB_PASSWORD`: сменить в CouchDB (`_users` / admin) + `backend/.env.runtime` + `up -d --force-recreate couchdb` через `docker-compose.obsidian.yml`. Все LiveSync-клиенты потребуют новый пароль.

### Класс F — App secrets (`GLITCHTIP_SECRET`, `COOKIE_ENCRYPTION_KEY`, `JWT_SECRET`)

**Downtime / эффект:** смена инвалидирует выпущенные артефакты (сессии/токены/cookie).

1. Сгенерировать: `openssl rand -hex 32` (или `-base64 48`).
2. Обновить в соответствующем `.env`/`.env.runtime`.
3. `up -d --force-recreate` затронутого сервиса.
4. **Эффект:** `GLITCHTIP_SECRET` — разлогинит GlitchTip-сессии; `COOKIE_ENCRYPTION_KEY`
   — инвалидирует сохранённый browser-стейт скрапера (потребуется re-login); `JWT_SECRET`
   (см. §3, появится после B3-4) — инвалидирует все выданные JWT (все юзеры разлогинятся).
   Планировать на low-traffic окно.
5. Vault entry.

### Класс G — Proxy creds (`SCRAPER_PROXY_URL` и др. `*_PROXY_URL`)

**Downtime:** нет для основного API; скраперы переключатся на новый прокси при следующем прогоне.

1. Получить новый прокси-endpoint/credentials у провайдера (mobileproxy и т.п.).
2. Обновить `SCRAPER_PROXY_URL` (и/или per-источник `CIAN_PROXY_URL`/`YANDEX_PROXY_URL`/`AVITO_PROXY_URL`) в tradein `.env.runtime` `sed`-ом.
3. `up -d --force-recreate --no-deps backend scraper` в tradein-стеке.
4. Vault entry.

> URL содержит `user:pass@host` — это секрет; не логировать целиком.

### Класс H — basic_auth (Caddy pilot users)

**Downtime:** нет. **Процедура полностью в `docs/runbooks/basic_auth_management.md`.**
Кратко: `scripts/auth/{add,remove}_user.sh` → правит `caddy/users.caddy.snippet`
(bcrypt-хеш, не plaintext) → commit → PR → merge → `deploy.yml` делает `caddy reload`.
При компрометации: `remove_user.sh` ASAP + новый credential + рассылка стейкхолдерам.

---

## 3. Особый случай: `SCRAPE_ADMIN_TOKEN` (issue #78 acceptance)

Issue #78 просит «тестовую ротацию `SCRAPE_ADMIN_TOKEN` без downtime».
**Статус токена: DEPRECATED** — app-level admin-auth был удалён в PR #436
(`backend/.env.example:30`), доступ к админ-эндпоинтам теперь закрыт Caddy basic_auth.
Поле оставлено в `core/deps.py` только для быстрого rollback.

**Вывод:** активной ротации не требуется — токен ни на что не влияет, пока
`AdminTokenAuth` dep не реинстейтнут. Если/когда его вернут, он попадает в класс **F**
(процедура: `sed` в `backend/.env.runtime` → `up -d --force-recreate --no-deps backend beat`,
downtime отсутствует). Фактический прод-прогон ротации — операционное действие
(Anton), не выполняется в рамках этого PR.

`JWT_SECRET` (упомянут в #78 «после B3-4») в кодовой базе **ещё отсутствует** —
добавить в реестр (класс **F**) при внедрении JWT-аутентификации.

---

## 4. Периодичность

| Класс | Плановая ротация | Внеплановая (немедленно) |
|---|---|---|
| A — deploy SSH key | 12 мес | компрометация / уход члена команды / **#391 (см. §2-A)** |
| B — PAT | 6–12 мес (или по expiry провайдера) | утечка / смена команды |
| C — DSN | по необходимости | утечка DSN |
| D — 3rd-party API | по политике провайдера | утечка / подозрительная активность |
| E — DB password | 12 мес | компрометация / смена команды |
| F — app secret | 12 мес | компрометация |
| G — proxy | по сроку аренды прокси | блокировка/утечка |
| H — basic_auth | конец пилота / per-user | компрометация пароля |

**Триггеры внеплановой ротации (любой класс):**
- Уход/смена члена команды с доступом к vault или VPS.
- Секрет случайно попал в git / лог / скриншот / чат.
- Подозрение на компрометацию VPS или CI-runner.

---

## 5. Audit-чеклист (онбординг / периодический ревью, раз в квартал)

- [ ] Все CI-секреты в Forgejo (и GitHub-зеркало для obsidian) актуальны и не истекли.
- [ ] `.env` / `.env.runtime` на VPS — chmod 600, владелец deploy-юзер (`ls -l`).
- [ ] Ни один секрет не закоммичен: `git grep -nE '(password|secret|token|api_key)\s*=\s*\S' -- '*.env*' ':!*.example'` пуст в tree.
- [ ] `git ls-files | grep -iE '\.pem$|id_rsa|id_ed25519|sshkey'` — пусто.
- [ ] Deploy SSH key из #391 ротирован (старый публичный ключ удалён из `authorized_keys`).
- [ ] `meta/00_credentials.md` в vault совпадает с фактическими именами из §1 (нет «осиротевших» записей).
- [ ] Каждая ротация за период имеет audit-entry в vault.
- [ ] basic_auth: `scripts/auth/list_users.sh` совпадает с актуальным списком пилотов.
- [ ] Уехавшие члены команды отозваны везде (Forgejo, GitHub, VPS `authorized_keys`, vault-доступ).

---

## 6. OIDC для CI/CD deploy — вердикт

**Запрос #78:** перейти на OIDC для Actions-деплоя вместо long-lived `DEPLOY_SSH_KEY`.

**Вердикт: FUTURE (сейчас не реализуемо).**

- Деплой во всех трёх пайплайнах (`deploy.yml`, `deploy-tradein.yml`, `deploy-obsidian.yml`)
  идёт через `appleboy/ssh-action` по SSH-ключу на Beget VPS. Это **прямой SSH на собственный
  хост**, а не federation в облако (AWS/GCP/Azure) — классический сценарий «GHA OIDC → cloud
  role» здесь не применим: конечная точка не понимает OIDC-токен, ей нужен SSH.
- Forgejo на проде — **v10.0.3** (Gitea 1.22 base). В этой версии Forgejo Actions **не
  предоставляет** OIDC-токен-эндпоинт для workflow (`ACTIONS_ID_TOKEN_REQUEST_URL` /
  `core.getIDToken()` отсутствуют; `id-token: write` permission не реализован). Поиск по репо
  подтверждает: ни одного OIDC/`id-token` упоминания в workflow нет.
- Даже на новых Forgejo OIDC-функциональность — это про Forgejo **как OIDC-провайдер для
  внешних сервисов**, а не drop-in замена SSH-ключа для деплоя на свой VPS.

**Что реально снижает риск SSH-ключа сейчас (рекомендации, не входят в этот PR):**
1. **Ротация ключа из #391** (см. §2-A) — приоритет: ключ скомпрометирован историей.
2. Ограничить ключ в `authorized_keys` через `command=`/`restrict`/`from=<runner-ip>` если
   IP runner-а стабилен (force-command на deploy-скрипт вместо полного shell).
3. Отдельный deploy-юзер с минимальными правами (не root), `sudo` только на нужные docker-команды.
4. Регулярная плановая ротация по классу A (12 мес).

**Пересмотреть OIDC**, когда: (а) Forgejo обновится до версии с OIDC-token-провайдером
для Actions, **и** (б) деплой-таргет сможет валидировать OIDC (напр. миграция на облачный
registry/host с IAM). До тех пор — short-lived SSH через `command=`-ограничение + плановая
ротация закрывают практический риск.

---

## 7. Что вне этого документа (Anton territory)

- **Реестр значений секретов** — vault `meta/00_credentials.md` (дополнить именами из §1, если расходится).
- **Фактическая ротация на проде** — операционное действие (SSH на VPS, `ALTER ROLE`, правка `.env`), выполняет владелец инфраструктуры.
- **Audit-entry per rotation** — Obsidian vault.
- **Чистка `sshkey.txt` из git-истории** (`git filter-repo`) — отдельная операция; ротация ключа (§2-A) важнее и делает старый blob бесполезным.