Ir al contenido
kovra kovra

Tutorial — un proyecto real

El inicio rápido es el recorrido de cinco minutos. Este es el largo: se toma un servicio chico — llamémoslo billing-api, con una base de datos y una API key de pagos — desde un .env plano hasta correrlo a través de kovra y dejar que un agente de IA trabaje en él sin ver nunca los secretos sensibles.

Asume que kovra está instalado. Cada caja tiene un selector de OS; las salidas mostradas son de macOS.

1. Inicializar el vault

Sección titulada «1. Inicializar el vault»

Desde el directorio del proyecto, crear el vault y su master key:

zsh
~/billing-api % kovra init
Initialized vault at ~/.vaults (OS keyring).

2. Sacar los secretos del .env

Sección titulada «2. Sacar los secretos del .env»

Supongamos que hoy la app lee un .env con un password de base de datos y una key de pagos. En vez de eso, poner esos valores en el vault — kovra lee cada uno desde un prompt oculto, así que nunca llega a argv ni al historial del shell:

zsh
~/billing-api % kovra add secret:dev/db/password
Added dev/db/password (Medium).
zsh
~/billing-api % kovra add secret:dev/app/api-key --description "Stripe test key"
Added dev/app/api-key (Medium).

Ahora lo mismo para producción. No hace falta marcarlos de forma especial — un secreto prod nace high automáticamente, así que nunca puede revelarse en silencio:

zsh
~/billing-api % kovra add secret:prod/db/password
Added prod/db/password (High).

Listar lo guardado — solo metadata, nunca valores:

zsh
~/billing-api % kovra list
┌────────┬─────────────────┬─────────────┬─────────┬─────────────┐
│ ORIGIN ┆ COORDINATE      ┆ SENSITIVITY ┆ MODE    ┆ FINGERPRINT │
╞════════╪═════════════════╪═════════════╪═════════╪═════════════╡
│ global ┆ dev/app/api-key ┆ medium      ┆ literal ┆ c8a476b5    │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ global ┆ dev/db/password ┆ medium      ┆ literal ┆ 73c128b4    │
└────────┴─────────────────┴─────────────┴─────────┴─────────────┘

3. Reemplazar .env por .env.refs

Sección titulada «3. Reemplazar .env por .env.refs»

Borrar el .env en texto plano y commitear un .env.refs en su lugar. Mapea los mismos nombres de variables a coordenadas — direcciones, no valores — así que es seguro en git:

# .env.refs — seguro para commitear; sin valores secretos.
project = billing-api


DATABASE_URL=secret:${ENV}/db/password
API_KEY=secret:${ENV}/app/api-key


LOG_LEVEL=${env:LOG_LEVEL | info}
PORT=8080

¿No está claro qué necesita el código? kovra scaffold --out .env.refs propone uno escaneando el código en busca de nombres de variables de entorno (nunca un valor).

4. Correr la app a través de kovra (dev)

Sección titulada «4. Correr la app a través de kovra (dev)»

Arrancar la app a través de kovra. Resuelve el .env.refs, busca cada valor y los inyecta directo en el proceso — nada se escribe a disco, argv ni al historial:

zsh
~/billing-api % kovra run --env dev -- your-app
app started · DATABASE_URL=14 chars · API_KEY set=yes · PORT=8080

La app tiene su configuración real; los secretos se usaron, no se vieron.

5. Producción: los dos guards

Sección titulada «5. Producción: los dos guards»

Apuntar el mismo comando a prod y kovra lo mide con una vara más alta. Un valor prod es high, y una inyección high/prod tiene dos guards independientes: debe apuntar a un ejecutable revisado y en el allowlist, y se detiene a pedir un bioProve. Al correrlo contra un programa no revisado, kovra se niega, por diseño:

zsh
~/billing-api % kovra run --env prod -- your-app
Error: `your-app` is not on the executor allowlist; high/prod injection refused

Agregar la herramienta de deploy revisada al allowlist con --allow y aprobar el prompt — un bioProve cubre todos los secretos de la corrida:

zsh
~/billing-api % kovra run --env prod --allow ./deploy -- ./deploy
# bioProve to inject prod/db/password, prod/app/api-key
deploying with DATABASE_URL=12 chars, API_KEY set=yes

6. Generar en vez de pegar

Sección titulada «6. Generar en vez de pegar»

Para un secreto nuevo — una key de firma de sesión — no inventarla y pegarla. Que kovra la genere server-side; el valor existe solo dentro del vault, nunca en pantalla:

zsh
~/billing-api % kovra generate secret:dev/app/session-secret --length 48
Generated dev/app/session-secret (48 chars, Medium) — value stored, not shown.

7. Entregárselo a un agente de IA

Sección titulada «7. Entregárselo a un agente de IA»

Ahora el premio. Onboardear el repo para que un agente de código pueda trabajar con estos secretos de forma segura:

zsh
~/billing-api % kovra setup
Vault ready; project `billing-api`.
Updated .mcp.json (register the kovra MCP server).
Updated CLAUDE.md (insert/update the kovra conventions block).
Setup complete. Review CLAUDE.md and .mcp.json, then reload your agent to pick up the MCP server.

A partir de acá, el agente puede ver que dev/db/password y dev/app/api-key existen, razonar sobre el proyecto y correr los tests con los valores inyectados — pero el texto plano de los secretos high/prod/inject-only nunca entra a su contexto. Si se le pide leer la key prod, se le niega, sin más. Ver kovra sobre MCP para exactamente qué puede y qué no puede hacer el agente.

8. Mantener los secretos fuera de git

Sección titulada «8. Mantener los secretos fuera de git»

Por último, una red de seguridad para el día en que alguien pegue un valor real en un archivo por error. Instalar el hook de pre-commit:

zsh
~/billing-api % kovra hooks install
Wrote ./.gitleaks.toml
Installed the gitleaks pre-commit hook at ./.git/hooks/pre-commit.

Ahora un commit que filtraría un secreto queda bloqueado antes de entrar a la historia.

El resultado

Sección titulada «El resultado»

billing-api ahora no guarda ningún secreto en texto plano en el repo ni en el entorno. Desarrolladores y agentes lo corren a través de kovra; dev es sin fricción, producción está gateada y es atribuible, y los valores sensibles nunca salen del vault. Desde acá: