Geheimnisse und Schlüssel verwalten

Verwenden Sie dieses Inventar, um zu entscheiden, welche Werte in die Laufzeitumgebung gehören, welche in der Datenbank generiert werden und welche von Plugins gespeichert werden. Jeder Abschnitt gibt an, wie sich die Rotation auf eine laufende Website auswirkt.

Unter Node.js legen Sie Laufzeitgeheimnisse im Secret Manager der Hosting-Plattform ab, damit sie beim Start des Prozesses in process.env eingehen. Für einen Worker verwenden Sie wrangler secret put. Setzen Sie Geheimwerte nicht in astro.config.mjs, wrangler.jsonc oder import.meta.env; Vite kann Build-Zeit-Werte in das Server-Bundle einbetten.

Übersicht

Der Verschlüsselungsschlüssel

EMDASH_ENCRYPTION_KEY verschlüsselt derzeit weder Plugin-Geheimnisse noch andere gespeicherte Daten. Wenn die Variable gesetzt ist, prüft EmDash ihr Format beim Start. Ein fehlerhafter Wert erzeugt eine Betreiber-seitige Log-Nachricht, aber die Website verarbeitet weiterhin Anfragen.

Der folgende Befehl generiert einen korrekt formatierten Wert. Speichern Sie ihn in der Laufzeitumgebung oder als Worker Secret, wenn Ihr Deployment diese Variable verwendet.

npx emdash secrets generate
# emdash_enc_v1_<43 base64url Zeichen>

# Cloudflare:
wrangler secret put EMDASH_ENCRYPTION_KEY

Das Format ist emdash_enc_v1_ gefolgt von 32 zufälligen Bytes als ungepolstertes base64url. Der Wert wird vom Betreiber bereitgestellt und nicht in der Datenbank gespeichert. Der Verlust hat keine Auswirkungen auf die Datenwiederherstellung, da keine gespeicherten Daten davon abhängen.

Generierte Site-Geheimnisse

Zwei Geheimnisse werden bei der ersten Verwendung automatisch generiert und in der options-Tabelle persistiert, sodass sie über Anfragen, Deployments und Isolates hinweg stabil sind. Die Generierung ist atomar — gleichzeitige Kaltstarts konvergieren auf einen Wert.

Preview Secret

Signiert Preview-URLs (HMAC). Gespeichert als emdash:preview_secret; 32 zufällige Bytes, base64url.

• Override: Setzen Sie EMDASH_PREVIEW_SECRET (Legacy-Alias: PREVIEW_SECRET), wenn Sie dasselbe Geheimnis über mehrere Prozesse benötigen oder es aus Audit-Gründen festlegen möchten. Die Umgebung hat immer Vorrang vor dem gespeicherten Wert.
• Rotation: Löschen Sie die Zeile emdash:preview_secret (oder ändern Sie die Env-Variable) und deployen Sie neu. Auswirkung: Zuvor ausgestellte Preview-Links validieren nicht mehr. Sonst bricht nichts — ein neues Geheimnis wird bei der nächsten Preview-Anfrage generiert (oder aus der Env gelesen).
• Bei Verlust: Nichts ist unwiederbringlich. Preview-Links sind per Design kurzlebig.

Siehe den Preview-Leitfaden für den Aufbau und die Verifizierung von Preview-URLs.

IP-Salt

Salzt den SHA-256-Hash der IP-Adressen von Kommentatoren (ip_hash bei Kommentaren), der für das Kommentar-Rate-Limiting verwendet wird. Gespeichert als emdash:ip_salt. Site-spezifisch, sodass Hashes nicht über EmDash-Installationen hinweg korrelierbar sind.

• Override: Setzen Sie EMDASH_IP_SALT. Aus Gründen der Abwärtskompatibilität werden auch EMDASH_AUTH_SECRET / AUTH_SECRET konsultiert — Installationen, die den Salt historisch daraus abgeleitet haben, behalten stabile Hashes.
• Rotation: Ändern Sie die Env-Variable oder löschen Sie die Zeile emdash:ip_salt. Auswirkung: Neue Kommentareinreichungen hashen zu anderen Werten, sodass die Rate-Limit-Zählung für alle neu beginnt. Bestehende Kommentare und ihre gespeicherten Hashes sind unberührt.
• Bei Verlust: Kein Datenverlust. Nur die Kontinuität des Rate-Limitings wird zurückgesetzt.

Session und API-Tokens

• Sessions verwenden Astros Session Store (Workers KV auf Cloudflare, Dateisystem auf Node). Das Cookie trägt eine opake Session-ID; es gibt kein Signiergeheimnis zu verwalten. Melden Sie sich ab, um eine Session zu beenden, oder leeren Sie den Session Store (z.B. den KV-Namespace), um alle zur erneuten Anmeldung zu zwingen.
• API-Tokens (ec_pat_, ec_oat_, ec_ort_ Präfixe) sind opake 256-Bit-Zufallswerte; nur ihr SHA-256-Hash wird gespeichert. Der Klartext wird einmal bei der Erstellung angezeigt. Rotieren durch Widerrufen und Neuerstellen im Admin.
• Einladungs-, Magic-Link- und Wiederherstellungs-Tokens sind einmalig verwendbar, als SHA-256-Hashes in auth_tokens gespeichert und zeitlich begrenzt (Einladungen 7 Tage, Magic Links 15 Minuten).

