Сховішча сакрэтаў — AiHummer Дакументацыя

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

Канвертавае шыфраванне

Сховішча выкарыстоўвае двухузроўневую іерархію ключоў:

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

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

AIHUMMER_MASTER_KEY (KEK)  ──wraps──▶  per-tenant DEK  ──AES-256-GCM──▶  secret value

[!NOTE] Сховішча абапіраецца на пашырэнне pgcrypto для PostgreSQL. Пераканайцеся, што яно даступна ў вашай базе даных — яно з’яўляецца часткай стандартных сістэмных патрабаванняў.

Майстар-ключ

Майстар-ключ — гэта загрузачнае значэнне: яно чытаецца з асяроддзя пры запуску і не наладжваецца з адміністратарскага UI.

# /home/.aihummer/etc/gateway.env
# 32 random bytes, base64-encoded
AIHUMMER_MASTER_KEY=Base64Of32RandomBytes==

Вы можаце згенераваць яго з дапамогай:

openssl rand -base64 32

[!WARNING] Майстар-ключ патрэбны для расшыфроўкі ўсяго ў сховішчы. Стаўцеся да яго, як да кораня вашых сакрэтаў, і рабіце яго рэзервовую копію асобна ад базы даных — калі вы яго страціце, зашыфраваныя значэнні немагчыма аднавіць. Глядзіце Аперацыі для рэкамендацый па рэзервовым капіяванні.

Без майстар-ключа

Калі AIHUMMER_MASTER_KEY не ўсталяваны, сховішча і ўсё, што ад яго залежыць, адключаюцца: захоўванне сакрэтаў у спакоі, сховішча ўліковых дадзеных і BYOK-ключы па тэнантах — усё выключана. Гэта наўмыснае паводзіны fail-closed — прадукт не пераходзіць цішком на захоўванне сакрэтаў у адкрытым тэксце.

Сакрэты ніколі не дасягаюць мадэлі

Гэта найбольш важная ўласцівасць сховішча, і яна структурная, а не проста нагадванне аб палітыцы.

[!DANGER] Сакрэты ніколі не ўкараняюцца ў сістэмны прампт, гісторыю размовы або любы бачны мадэлі тэкст, і яны ніколі не запісваюцца ў логі. Інструменты, якім патрэбны ўліковы дадзены, разраджаюць яго са сховішча падчас выкліку, унутры gateway, і выкарыстоўваюць яго для аўтэнтыфікацыі выходнага запыту — мадэль бачыць толькі вынік выкліку інструмента, а не сакрэт.

Паколькі інтэрактыўнасць кіруецца выклікам інструментаў (глядзіце Guardrails і абарона ад prompt-injection), няма шляху, па якім прампт можа папрасіць мадэль «зачытаць» захаваны сакрэт: у мадэлі няма копіі яго для чытання.

Агульныя і ўліковыя дадзеныя па карыстальніках

Сховішча адрознівае агульныя (на ўзроўні працоўнай прасторы) ўліковыя дадзеныя і персанальныя (па карыстальніках) ўліковыя дадзеныя. OAuth2-токены па карыстальніках, атрыманыя праз паток Connections, захоўваюцца ў сховішчы і разраджаюцца дзейным карыстальнікам, з запасным варыянтам на ўзроўні працоўнай прасторы, дзе гэта дарэчна. Гэта дазваляе аднаму інструменту дзейнічаць ад імя розных карыстальнікаў з іх уласнай аўтарызацыяй, ніколі не раскрываючы токен аднаго карыстальніка іншаму.

Куды далей

RBAC і абмежаваныя API-ключы — хто можа чытаць або змяняць канфігурацыю на аснове сховішча.
Row-Level Security — ізаляцыя па тэнантах у базе даных, якая ляжыць у аснове сховішча.
Guardrails і абарона ад prompt-injection — чаму мадэль ніколі нельга падмануць, каб яна выдала сакрэт.