Vault Service

Файл: backend/src/services/vault.rs

Сервис управления криптографическим хранилищем (vault). Обеспечивает PIN-авторизацию, блокировку/разблокировку, восстановление через BIP39 фразу и управление состоянием защищённого хранилища секретов.

Эндпоинты

Метод	Путь	Функция	Описание
POST	/api/vault/setup	setup_vault_with_recovery_svc	Настроить vault с recovery-фразой
POST	/api/vault/setup-pin	setup_pin_svc	Настроить PIN (первичный/смена)
POST	/api/vault/unlock	unlock_vault_with_pin_svc	Разблокировать по PIN
POST	/api/vault/unlock-recovery	unlock_vault_with_recovery_svc	Разблокировать по recovery-фразе
POST	/api/vault/lock	lock_vault_svc	Заблокировать vault
POST	/api/vault/change-pin	change_vault_pin_svc	Сменить PIN
POST	/api/vault/reset-pin	reset_pin_state_svc	Сбросить состояние попыток PIN
GET	/api/vault/pin-state	get_pin_state_svc	Состояние попыток PIN
GET	/api/vault/is-pin-set	is_pin_set_svc	Установлен ли PIN
GET	/api/vault/is-unlocked	is_unlocked_svc	Разблокирован ли vault
GET	/api/vault/status	get_vault_status_svc	Полный статус vault
POST	/api/vault/heartbeat	vault_heartbeat_svc	Heartbeat: продление сессии
POST	/api/vault/auto-lock	set_auto_lock_timeout_svc	Таймаут автоблокировки
GET	/api/vault/has-recovery-phrase	has_recovery_phrase_svc	Есть ли сохранённая recovery-фраза
GET	/api/vault/recovery-phrase	get_recovery_phrase_svc	Получить recovery-фразу
POST	/api/vault/confirm-recovery-backup	confirm_recovery_backup_svc	Подтвердить бэкап фразы
GET	/api/vault/background-operation-mode	get_background_operation_mode_svc	Режим фоновых операций
POST	/api/vault/background-operation-mode	set_background_operation_mode_svc	Установить режим фоновых операций
POST	/api/vault/reset	reset_vault_svc	Полный сброс vault

Зависимости

• VaultManager — криптографические операции (Argon2, ChaCha20Poly1305)
• DeviceManager — извлечение приватного ключа устройства
• IdentityManager — flush pending signing key после разблокировки

---

setup_vault_with_recovery_svc

POST /api/vault/setup

Настраивает vault с предоставленной recovery-фразой и PIN-кодом. Используется при ручном восстановлении.

Параметры

Имя	Тип	Описание
words	String	BIP39 recovery-фраза (12 слов через пробел)
pin	String	4-значный PIN-код
vault_manager	Arc<Mutex<VaultManager>>	Менеджер хранилища
device_manager	Arc<Mutex<DeviceManager>>	Менеджер устройств
identity_manager	Arc<Mutex<IdentityManager>>	Менеджер идентичности

Логика

1. Валидирует PIN (ровно 4 цифры)
2. Парсит recovery-фразу из строки
3. Извлекает приватный ключ устройства (до блокировки vault)
4. Вызывает vault.setup_with_recovery_phrase(&phrase, &pin)
5. Сохраняет приватный ключ устройства в vault
6. Flush'ит pending identity signing key
7. Записывает метрики

---

setup_pin_svc

POST /api/vault/setup-pin

Универсальный эндпоинт настройки PIN. При первом вызове генерирует BIP39 фразу и создаёт vault; при повторном — меняет PIN.

Возвращает

Result<SetupPinResponse, String> — содержит words: Vec<String> (пустой при смене PIN)

Логика

1. Валидирует PIN (4 цифры)
2. Если vault не настроен:
   • Генерирует новую BIP39 recovery-фразу
   • Создаёт vault с фразой и PIN
   • Сохраняет зашифрованную фразу в БД
   • Сохраняет приватный ключ устройства
   • Flush'ит pending signing key
   • Возвращает слова фразы
