Gestionar secretos y claves

Use este inventario para decidir qué valores pertenecen al entorno de ejecución, cuáles se generan en la base de datos y cuáles almacenan los plugins. Cada sección indica cómo afecta la rotación a un sitio en funcionamiento.

En Node.js, coloque los secretos de ejecución en el gestor de secretos de la plataforma de alojamiento para que entren en process.env cuando se inicie el proceso. Para un Worker, use wrangler secret put. No coloque valores secretos en astro.config.mjs, wrangler.jsonc ni import.meta.env; Vite puede incrustar valores de tiempo de compilación en el bundle del servidor.

Resumen

La clave de cifrado

EMDASH_ENCRYPTION_KEY cifra los ajustes de plugin declarados con type: "secret". EmDash usa AES-GCM con el ID del plugin y la clave del ajuste como datos autenticados. Un valor con formato incorrecto genera un mensaje de inicio dirigido al operador, y las operaciones que necesitan ajustes de plugin cifrados fallan de forma cerrada. Las solicitudes del sitio no relacionadas siguen funcionando.

El siguiente comando genera un valor con el formato correcto. Guárdelo en el entorno de ejecución o como secreto de Worker si su despliegue usa esta variable.

npx emdash secrets generate
# emdash_enc_v1_<43 base64url chars>

# Cloudflare:
wrangler secret put EMDASH_ENCRYPTION_KEY

El formato es emdash_enc_v1_ seguido de 32 bytes aleatorios en base64url sin relleno. El valor lo proporciona el operador y no se almacena en la base de datos. Consérvelo en un gestor de secretos y en una copia de seguridad de recuperación independiente.

Para rotar la clave, anteponga un valor nuevo y conserve el valor anterior tras una coma:

EMDASH_ENCRYPTION_KEY=emdash_enc_v1_<new-key>,emdash_enc_v1_<old-key>

EmDash cifra los valores nuevos y los guardados de nuevo con la primera clave. Usa la huella kid almacenada para seleccionar una clave anterior al leer. Vuelva a guardar cada secreto de plugin antes de eliminar la clave anterior y, a continuación, verifique esas integraciones desde un despliegue que contenga únicamente la clave nueva. Actualmente EmDash no informa de qué ID de clave siguen en uso, así que mantenga un inventario de las credenciales que vuelve a guardar y no elimine una clave anterior hasta que cada integración haya superado esa verificación.

Secretos de sitio generados

Dos secretos se generan automáticamente en el primer uso y se persisten en la tabla options, por lo que son estables entre solicitudes, despliegues e isolates. La generación es atómica: los arranques en frío concurrentes convergen en un único valor.

Secreto de preview

Firma las URL de preview (HMAC). Se almacena como emdash:preview_secret; 32 bytes aleatorios, base64url.

• Sobrescritura: defina EMDASH_PREVIEW_SECRET (alias heredado: PREVIEW_SECRET) si necesita el mismo secreto en varios procesos o quiere fijarlo por motivos de auditoría. El entorno siempre prevalece sobre el valor almacenado.
• Rotación: elimine la fila emdash:preview_secret (o cambie la variable de entorno) y vuelva a desplegar. Impacto: los enlaces de preview emitidos anteriormente dejan de validarse. Nada más se rompe: se genera un secreto nuevo (o se lee del entorno) en la siguiente solicitud de preview.
• Si se pierde: nada es irrecuperable. Los enlaces de preview son de corta duración por diseño.

Consulte la guía de preview para saber cómo se construyen y verifican las URL de preview.

Sal de IP

Añade sal al hash SHA-256 de las direcciones IP de quienes comentan (ip_hash en los comentarios) que se usa para limitar la frecuencia de los comentarios. Se almacena como emdash:ip_salt. Es específica del sitio, por lo que los hashes no se pueden correlacionar entre instalaciones de EmDash.

• Sobrescritura: defina EMDASH_IP_SALT. Por compatibilidad con versiones anteriores, también se consultan EMDASH_AUTH_SECRET / AUTH_SECRET: las instalaciones que históricamente derivaban la sal de esas variables mantienen hashes estables.
• Rotación: cambie la variable de entorno o elimine la fila emdash:ip_salt y, a continuación, vuelva a desplegar. Impacto: los nuevos envíos de comentarios generan hashes distintos, por lo que el recuento del límite de frecuencia se reinicia para todos. Los comentarios existentes y sus hashes almacenados no se modifican.
• Si se pierde: sin pérdida de datos. Solo se reinicia la continuidad del límite de frecuencia.

Tokens de sesión y API

