Secretos

Cómo Beeuni almacena las credenciales del proyecto y controla si el código del agente puede leer cada valor.

Un secreto es una credencial por proyecto — una clave de API, un token o una cadena de conexión — que una sesión necesita, pero que no debe estar en el repositorio. Beeuni almacena los secretos en el proyecto, nunca en la cuenta, y cifra cada valor con AES-256-GCM mediante una clave derivada por proyecto.

Identificador y nombre

Cada secreto tiene dos nombres. El identifier es el identificador que usas en la CLI y en la concesión secrets de un agente. El name es la clave de variable de entorno en mayúsculas dentro del sandbox, por ejemplo STRIPE_API_KEY. En la mayoría de los proyectos, el identificador y el nombre coinciden. Solo difieren cuando un proyecto contiene varios valores candidatos para un mismo nombre; por ejemplo, una clave principal y una de respaldo de Google Maps pueden resolver ambas a GOOGLE_MAPS_API_KEY.

Cada regla de acceso usa el identificador. Ninguna usa el nombre.

Exposición y uso

Un secreto tiene dos configuraciones independientes. Léelas por separado; responden a preguntas diferentes.

La documentación antigua de Beeuni presentaba una sola lista que mezclaba ambas. Ya no existe. No hay que elegir entre un «límite de red» y un «intermediario HTTPS»: un único mecanismo sirve para todos los secretos con salida de red controlada en todos los proveedores de sandbox.

Las tres exposiciones

Usos

Beeuni asigna la mayoría de los usos, no tú:

• Código del agente — implícito siempre que la exposición no sea none.
• Gateway de LLM — se asigna cuando el valor es una clave reconocida de un proveedor de modelos. El gateway autentica las solicitudes al proveedor en el servidor.
• Connector:<slug> — se asigna mediante el flujo de vinculación del conector.
• Git — Beeuni lo asigna para su propio acceso a Git. Es de solo lectura; no puedes establecerlo ni eliminarlo.

Un secreto con exposición none y sin uso se muestra como Disabled: está almacenado y cifrado, pero nada lo consume.

Secretos enviados y secretos calculados

La exposición que puede usar un secreto depende del sistema ascendente, no de Beeuni.

• Secretos enviados — el valor viaja por la red. Claves de API, tokens de portador y contraseñas. Son la gran mayoría. Hay un momento en el que el valor está presente como bytes en una solicitud saliente, por lo que Beeuni puede colocarlo directamente, fuera del sandbox. Un secreto enviado puede pasar a egress-enforced cuando el indicador secrets_egress está activado; de forma predeterminada, se carga en el entorno del sandbox.
• Secretos calculados — el valor es un ingrediente de un cálculo y nunca viaja. Claves de firma AWS SigV4, secretos de firma de webhooks HMAC, aserciones de cliente JWT y claves privadas SSH. Quien calcula debe tener el valor. Ningún límite de red sirve de ayuda, porque nada en la red contiene la credencial. Los secretos calculados deben permanecer en environment.

Environment es la exposición predeterminada y la única que puede servir una credencial con la que el sandbox debe hacer cálculos. Los protocolos que no usan HTTPS — una cadena de conexión de Postgres o credenciales SMTP — están en la misma situación: deben permanecer en environment.

Cuando guardas un valor que parece material de firma, como un par de claves de acceso AKIA… o material PEM/SSH, Beeuni lo establece de forma predeterminada en environment y explica el motivo: esta clave firma las solicitudes localmente, por lo que la aplicación de salida de red no puede utilizarse.

Exposición Egress-enforced

El sandbox recibe una variable de entorno cuyo valor es un identificador, no la credencial. El agente usa esa variable exactamente como usaría la clave real: en un encabezado, una cadena de consulta o un cuerpo. Authorization: Bearer $VAR, Cookie: …=$VAR, un encabezado X-Api-Key, un parámetro de consulta y un campo de cuerpo JSON o de formulario funcionan: Beeuni encuentra el identificador dondequiera que aparezca (sin procesar, codificado en URL, como base64 independiente o con escape JSON) y lo sustituye por el valor real. Al salir, Beeuni reemplaza el identificador por el valor real, pero solo en solicitudes a hosts que hayas aprobado.

Hechos que se derivan de esta estructura:

