Segreti

Come Beeuni archivia le credenziali dei progetti e controlla se il codice degli agenti può leggere ciascun valore.

Un segreto è una credenziale specifica del progetto — una chiave API, un token o una stringa di connessione — necessaria a una sessione, ma che non deve trovarsi nel repository. Beeuni archivia i segreti nel progetto, mai nell’account, e cifra ogni valore con AES-256-GCM usando una chiave derivata per progetto.

Identificatore e nome

Ogni segreto ha due nomi. L’identifier è l’identificatore da usare nella CLI e nella concessione secrets di un agente. Il name è la chiave in maiuscolo della variabile d’ambiente nella sandbox, ad esempio STRIPE_API_KEY. Nella maggior parte dei progetti, identificatore e nome corrispondono. Sono diversi solo quando un progetto contiene harness sperimentaleù valori possibili per lo stesso nome: per esempio, una chiave Google Maps principale e una di riserva possono entrambe corrispondere a GOOGLE_MAPS_API_KEY.

Tutte le regole di accesso usano l’identificatore, mai il nome.

Esposizione e utilizzo

Un segreto ha due impostazioni indipendenti. Considerale separatamente: rispondono a domande diverse.

La documentazione precedente di Beeuni presentava un unico elenco che mescolava i due aspetti. Non esiste harness sperimentaleù. Non c’è una scelta tra un «confine di rete» e un «broker HTTPS»: un solo meccanismo serve tutti i segreti con uscita di rete controllata su ogni provider di sandbox.

Le tre modalità di esposizione

Utilizzi

La maggior parte degli utilizzi viene assegnata da Beeuni, non da te:

• Codice dell’agente — implicito ogni volta che l’esposizione non è none.
• Gateway LLM — assegnato quando il valore è una chiave riconosciuta di un provider di modelli. Il gateway autentica le richieste al provider lato server.
• Connector:<slug> — assegnato dal flusso di collegamento del connettore.
• Git — assegnato da Beeuni per il proprio accesso a Git. È di sola lettura: non puoi impostarlo né rimuoverlo.

Un segreto con esposizione none e nessun utilizzo viene visualizzato come Disabled: è archiviato, cifrato e non viene usato da nessuno.

Segreti trasmessi e segreti calcolati

La modalità di esposizione che un segreto può usare dipende dal sistema a monte, non da Beeuni.

• Segreti trasmessi — il valore viene inviato sulla rete. Chiavi API, token bearer, password. È la categoria di gran lunga harness sperimentaleù comune. Poiché il valore compare per un momento come byte in una richiesta in uscita, Beeuni può inserirlo direttamente, fuori dalla sandbox. Un segreto trasmesso può passare a egress-enforced quando è attivo il flag secrets_egress; per impostazione predefinita, viene caricato nell’ambiente della sandbox.
• Segreti calcolati — il valore è un ingrediente di un calcolo e non viene mai trasmesso. Chiavi di firma AWS SigV4, segreti di firma HMAC per webhook, asserzioni client JWT, chiavi private SSH. Chi esegue il calcolo deve avere il valore. Un confine di rete non aiuta, perché la credenziale non compare nella trasmissione. I segreti calcolati devono rimanere su environment.

Environment è la modalità di esposizione predefinita ed è l’unica che può fornire una credenziale con cui la sandbox deve eseguire calcoli. Anche i protocolli diversi da HTTPS — una stringa di connessione Postgres, credenziali SMTP — richiedono la modalità environment.

Quando salvi un valore che sembra materiale di firma, come una coppia di chiavi AKIA… o materiale PEM/SSH, Beeuni imposta la modalità predefinita su environment e ne spiega il motivo: questa chiave firma le richieste localmente, quindi non è possibile applicare l’uscita di rete controllata.

Esposizione Egress-enforced

La sandbox riceve una variabile d’ambiente il cui valore è un handle, non la credenziale. L’agente usa questa variabile proprio come userebbe la chiave reale: in un’intestazione, una stringa di query o un corpo. Authorization: Bearer $VAR, Cookie: …=$VAR, un’intestazione X-Api-Key, un parametro di query e un campo del corpo JSON o di un modulo funzionano tutti: Beeuni individua l’handle ovunque si trovi (in chiaro, con codifica URL, come Base64 autonomo o con escape JSON) e lo sostituisce con il valore reale. In uscita, Beeuni sostituisce l’handle con il valore reale, ma solo per le richieste dirette agli host che hai approvato.

