AiHummer
Русский▾
ВойтиЛичный кабинет
v1.0.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Безопасность/Хранилище секретов

Хранилище секретов

v1.0.x · обновлено 2026-07-21

AiHummer хранит все доступы — токены каналов, пароли SMTP/IMAP, OAuth-токены, ключи LLM на арендатора (BYOK) — в зашифрованном хранилище секретов (vault). Хранилище использует конвертное шифрование, поэтому значение в покое нельзя прочитать из одной только базы данных, и устроено так, что секрет не передаётся в контекст модели, а его значения должны маскироваться и не передаваться в журналы.

Конвертное шифрование

Хранилище секретов использует двухуровневую иерархию ключей:

  • Мастер-ключ (KEK) — задаётся через AIHUMMER_MASTER_KEY, это base64-кодированное значение из 32 байт — оборачивает и разворачивает ключи данных. Он не покидает хост и никогда не пишется в базу.
  • Ключ шифрования данных на арендатора (DEK) шифрует сами значения секретов алгоритмом AES-256-GCM (аутентифицированное шифрование). У каждого арендатора свой DEK, поэтому ключами одного арендатора нельзя расшифровать секреты другого.

Значения секретов хранятся как шифротекст; DEK хранится обёрнутым в KEK. Расшифровка происходит в памяти в момент, когда секрет нужен (например, когда коннектор проходит аутентификацию), а открытый текст затем отбрасывается.

AIHUMMER_MASTER_KEY (KEK)  ──оборачивает──▶  DEK арендатора  ──AES-256-GCM──▶  значение секрета

[!NOTE] Хранилище секретов опирается на расширение PostgreSQL pgcrypto. Убедитесь, что оно доступно в вашей базе — это часть стандартных системных требований.

Мастер-ключ

Мастер-ключ — это значение начальной загрузки: он читается из окружения при старте и не настраивается из веб-интерфейса. Установщик (и шлюз при первом запуске) всегда создаёт AIHUMMER_MASTER_KEY — он не опционален, поскольку от него зависят хранение секретов в покое, хранилище доступов и BYOK на арендатора. Поэтому в стандартной установке он всегда есть.

# ~/.aihummer/etc/gateway.env
# 32 случайных байта в base64
AIHUMMER_MASTER_KEY=Base64Of32RandomBytes==

Сгенерировать его можно так:

openssl rand -base64 32

[!WARNING] Что произойдёт: зашифрованные значения будет невозможно восстановить — резервная копия базы без AIHUMMER_MASTER_KEY не позволит расшифровать секреты. При каком условии: если мастер-ключ утерян. Как исправить заранее: относитесь к нему как к корню ваших секретов и делайте резервную копию отдельно от базы данных.

Если мастер-ключ отсутствует

Поскольку ключ создаётся всегда, в стандартной установке хранилище секретов всегда работает. Описанное поведение — это защита fail-closed на необычный случай, когда AIHUMMER_MASTER_KEY по какой-то причине не задан (например, из-за правки env-файла вручную): хранилище секретов и всё, что от него зависит, отключены — хранение секретов в покое, хранилище доступов и ключи BYOK на арендатора выключены. Это сделано намеренно — продукт не переходит молча к хранению секретов в открытом виде.

Секреты не доходят до модели

Это важнейшее свойство хранилища секретов, и оно структурное, а не просто напоминание о политике.

[!DANGER] Секреты не внедряются в системный промпт, в историю диалога или в любой видимый модели текст; значения секретов должны маскироваться и не передаваться в журналы. Инструменты, которым нужен доступ, получают его из хранилища в момент вызова, внутри шлюза, и используют для аутентификации исходящего запроса — модель видит только результат вызова инструмента, а не сам секрет.

Поскольку интерактивность строится на вызове инструментов (см. Правила безопасности и защиту от инъекций), архитектура не передаёт значение секрета модели: у модели нет его копии для чтения. Дополнительно ограничивайте инструменты, исходящие адреса и журналируйте обращения к секретам.

Общие и персональные доступы

Хранилище различает общие (на уровне рабочего пространства) и персональные (на пользователя) доступы. Персональные OAuth2-токены, полученные через поток подключений, хранятся в хранилище и выбираются по действующему пользователю, с резервным общим доступом рабочего пространства, где это уместно. Это позволяет одному инструменту действовать от имени разных пользователей с их собственной авторизацией, ни разу не раскрывая токен одного пользователя другому.

Куда дальше