El vault

El vault es donde kovra guarda los secretos. Es un almacén local y cifrado — nada sale de la máquina a menos que se comparta explícitamente.

Cifrado en reposo

Cada entrada se cifra con ChaCha20-Poly1305 bajo una master key por vault. Esa clave nunca se manipula directamente: se custodia en el keychain del SO (el macOS Keychain en la plataforma de referencia), y kovra la carga solo para cifrar y descifrar. La memoria que porta secretos se zeroiza tras su uso, de modo que un valor no perdura en la memoria del proceso.

macOS

zsh

~/my-app % kovra init
Initialized vault at ~/.vaults (OS keyring).

Windows

PowerShell

PS C:\my-app> kovra init
Initialized vault at %LOCALAPPDATA%\kovra\vaults (Credential Manager).

Recuperación ante desastres

La master key es la raíz de confianza de todo el vault — si se pierde, las entradas cifradas son irrecuperables. kovra key export escribe un respaldo cifrado y protegido por passphrase (un blob age estándar) que se puede guardar en un gestor de contraseñas; kovra key import lo restaura. La clave en plaintext nunca aterriza en un archivo.

Vaults globales vs. de proyecto

kovra resuelve secretos contra dos scopes:

• Un vault global — los secretos personales, a nivel de toda la máquina.
• Un vault de proyecto — secretos acotados a un repositorio.

Por defecto un vault de proyecto prevalece sobre el vault global en la coordenada exacta: si ambos definen secret:dev/db/password, gana el del proyecto. La mayoría de los comandos aceptan un flag --project <name> para apuntar a un vault de proyecto específico en lugar del global.

Cuando se necesita saltarse el override y leer el valor global explícitamente, se usa el selector de scope global dentro de la propia coordenada:

secret://global/dev/db/password # resolve only against the global vault

Ver Coordenadas para la gramática completa de direcciones.

Qué se almacena — y qué no

Una entrada del vault contiene el valor cifrado más metadatos: su coordenada, su nivel de sensibilidad, una descripción opcional, y flags como si es una referencia o si está habilitada para reveal del lado del agente. El listado y la auditoría operan sobre estos metadatos — nunca tocan el valor:

macOS

zsh

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

Windows

PowerShell

PS C:\my-app> kovra list
┌────────┬─────────────────┬─────────────┬─────────┬─────────────┐
│ ORIGIN ┆ COORDINATE      ┆ SENSITIVITY ┆ MODE    ┆ FINGERPRINT │
╞════════╪═════════════════╪═════════════╪═════════╪═════════════╡
│ global ┆ dev/app/api-key ┆ medium      ┆ literal ┆ c8a476b5    │
├╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ global ┆ dev/db/password ┆ medium      ┆ literal ┆ 73c128b4    │
└────────┴─────────────────┴─────────────┴─────────┴─────────────┘

macOS

zsh

~/my-app % kovra audit
TIMESTAMP             ACTION  COORDINATE       SENS    ORIGIN  FPR  RESULT
2026-06-05T19:29:26Z  create  dev/db/password  medium  human   -    created
2026-06-05T19:29:51Z  reveal  dev/app/api-key  medium  human   -    revealed
2026-06-05T19:32:44Z  inject  dev/db/password  medium  human   -    injected
3 event(s).

Windows

PowerShell

PS C:\my-app> kovra audit
TIMESTAMP             ACTION  COORDINATE       SENS    ORIGIN  FPR  RESULT
2026-06-05T19:29:26Z  create  dev/db/password  medium  human   -    created
2026-06-05T19:29:51Z  reveal  dev/app/api-key  medium  human   -    revealed
2026-06-05T19:32:44Z  inject  dev/db/password  medium  human   -    injected
3 event(s).

No toda entrada es un secreto literal. Una entrada puede ser, en cambio, una referencia — un puntero a un valor en un proveedor cloud (azure-kv://, aws-sm://) que se resuelve en tiempo de ejecución bajo la identidad propia — o una credencial tipada como un enrolamiento TOTP o un keypair asimétrico, donde la semilla cruda o la mitad privada nunca se revela. Eso se cubre en sus propias secciones.