Gérer les secrets et les clés

Utilisez cet inventaire pour déterminer quelles valeurs appartiennent à l’environnement d’exécution, lesquelles sont générées dans la base de données et lesquelles sont stockées par les plugins. Chaque section indique comment la rotation affecte un site en cours d’exécution.

Sur Node.js, placez les secrets d’exécution dans le gestionnaire de secrets de la plateforme d’hébergement afin qu’ils entrent dans process.env au démarrage du processus. Pour un Worker, utilisez wrangler secret put. Ne placez pas de valeurs secrètes dans astro.config.mjs, wrangler.jsonc ni import.meta.env ; Vite peut intégrer des valeurs de build dans le bundle du serveur.

Vue d’ensemble

La clé de chiffrement

EMDASH_ENCRYPTION_KEY chiffre les paramètres de plugin déclarés avec type: "secret". EmDash utilise AES-GCM avec l’ID du plugin et la clé du paramètre comme données authentifiées. Une valeur mal formée produit un message de démarrage destiné à l’opérateur, et les opérations qui nécessitent des paramètres de plugin chiffrés échouent de manière fermée. Les requêtes du site sans rapport continuent de fonctionner.

La commande suivante génère une valeur correctement formatée. Stockez-la dans l’environnement d’exécution ou comme secret Worker si votre déploiement utilise cette variable.

npx emdash secrets generate
# emdash_enc_v1_<43 base64url chars>

# Cloudflare:
wrangler secret put EMDASH_ENCRYPTION_KEY

Le format est emdash_enc_v1_ suivi de 32 octets aléatoires en base64url sans remplissage. La valeur est fournie par l’opérateur et n’est pas stockée dans la base de données. Conservez-la dans un gestionnaire de secrets et dans une sauvegarde de récupération distincte.

Pour faire pivoter la clé, ajoutez une nouvelle valeur en tête et conservez l’ancienne après une virgule :

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

EmDash chiffre les valeurs nouvelles et réenregistrées avec la première clé. Il utilise l’empreinte kid stockée pour sélectionner une clé plus ancienne lors des lectures. Réenregistrez chaque secret de plugin avant de supprimer l’ancienne clé, puis vérifiez ces intégrations depuis un déploiement qui ne contient que la nouvelle clé. EmDash ne signale pas actuellement quels ID de clé restent en usage ; tenez donc un inventaire des identifiants que vous réenregistrez et ne supprimez pas une ancienne clé tant que chaque intégration n’a pas passé cette vérification.

Secrets de site générés

Deux secrets sont générés automatiquement à la première utilisation et persistés dans la table options ; ils sont donc stables d’une requête, d’un déploiement et d’un isolate à l’autre. La génération est atomique : des démarrages à froid concurrents convergent vers une seule valeur.

Secret de preview

Signe les URL de preview (HMAC). Stocké sous emdash:preview_secret ; 32 octets aléatoires, base64url.

• Surcharge : définissez EMDASH_PREVIEW_SECRET (ancien alias : PREVIEW_SECRET) si vous avez besoin du même secret sur plusieurs processus ou si vous voulez le figer pour des raisons d’audit. L’environnement l’emporte toujours sur la valeur stockée.
• Rotation : supprimez la ligne emdash:preview_secret (ou modifiez la variable d’environnement) et redéployez. Impact : les liens de preview émis précédemment cessent d’être valides. Rien d’autre ne casse — un nouveau secret est généré (ou lu depuis l’environnement) à la requête de preview suivante.
• En cas de perte : rien n’est irrécupérable. Les liens de preview sont de courte durée par conception.

Consultez le guide de la preview pour savoir comment les URL de preview sont construites et vérifiées.

Sel IP

Sale le hachage SHA-256 des adresses IP des auteurs de commentaires (ip_hash sur les commentaires) utilisé pour la limitation de débit des commentaires. Stocké sous emdash:ip_salt. Propre au site, de sorte que les hachages ne sont pas corrélables entre installations EmDash.

• Surcharge : définissez EMDASH_IP_SALT. Pour la rétrocompatibilité, EMDASH_AUTH_SECRET / AUTH_SECRET sont également consultés — les installations qui dérivaient historiquement le sel de ces variables conservent des hachages stables.
• Rotation : modifiez la variable d’environnement ou supprimez la ligne emdash:ip_salt, puis redéployez. Impact : les nouveaux commentaires soumis produisent des hachages différents, de sorte que le comptage de la limitation de débit repart de zéro pour tout le monde. Les commentaires existants et leurs hachages stockés ne sont pas modifiés.
• En cas de perte : aucune perte de données. Seule la continuité de la limitation de débit est réinitialisée.

Jetons de session et d’API