Da questa struttura derivano alcuni fatti:

• Il valore reale non si trova mai nella sandbox: né come variabile d’ambiente, né come file, né come alias.
• Un handle inviato a un host che non hai approvato arriva come stringa letterale. Il sistema a monte lo rifiuta. Non ha alcun valore.
• Un handle con firma non valida non viene mai accettato e Beeuni lo registra come handle contraffatto. Un handle valido per un segreto che questa sessione non può usare viene registrato come rubato.
• Ogni richiesta inoltrata genera un record di controllo per la singola richiesta.
• Il traffico verso gli host non inclusi nell’elenco viene instradato attraverso il tunnel senza essere letto. I client TLS con certificato bloccato e i client mTLS che comunicano con questi host non subiscono modifiche.

Corrispondenza esatta degli host

Elenca tutti gli host che contatti, uno per riga, usando il nome host esatto.

api.example.com non include uploads.api.example.com. Aggiungi il secondo host allo stesso segreto. Beeuni rifiuta le policy non applicabili con 400 quando le salvi: non archivia mai una regola che non può applicare.

Due segreti con egress vincolato possono condividere un host. Ogni handle corrisponde al proprio valore, quindi entrambi vengono sostituiti correttamente nella stessa richiesta.

Verificalo con due test

Esegui entrambi i test dall’interno della sandbox, verso un host presente nell’elenco. L’esempio usa postman-echo.com, che offre un endpoint per ciascun tipo. Aggiungilo agli host consentiti per la durata del test.

# 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

Esamina i risultati insieme, eseguendo prima il test 1: è l’unico che ti dice se l’host è raggiungibile, e il test 2 non dimostra nulla finché il primo non ha esito positivo.

Verifica che il valore reale non sia presente da nesbeeuni parte nell’ambiente guest:

env | grep '^STRIPE_API_KEY='
# expected: the handle, not the credential

L’identificatore compare anche in BEEUNI_SECRET_CAPABILITIES, il catalogo privo di valori che indica all’agente quali segreti esistono, quale variabile contiene ogni handle e quali host copre ciascuno. Non contiene mai un valore.

Un host presente nell’elenco presenta un certificato emesso da Beeuni per questa sandbox, di cui la sandbox si fida già, anziché quello dell’origine:

curl -sv https://postman-echo.com/status/200 2>&1 | grep 'issuer:'
# issuer: CN=Beeuni Egress CA (<project prefix>); O=Beeuni

Cosa cambia con il relay

Si raggiunge un host approvato tramite Beeuni, quindi il comportamento è leggermente diverso da una chiamata diretta:

• Le risposte non vengono trasmesse in streaming. Gli eventi inviati dal server e i websocket non funzionano tramite un host approvato.
• Il corpo di una richiesta è limitato a 1 MiB, la risposta a 5 MiB e l’intera chiamata a 30 secondi. Beeuni segue al massimo 3 reindirizzamenti.
• Viene restituito solo un insieme fisso di intestazioni di risposta: tipo e lingua del contenuto, validatori di cache, le intestazioni relative ai limiti di frequenza, retry-after, x-request-id.
• Vengono intercettati solo i client che rispettano https_proxy. Beeuni imposta questa variabile e la relativa CA attendibile nell’ambiente dell’agente. Un processo avviato con un ambiente ripulito chiama direttamente l’host e invia la richiesta contenente l’handle.

Per le richieste che Beeuni non può intercettare, l’agente dispone di un accesso esplicito agli stessi host, secondo la stessa policy:

beeuni secrets call STRIPE_API_KEY https://api.stripe.com/v1/customers

Esposizione nell’ambiente

La sandbox riceve il valore reale come variabile d’ambiente in testo semplice. Il codice dell’agente può leggerlo, stamparlo e inoltrarlo ovunque. Beeuni non può oscurarlo, verificarne l’uso né impedirne la fuoriuscita.

