Geheimnisse & Schlüsselverwaltung

EmDash verwendet eine kleine Anzahl von Geheimnissen für Vorschauen, Kommentare, Authentifizierung, Speicher und Plugins. Diese Seite ist das vollständige Inventar: woher jedes Geheimnis stammt, wo es gespeichert wird, wie man es rotiert und was kaputt geht, wenn es verloren geht.

Übersicht

Der Verschlüsselungsschlüssel

EMDASH_ENCRYPTION_KEY ist der Schlüssel der Site zur Verschlüsselung von Plugin-Geheimnissen im Ruhezustand. Er wird vom Betreiber bereitgestellt und nie in der Datenbank gespeichert — die Datenbank enthält nur Chiffretext, sodass ein geleaktes Datenbank-Backup den Schlüssel nicht preisgibt.

Generieren Sie einen und setzen Sie ihn als Umgebungsvariable (oder Worker-Secret):

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 Schlüssel wird beim Runtime-Start validiert; ein fehlerhafter Wert protokolliert einen betreiberseitigen Fehler, ohne Anfragepfade zu unterbrechen.

Rotation

Die Variable akzeptiert eine kommaseparierte Liste von Schlüsseln. Der erste Eintrag ist der primäre und wird für neue Schreibvorgänge verwendet; alle Einträge werden für die Entschlüsselung versucht. Jeder verschlüsselte Wert ist mit einem 8-Zeichen-Schlüssel-Fingerprint (dem kid, druckbar über emdash secrets fingerprint <key>) versehen, sodass die Runtime automatisch den richtigen Schlüssel wählt.

Zum Rotieren: Generieren Sie einen neuen Schlüssel, stellen Sie ihn der Liste voran (EMDASH_ENCRYPTION_KEY="neu,alt"), deployen Sie erneut und entfernen Sie den alten Schlüssel, sobald bestehende Werte neu verschlüsselt wurden.

Generierte Site-Geheimnisse

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

Preview-Secret

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

• Override: Setzen Sie EMDASH_PREVIEW_SECRET (Legacy-Alias: PREVIEW_SECRET), wenn Sie das gleiche Secret über mehrere Prozesse benötigen oder es für Audit-Zwecke festpinnen möchten. Die Umgebung gewinnt immer über den gespeicherten Wert.
• Rotation: Löschen Sie die emdash:preview_secret-Zeile (oder ändern Sie die Env-Variable) und deployen Sie erneut. Auswirkung: zuvor ausgegebene Vorschau-Links validieren nicht mehr. Nichts anderes bricht — ein frisches Secret wird beim nächsten Vorschau-Request generiert (oder aus der Env gelesen).
• Bei Verlust: Nichts ist unwiederbringlich. Vorschau-Links sind von Natur aus kurzlebig.

Siehe den Vorschau-Leitfaden für Informationen zur Erstellung und Verifizierung von Vorschau-URLs.

IP-Salt

Salzt den SHA-256-Hash von Kommentator-IP-Adressen (ip_hash bei Kommentaren) für die Kommentar-Ratenbegrenzung. Gespeichert als emdash:ip_salt. Site-spezifisch, sodass Hashes nicht über EmDash-Installationen hinweg korrelierbar sind.

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

Session- und API-Token

• 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. Abmelden beendet eine Session, oder leeren Sie den Session-Store (z.B. den KV-Namespace), um alle zur erneuten Anmeldung zu zwingen.
• API-Token (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 Recovery-Token sind zweckgebunden, 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 legt nur Hashes offen, 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 nie in die Datenbank geschrieben. Rotieren Sie sie beim Anbieter, aktualisieren Sie die Variable, deployen Sie erneut.

Auf Cloudflare setzen Sie diese mit wrangler secret put; lokal in .env. R2 über Binding benötigt keine Credentials — der Zugriff wird durch das Binding in wrangler.jsonc gewährt, was das empfohlene Setup auf Workers ist. Siehe Speicheroptionen.

Plugin-Geheimnisse

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

• Rotation: Rotieren Sie den Schlüssel beim Anbieter und fügen Sie den neuen Wert in die Plugin-Einstellungsseite 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 (respektiert XDG_CONFIG_HOME), erstellt mit Nur-Eigentümer-Berechtigungen (0600):

• Site-Token — 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-Token — emdash plugin publish authentifiziert sich beim EmDash Marketplace über einen GitHub-Device-Flow und speichert das resultierende JWT, indiziert als marketplace:<origin>. Für CI-Publishing setzen Sie stattdessen EMDASH_MARKETPLACE_TOKEN — es hat Vorrang vor dem gespeicherten Credential.

Den Verlust der Datei ist harmlos: Führen Sie emdash login (oder emdash plugin publish, das den Device-Flow erneut startet) wieder aus.

Plugin-Registry-CLI-Credentials

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

• Sie authentifiziert sich über atproto OAuth. Die OAuth-Session-/Status-Blobs befinden sich in ~/.emdash/oauth/, und die Publisher-Identität (DID, Handle, PDS) ist in ~/.emdash/credentials.json zwischengespeichert; beides wird mit Nur-Eigentümer-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 noch die OAuth-Session-Dateien in ~/.emdash/oauth/ auf dem Runner — die Env-Variablen allein tragen die OAuth-Session nicht.
• Das Rotieren oder Widerrufen von Publishing-Zugriff geschieht bei Ihrem AT Protocol-Konto (z.B. App-Passwörter), nicht in EmDash. Siehe Atmosphere-Auth.

Rotations-Kurzreferenz