Gestión de secretos y variables de entorno

En una aplicación de React, las variables de entorno pertenecen a dos clases: del lado del servidor (nunca se envían al navegador) y del lado del cliente (se incorporan al bundle de JavaScript). Entender a qué clase pertenece cada variable es el primer paso para gestionar secretos, porque las variables del lado del cliente son, en la práctica, públicas una vez desplegado el bundle.

En los proyectos de Vite, solo las variables con el prefijo VITE_ se incluyen en el bundle del cliente. VITE_PUBLIC_API_URL=https://api.example.com está disponible en el código del navegador mediante import.meta.env.VITE_PUBLIC_API_URL. Todas las demás variables se eliminan del bundle en tiempo de compilación y permanecen solo en el servidor.

En Next.js, el prefijo NEXT_PUBLIC_ expone una variable al JavaScript del navegador. NEXT_PUBLIC_ANALYTICS_ID=UA-123 se incorpora al bundle del cliente. Las variables sin el prefijo (como DATABASE_URL) solo están disponibles en el código del servidor (Server Components, API routes y Server Actions) y nunca se envían al navegador.

Una variable sin prefijo sigue siendo accesible si se serializa accidentalmente. Por ejemplo, si un Server Component pasa su objeto de configuración completo como prop a un Client Component y esa configuración incluye DATABASE_URL, el secreto aparece en el HTML enviado al navegador. Un paso cuidadoso de props y una auditoría de la serialización evitan esto.

Lo siguiente nunca debe aparecer en el bundle del cliente: cadenas de conexión y contraseñas de bases de datos, claves secretas de API de terceros (Stripe secret key, OpenAI API key), claves privadas RSA/EC, secretos de firma de JWT y tokens internos de autenticación de servicios. Si necesita alguno para una llamada a una API, haga que la llamada pase por un endpoint del servidor.

El patrón Backend for Frontend (BFF) sitúa una capa de servidor delgada entre la aplicación React y los servicios externos sensibles. El cliente llama a /api/stripe/charge, el servidor BFF añade la clave secreta de Stripe y llama a la API de Stripe, y el BFF devuelve solo los datos de respuesta necesarios. Los secretos permanecen permanentemente en el servidor.

dotenv-vault cifra su archivo .env y permite compartirlo y desplegarlo de forma segura entre entornos sin registrar secretos en texto plano en el control de versiones. Entre las alternativas para producción se incluyen HashiCorp Vault (empresarial), AWS Parameter Store (SSM) y GCP Secret Manager; todos proporcionan recuperación de secretos mediante API en tiempo de ejecución, en lugar de durante la compilación.

Las plataformas de CI/CD (GitHub Actions, GitLab CI) ofrecen almacenamiento cifrado de secretos accesible como variables de entorno durante las compilaciones. Almacene los secretos en GitHub Secrets y haga referencia a ellos en los workflows como ${{ secrets.STRIPE_SECRET_KEY }}. Los secretos se enmascaran en los registros y nunca se incluyen en el artefacto compilado.

Next.js y Vite admiten varios archivos .env: .env (todos los entornos), .env.local (anulaciones locales, ignorado por Git), .env.development y .env.production. El archivo local reemplaza los valores del archivo compartido, lo que permite una configuración específica para cada desarrollador sin afectar a los demás entornos.

Después de compilar, audite el bundle de JavaScript en busca de secretos expuestos accidentalmente. Ejecute grep -r "password|secret|api_key" dist/ o utilice una herramienta específica como strings para analizar los archivos compilados. Algunos secretos, si se incluyen accidentalmente, se pueden identificar claramente por su formato (UUID, cadenas base64 o prefijos de clave como sk_live_).

Cada entorno y cada servicio solo debe tener acceso a los secretos que necesita. El cliente React no necesita ningún secreto; solo debe recibir identificadores públicos. El servidor BFF solo necesita los secretos requeridos por las API a las que llama. Los entornos de desarrollo deben usar claves de API que no sean de producción, con permisos limitados y límites de gasto.

¿Qué ocurre con una variable de entorno de Next.js que tiene el prefijo NEXT_PUBLIC_?

Vite utiliza VITE_ y Next.js utiliza NEXT_PUBLIC_ para exponer variables al bundle del navegador. Todas las demás variables solo están disponibles en el servidor. Nunca incluya contraseñas de bases de datos, claves secretas de API ni secretos de firma de JWT en el código del cliente. Use el patrón BFF para poner las llamadas a API sensibles detrás de un proxy. Use dotenv-vault, AWS Parameter Store o GitHub Secrets para gestionar los secretos en producción. Audite los bundles compilados en busca de secretos expuestos accidentalmente.