L’esposizione nell’ambiente è quella predefinita. Ogni nuovo segreto la usa, a meno che tu non lo trasferisca all’egress vincolato, una funzionalità sperimentale che richiede il flag secrets_egress. Una credenziale calcolata e qualsiasi protocollo non HTTPS devono rimanere nell’ambiente.

Chi può usare un segreto

Ogni valore segreto ha un pubblico, la stessa scelta Chi può usarlo disponibile per un account di un connettore:

Una sessione svolge sempre due ruoli: è il suo agente e, solo quando è privata, la sua persona.

• Una persona può accedere a un valore in una sessione privata avviata da quella persona. Un prompt di chiunque altro rimuove la persona dalla sessione, che quindi non può harness sperimentaleù accedere al valore. Le sessioni condivise, i trigger, le pianificazioni, i webhook e le sessioni email e Telegram non hanno una persona.
• Un agente può accedere a un valore in tutte le proprie sessioni, incluse quelle con trigger, pianificazioni e condivise. Condividi un valore con l’agente se serve a un’esecuzione senza supervisione. Chiunque possa eseguire quell’agente può quindi usare il valore tramite l’agente, perciò il controllo è l’autorizzazione a eseguire l’agente (l’autorizzazione è configurata nell’agente).
• La stessa regola vale per i consumer lato server. Un connettore associato al segreto lo usa solo per un chiamante incluso nel pubblico. Chiunque altro riceve credential_not_shared e nesbeeuni richiesta lascia Beeuni.
• I servizi Beeuni che agiscono per conto di nessuno — il proxy Git, i controlli delle firme dei webhook, le installazioni dei canali e le app Beeuni — usano solo valori condivisi con tutti.

harness sperimentaleù valori possono condividere lo stesso nome. Un valore condiviso con la persona della sessione ha la precedenza su uno condiviso con l’agente, che a sua volta ha la precedenza su quello condiviso con tutti. Esempio: DEEL_API_TOKEN contiene un valore del team, mentre un secondo valore con l’identificatore DEEL_API_TOKEN-finance è condiviso solo con il gruppo Finance. I membri di Finance ricevono il valore Finance nelle loro sessioni private; tutti gli altri e ogni trigger ricevono il valore del team.

È una persona a impostare il pubblico. Una sessione agente non può modificarlo (403), quindi un agente non può ampliare il pubblico di un valore da cui è escluso né aggiungere sé stesso. Chi gestisce i segreti del progetto continua a vedere i valori che non sono condivisi con lui, contrassegnati come Non condiviso con te, e può ampliarne di nuovo il pubblico.

Condividere una sessione che contiene un valore personale

Un valore condiviso solo con te e reso disponibile nella tua sessione privata come variabile d’ambiente è in testo semplice all’interno di quella sandbox. Condividere la sessione permetterebbe a ogni nuovo visualizzatore di leggerlo e non è possibile rimuovere una variabile d’ambiente da una sandbox in esecuzione. Perciò Beeuni impedisce di condividere quella sessione o di crearne un link pubblico, indicando 409 PERSONAL_SECRET_REQUIRES_PRIVATE_SESSION e i nomi dei valori presenti. Avvia una nuova sessione da condividere oppure condividi prima il valore con tutti. I valori resi disponibili tramite l’agente e quelli con egress vincolato o lato server (verificati a ogni richiesta) non impediscono la condivisione.

Quando restringi il pubblico, Beeuni invia di nuovo tutti i valori alle sandbox in esecuzione. Un valore già distribuito come variabile d’ambiente rimane nella sandbox fino al riavvio. Se potrebbe essere stato letto, ruotalo.

Quando inserisci un valore tramite un link

Un agente che ha bisogno di un valore che non gli hai fornito invia un link. La pagina del link offre la scelta Chi può usarlo: tutti nel progetto (impostazione predefinita) oppure solo la persona che lo ha richiesto. Scegli la seconda opzione per qualsiasi dato personale, come un token per le buste paga o un accesso personale. La pagina mostra il nome visualizzato della persona che lo ha richiesto, mai l’email, perché chiunque abbia il link può aprirlo.

Sostituzione personale