• El valor real nunca está en el sandbox: ni como variable de entorno, ni en un archivo ni como alias.
• Un identificador enviado a un host que no hayas aprobado llega como la cadena literal del identificador. El sistema ascendente lo rechaza. No tiene ningún valor.
• Un identificador con una firma incorrecta nunca se acepta, y Beeuni lo registra como un identificador falsificado. Un identificador válido para un secreto que esta sesión no puede consumir se registra como robado.
• Cada solicitud retransmitida genera un registro de auditoría por solicitud.
• Los hosts que no están en la lista se tunelizan sin ser leídos. Los clientes con TLS fijado y mTLS hacia esos hosts no se ven afectados.

Coincidencia exacta de hosts

Enumera todos los hosts a los que llamas, un nombre de host exacto por línea.

api.example.com no cubre uploads.api.example.com. Añade el segundo host al mismo secreto. Beeuni rechaza una política que no se puede aplicar con 400 al guardarla; nunca almacena una regla que no pueda aplicar.

Dos secretos con control de salida pueden compartir un host. Cada identificador se asocia a su propio valor, por lo que ambos se sustituyen correctamente en la misma solicitud.

Verifícalo con dos pruebas

Ejecuta ambas pruebas desde dentro del entorno aislado, contra un host que esté en la lista. El ejemplo usa postman-echo.com, que ofrece un endpoint de cada tipo. Añádelo como host permitido mientras dure la prueba.

# 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

Lee los resultados en conjunto y ejecuta primero la prueba 1: es la única que te indica si se puede acceder al host, y la prueba 2 no demuestra nada hasta que la primera pase.

Confirma que el valor real no aparece en ninguna parte del entorno invitado:

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

El identificador también aparece en BEEUNI_SECRET_CAPABILITIES, el catálogo sin valores que indica al agente qué secretos existen, qué variable contiene cada identificador y qué hosts cubre cada uno. Nunca contiene un valor.

Un host de la lista presenta un certificado que Beeuni emitió para este entorno aislado, en el que el entorno aislado ya confía, en lugar del certificado propio del origen:

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

Qué cambia con el relay

Se accede a un host aprobado a través de Beeuni, por lo que se comporta de forma algo diferente a una llamada directa:

• Las respuestas no se transmiten en streaming. Los eventos enviados por el servidor y los websockets no funcionan a través de un host aprobado.
• El cuerpo de una solicitud tiene un límite de 1 MiB, el de una respuesta, de 5 MiB, y la llamada completa, de 30 segundos. Beeuni sigue un máximo de 3 redirecciones.
• Solo se devuelven un conjunto fijo de encabezados de respuesta: tipo y lenguaje del contenido, validadores de caché, la familia de límites de velocidad, retry-after, x-request-id.
• Solo se interceptan los clientes que respetan https_proxy. Beeuni establece esa variable y la confianza de CA correspondiente en el entorno del agente. Un proceso iniciado con un entorno limpio llama directamente al host y su solicitud sale con el identificador.

Para una solicitud que Beeuni no puede interceptar, el agente dispone de una vía explícita a los mismos hosts con la misma política:

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

Exposición en el entorno

El entorno aislado recibe el valor real como una variable de entorno de texto sin formato. El código del agente puede leerlo, imprimirlo y enviarlo a cualquier parte. Beeuni no puede ocultarlo, ni auditar su uso ni impedir que salga.

La exposición en el entorno es la opción predeterminada. Todos los secretos nuevos usan esta opción, a menos que cambies el secreto a control de salida, que es experimental y requiere la marca secrets_egress. Una credencial calculada y cualquier protocolo que no sea HTTPS deben permanecer en el entorno.

Quién puede usar un secreto

Cada valor secreto tiene un público: la misma opción Quién puede usarlo que para una cuenta de conector:

Una sesión actúa como dos cosas a la vez: siempre como su agente y como su persona solo mientras la sesión sea privada.

• Una persona obtiene acceso a un valor en una sesión privada que esa persona ha iniciado. Un mensaje de cualquier otra persona elimina a la persona de la sesión, por lo que el valor deja de estar disponible. Las sesiones compartidas, los desencadenadores, las programaciones, los webhooks y las sesiones de correo electrónico y Telegram no tienen persona.
• Un agente obtiene acceso a un valor en todas las sesiones de ese agente, incluidos los desencadenadores, las programaciones y las sesiones compartidas. Comparte un valor con el agente si lo necesita para una ejecución desatendida. Cualquier persona que pueda ejecutar ese agente podrá usar el valor a través de él, así que ejecutar el agente es el control de acceso (quién puede ejecutar un agente se configura en el agente).
• Los consumidores del lado del servidor siguen la misma regla. Un conector vinculado al secreto solo lo usa si quien lo llama pertenece al público. Cualquier otra persona recibe credential_not_shared y ninguna solicitud sale de Beeuni.
• Los servicios de Beeuni que no actúan en nombre de nadie —el proxy de Git, las comprobaciones de firma de webhooks, las instalaciones de canales y las aplicaciones de Beeuni— solo usan valores compartidos con todos.

