El contrato .env.refs

.env.refs es cómo se conectan los secretos del vault a los procesos. Mapea cada nombre local de variable de entorno a una fuente — casi siempre una coordenada del vault. Como contiene direcciones, no valores, es seguro versionarlo en el repo. El vault contiene los valores; este archivo contiene solo dónde encontrarlos.

#.env.refs — safe to commit; contains no secret values.
project = my-app

# Vault-backed, parameterized by --env (${ENV} is substituted at run time).
DATABASE_URL=secret:${ENV}/db/password
API_KEY=secret:${ENV}/app/api-key

# Passthrough from the execution environment, with a fallback if unset.
LOG_LEVEL=${env:LOG_LEVEL | info}

# A plain literal (not a secret).
PORT=8080

Ejecutar un comando con todo resuelto e inyectado en el proceso hijo — nada escrito en disco, argv ni historial del shell:

macOS

zsh

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

Windows

PowerShell

PS C:\my-app> kovra run --env dev -- your-app
app started · DATABASE_URL=14 chars · API_KEY set=yes · PORT=8080

Tipos de línea

Forma	Significado
NAME=secret:<env>/<comp>/<key>	Una coordenada del vault. Puede usar ${ENV}. Un | fallback opcional aplica si no resuelve.
NAME=${env:VAR}	Un passthrough desde el entorno de ejecución. Soporta ${env:VAR | fallback}.
NAME=literal	Un valor literal (no un secreto), p. ej. PORT=8080.
project = <name>	Vincula este archivo a un vault de proyecto (la resolución lo apunta).

Reglas que lo mantienen seguro

• Nunca valores. El archivo contiene solo direcciones — por eso versionarlo es seguro y por eso un .env.refs filtrado no expone nada.
• La única interpolación es ${ENV} dentro del segmento de entorno de una coordenada, y la forma de passthrough ${env:NAME}. La interpolación entre variables se rechaza — no se puede componer un secreto dentro del string de otra variable, porque ese string compuesto quedaría logueado y anularía la política. Componer secretos es tarea de la aplicación, no del contrato.
• La resolución es una única pasada ordenada sobre el archivo.

Dejar que kovra lo escriba

No hace falta redactar .env.refs a mano. kovra scaffold escanea el código fuente del repo en busca de referencias a variables de entorno y propone un archivo inicial — lee solo los nombres de las variables, nunca un valor (nunca lee un archivo .env*):

macOS

zsh

~/my-app % kovra scaffold --out .env.refs
Wrote 2 proposed coordinate(s) to .env.refs — review before use.

Windows

PowerShell

PS C:\my-app> kovra scaffold --out .env.refs
Wrote 2 proposed coordinate(s) to .env.refs — review before use.

Y kovra doctor (alias kovra lint) lo valida: que cada coordenada resuelva, sin entradas huérfanas del vault, sin fallback de prod, las referencias reportadas por status — coordenadas y status solamente, nunca un valor.

macOS

zsh

~/my-app % kovra doctor --env dev
doctor: clean — no findings (env `dev`).

Windows

PowerShell

PS C:\my-app> kovra doctor --env dev
doctor: clean — no findings (env `dev`).