Una sostituzione personale è un tuo valore per un determinato nome, usato al posto del valore condiviso nelle sessioni che avvii. Al momento Beeuni la usa solo per una credenziale di accesso OAuth. Beeuni non permette mai di usare come sostituzione personale una chiave di un provider LLM, ad esempio ANTHROPIC_API_KEY.

Aggiungere un segreto

beeuni secrets set STRIPE_API_KEY=sk_live_...

beeuni secrets share DEEL_API_TOKEN --user me
beeuni secrets share DEEL_API_TOKEN --user finance@example.com --group <group-id>
beeuni secrets share NIGHTLY_REPORT_TOKEN --agent reporter
beeuni secrets share DEEL_API_TOKEN --everyone

Concedere un segreto a un agente

Una sessione riceve un segreto solo quando l’agente che esegue include l’identificatore nel proprio elenco secrets. La corrispondenza si basa sull’identificatore, non sul nome, e ignora le maiuscole/minuscole.

Dalla dashboard

Nella pagina Secrets, accanto ai segreti che nessun agente può ricevere compare l’indicazione Nessun agente può ricevere questo segreto. Scegli un agente e conferma. Beeuni modifica beeuni.yaml e lo salva come chore(agents): grant <IDENTIFIER> to <agent>.

La concessione funziona sia che il manifest dichiari già l’agente, sia che non lo faccia. Se l’agente non è dichiarato nel manifest, viene aggiunta una nuova voce con questo unico elenco secrets. Se l’agente è già dichiarato, tutti gli altri campi — model, tools, connectors — rimangono invariati e l’identificatore viene aggiunto all’elenco esistente. Se l’agente ha già accesso all’identificatore, non serve alcun commit e Beeuni non ne esegue uno.

Un agente in secrets: all è un caso speciale. all non può contenere un segreto con enforcement dell’egress, quindi Beeuni scrive un elenco esplicito: tutti gli identificatori presenti oggi nel progetto, harness sperimentaleù questo. Nulla cambia per i segreti che l’agente riceve già. Ogni segreto aggiunto in seguito richiederà una concessione separata.

In due casi la concessione viene rifiutata:

• Un progetto con beeuni_version: 1 (beeuni.toml) non ha una mappa degli agenti da modificare. La richiesta fallisce con 400 e manifest_v1_unsupported. Modifica il manifest manualmente oppure sposta il progetto su beeuni_version: 2.
• Un segreto Disabilitato non ha nulla da fornire. La richiesta fallisce con 409 e secret_not_grantable. Assegna prima un’esposizione al segreto.

Se il progetto non ha ancora un blocco agents:, leggi Il primo blocco agents: modifica l’intero progetto prima di confermare. Quella modifica cambia l’accesso ai segreti per tutti gli altri agenti.

Manualmente

La stessa concessione, scritta direttamente:

beeuni_version: 2
agents:
  my-agent:
    secrets: [STRIPE_API_KEY]

Quando una sessione richiede un segreto non concesso al suo agente

Un agente che necessita di una credenziale crea un link al segreto (beeuni secrets request). Il valore inserito viene salvato anche se non è concesso all’agente della sessione. La sessione non lo riceve mai, quindi Beeuni lo segnala in ogni schermata:

• Il modulo del link mostra Salvato, ma <agent> non può ancora leggerlo e indica il nome del segreto.
• La risposta di creazione e il messaggio successivo alla sessione elencano i nomi withheld con le istruzioni per risolvere il problema.
• All’interno della sessione, beeuni secrets ls mostra una chiave dichiarata ma non inclusa nella concessione come not granted, non come missing.

L’agente non può ampliare da solo la propria concessione. Apri Customize → Agents → <agent> → Secrets e abilita il segreto. Al salvataggio, Beeuni applica la modifica alle sessioni dell’agente già in esecuzione. L’agente può anche recuperarla subito con beeuni secrets sync e ogni prompt sincronizza di nuovo i segreti della sessione. Non serve riavviare.

Il primo blocco agents: modifica l’intero progetto

Elenca quindi tutti gli agenti che hanno bisogno di segreti, non solo quello che stai correggendo. Ecco perché la dashboard ti chiede di confermare la prima volta: dopo quel commit, agents: diventa la lista di autorizzazione del progetto e qualsiasi agente che non vi compare viene eseguito senza segreti del progetto.