Varios valores pueden compartir un nombre. Un valor compartido con la persona de la sesión prevalece sobre uno compartido con su agente, y este, sobre el valor compartido con todos. Por ejemplo: DEEL_API_TOKEN contiene un valor para el equipo, y un segundo valor con el identificador DEEL_API_TOKEN-finance se comparte solo con el grupo de Finanzas. Los miembros de Finanzas obtienen el valor de Finanzas en sus sesiones privadas; todos los demás y todos los desencadenadores obtienen el valor del equipo.

Una persona configura el público. Una sesión de agente no puede cambiarlo (403), así que un agente no puede ampliar el acceso a un valor que se le haya restringido ni añadirse a sí mismo. Las personas que administran los secretos del proyecto siguen viendo un valor que no se comparte con ellas, marcado como No compartido contigo, para que puedan ampliar el acceso de nuevo.

Compartir una sesión que contiene un valor personal

Un valor compartido solo contigo que llegó a tu sesión privada como variable de entorno está en texto sin formato dentro de ese entorno aislado. Compartir la sesión permitiría que cualquier nueva persona con acceso lo leyera, y no se puede retirar una variable de entorno de un entorno aislado en ejecución. Por eso Beeuni se niega a compartir esa sesión o a crear un enlace público a ella si contiene 409 PERSONAL_SECRET_REQUIRES_PRIVATE_SESSION y los nombres que contiene. Inicia una sesión nueva para compartirla o comparte primero el valor con todos. Los valores a los que se accede a través del agente y los valores con control de salida o del lado del servidor (que se comprueban en cada solicitud) no impiden compartir la sesión.

Cuando restringes un público, Beeuni vuelve a enviar todos los entornos aislados en ejecución. Un valor que ya se haya entregado como variable de entorno permanece en un entorno aislado hasta que se reinicie. Si existe la posibilidad de que se haya leído, cámbialo.

Cuando introduces un valor mediante un enlace

Un agente que necesita un valor que no le has proporcionado te envía un enlace. La página del enlace ofrece la opción Quién puede usarlo: todos en el proyecto (opción predeterminada) o solo la persona que lo solicitó. Elige la segunda opción para cualquier dato personal, como un token de nómina o un inicio de sesión personal. La página muestra el nombre visible de la persona que lo solicitó, nunca su correo electrónico, porque cualquiera que tenga el enlace puede abrirlo.

Anulación personal

Una anulación personal es tu propio valor para un nombre, que se usa en lugar del valor compartido en las sesiones que inicias. Actualmente, Beeuni solo la usa para una credencial de inicio de sesión OAuth. Beeuni nunca permite que una clave de proveedor de LLM, por ejemplo ANTHROPIC_API_KEY, se convierta en una anulación personal.

Añadir un secreto

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

Conceder un secreto a un agente

Una sesión recibe un secreto solo cuando el agente que la ejecuta incluye el identificador en su lista secrets. La coincidencia se basa en el identificador, no en el nombre, y no distingue entre mayúsculas y minúsculas.

Desde el panel

La página Secrets marca los secretos que ningún agente puede recibir: Ningún agente puede recibir este secreto. Elige allí un agente y confirma. Beeuni edita beeuni.yaml y lo confirma como chore(agents): grant <IDENTIFIER> to <agent>.

La concesión funciona tanto si el manifiesto ya declara ese agente como si no. Si el agente no está declarado en el manifiesto, se añade una nueva entrada con esta única lista secrets. Si ya está declarado, conserva todos los demás campos —model, tools, connectors— y el identificador se agrega a su lista actual. Si el agente ya tiene acceso al identificador, no hace falta confirmar ningún cambio y Beeuni no lo hace.

Un agente en secrets: all es un caso especial. all no puede incluir un secreto con aplicación de egreso, así que Beeuni escribe una lista explícita con todos los identificadores que el proyecto tiene actualmente, más este. No cambia nada de lo que recibe el agente en este momento. Cualquier secreto que añadas más adelante necesitará su propia concesión.

Hay dos casos en los que se rechaza la concesión:

• Un proyecto en beeuni_version: 1 (beeuni.toml) no tiene un mapa de agentes que editar. La solicitud falla con 400 y manifest_v1_unsupported. Edita el manifiesto manualmente o cambia el proyecto a beeuni_version: 2.
• Un secreto Disabled no tiene ningún valor que entregar. La solicitud falla con 409 y secret_not_grantable. Asígnale primero una exposición.

