ADR-0010: Расширяемые схемы credentials с хранением в БД и app-level encryption

Status: accepted Date: 2026-04-17 Deciders: команда проекта Supersedes: часть ADR-0009 в части хранения секретов в Vault

Контекст

В ADR-0009 предполагалось хранение секретов credentials исключительно в Vault. Уточнение:

• Поставщики используют разные форматы авторизации (login/pass, API key, OAuth, bearer).
• Будем расширять список форматов при подключении новых поставщиков.
• Vault как hard requirement преждевременно усложняет deployment.

Нужна модель, которая:

• Поддерживает несколько схем авторизации.
• Расширяема без переделки ядра.
• Обеспечивает приемлемый уровень безопасности секретов.
• Не зависит от обязательного наличия Vault.

Решение

Pluggable credential schemas + DB storage с app-level encryption.

• Каждая SupplierCredential хранит auth_schema (тип) и auth_payload (JSONB).
• Стартовый набор схем: login_password, api_key, oauth2, bearer_token, custom.
• Каждая схема описана JSON Schema’ой; UI клиентского кабинета рендерится по ней.
• Поля, помеченные secret: true, шифруются перед записью в БД.
• Шифрование — envelope: master key (env / KMS) + per-customer/supplier DEK (Data Encryption Key).
• Расшифровка только в момент использования connector’ом, in-memory.
• Vault Transit / AWS KMS — допустимый, но не обязательный backend для master key (deployment decision).

Последствия

Плюсы

• Простой стартовый deployment без Vault.
• Расширяемость на новые auth-схемы без изменения ядра credentials.
• Auto-generated UI на основе JSON Schema.
• Возможность работать с разными ключевыми материалами симметрично.

Минусы

• App-level encryption — наша зона ответственности (правильная имплементация envelope, ротация DEK, защита master key в проде).
• Ниже уровень аудита по сравнению с Vault out-of-the-box.

Нейтральные последствия

• Можно мигрировать на Vault Transit когда/если потребуется — без изменения данных credentials, только смена backend для master key.

Рассмотренные альтернативы

Vault как hard requirement

Сложнее в развёртывании, особенно на ранних этапах. Не нужно для текущего масштаба.

Plaintext в БД

Категорически неприемлемо.

Один формат credentials (например, только login_password)

Не покрывает реальное разнообразие API.

Ссылки

• ADR-0009 (multi-tenant supplier credentials).
• ../../10-business/contexts/credentials.md