--- title: "Tajne vrednosti" description: "Kako Beeuni čuva akreditive projekta i kontroliše da li kod agenta može da pristupi svakoj vrednosti." --- Тајна је акредитив специфичан за пројекат — API кључ, токен или ниска за повезивање — који је сесији потребан, али не сме да се налази у репозиторијуму. Beeuni чува тајне у пројекту, никада на налогу, и шифрује сваку вредност помоћу AES-256-GCM, користећи кључ изведен за сваки пројекат. ## Идентификатор и назив Свака тајна има два назива. `identifier` је ручица коју користите у CLI-ју и у `secrets` дозволи агента. `name` је кључ променљиве окружења написан великим словима у sandbox-у, на пример `STRIPE_API_KEY`. У већини пројеката идентификатор и назив се подударају. Разликују се само када пројекат садржи више кандидатских вредности за један назив — на пример, примарни и резервни кључ за Google Maps могу оба да се разреше у `GOOGLE_MAPS_API_KEY`. Свако правило приступа користи идентификатор. Ниједно не користи назив. ## Излагање и употреба Тајна има две независне поставке. Читајте их одвојено; оне одговарају на различита питања. | Поставка | На које питање одговара | Вредности | |---|---|---| | **Излагање** | Може ли код агента да прочита стварну вредност? | `environment`, `egress-enforced`, `none` | | **Употреба** | Ко је троши? | Код агента, LLM gateway, Connector, Git | Старија Beeuni документација приказивала је једну листу која је мешала ово двоје. Та листа је уклоњена. Не постоји избор између „мрежне границе“ и „HTTPS посредника“: један механизам служи свакој тајни са наметнутим излазним саобраћајем на сваком sandbox провајдеру. ### Три врсте излагања | Излагање | Шта sandbox садржи | Користите га за | |---|---|---| | **Environment** | Стварну вредност као обичну променљиву окружења | Подразумевано. Вредности са којима агент мора да рачуна и протоколи који нису HTTPS | | **Egress-enforced** | **Ручицу** — самописујући чувар места који сам по себи не вреди ништа | Експериментално. HTTPS позиве, када је укључена заставица `secrets_egress` | | **None** | Ништа | Акредитив који троши само Beeuni услуга или вредност која се чува, али је онемогућена | :::warning[Основно правило] **Environment** је подразумевано излагање. Стварна вредност се учитава у sandbox, где агент може да је прочита, испише и проследи. **Egress-enforced** држи вредност ван sandbox-а, али је експериментално: омогућите заставицу функције `secrets_egress` (Settings → Feature flags) да бисте га користили. До тада се тајна учитава у окружење sandbox-а. ::: ### Употребе Већину употреба додељује Beeuni, а не ви: - **Код агента** — подразумева се кад год излагање није `none`. - **LLM gateway** — додељује се када је вредност препозната као кључ добављача модела. Gateway обавља аутентификацију захтева према добављачу на страни сервера. - **Connector:<slug>** — додељује се током тока повезивања конектора. - **Git** — Beeuni га додељује за сопствени Git приступ. Само за читање; не можете да га поставите нити обришете. Тајна са излагањем `none` и без употребе приказује се као **Disabled**: сачувана је, шифрована и ништа је не троши. ## Послате и израчунате тајне Које излагање тајна може да користи својство је **узводног система**, а не Beeuni-ја. - **Послате тајне** — вредност путује преко мреже. API кључеви, bearer токени, лозинке. Ово је велика већина. Постоји тренутак када је вредност низ бајтова у одлазном захтеву, па Beeuni може да је постави тамо сам, ван sandbox-а. Послата тајна може да пређе на **egress-enforced** када је укључена заставица `secrets_egress`; подразумевано се учитава у окружење sandbox-а. - **Израчунате тајне** — вредност је састојак у израчунавању и никада не путује. AWS SigV4 кључеви за потписивање, тајне за потписивање HMAC webhook-а, JWT тврдње клијента, приватни SSH кључеви. Ко год врши израчунавање мора да поседује вредност. Мрежна граница не помаже, јер ништа у преносу не садржи акредитив. Израчунате тајне морају да остану на **environment**. Environment је подразумевано излагање и једино које може да послужи акредитиву са којим sandbox мора да врши израчунавања. Протоколи који нису HTTPS — ниска за повезивање са Postgres-ом, SMTP акредитиви — налазе се у истом положају: морају да остану на environment-у. Када сачувате вредност која изгледа као материјал за потписивање, као што је `AKIA…` пар приступних кључева или PEM/SSH материјал, Beeuni је подразумевано поставља на **environment** и наводи разлог: овај кључ локално потписује захтеве, па се излазно наметање не може применити. ## Излагање Egress-enforced :::warning[Експериментално — потребна је заставица secrets_egress] Наметaње на мрежи је експериментално. Омогућите заставицу функције `secrets_egress` (Settings → Feature flags) да бисте је користили. До тада се тајна учитава у окружење sandbox-а. Када је заставица искључена, креирање тајне са излагањем egress-enforced враћа `403` `feature_disabled`. ::: Sandbox прима променљиву окружења чија је вредност **ручка**, а не акредитив. Агент користи ту променљиву управо онако како би користио стварни кључ — у заглављу, нисци упита или телу. `Authorization: Bearer $VAR`, `Cookie: …=$VAR`, заглавље `X-Api-Key`, параметар упита и поље JSON или form тела — све функционише: Beeuni проналази ручицу где год да се појави (необрађену, URL-кодирану, као самостални base64 или JSON-ескејповану) и замењује је стварном вредношћу. При изласку Beeuni замењује ручицу стварном вредношћу, али само за захтеве упућене хостовима које сте одобрили. :::warning[Пошаљите ручицу непромењену — немојте је сами кодирати у base64] Једна ствар не функционише: скривање ручице у base64 блобу који сами направите, што ради **HTTP Basic auth** (`curl -u $VAR:` → `Authorization: Basic `). Beeuni не може да пронађе ручицу која је уграђена, неусклађена и налази се у base64-у који сте ви кодирали, па се замена никада не дешава и узводни систем одговара са `401`. Уместо тога, поставите ручицу у Bearer/token заглавље, параметар упита или поље тела. Ако API подржава само Basic auth, за ту тајну користите излагање **environment**. ::: Чињенице које произлазе из таквог облика: - Стварна вредност **никада** није у sandbox-у: ни као променљива окружења, ни у датотеци, ни као псеудоним. - Ручица послата хосту који нисте одобрили стиже као дословни низ ручице. Узводни систем је одбија. Не вреди ништа. - Ручица са неисправним потписом се никада не прихвата, а Beeuni је бележи као фалсификовану ручицу. Важећа ручица за тајну коју ова сесија не сме да троши бележи се као украдена. - Сваки прослеђени захтев уписује ревизиони запис по захтеву. - Хостови који нису на листи тунелују се без читања. Клијенти са закаченим TLS-ом и mTLS-ом према тим хостовима нису погођени. ### Хостови се тачно подударају Наведите сваки хост који позивате, по једно тачно име хоста у сваком реду. | Одбијено | Разлог | |---|---| | Host са џокером, `*.example.com` | Агент никада не сме да бира одредиште | | URL шема која није HTTPS | Beeuni прекида TLS да би извршио замену | `api.example.com` не обухвата `uploads.api.example.com`. Додајте други хост истој тајни. Beeuni одбија политику која се не може применити са `400` када је сачувате — никада не чува правило које не може да примени. Две тајне са принудним излазним саобраћајем могу да деле један хост. Сваки руковалац се мапира на сопствену вредност, па се обе исправно замењују у истом захтеву. ### Проверите то са две пробе Покрените обе пробе изнутра sandbox-а, према хосту који се налази на листи. Пример користи `postman-echo.com`, који пружа по једну крајњу тачку сваке врсте. Додајте га као дозвољени хост током трајања теста. ```bash # 1. Reachability — an endpoint that does NOT echo request headers. curl -s -o /dev/null -w '%{http_code}\n' https://postman-echo.com/status/200 # expected: 200 # 2. Substitution — an endpoint that DOES echo request headers. curl -sS -H "authorization: Bearer $STRIPE_API_KEY" https://postman-echo.com/get # expected: 200, with "Bearer [REDACTED]" in the echoed headers ``` Посматрајте их заједно, тако што ћете прво покренути пробу 1: она је једина која вам говори да је хост доступан, а проба 2 не доказује ништа док не прође. | Резултат пробе 2 | Значење | |---|---| | `200`, ехо заглавље приказује `[REDACTED]` | Ради. Права вредност је прослеђена узводно, а ехо је редигован при повратку. | | `200`, ехо заглавље приказује самог руковаоца | Замена није извршена. Проверите листу хостова и одобрење агента. | | `401` са стварног API хоста | Замена није извршена. Проверите исте две ствари. | | Празан одговор или грешка при повезивању | Стварни неуспех. Ово није знак успеха. | Потврдите да се права вредност нигде не налази у guest-у: ```bash env | grep '^STRIPE_API_KEY=' # expected: the handle, not the credential ``` Идентификатор се такође појављује унутар `BEEUNI_SECRET_CAPABILITIES`, каталога без вредности који агенту говори које тајне постоје, која променљива садржи ког руковаоца и које хостове свака од њих покрива. Он никада не садржи вредност. Хост са листе приказује сертификат који је Beeuni издао за овај sandbox и коме sandbox већ верује, уместо сопственог сертификата изворишта: ```bash curl -sv https://postman-echo.com/status/200 2>&1 | grep 'issuer:' # issuer: CN=Beeuni Egress CA (); O=Beeuni ``` ### Шта relay мења До одобреног хоста се долази преко Beeuni-ја, па се понаша мало другачије него директан позив: - Одговори се не преносе у реалном времену. Server-sent events и websockets не раде преко одобреног хоста. - Тело захтева је ограничено на 1 MiB, одговор на 5 MiB, а цео позив на 30 секунди. Beeuni прати највише 3 преусмеравања. - Враћа се само утврђени скуп заглавља одговора — тип и језик садржаја, валидатори кеширања, група ограничења брзине, `retry-after`, `x-request-id`. - Пресрећу се само клијенти који поштују `https_proxy`. Beeuni поставља ту променљиву и одговарајуће поверење у CA у окружењу агента. Процес покренут са очишћеним окружењем позива хост директно, а његов захтев одлази са руковаоцем. За захтев који Beeuni не може да пресретне, агент има експлицитна врата ка истим хостовима у оквиру исте политике: ```bash beeuni secrets call STRIPE_API_KEY https://api.stripe.com/v1/customers ``` ## Излагање окружења sandbox прима праву вредност као обичну променљиву окружења. Код агента може да је прочита, испише и проследи било где. Beeuni не може да је редигује, не може да надзире њену употребу и не може да спречи њено напуштање. Окружење је подразумевани начин излагања. Свака нова тајна га користи осим ако тајну не преместите на излазно контролисани режим, који је експерименталан и захтева ознаку `secrets_egress`. Изведени акредитив и сваки протокол који није HTTPS морају да остану у окружењу. ## Ко може да користи тајну Свака вредност тајне има публику — исти избор **Ко може да је користи** као код налога конектора: | Избор | Ко може да користи вредност | | --- | --- | | **Сви у пројекту** (подразумевано) | Свака сесија у пројекту, укључујући окидаче, распореде и дељене сесије. | | **Само ви** | Ви, директно, и ваше сопствене приватне сесије. | | **Одређене особе, групе или агенти** | Особе и групе које изаберете (директно и у сопственим приватним сесијама), као и агенти које изаберете (у свакој њиховој сесији). | Сесија истовремено има две улоге: свог **агента**, увек, и своју **особу**, само док је сесија приватна. - **Особа** приступа вредности у сесији која је **приватна** и коју је покренула та особа. Унос било кога другог уклања особу сесије, па вредност престаје да јој се прослеђује. Дељене сесије, окидачи, распореди, вебхукови, имејл и Telegram сесије немају особу. - **Агент** приступа вредности у свакој сесији тог агента — укључујући окидаче, распореде и дељене сесије. Делите вредност са агентом када је потребна ненадгледаном покретању. Свако ко може да покрене тог агента тада може да користи вредност преко њега, па је покретање агента контролна тачка (ко сме да покрене агента подешава се на агенту). - Потрошачи на страни сервера следе исто правило. Конектор повезан са тајном троши је само за позиваоца који је у публици. Сви остали добијају `credential_not_shared`, а ниједан захтев не напушта Beeuni. - Beeuni услуге које не делују ни за кога — Git proxy, провере потписа вебхука, инсталације канала и Beeuni Apps — користе само вредности дељене са свима. Више вредности може да дели једно име. Вредност дељена са особом сесије има предност над оном дељеном са њеним агентом, а та има предност над вредношћу дељеном са свима. Пример: `DEEL_API_TOKEN` садржи вредност тима, а друга вредност под идентификатором `DEEL_API_TOKEN-finance` дељена је само са групом Finance. Чланови групе Finance добијају вредност Finance у својим приватним сесијама; сви остали и сваки окидач добијају вредност тима. Особа подешава публику. Сесија агента не може да је промени (`403`), па агент не може да прошири вредност која је сужена тако да га не укључује, нити да дода самог себе. Особе које управљају тајнама пројекта и даље виде вредност која није дељена са њима, означену као **Није дељено са вама**, како би могле поново да прошире публику. ### Дељење сесије која садржи личну вредност Вредност дељена само са вама која је стигла у вашу приватну сесију као **променљива окружења** налази се у чистом тексту унутар тог sandbox-а. Дељење сесије омогућило би сваком новом посетиоцу да је прочита, а променљива окружења не може да се уклони из sandbox-а који ради. Зато Beeuni одбија да дели ту сесију или да изда јавни линк до ње, са `409 PERSONAL_SECRET_REQUIRES_PRIVATE_SESSION` и именима које она садржи. Покрените нову сесију за дељење или прво поделите вредност са свима. Вредности којима се приступа преко агента, као и излазно контролисане или серверске вредности (проверене при сваком захтеву), не спречавају дељење. Када сузите публику, Beeuni поново прослеђује подешавања у сваки sandbox који ради. Вредност која је већ достављена као променљива окружења остаје у sandbox-у док се он не покрене поново. Ако је можда прочитана, ротирајте је. ### Када унесете вредност преко линка Агенту коме је потребна вредност коју му нисте дали шаље се линк. Страница линка нуди избор **Ко може да је користи**: сви у пројекту (подразумевано) или само особа која је затражила вредност. Изаберите другу опцију за било шта лично — токен за обрачун зарада, личну пријаву. На страници се приказује само име особе која је затражила вредност, никада имејл, јер линк може да отвори свако ко га има. ### Лично прегласавање Лично прегласавање је ваша сопствена вредност за једно име, која се користи уместо дељене вредности у сесијама које покрећете. Beeuni га тренутно користи само за један акредитив за OAuth пријаву. Beeuni никада не дозвољава да кључ добављача LLM-а, на пример `ANTHROPIC_API_KEY`, постане лично прегласавање. ## Додавање тајне 1. **Подесите вредност из CLI-ја** ```bash beeuni secrets set STRIPE_API_KEY=sk_live_... ``` Beeuni је чува за све у пројекту. Додајте `--only-me` да би била употребљива само за вас. Да бисте сачували више од једне вредности под истим именом, додајте `--identifier `. Имена не могу да почињу са `BEEUNI_` — Beeuni резервише тај префикс за вредности платформе. Касније промените ко може да је користи: ```bash beeuni secrets share DEEL_API_TOKEN --user me beeuni secrets share DEEL_API_TOKEN --user finance@example.com --group beeuni secrets share NIGHTLY_REPORT_TOKEN --agent reporter beeuni secrets share DEEL_API_TOKEN --everyone ``` 2. **Или користите контролну таблу** Отворите страницу Secrets пројекта, унесите кључ и вредност, изаберите **Ко може да је користи** и сачувајте. Beeuni одмах шифрује вредност, а подразумевана подешавања за сваку нову тајну су **Сви у пројекту** и изложеност преко **environment** — стварна вредност се учитава у sandbox. Колона **Ко може да је користи** приказује публику за сваку вредност. Да бисте тајну пребацили на изложеност са наметнутим излазним саобраћајем, прво омогућите ознаку функције `secrets_egress` (Settings → Feature flags); функција је експериментална. Када је ознака укључена, на страници Secrets приказује се контрола **„Може ли ваш код да прочита ову вредност?“**: одговор *не* пребацује тајну на наметање излазног саобраћаја и приказује листу хостова; одговор *да* задржава изложеност преко environment. Када је ознака искључена, тајна остаје на environment. 3. **Доделите је агенту** Изаберите агента на страници Secrets или сами додајте идентификатор на листу `secrets` тог агента у `beeuni.yaml`. Сесија добија само тајне додељене њеном агенту. Погледајте [Доделите тајну агенту](#grant-a-secret-to-an-agent). ## Доделите тајну агенту Сесија добија тајну само ако је агент који је покреће наведе на својој листи `secrets`. Подударање се врши према идентификатору, а не називу, без разликовања великих и малих слова. :::warning[За употребу са наметањем излазног саобраћаја и у сервисима потребно је именовано одобрење] `secrets: all` додељује само изложеност преко environment. Тајна са наметањем излазног саобраћаја, као и свака тајна коју користи Beeuni сервис, захтева да њен идентификатор буде наведен на листи агента. Пројекат без блока `agents:` у `beeuni.yaml` никада не добија тајну. Недодељена тајна се тихо одбацује: сесија се нормално покреће, а први позив хосту не успева као да су акредитиви погрешни. ::: ### Са контролне табле Страница Secrets означава тајну коју ниједан агент не може да добије: **Ниједан агент не може да добије ову тајну**. Изаберите агента и потврдите. Beeuni уређује `beeuni.yaml` и чува измену као `chore(agents): grant to `. Додела функционише без обзира на то да ли манифест већ декларише агента. Агент који није декларисан у манифесту добија нови унос са листом `secrets` која садржи само овај идентификатор. Агент који је већ декларисан задржава сва остала поља — модел, алате и конекторе — а идентификатор се додаје на његову постојећу листу. Ако агент већ има приступ идентификатору, измена није потребна и Beeuni је не прави. Посебан случај је агент на `secrets: all`. `all` не може да садржи тајну са наметањем излазног саобраћаја, па Beeuni уписује изричиту листу: све идентификаторе који тренутно постоје у пројекту, плус овај. Агент не губи ниједну тајну коју тренутно добија. Тајна коју касније додате захтева посебну доделу. Додела се одбија у два случаја: - Пројекат који користи `beeuni_version: 1` (`beeuni.toml`) нема мапу агената за измену. Захтев не успева са `400` и `manifest_v1_unsupported`. Уредите манифест ручно или пребаците пројекат на `beeuni_version: 2`. - За тајну чији је статус **Disabled** нема вредности за испоруку. Захтев не успева са `409` и `secret_not_grantable`. Прво подесите изложеност. Ако пројекат још нема блок `agents:`, прочитајте [Први блок `agents:` мења цео пројекат](#the-first-agents-block-changes-the-whole-project) пре него што потврдите. Та измена мења приступ тајнама свих осталих агената. ### Ручно Иста додела, унета директно: ```yaml beeuni_version: 2 agents: my-agent: secrets: [STRIPE_API_KEY] ``` ### Када сесија затражи тајну која није додељена њеном агенту Агент коме су потребни акредитиви прави везу за тајну (`beeuni secrets request`). Вредност коју унесете чува се чак и када није додељена агенту сесије. Та сесија је никада не добија, па Beeuni то приказује на свим местима: - Образац за везу приказује **Сачувано, али `` још не може да га прочита** и наводи назив тајне. - Одговор на прављење везе и накнадна порука сесији наводе називе `withheld` уз упутство како да решите проблем. - У сесији, `beeuni secrets ls` приказује декларисани кључ који није додељен као `not granted`, а не као `missing`. Агент не може сам да прошири своју доделу. Отворите **Customize → Agents → `` → Secrets** и омогућите тајну. Када сачувате измену, Beeuni је прослеђује активним сесијама агента. Агент је може одмах преузети и помоћу `beeuni secrets sync`, а при сваком упиту сесија поново синхронизује тајне. Поновно покретање није потребно. ### Први блок `agents:` мења цео пројекат :::warning[Декларисање једног агента ускраћује тајне осталима] Пројекат без блока `agents:` — или без `beeuni.yaml` уопште — није контролисан: сваки агент добија сваку тајну изложену преко environment, а ниједан агент не добија тајну са наметањем излазног саобраћаја. Чим пројекат декларише првог агента, сви агенти који **нису** на списку престају да добијају тајне пројекта — укључујући тајне environment које су им биле доступне само минут раније. Навођењем једног агента ускраћујете приступ осталима. ::: Зато наведите све агенте којима су потребне тајне, а не само оног ког подешавате. Зато контролна табла први пут тражи потврду: после те измене, `agents:` је листа дозвољених агената пројекта, а агент који недостаје на њој ради без тајни пројекта. ## Излагање могућности корисницима трећих страна :::warning[Правила за тајне у Beeuni-ју нису систем за ауторизацију више корисника] Правило за тајну штити **агента вашег пројекта** од откривања ваших акредитива. Оно не одређује који ваши крајњи корисници смеју да их користе. ::: Ако правите нешто где **непоуздани корисници трећих страна** имају приступ некој могућности — јавној површини за ћаскање, дељеној апликацији или агенту коме свако на интернету може да шаље упите — немојте им уопште давати правила за тајне. Сви корисници те површине деле једног агента пројекта, једну доделу и једну листу хостова. Beeuni не може да разликује једног вашег корисника од другог, па тајна са наметањем излазног саобраћаја доступна упитима било ког корисника постаје акредитив који сваки корисник може да користи, у границама пуног опсега приступа који омогућава кључ код узводног сервиса. Поставите потребну границу на својој страни: 1. Покрените сопствени сервис за ауторизацију и прокси. Он чува акредитив за узводни сервис. 2. Усмерите агента на свој сервис, а не директно на узводни сервис. Дајте агенту само акредитив за свој сервис — тај акредитив може да буде ограничен наметањем излазног саобраћаја на ваш хост. 3. Ваш сервис идентификује крајњег корисника, примењује ваша правила ауторизације и квоте по кориснику и тек онда позива узводни сервис акредитивом који чува. Тај сервис је место за правила по кориснику: ко чему може да приступи, колико често и којим записима. Изложеност тајни у Beeuni-ју је слој испод тога и не може да је замени. ## Листа тајни Покрените `beeuni secrets ls` да бисте видели које тајне пројекат декларише и за које су постављене вредности. Листа садржи метаподатке конфигурације. Вредности тајни се никада не приказују. Токен агента са ограниченим опсегом види само идентификаторе из доделе тог агента. `secrets_allowlist` специфичан за сесију контролише испоруку тајни у ту сесију, али не скрива метаподатке конфигурације које дозвољава додела агента. ## Ротирање тајне 1. **Поставите нову вредност** Покрените исту команду са новом вредношћу или је поново поставите на страници Secrets пројекта: ```bash beeuni secrets set STRIPE_API_KEY=sk_live_new... ``` 2. **Beeuni га прослеђује активним сесијама** Beeuni прослеђује измену сваком sandbox окружењу у ком је активна сесија за пројекат, уз најбољи могући труд. За акредитиве модела или мрежног пролаза, Beeuni поново покреће стандардни harness процес за компатибилност. За ротирање тајне са наметнутим излазним саобраћајем уопште није потребно проследити вредност: sandbox окружење чува референцу, а Beeuni чита тренутну вредност када стигне следећи захтев. ## Уклањање тајне Покрените `beeuni secrets unset STRIPE_API_KEY` (или `unset `), односно избришите је са странице Secrets пројекта. :::warning[Уклањање је тренутно, пропагација није] Beeuni одмах брише заједничку тајну. Прослеђивање већ покренутим sandbox окружењима је уз најбољи могући труд, исто као и при ротирању. ::: ## Дељење вредности без њеног прегледа Покрените `beeuni secrets request STRIPE_API_KEY` да бисте направили везу. Свако ко има везу може да унесе вредност. Ви је никада не видите. Везе подразумевано важе 7 дана; подесите трајање помоћу `--expires ` (највише 30 дана). Истекла веза приказује јасну страницу „expired“ — направите нову истом командом. ## Директно давање вредности агенту Ако налепите кључ у сесију, агент га одмах чува помоћу `beeuni secrets set`. Не шаље вам везу. Агенту је потребна дозвола за упис тајни у пројекат. Без ње, агент добија `403` и уместо тога прави везу за тајну. Агент може да сачува тајну окружења или тајну конектора (`--scope connector`). Испорука са наметнутим правилима и спискови хостова доступни су само људима. ## Пример од почетка до краја `beeuni.yaml`: ```yaml beeuni_version: 2 default_agent: my-agent agents: my-agent: secrets: [STRIPE_API_KEY] ``` Конфигурација тајне. Прва команда чува вредност уз подразумевано излагање у окружењу. Друга је пребацује на излагање са наметнутим излазним саобраћајем, што је експериментално и захтева заставицу `secrets_egress` (Settings → Feature flags); враћа `403` `feature_disabled` док је заставица искључена. ```bash beeuni secrets set STRIPE_API_KEY=sk_live_... beeuni secrets delivery STRIPE_API_KEY egress --allow-host api.stripe.com ``` Агент затим позива Stripe помоћу променљиве коју је добио: ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H "authorization: Bearer $STRIPE_API_KEY" \ https://api.stripe.com/v1/customers # expected: 200 ``` `$STRIPE_API_KEY` садржи референцу. Stripe добија стварни кључ јер је `api.stripe.com` на списку. Исти захтев ка хосту који није на списку шаље референцу, а узводни сервер је одбија. Исти захтев агента чији списак `secrets` не садржи `STRIPE_API_KEY` враћа `401`. Та сесија се нормално покреће — тајна за коју нема дозволу није грешка, једноставно се никада не испоручује. ## CLI команде | Команда | Шта ради | |---|---| | `beeuni secrets ls` | Наводи тајне декларисане и постављене за пројекат | | `beeuni secrets set KEY=VALUE [--identifier ] [--scope runtime\|connector]` | Креира или ажурира тајну. `KEY=-` чита вредност са стандардног улаза. `--scope connector` је чува на страни сервера | | `beeuni secrets unset IDENTIFIER` | Уклања тајну | | `beeuni secrets delivery IDENTIFIER egress --allow-host ` | Излагање са наметнутим излазним саобраћајем за наведене хостове. Експериментално; захтева заставицу `secrets_egress` | | `beeuni secrets delivery IDENTIFIER runtime` | Излагање у окружењу (подразумевано) | | `beeuni secrets delivery IDENTIFIER denied` | Онемогућено | | `beeuni secrets call IDENTIFIER URL` | Шаље један HTTPS захтев везан за правила преко Beeuni-ја. Експериментално; захтева заставицу `secrets_egress` | | `beeuni secrets sync` | У сесији агента: преузима тајне ове сесије и одмах даје дозволу. Као особа: поново прослеђује свим активним sandbox окружењима пројекта | | `beeuni secrets request NAME [--scope runtime\|connector] [--expires ]` | Прави везу како би неко други могао да унесе вредност | | `beeuni env push --from ` | Отпрема датотеку `.env` као тајне | | `beeuni env pull [--out ] [--force]` | Извози називе тајни, не њихове вредности, у датотеку `.env` | CLI задржава сачуване називе: `runtime` означава излагање у окружењу, `egress` излагање са наметнутим излазним саобраћајем, а `denied` онемогућено. Покрените `beeuni secrets --help` да бисте видели све заставице. Везе за подешавање подразумевано користе `connector`. Користите `--scope runtime` само када љуска агента мора да добије вредност. Тајна повезана са конектором остаје на страни сервера. ## Називи и дозволе Правила формата за два назива: | Назив | Формат | |---|---| | `identifier` | `^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$` | | `name` | `^[A-Z_][A-Z0-9_]{0,63}$` | За читање или упис тајне потребна је дозвола `project.secret.read` или `project.secret.write`. Менаџер пројекта има обе. Прилагођена улога само додаје дозволе — Beeuni нема правило за одбијање — стога ниједна улога не може да ускрати било коју од њих менаџеру. Да бисте ограничили менаџера, уклоните му улогу менаџера. Испорука сесији зависи од одлуке о улози особе која ју је покренула, укрштене са дозволом из манифеста покренутог агента. Обе морају да дозволе приступ тајни. Погледајте [Један речник, два повезивања](/docs/sr/accounts#one-vocabulary-two-bindings). ## REST руте Све руте се налазе испод `/v1/projects/{projectId}`. | Метод | Путања | Опис | |---|---|---| | GET | `/secrets` | Наводи тајне. Ако је позивалац токен ограниченог агента, приказ је ограничен на дозволе позиваоца. | | POST | `/secrets` | Креира или ажурира заједничку вредност. Тело: `{name, identifier?, value}`, уз опционална правила испоруке. | | PUT | `/secrets/{identifier}/strategy` | Мења излагање и списак хостова. | | POST | `/secrets/{identifier}/grant` | Додаје идентификатор на списак `secrets` једног агента у `beeuni.yaml`. Тело: `{agent}`. | | DELETE | `/secrets/{name}` | Брише заједничку вредност. Личне замене остају на снази. | | PUT | `/secrets/{name}/personal` | Поставља или укључује личну замену позиваоца. | | DELETE | `/secrets/{name}/personal` | Уклања личну замену позиваоца. | `POST /secrets` одбија називе који почињу са `BEEUNI_`. Враћа `409` ако `identifier` већ постоји са другачијим `name`. Одбија тачан назив `CODEX_AUTH_JSON` са `400` — Beeuni управља том тајном током подешавања ChatGPT претплате. Обе руте за упис враћају објекат `delivery_sync` када је измена морала да стигне до покренутих sandbox окружења. `ok: false` значи да је вредност сачувана, али да бар једна активна сесија и даље користи претходну вредност; наведене сесије ће је преузети при поновном покретању. Тајна на списку садржи `delivery_blocked_reason`. Вредност `no_agent_grant` значи да ниједан агент не може да прими ову тајну. `null` значи да је додељена, да за излагање није потребна дозвола или да Beeuni није могао да прочита манифест. `POST /secrets/{identifier}/grant` уклања тај разлог. Враћа `already_granted: true` када списак агента већ дозвољава идентификатор; у том случају Beeuni ништа не чува. Враћа `adopted_governance: true` када је изменом додат први блок `agents:` у пројекту — измена [описана изнад](#grant-a-secret-to-an-agent). Враћа `400` `manifest_v1_unsupported` за пројекат `beeuni.toml`, а `409` `secret_not_grantable` за онемогућену тајну. ## Ротирање и пропагација Упис тајне не чека поновно покретање сесије. Beeuni прослеђује измену сваком активном sandbox окружењу у пројекту: 1. Beeuni прави нови снимак окружења, користећи дозволу покренутог агента `secrets`. 2. Sandbox уписује снимак у окружење активног агента. Нови позиви алата одмах преузимају измену. 3. Ако је измењена тајна акредитив LLM провајдера, Beeuni поново покреће стандардни harness. Ово прослеђивање се врши уз најбољи могући труд. API позив који мења тајну враћа се пре него што се прослеђивање заврши. Неуспело прослеђивање се само бележи, не покушава се поново. Sandbox окружење у ком прослеђивање није успело задржава стару вредност до следећег успешног прослеђивања или поновног покретања сесије. ## Акредитиви модела Пројекту на Beeuni-ју који користи управљани приступ моделима није потребан сопствени кључ. Да бисте користили свој кључ, поставите променљиве провајдера на које се позива конфигурација стандардни harness провајдера. Препознатом кључу модела додељује се намена **LLM gateway** која га троши на страни сервера; не мора да буде присутан у sandbox окружењу. Не користите општи резултат верификације провајдера као доказ исправности у раду. Он не може да потврди изабрани модел, регион, права приступа и дијалект API-ја. Пошаљите стварни упит тачном моделу.