Si el proyecto aún no tiene un bloque agents:, lee El primer bloque agents: cambia todo el proyecto antes de confirmar. Ese único cambio modifica el acceso a los secretos de todos los demás agentes.

Manualmente

La misma concesión, escrita directamente:

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

Cuando una sesión solicita un secreto que no se ha concedido a su agente

Un agente que necesita una credencial genera un enlace de secreto (beeuni secrets request). El valor que introduzcas se guarda aunque no se haya concedido al agente de la sesión. Esa sesión nunca lo recibe, así que Beeuni lo indica en todas las interfaces:

• El formulario del enlace muestra Guardado, pero <agent> aún no puede leerlo e indica el secreto.
• La respuesta de generación y el mensaje posterior a la sesión indican los nombres de withheld y cómo solucionarlo.
• Dentro de la sesión, beeuni secrets ls muestra una clave declarada fuera de la concesión como not granted, no como missing.

El agente no puede ampliar su propia concesión. Abre Customize → Agents → <agent> → Secrets y activa el secreto. Al guardarlo, Beeuni aplica el cambio a las sesiones activas del agente. El agente también puede obtenerlo de inmediato con beeuni secrets sync, y cada prompt vuelve a sincronizar los secretos de la sesión. No es necesario reiniciarla.

El primer bloque agents: cambia todo el proyecto

Por eso, incluye a todos los agentes que necesiten secretos, no solo al que estás configurando. Por eso el panel te pide confirmación la primera vez: después de ese cambio, agents: será la lista de permitidos del proyecto y cualquier agente que no figure en ella se ejecutará sin secretos del proyecto.

Exponer capacidades a usuarios de terceros

Si estás creando algo donde usuarios de terceros no confiables acceden a una capacidad —un chat público, una aplicación compartida o un agente al que cualquier persona en internet puede enviar prompts—, no les des acceso a las políticas de secretos. Todos los usuarios de esa interfaz comparten un agente de proyecto, una concesión y una lista de hosts. Beeuni no puede distinguir a un cliente tuyo de otro, así que cualquier secreto con aplicación de egreso al que pueda acceder el prompt de un usuario es una credencial que todos pueden usar, hasta el alcance total que tenga la clave del servicio externo.

Implementa por tu cuenta el límite que realmente necesitas:

1. Crea tu propio servicio de autorización y proxy. Este servicio guarda la credencial del servicio externo.
2. Dirige el agente a tu servicio, no al servicio externo. Dale al agente solo una credencial para tu servicio; esta puede configurarse con aplicación de egreso para tu propio host.
3. Tu servicio identifica al usuario final, aplica tus propias reglas de autorización y cuotas por usuario, y solo entonces llama al servicio externo con la credencial que guarda.

Ese servicio es donde corresponden las reglas por usuario: quién puede llamar a qué, con qué frecuencia y para qué registros. La exposición de secretos de Beeuni es una capa inferior y no la sustituye.

Listar tus secretos

Ejecuta beeuni secrets ls para ver qué secretos declara un proyecto y cuáles tienen un valor configurado.

La lista contiene metadatos de configuración. Nunca devuelve valores de secretos. Un token de agente con alcance solo ve los identificadores incluidos en la concesión de ese agente. Un secrets_allowlist específico de la sesión controla la entrega a esa sesión, pero no oculta los metadatos de configuración permitidos por la concesión del agente.

Rotar un secreto

beeuni secrets set STRIPE_API_KEY=sk_live_new...

Eliminar un secreto

Ejecuta beeuni secrets unset STRIPE_API_KEY (o unset <identifier>), o elimínalo desde la página Secrets del proyecto.

Compartir un valor sin verlo

Ejecuta beeuni secrets request STRIPE_API_KEY para crear un enlace. Cualquiera que tenga el enlace puede introducir el valor. Tú nunca lo ves. Los enlaces son válidos durante 7 días de forma predeterminada; ajusta este plazo con --expires <minutes> (máximo 30 días). Un enlace caducado muestra una página clara con el mensaje «caducado»: crea uno nuevo con el mismo comando.

Darle un valor directamente a un agente

Si pegas una clave en una sesión, el agente la guarda de inmediato con beeuni secrets set. No te envía un enlace. El agente necesita permiso para escribir secretos en el proyecto. Si no lo tiene, recibe 403 y crea un enlace para el secreto. Un agente puede guardar un secreto de entorno o un secreto de conector (--scope connector). La entrega con aplicación de políticas y las listas de hosts siguen siendo funciones exclusivas para las personas.