Es gibt nichts proaktiv zu sichern oder zu rotieren: Ein Datenbank-Leak offenbart nur Hashes, und jedes Token kann im Admin widerrufen oder neu ausgestellt werden.

Vom Benutzer bereitgestellte Service-Credentials

Credentials für externe Dienste werden aus der Umgebung gelesen und niemals in die Datenbank geschrieben. Rotieren Sie sie beim Anbieter, aktualisieren Sie die Variable, deployen Sie neu.

Auf Cloudflare setzen Sie diese mit wrangler secret put; für lokale Entwicklung legen Sie sie in .env. Wrangler liest entweder .dev.vars oder .env, nicht beides, und .dev.vars hat Vorrang, wenn vorhanden. R2 über ein Binding benötigt keine Access-Key-Variablen, da das Binding Laufzeitzugriff gewährt. Siehe Medienspeicher.

Plugin-Geheimnisse

Einstellungen, die ein Plugin mit type: "secret" deklariert (API-Schlüssel für E-Mail-Provider, Formular-CAPTCHAs usw.), werden in der Admin-UI eingegeben und in der Datenbank gespeichert — in der options-Tabelle unter plugin:<id>:settings:<key> oder im Schlüssel-Wert-Speicher des Plugins. Ob ein gespeichertes Geheimnis an die Admin-UI zurückgegeben wird, liegt am Plugin; gut implementierte Plugins geben nur ein „Wert ist gesetzt”-Flag zurück anstatt des Geheimnisses selbst (das mitgelieferte Forms-Plugin macht dies).

• Rotation: Rotieren Sie den Schlüssel beim Anbieter und fügen Sie den neuen Wert auf der Einstellungsseite des Plugins ein. Wirkt sofort.
• Bei Verlust: Geben Sie den Wert im Admin neu ein. Nichts anderes hängt davon ab.

CLI-Credentials

Die emdash-CLI hält zwei Arten von Credentials, beide in ~/.config/emdash/auth.json (unter Beachtung von XDG_CONFIG_HOME), erstellt mit Owner-Only-Berechtigungen (0600):

• Site-Tokens — emdash login authentifiziert sich gegen Ihre EmDash-Instanz über einen OAuth Device Flow und speichert das resultierende Token, indiziert nach Instanz-URL. emdash logout entfernt es; pro Aufruf überschreibt --token oder EMDASH_TOKEN das gespeicherte Token.
• Marketplace-Tokens — emdash plugin publish authentifiziert sich am EmDash Marketplace über einen GitHub Device Flow und speichert das resultierende JWT, indiziert nach marketplace:<origin>. Für CI-Publishing setzen Sie stattdessen EMDASH_MARKETPLACE_TOKEN — es hat Vorrang vor dem gespeicherten Credential.

Der Verlust der Datei ist harmlos: Führen Sie emdash login (oder emdash plugin publish, das den Device Flow erneut ausführt) erneut aus.

Plugin-Registry-CLI-Credentials

Die separate emdash-plugin-CLI (Paket @emdash-cms/plugin-cli) zielt auf die experimentelle AT Protocol Registry. Das Veröffentlichen dort ist an Ihre AT Protocol-Identität (Ihre Publisher-DID) gebunden — die Website selbst hält keine Publishing-Credentials, und Installationen verifizieren Artefakte gegen Prüfsummen aus Release-Einträgen, die dieser DID zugeschrieben werden.

• Sie authentifiziert sich über atproto OAuth. Die OAuth-Session-/State-Blobs befinden sich in ~/.emdash/oauth/, und die Publisher-Identität (DID, Handle, PDS) wird in ~/.emdash/credentials.json zwischengespeichert; beide werden mit Owner-Only-Berechtigungen geschrieben.
• In CI stellen Sie die Identität über EMDASH_PUBLISHER_DID, EMDASH_PUBLISHER_HANDLE und EMDASH_PUBLISHER_PDS bereit; EMDASH_REGISTRY_URL überschreibt den Registry-Host. Automatisiertes publish aus CI benötigt weiterhin die OAuth-Session-Dateien in ~/.emdash/oauth/ auf dem Runner — die Env-Variablen allein tragen die OAuth-Session nicht.
• Das Rotieren oder Widerrufen des Publishing-Zugangs erfolgt über Ihr AT Protocol-Konto (z.B. App-Passwörter), nicht in EmDash. Siehe Atmosphere-Authentifizierung.

Rotations-Kurzreferenz