• Las sesiones usan el almacén de sesiones de Astro (Workers KV en Cloudflare, sistema de archivos en Node). Los adaptadores que no configuran un almacén, como Vercel, necesitan un controlador de sesión en astro.config.mjs; sin él, el inicio de sesión falla con un error que explica que se requiere un controlador de sesión. La cookie contiene un ID de sesión opaco; no hay ningún secreto de firma que gestionar. Cierre la sesión para terminarla, o vacíe el almacén de sesiones (p. ej., el namespace de KV) para obligar a todos a iniciar sesión de nuevo.
• Los tokens de API (prefijos ec_pat_, ec_oat_, ec_ort_) son valores aleatorios opacos de 256 bits; solo se almacena su hash SHA-256. El texto plano se muestra una sola vez al crearlo. Rote el token revocándolo y volviéndolo a crear en el admin.
• Los tokens de invitación, de enlace mágico y de recuperación tienen un único propósito, se almacenan como hashes SHA-256 en auth_tokens y tienen una duración limitada (invitaciones 7 días, enlaces mágicos 15 minutos).

No hay nada que respaldar ni rotar de forma proactiva: una filtración de la base de datos solo expone hashes, y todos los tokens se pueden revocar o volver a emitir desde el admin.

Credenciales de servicio proporcionadas por el usuario

Las credenciales de servicios externos se leen del entorno y nunca se escriben en la base de datos. Rótelas en el proveedor, actualice la variable y vuelva a desplegar.

En Cloudflare, defínalas con wrangler secret put; para el desarrollo local, colóquelas en .env. Wrangler lee .dev.vars o .env, no ambos, y .dev.vars tiene prioridad cuando existe. R2 mediante un binding no necesita variables de clave de acceso porque el binding concede el acceso en tiempo de ejecución. Consulte almacenamiento de medios.

En Node, EmDash lee la clave secreta de Turnstile del entorno de proceso del servidor cuando llega una solicitud, y ni astro dev ni el servidor compilado cargan .env en él. Defina la clave en el entorno de su host, expórtela en el shell que ejecuta astro dev o inicie el servidor compilado con node --env-file=.env ./dist/server/entry.mjs.

Secretos de plugin

Los ajustes que un plugin declara con type: "secret" (claves de API de proveedores de correo, CAPTCHAs de formularios, etc.) se introducen en la interfaz del admin y se cifran en la tabla options bajo plugin:<id>:settings:<key>. El admin recibe únicamente si un secreto está definido, incluso cuando la clave de cifrado correspondiente no está disponible, de modo que un administrador puede reemplazar una credencial ilegible. El código del plugin lee el texto plano mediante ctx.settings dentro de su entorno de ejecución aislado. Los valores almacenados fuera de un esquema de ajustes declarado, incluidas las entradas arbitrarias de KV y de estado del plugin, no usan esta ruta de cifrado.

• Rotación de credenciales: rote la credencial en el proveedor y pegue el nuevo valor en la página de ajustes del plugin. Al guardar se escribe un nuevo sobre cifrado.
• Migración de texto plano: los secretos almacenados por una versión anterior de EmDash siguen siendo legibles. Guarde cada valor de nuevo para cifrarlo.
• Si se pierde la clave de cifrado: restaure el EMDASH_ENCRYPTION_KEY correspondiente desde la copia de seguridad de claves independiente. Si no existe ninguna copia, reemplace cada credencial afectada en su proveedor e introduzca los reemplazos después de configurar una nueva clave de cifrado.

Credenciales de CLI

La CLI emdash almacena los tokens del sitio en ~/.config/emdash/auth.json (respetando XDG_CONFIG_HOME) con permisos solo para el propietario (0600). emdash login se autentica en su instancia de EmDash mediante un flujo de dispositivo OAuth y almacena el token indexado por la URL de la instancia. emdash logout lo elimina; en cada invocación, --token o EMDASH_TOKEN sobrescribe el token almacenado.

Perder el archivo es inofensivo: ejecute emdash login de nuevo.

Credenciales de CLI del registro de plugins

La CLI independiente emdash-plugin (paquete @emdash-cms/plugin-cli) tiene como destino el registro de AT Protocol experimental. La publicación allí está vinculada a su identidad de AT Protocol (su DID de publicador): el sitio en sí no guarda credenciales de publicación, y las instalaciones verifican los artefactos con las sumas de comprobación de los registros de versión atribuidos a ese DID.

• Se autentica mediante OAuth de atproto. Los blobs de sesión/estado de OAuth residen en ~/.emdash/oauth/, y la identidad del publicador (DID, handle, PDS) se guarda en caché en ~/.emdash/credentials.json; ambos se escriben con permisos solo para el propietario.
• En CI, proporcione la identidad mediante EMDASH_PUBLISHER_DID, EMDASH_PUBLISHER_HANDLE y EMDASH_PUBLISHER_PDS; EMDASH_REGISTRY_URL sobrescribe el host del registro. Un publish automatizado desde CI sigue necesitando los archivos de sesión de OAuth en ~/.emdash/oauth/ en el runner: las variables de entorno por sí solas no transportan la sesión de OAuth.
• Rotar o revocar el acceso de publicación se hace en su cuenta de AT Protocol (p. ej., contraseñas de aplicación), no en EmDash. Consulte Atmosphere auth.

Referencia rápida de rotación