Qué es un gestor de secretos (y por qué tu .env no lo es)

Todo proyecto tiene secretos: claves de API, tokens de bases de datos, credenciales de terceros. Y casi todos los equipos los gestionan igual: un archivo .env en la raíz del repo, con un .gitignore que promete protegerlo. Ese archivo no es un gestor de secretos. Es solo texto plano con buenas intenciones.

Un gestor de secretos (secrets manager) es un sistema diseñado específicamente para almacenar, cifrar, distribuir y auditar credenciales sensibles, separándolas por completo del código y del control de acceso genérico del sistema de ficheros. Un .env no hace nada de eso: solo guarda cadenas de texto en un fichero.

¿Qué es exactamente un gestor de secretos?

Un gestor de secretos serio cumple, como mínimo, estas propiedades:

• Cifrado real, en reposo y en tránsito — no solo "el fichero está en un servidor privado".
• Control de acceso granular, por entorno (dev, staging, prod) y por servicio o persona.
• Auditoría: quién accedió a qué secreto, cuándo y desde dónde.
• Rotación y revocación de credenciales sin tener que redeployar medio sistema.
• Ningún secreto en texto plano llega a tocar disco, logs, ni historial de comandos.

Un .env no cumple ninguno de estos puntos por diseño. Nació como una convención de conveniencia (dotenv y frameworks tipo Rails lo popularizaron), no como una herramienta de seguridad.

Por qué tu .env no es un gestor de secretos

Vive en texto plano, siempre

cat .env
DATABASE_URL=postgres://user:pass@host:5432/db
STRIPE_SECRET_KEY=sk_live_51H...
OPENAI_API_KEY=sk-proj-...

Cualquiera con acceso de lectura al filesystem —un desarrollador, un backup mal configurado, una imagen Docker que no debería incluirlo, un proceso de CI con permisos de más— puede leer esas claves directamente. No hay cifrado, no hay control, no hay fricción.

Acaba filtrándose en git, tarde o temprano

El .gitignore ayuda, pero no es infalible: un git add -A sin mirar, un fork que copia el .env.example mal nombrado, un commit antiguo en el historial que nadie limpió. Cada día se filtran secretos en repositorios públicos por errores exactamente así, y existen bots que escanean GitHub buscando patrones de claves activas en cuestión de minutos.

Comprobar tu propio historial es sencillo y suele dar sustos:

git log -p --all | grep -iE \"sk_live|AKIA|-----BEGIN\"

No tiene control de acceso ni trazabilidad

Con un .env, quien tiene el fichero tiene todo: la clave de Stripe, la de la base de datos y la del proveedor de IA, todas juntas. No puedes dar acceso solo al secreto de producción a una persona y no a otra, ni saber después quién lo leyó o cuándo.

La IA generando código empeora el problema

Los asistentes de código (Copilot, Cursor, agentes tipo Claude Code) leen el repo completo para trabajar, y eso incluye el .env si está en el directorio del proyecto. Un secreto puede acabar citado en una sugerencia, en un log de conversación, o pegado sin querer en un commit generado automáticamente. En /ai-security explicamos por qué el código generado por IA multiplica la superficie de exposición de secretos, no solo por errores humanos sino por el propio flujo de trabajo del agente.

Qué debería hacer un gestor de secretos de verdad

Además de las propiedades básicas, un gestor de secretos moderno debería permitir:

1. Que el código solo referencie el nombre del secreto, nunca el valor.
2. Que el secreto se descifre solo en el punto de consumo (backend autorizado o dispositivo verificado), no en tránsito por servidores intermedios en texto plano.
3. Revocar hacia adelante: cortar el acceso futuro a un secreto de forma inmediata. Esto no borra copias que ya se descargaron antes de revocar — para eso hace falta rotar la credencial subyacente en el proveedor original (Stripe, AWS, OpenAI, etc.).
4. Integrarse con el flujo real de desarrollo: CLI, SDK, CI/CD, sin fricción añadida.

Cómo lo resuelve Koove

Koove es un gestor de secretos de conocimiento cero (zero-knowledge): el servidor solo almacena ciphertext, nunca ve el valor real de tus claves. El cifrado usa envelope encryption con X25519 y AES-256-GCM sobre primitivas abiertas y auditables.

En la práctica, en vez de escribir la clave en un .env, la guardas una vez:

koove set STRIPE_SECRET_KEY sk_live_51H... --env prod

Y tu código solo referencia el nombre:

import { getSecret } from \"@koove/sdk\";

const stripeKey = await getSecret(\"STRIPE_SECRET_KEY\");

El valor real nunca aparece en el repo, ni en el historial de chat de tu asistente de IA, ni en un log de CI. El secreto se descifra únicamente en consumidores verificados: apps móviles autenticadas con Play Integrity o App Attest más biometría, o backends autorizados explícitamente. Toda la referencia de comandos y SDKs está en /docs/sdk.

Este flujo encaja especialmente bien cuando es tu propio asistente de IA quien añade nuevas integraciones al proyecto: puede ejecutar koove set para guardar una clave nueva sin que esa clave llegue jamás a tocar el código fuente que genera.

Limitaciones honestas

Koove reduce drásticamente la superficie de exposición de secretos, pero no convierte tu aplicación en invulnerable. La seguridad global sigue dependiendo de cómo proteges el acceso a tu cuenta de Koove, tus dispositivos y las credenciales de tu CI. Revocar un secreto detiene el acceso futuro, pero no puede "des-descargar" copias que un consumidor ya obtuvo antes de la revocación — si sospechas de un compromiso, rota también la credencial en el proveedor original. Y, siendo honestos, Koove no ostenta certificaciones SOC 2 o ISO; si eso es un requisito duro para tu organización, es mejor saberlo ahora que después. Puedes revisar más detalles en el /faq.

Cómo empezar

1. Crea una cuenta en /register.
2. Instala la CLI y ejecuta koove set para tu primer secreto.
3. Sustituye las llamadas a process.env por getSecret() del SDK.
4. Revisa /plans si necesitas entornos separados para equipo o producción.

Un .env puede seguir siendo útil para configuración no sensible — pero para claves de API, tokens y credenciales, necesitas algo que de verdad se llame gestor de secretos. Si quieres ver cómo encaja esto en un flujo de desarrollo asistido por IA, echa un vistazo a /ai-security o regístrate y prueba koove set en tu próximo proyecto.