3. Если vault уже настроен:
   • Проверяет, что vault разблокирован
   • Меняет PIN
   • Возвращает пустой список слов

---

unlock_vault_with_pin_svc

POST /api/vault/unlock

Разблокирует vault по PIN-коду.

Возвращает

Result<UnlockResponse, String> — содержит success: bool и remaining_attempts: u32

Логика

1. Вызывает vault.unlock_with_pin(&pin)
2. Если успешно — flush'ит pending signing key
3. Записывает метрики (успех/ошибка + длительность)

---

unlock_vault_with_recovery_svc

POST /api/vault/unlock-recovery

Разблокирует vault по BIP39 recovery-фразе (используется при забытом PIN).

Логика

1. Парсит recovery-фразу
2. Вызывает vault.unlock_with_recovery_phrase(&phrase)
3. Flush'ит pending signing key
4. Записывает метрики

---

lock_vault_svc

POST /api/vault/lock

Блокирует vault — секреты становятся недоступны до следующей разблокировки.

---

change_vault_pin_svc

POST /api/vault/change-pin

Меняет PIN-код (vault должен быть разблокирован).

Логика

1. Валидирует новый PIN (4 цифры)
2. Вызывает vault.change_pin(&new_pin)

---

reset_pin_state_svc

POST /api/vault/reset-pin

Сбрасывает счётчик неудачных попыток PIN. Требует текущий PIN для верификации.

Логика

1. Верифицирует текущий PIN через unlock_with_pin
2. Вызывает vault.reset_pin_state()

---

get_pin_state_svc

GET /api/vault/pin-state

Возвращает состояние PIN: количество оставшихся попыток, время блокировки.

---

is_pin_set_svc / is_unlocked_svc

GET /api/vault/is-pin-set / GET /api/vault/is-unlocked

Проверки состояния: настроен ли vault, разблокирован ли. Это status endpoints — они не вызывают touch_activity() и не продлевают сессию auto-lock.

---

get_vault_status_svc

GET /api/vault/status

Возвращает полный статус vault: is_setup, is_unlocked, secrets_count, auto_lock_timeout, background_operation_mode. Это status endpoint — не продлевает сессию auto-lock.

---

vault_heartbeat_svc

POST /api/vault/heartbeat

Единственный внешний способ продлить сессию auto-lock. Вызывается frontend activity tracker (mousemove/keydown/pointerdown, throttle 30s). Обновляет last_activity_at через touch_activity() и возвращает текущий статус unlock.

Возвращает

Result<bool, String> — true если vault разблокирован

---

set_auto_lock_timeout_svc

POST /api/vault/auto-lock

Устанавливает таймаут автоматической блокировки vault (в секундах).

---

has_recovery_phrase_svc / get_recovery_phrase_svc / confirm_recovery_backup_svc

Управление recovery-фразой:

• has_recovery_phrase_svc — проверяет, есть ли сохранённая (незабэкапленная) фраза
• get_recovery_phrase_svc — возвращает слова фразы (vault должен быть разблокирован)
• confirm_recovery_backup_svc — удаляет фразу из БД (пользователь подтвердил, что записал)

---

get_background_operation_mode_svc

GET /api/vault/background-operation-mode

Возвращает текущий режим фоновых операций: "continue" или "pause".

---

set_background_operation_mode_svc

POST /api/vault/background-operation-mode

Устанавливает режим фоновых операций при заблокированном vault.

Параметры

Имя	Тип	Описание
mode	String	"continue" или "pause"

Режимы

Режим	Описание
continue	(default) Фоновые задачи получают ScopedKey при старте и продолжают работу при auto-lock
pause	Фоновые задачи используют кэш ключей из менеджеров, при lock — пауза, при unlock — resume

Связано: VaultManager.set_background_operation_mode(), ScopedKey

---

reset_vault_svc

POST /api/vault/reset

Полный сброс vault. Требует текущий PIN для верификации. Удаляет все секреты.