• Les sessions utilisent le stockage de sessions d’Astro (Workers KV sur Cloudflare, système de fichiers sur Node). Les adaptateurs qui ne configurent pas de stockage, comme Vercel, ont besoin d’un pilote de session dans astro.config.mjs ; sans lui, la connexion échoue avec une erreur expliquant qu’un pilote de session est requis. Le cookie contient un ID de session opaque ; il n’y a aucun secret de signature à gérer. Déconnectez-vous pour terminer une session, ou videz le stockage de sessions (par ex. le namespace KV) pour forcer tout le monde à se reconnecter.
• Les jetons d’API (préfixes ec_pat_, ec_oat_, ec_ort_) sont des valeurs aléatoires opaques de 256 bits ; seul leur hachage SHA-256 est stocké. Le texte en clair n’est affiché qu’une fois, à la création. Faites pivoter un jeton en le révoquant puis en le recréant dans l’admin.
• Les jetons d’invitation, de lien magique et de récupération ont un usage unique, sont stockés sous forme de hachages SHA-256 dans auth_tokens et sont limités dans le temps (invitations : 7 jours, liens magiques : 15 minutes).

Il n’y a rien à sauvegarder ni à faire pivoter de manière proactive : une fuite de la base de données n’expose que des hachages, et chaque jeton peut être révoqué ou réémis depuis l’admin.

Identifiants de service fournis par l’utilisateur

Les identifiants des services externes sont lus depuis l’environnement et ne sont jamais écrits dans la base de données. Faites-les pivoter chez le fournisseur, mettez à jour la variable, puis redéployez.

Sur Cloudflare, définissez-les avec wrangler secret put ; pour le développement local, placez-les dans .env. Wrangler lit soit .dev.vars, soit .env, pas les deux, et .dev.vars est prioritaire lorsqu’il est présent. R2 via un binding n’a pas besoin de variables de clé d’accès, car le binding accorde l’accès à l’exécution. Consultez stockage des médias.

Sur Node, EmDash lit la clé secrète Turnstile depuis l’environnement de processus du serveur à l’arrivée d’une requête, et ni astro dev ni le serveur compilé ne chargent .env dans celui-ci. Définissez la clé dans l’environnement de votre hôte, exportez-la dans le shell qui exécute astro dev, ou démarrez le serveur compilé avec node --env-file=.env ./dist/server/entry.mjs.

Secrets de plugin

Les paramètres qu’un plugin déclare avec type: "secret" (clés d’API de fournisseurs d’e-mail, CAPTCHA de formulaires, etc.) sont saisis dans l’interface d’admin et chiffrés dans la table options sous plugin:<id>:settings:<key>. L’admin reçoit uniquement l’information indiquant si un secret est défini, même lorsque la clé de chiffrement correspondante est indisponible ; un administrateur peut ainsi remplacer un identifiant illisible. Le code du plugin lit le texte en clair via ctx.settings dans son environnement d’exécution isolé. Les valeurs stockées en dehors d’un schéma de paramètres déclaré, y compris les entrées arbitraires de KV et d’état du plugin, n’utilisent pas ce chemin de chiffrement.

• Rotation des identifiants : faites pivoter l’identifiant chez le fournisseur et collez la nouvelle valeur dans la page de paramètres du plugin. L’enregistrement écrit une nouvelle enveloppe chiffrée.
• Migration du texte en clair : les secrets stockés par une version antérieure d’EmDash restent lisibles. Enregistrez à nouveau chaque valeur pour la chiffrer.
• Si la clé de chiffrement est perdue : restaurez l’EMDASH_ENCRYPTION_KEY correspondante depuis la sauvegarde de clés distincte. Si aucune copie n’existe, remplacez chaque identifiant concerné chez son fournisseur et saisissez les remplacements après avoir configuré une nouvelle clé de chiffrement.

Identifiants CLI

La CLI emdash stocke les jetons du site dans ~/.config/emdash/auth.json (en respectant XDG_CONFIG_HOME) avec des permissions réservées au propriétaire (0600). emdash login s’authentifie auprès de votre instance EmDash via un flux d’appareil OAuth et stocke le jeton indexé par l’URL de l’instance. emdash logout le supprime ; à chaque invocation, --token ou EMDASH_TOKEN remplace le jeton stocké.

Perdre le fichier est sans conséquence : relancez emdash login.

Identifiants CLI du registre de plugins

La CLI autonome emdash-plugin (paquet @emdash-cms/plugin-cli) cible le registre AT Protocol expérimental. La publication y est liée à votre identité AT Protocol (votre DID d’éditeur) — le site lui-même ne détient aucun identifiant de publication, et les installations vérifient les artefacts à partir des sommes de contrôle des enregistrements de version attribués à ce DID.

• Elle s’authentifie via OAuth atproto. Les blobs de session/d’état OAuth se trouvent dans ~/.emdash/oauth/, et l’identité de l’éditeur (DID, handle, PDS) est mise en cache dans ~/.emdash/credentials.json ; les deux sont écrits avec des permissions réservées au propriétaire.
• En CI, fournissez l’identité via EMDASH_PUBLISHER_DID, EMDASH_PUBLISHER_HANDLE et EMDASH_PUBLISHER_PDS ; EMDASH_REGISTRY_URL remplace l’hôte du registre. Un publish automatisé depuis la CI nécessite toujours les fichiers de session OAuth dans ~/.emdash/oauth/ sur le runner — les variables d’environnement seules ne transportent pas la session OAuth.
• La rotation ou la révocation de l’accès de publication se fait sur votre compte AT Protocol (par ex. mots de passe d’application), pas dans EmDash. Consultez Atmosphere auth.

Référence rapide de rotation