Ejemplo completo

beeuni.yaml:

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

Configuración de secretos. El primer comando guarda el valor con la exposición de entorno predeterminada. El segundo lo cambia a exposición con aplicación de salida, que es experimental y requiere la marca secrets_egress (Settings → Feature flags); devuelve 403 feature_disabled mientras la marca esté desactivada.

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

A continuación, el agente llama a Stripe con la variable que recibió:

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 identificador. Stripe recibe la clave real porque api.stripe.com está en la lista. La misma solicitud a un host que no está en la lista envía el identificador, que el servicio ascendente rechaza.

La misma solicitud de un agente cuya lista secrets omite STRIPE_API_KEY devuelve 401. Esa sesión se inicia con normalidad: un secreto sin autorización no es un error, simplemente nunca se entrega.

Comandos de CLI

La CLI conserva la terminología almacenada: runtime es la exposición de entorno, egress es la exposición con aplicación de salida y denied está desactivado. Ejecuta beeuni secrets --help para consultar todas las marcas.

De forma predeterminada, los enlaces de configuración usan connector. Usa --scope runtime solo si el shell del agente necesita recibir el valor. Un secreto vinculado a un conector permanece en el servidor.

Nombres y permisos

Reglas de formato para los dos nombres:

Para leer o escribir un secreto se necesita el permiso project.secret.read o project.secret.write. Un administrador del proyecto tiene ambos. Un rol personalizado solo añade permisos —Beeuni no tiene reglas de denegación—, así que ningún rol puede quitarle ninguno de los dos a un administrador. Para restringir a un administrador, quítale el rol de administrador.

La entrega a una sesión depende de los permisos de la persona que la inició, intersectados con la concesión del manifiesto del agente que se inició. Ambos deben permitir el secreto. Consulta Un vocabulario, dos vinculaciones.

Rutas REST

Todas las rutas están bajo /v1/projects/{projectId}.

POST /secrets rechaza los nombres que empiezan por BEEUNI_. Devuelve 409 si identifier ya existe con un name diferente. Rechaza el nombre exacto CODEX_AUTH_JSON con 400: Beeuni administra ese secreto mediante la incorporación de suscripciones a ChatGPT.

Ambas rutas de escritura devuelven un objeto delivery_sync cuando el cambio debe llegar a los sandboxes en ejecución. ok: false significa que el valor se guardó, pero al menos una sesión activa sigue usando el anterior; las sesiones indicadas lo recibirán al reiniciarse.

Un secreto de la lista incluye delivery_blocked_reason. El valor no_agent_grant significa que ningún agente puede recibir este secreto. null significa que está concedido, que la exposición no requiere una concesión o que Beeuni no pudo leer el manifiesto.

POST /secrets/{identifier}/grant elimina ese motivo. Devuelve already_granted: true si la lista del agente ya incluye el identificador; en ese caso, Beeuni no realiza ningún cambio. Devuelve adopted_governance: true cuando la edición añade el primer bloque agents: del proyecto, el cambio descrito arriba. Responde 400 manifest_v1_unsupported si el proyecto es beeuni.toml y 409 secret_not_grantable si el secreto está desactivado.

Rotación y propagación

La escritura de un secreto no espera a que se reinicie una sesión. Beeuni envía el cambio a todos los sandboxes activos del proyecto:

1. Beeuni crea una nueva instantánea del entorno usando la concesión secrets del agente en ejecución.
2. El sandbox escribe la instantánea en el entorno activo del agente. Las nuevas llamadas a herramientas reciben el cambio de inmediato.
3. Si el secreto modificado es una credencial de proveedor de LLM, Beeuni reinicia harness estándar.

Este envío se hace todo lo posible. La llamada a la API que cambia el secreto se devuelve antes de que termine el envío. Los fallos de envío solo se registran; no se vuelven a intentar. Un sandbox cuyo envío falla conserva el valor anterior hasta el siguiente envío correcto o hasta que se reinicie la sesión.

Credenciales de modelo

Un proyecto que usa el acceso administrado a modelos de Beeuni no necesita su propia clave. Para usar la tuya, configura las variables del proveedor a las que hace referencia la configuración de proveedor de harness estándar. A una clave de modelo reconocida se le asigna el uso de puerta de enlace de LLM, que la usa en el servidor; no es necesario que esté en el sandbox.

No uses un resultado genérico de verificación del proveedor como prueba del funcionamiento en tiempo de ejecución. No puede verificar el modelo, la región, los derechos de acceso ni el dialecto de API seleccionados. Envía una solicitud real al modelo exacto.