Esporre funzionalità a utenti di terze parti

Se stai realizzando qualcosa in cui utenti terzi non attendibili possono accedere a una funzionalità — una chat pubblica, un’app condivisa, un agente a cui chiunque su Internet può inviare prompt — non affidare loro le policy dei segreti. Tutti gli utenti di quella superficie condividono un unico agente del progetto, un’unica concessione e un unico elenco di host. Beeuni non può distinguere un tuo cliente da un altro; quindi, se un prompt di qualsiasi utente può raggiungere un segreto con enforcement dell’egress, tutti gli utenti possono usare quella credenziale, fino ai limiti completi della chiave a monte.

Crea il confine di sicurezza di cui hai davvero bisogno, dal tuo lato:

1. Crea un tuo servizio di autorizzazione e proxy. Sarà questo a custodire la credenziale a monte.
2. Indirizza l’agente al tuo servizio, non al servizio a monte. Fornisci all’agente solo una credenziale per il tuo servizio: potrai applicarvi l’enforcement dell’egress limitandolo al tuo host.
3. Il tuo servizio identifica l’utente finale, applica le tue regole di autorizzazione e i limiti per utente, quindi effettua la chiamata a monte usando la credenziale che custodisce.

È nel tuo servizio che devono risiedere le regole per singolo utente: chi può chiamare cosa, con quale frequenza e per quali record. L’esposizione dei segreti di Beeuni opera a un livello inferiore e non la sostituisce.

Elencare i segreti

Esegui beeuni secrets ls per vedere quali segreti dichiara un progetto e quali hanno un valore impostato.

L’elenco contiene metadati di configurazione, non restituisce mai i valori dei segreti. Un token con ambito limitato a un agente vede solo gli identificatori inclusi nella concessione dell’agente. Un secrets_allowlist specifico della sessione controlla la distribuzione dei segreti a quella sessione, ma non nasconde i metadati di configurazione accessibili in base alla concessione dell’agente.

Ruotare un segreto

beeuni secrets set STRIPE_API_KEY=sk_live_new...

Rimuovere un secret

Esegui beeuni secrets unset STRIPE_API_KEY (o unset <identifier>), oppure eliminalo dalla pagina Secrets del progetto.

Condividere un valore senza vederlo

Esegui beeuni secrets request STRIPE_API_KEY per creare un link. Chiunque abbia il link può inserire il valore. Tu non lo vedrai mai. Per impostazione predefinita, i link restano validi per 7 giorni; puoi modificare la durata con --expires <minutes> (massimo 30 giorni). Un link scaduto mostra una pagina con l’indicazione chiara «scaduto»: crea un nuovo link con lo stesso comando.

Fornire direttamente un valore a un agente

Se incolli una chiave in una sessione, l’agente la salva subito con beeuni secrets set. Non ti invia un link. L’agente ha bisogno dell’autorizzazione del progetto per scrivere i secret. Senza questa autorizzazione, riceve 403 e crea invece un link per il secret. Un agente può salvare un secret di ambiente o un secret del connettore (--scope connector). L’invio vincolato e gli elenchi di host restano funzioni riservate agli utenti.

Esempio completo

beeuni.yaml:

beeuni_version: 2
default_agent: my-agent
agents:
  my-agent:
    secrets: [STRIPE_API_KEY]

Configurazione del secret. Il primo comando salva il valore con l’esposizione di ambiente predefinita. Il secondo lo imposta con l’esposizione vincolata all’uscita, una funzione sperimentale che richiede il flag secrets_egress (Settings → Feature flags); se il flag è disattivato, restituisce 403 feature_disabled.

beeuni secrets set STRIPE_API_KEY=sk_live_...
beeuni secrets delivery STRIPE_API_KEY egress --allow-host api.stripe.com

L’agente chiama quindi Stripe usando la variabile che gli è stata fornita:

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 contiene un riferimento. Stripe riceve la chiave reale, perché api.stripe.com è nell’elenco. La stessa richiesta a un host non presente nell’elenco invia il riferimento e il servizio a monte lo rifiuta.

