Gestión de secretos

Almacena y administra valores de configuración sensibles con cifrado AES-256-GCM, acceso por alcance y rotación sin tiempo de inactividad.

Cómo sh0 cifra los secretos

Todos los secretos (variables de entorno marcadas como sensibles) se cifran en reposo en la base de datos SQLite de sh0 usando cifrado autenticado AES-256-GCM, con la biblioteca criptográfica ring.

El flujo de cifrado:

1. Se genera una clave de cifrado única de 256 bits durante la instalación de sh0 y se almacena en el directorio de configuración del servidor.
2. Cada valor de secreto se cifra con un nonce único (96 bits aleatorios), asegurando que valores idénticos produzcan textos cifrados diferentes.
3. La etiqueta de autenticación (GCM) garantiza que los secretos no puedan ser alterados sin detección.
4. Los secretos solo se descifran en memoria cuando se inyectan en los contenedores al inicio.

Agregar secretos vía panel de control

La forma más común de administrar secretos es a través del panel de Variables de entorno del panel de control.

1. Navega a tu aplicación y abre Configuración → Variables de entorno.
2. Haz clic en Agregar variable.
3. Ingresa el nombre de la variable (por ejemplo, DATABASE_URL).
4. Ingresa el valor.
5. Cada valor se cifra antes de guardarse; no hay nada que activar.
6. Haz clic en Guardar.

Vía la API:

curl -X POST https://panel.example.com/api/v1/apps/APP_ID/env-vars \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "DATABASE_URL",
    "value": "postgres://user:pass@db:5432/mydb"
  }'

Importación masiva desde archivo .env

Si tienes un archivo .env existente, puedes importar todas las variables de una vez.

1. En el panel de Variables de entorno, haz clic en Importación masiva.
2. Pega el contenido de tu archivo .env o súbelo directamente.
3. sh0 analiza el archivo y muestra una vista previa de todas las variables.
4. Revisa, marca los valores sensibles como secretos y haz clic en Importar.

El analizador admite la sintaxis estándar de .env:

# Database
DATABASE_URL=postgres://user:pass@db:5432/mydb
REDIS_URL=redis://redis:6379

# API Keys
STRIPE_SECRET_KEY=sk_live_abc123
SENDGRID_API_KEY=SG.xyz789

# App Config
NODE_ENV=production
PORT=3000

Alcance de secretos

Los secretos se pueden asignar a dos niveles, dándote control sobre qué contenedores tienen acceso a qué valores.

Secretos a nivel de stack

Los secretos a nivel de stack se comparten entre todos los servicios del stack. Esto es ideal para configuración compartida como credenciales de base de datos que múltiples servicios necesitan.

Establece un secreto a nivel de stack desde Configuración del stack → Variables de entorno, o vía la API:

curl -X POST https://panel.example.com/api/v1/projects/PROJECT_ID/env-vars \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "DATABASE_URL",
    "value": "postgres://user:pass@db:5432/mydb"
  }'

Secretos a nivel de aplicación

Los secretos a nivel de aplicación son específicos de un solo servicio. Tienen precedencia sobre los secretos a nivel de stack con el mismo nombre, permitiéndote anular valores compartidos para servicios individuales.

Rotación de secretos

Rotar un secreto significa actualizar su valor y volver a desplegar la app que lo usa:

1. Actualice el valor en el panel o mediante la API.
2. Vuelva a desplegar la app: el nuevo contenedor arranca con el nuevo valor.
3. El contenedor anterior sigue atendiendo el tráfico hasta que el nuevo supera su comprobación de salud.
4. Después, el tráfico pasa al nuevo contenedor.

curl -X PATCH https://panel.example.com/api/v1/apps/APP_ID/env-vars/ENV_ID \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "sk_live_new_key_456"
  }'

curl -X POST https://panel.example.com/api/v1/apps/APP_ID/deployments \
  -H "Authorization: Bearer $SH0_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Acceder a secretos en contenedores

Los secretos se inyectan en los contenedores como variables de entorno estándar. Tu aplicación los accede de la misma manera que accedería a cualquier variable de entorno:

const dbUrl = process.env.DATABASE_URL;
const stripeKey = process.env.STRIPE_SECRET_KEY;

import os
db_url = os.environ["DATABASE_URL"]
stripe_key = os.environ["STRIPE_SECRET_KEY"]

let db_url = std::env::var("DATABASE_URL")?;
let stripe_key = std::env::var("STRIPE_SECRET_KEY")?;

Los secretos se establecen al iniciar el contenedor y permanecen disponibles durante toda la vida del contenedor. No se escriben en disco dentro del contenedor.