Secrets

Chinaski mantiene sus valores secretos importantes (el secret maestro sobre el que corre, y las credenciales de los servicios con los que habla) fuera del texto plano y fuera de la vista. Esta página explica cómo funciona CHINASKI_SECRET, qué settings se almacenan cifradas y qué sucede si rotas el secret maestro.

La variable de entorno CHINASKI_SECRET

Este es el único secret maestro de una instancia de Chinaski, y debe existir antes de que arranque el servidor: sin él el CMS se niega a correr del todo.

Protege dos cosas:

1. Sesiones de admin. La cookie de tu sesión de sign-in está firmada criptográficamente con esta key. Los usuarios nunca la ven ni la manejan.
2. Almacenamiento cifrado. La key de cifrado que protege las credenciales almacenadas en la base de datos se deriva de ella. Esas credenciales nunca se escriben a disco en texto plano.

Generarla es un paso de una sola vez que el instalador hace por ti en el deployment estándar: el valor se escribe en un archivo env con permisos bloqueados (0600, dentro de un directorio 0700) que solo el usuario de servicio del CMS puede leer. En el flujo de instalación offline, la receta es:

export CHINASKI_SECRET=$(openssl rand -hex 32)    # do this once; save the value

Nunca lo commitees a repositorios, no lo compartas entre instancias, y conserva una copia en algún lugar seguro; no puedes recuperarlo del sistema corriendo.

Qué se almacena cifrado

Varias settings en el área de admin son valores sensibles a la seguridad y se almacenan cifrados en la base de datos. Las settings secretas registradas son:

• Contraseña SMTP
• Webhook secret
• Deploy S3 secret key
• Turnstile secret key
• Backup (Spaces) secret key
• OAuth client secret

El cifrado es autenticado (AES-256-GCM con un nonce aleatorio por valor y una tag de integridad). Los valores cifrados se almacenan con un prefijo de versión para que el formato pueda evolucionar. Si una fila fue escrita por una versión anterior en texto plano, el sistema la tolera hasta que la setting se guarda de nuevo, punto en el cual se actualiza a forma cifrada.

Secrets y la API

La API de lectura nunca devuelve settings secretas: se eliminan de la respuesta incluso para las API keys autenticadas. Las escrituras por API cifran un nuevo valor de la misma manera que la UI de admin. Las integraciones de terceros no pueden leer tus credenciales almacenadas a través de la API.

Rotación del secret maestro

Cambiar CHINASKI_SECRET es una operación seria con consecuencias conocidas:

• Todos quedan deslogueados. Las cookies de sesión existentes fueron firmadas con la key vieja y se vuelven inválidas en el momento en que la nueva key surte efecto; todos los admins y editores deben iniciar sesión de nuevo. No hay superposición ni key de fallback.
• Las credenciales almacenadas dejan de funcionar. Las credenciales cifradas de la base de datos (SMTP, webhook, Turnstile, OAuth, S3, backup) fueron cifradas bajo una key derivada del secret viejo. Con el secret nuevo no pueden descifrarse.
• Arreglarlo significa re-guardar. Después de la rotación, abre las settings relevantes en el área de admin y re-guarda cada valor de credencial para que se recifre bajo la nueva key. Esta misma acción actualiza cualquier valor legacy de texto plano que aún puedas tener.

No hay un comando integrado para automatizar la migración de secrets almacenados a través de una rotación en el release actual; planea la rotación: elige una ventana de mantenimiento, rota el valor del env, reinicia la instancia, inicia sesión fresco y re-guarda cada setting afectada. Prueba el correo, los webhooks y cualquier otra integración configurada después.

Prácticas de higiene que el sistema aplica

• Los secrets viven solo en el entorno o en valores de base de datos cifrados; la aplicación conserva una copia en texto plano en memoria solo donde se necesita para hablar con un servicio.
• El archivo de base de datos y el archivo env son legibles solo por el dueño; el directorio de backups es solo del dueño. Las instalaciones estándar los ponen dentro de directorios a los que solo el usuario de servicio chinaski puede acceder.
• La herramienta de setup por script prefiere leer la contraseña de admin de una variable de entorno en lugar de una flag de línea de comandos, así que la contraseña no aparece en la lista de procesos durante el setup.
• Para hosts aislados/airgapped, establecer CHINASKI_AIRGAP=1 deshabilita cada llamada saliente que el CMS pudiera hacer; nada de tu deployment necesita salir de la máquina para que el núcleo corra.