La stessa richiesta da un agente il cui elenco secrets non include STRIPE_API_KEY restituisce 401. La sessione si avvia normalmente: un secret non autorizzato non genera un errore, semplicemente non viene mai fornito.

Comandi CLI

La CLI mantiene la terminologia salvata: runtime indica l’esposizione di ambiente, egress l’esposizione vincolata all’uscita e denied la disattivazione. Esegui beeuni secrets --help per visualizzare tutti i flag.

Per impostazione predefinita, i link di configurazione usano connector. Usa --scope runtime solo se la shell dell’agente deve ricevere il valore. Un secret associato a un connettore resta sul server.

Nomi e autorizzazioni

Regole di formato per i due nomi:

Per leggere o scrivere un secret servono l’autorizzazione project.secret.read o project.secret.write. Un responsabile del progetto ha entrambe. Un ruolo personalizzato può solo aggiungere autorizzazioni: Beeuni non prevede regole di diniego, quindi nessun ruolo può negarne una a un responsabile. Per limitare un responsabile, rimuovi il ruolo di responsabile.

La consegna a una sessione dipende dal verdetto sui ruoli della persona che l’ha avviata, incrociato con le autorizzazioni del manifest dell’agente avviato. Entrambi devono consentire l’accesso al secret. Consulta Un vocabolario, due associazioni.

Endpoint REST

Tutti gli endpoint si trovano sotto /v1/projects/{projectId}.

POST /secrets rifiuta i nomi che iniziano con BEEUNI_. Restituisce 409 se identifier esiste già con un name diverso. Rifiuta il nome esatto CODEX_AUTH_JSON con 400: Beeuni gestisce quel secret durante la procedura di attivazione dell’abbonamento ChatGPT.

Entrambi gli endpoint di scrittura restituiscono un oggetto delivery_sync quando la modifica deve essere propagata alle sandbox in esecuzione. ok: false significa che il valore è stato salvato, ma almeno una sessione attiva usa ancora quello precedente; le sessioni elencate lo acquisiranno al riavvio.

Un secret nell’elenco include delivery_blocked_reason. Il valore no_agent_grant significa che nessun agente può ricevere il secret. null significa che il secret è autorizzato, che l’esposizione non richiede autorizzazioni o che Beeuni non è riuscito a leggere il manifest.

POST /secrets/{identifier}/grant elimina questo motivo. Restituisce already_granted: true se l’elenco dell’agente include già l’identificatore; in tal caso, Beeuni non applica alcuna modifica. Restituisce adopted_governance: true se la modifica aggiunge il primo blocco agents: del progetto: la modifica descritta sopra. Restituisce 400 manifest_v1_unsupported per un progetto beeuni.toml e 409 secret_not_grantable per un secret disattivato.

Rotazione e propagazione

La scrittura di un secret non aspetta il riavvio della sessione. Beeuni invia la modifica a tutte le sandbox attive del progetto:

1. Beeuni crea un nuovo snapshot dell’ambiente usando le autorizzazioni secrets dell’agente in esecuzione.
2. La sandbox scrive lo snapshot nell’ambiente dell’agente attivo. Le nuove chiamate agli strumenti acquisiscono subito la modifica.
3. Se il secret modificato è una credenziale di un provider LLM, Beeuni riavvia harness standard.

L’invio viene effettuato con il massimo impegno possibile. La chiamata API che modifica il secret restituisce una risposta prima che l’invio sia completato. Gli invii non riusciti vengono registrati, ma non ritentati. Una sandbox per cui l’invio non è riuscito mantiene il vecchio valore fino al successivo invio riuscito o al riavvio della sessione.

Credenziali del modello

Un progetto che usa l’accesso ai modelli gestito da Beeuni non ha bisogno di una propria chiave. Per usare le tue, imposta le variabili del provider a cui fa riferimento la configurazione del provider harness standard. A una chiave di un modello riconosciuto viene assegnato l’utilizzo gateway LLM, che la usa sul server; non è necessario che sia presente nella sandbox.

Non considerare l’esito generico della verifica del provider una prova del funzionamento in fase di esecuzione. Non può verificare il modello selezionato, la regione, i diritti di accesso né il dialetto API. Invia un prompt reale usando esattamente quel modello.