ADR-011: Recovery-слот мастер-ключа

Status: Accepted · Date: 2026-07-04

Контекст

ADR-005 выбрал локальный мастер-ключ в файле как default-провайдера KMS. Следствие: файл — единственный экземпляр корня доверия, его потеря необратимо уничтожает все 🔒-поля. Для self-hosted-оператора без дисциплины бэкапов это самый вероятный катастрофический сценарий всей системы.

Решение

Модель слотов (как LUKS): один мастер-ключ, независимые способы его получить.

Слот-файл — как раньше; ключ генерируется панелью при первом старте.
Recovery-слот — мастер-ключ, обёрнутый ключом из сгенерированного recovery-кода (~130 бит, Argon2id), хранится в БД (key_recovery). Код показывается один раз на экране установки.

Восстановление: astral recover --recovery-code (потерян файл), astral recovery-code new (потерян код при живом файле). Худший случай (потеряно всё) автоматизирован astral crypto reset; ссылки подписок переживают сброс — поиск по незашифрованному token_hash. См. Шифрование.

Отклонённые альтернативы

Парольная фраза пользователя вместо генерируемого кода — свойство «дамп БД сам по себе бесполезен» деградирует до стойкости выбранного пароля; генерируемый код сохраняет ~130 бит независимо от пользователя.

Shamir secret sharing (K из N) — операционный overkill: у типовой инсталляции один оператор, делить секрет не между кем.

Копия ключа в облачном KMS по умолчанию — внешняя зависимость и учётная запись облака противоречат self-hosted-профилю; доступно через провайдера vault для тех, кому нужно.

Ничего не делать (только документировать бэкап) — предыдущее состояние; вероятность потери файла на порядки выше вероятности одновременной потери файла и кода.

Последствия

(+) Потеря любого одного секрета обратима; невосстановимый сценарий требует потерять файл, код и не иметь бэкапа БД одновременно.
(+) Дамп БД по-прежнему бесполезен сам по себе (код вне БД, Argon2id против перебора).
(−) Ротация мастер-ключа обязана атомарно обновлять оба слота — учтено в astral rewrap-keys.
(−) Ещё один секрет, который оператору нужно однажды записать; его потеря — не событие, пока жив файл.