Gestire secret e chiavi

Usa questo inventario per decidere quali valori appartengono all’ambiente di runtime, quali vengono generati nel database e quali sono memorizzati dai plugin. Ogni sezione indica come la rotazione influisce su un sito in esecuzione.

Su Node.js, metti i secret di runtime nel gestore di secret della piattaforma di hosting così entrano in process.env all’avvio del processo. Per un Worker, usa wrangler secret put. Non mettere valori secret in astro.config.mjs, wrangler.jsonc o import.meta.env; Vite può incorporare valori di build nel bundle del server.

Panoramica

La chiave di cifratura

EMDASH_ENCRYPTION_KEY cifra le impostazioni del plugin dichiarate con type: "secret". EmDash usa AES-GCM con l’ID del plugin e la chiave dell’impostazione come dati autenticati. Un valore malformato produce un messaggio di avvio rivolto all’operatore, e le operazioni che richiedono impostazioni cifrate del plugin falliscono in chiusura. Le richieste del sito non correlate continuano a funzionare.

Il comando seguente genera un valore correttamente formattato. Conservalo nell’ambiente di runtime o come secret Worker se il tuo deployment usa questa variabile.

npx emdash secrets generate
# emdash_enc_v1_<43 base64url chars>

# Cloudflare:
wrangler secret put EMDASH_ENCRYPTION_KEY

Il formato è emdash_enc_v1_ seguito da 32 byte casuali come base64url senza padding. Il valore è fornito dall’operatore e non è memorizzato nel database. Conservalo in un gestore di secret e in un backup di recupero separato.

Per ruotare la chiave, anteponi un nuovo valore e conserva il vecchio dopo una virgola:

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

EmDash cifra i valori nuovi e risalvati con la prima chiave. Usa l’impronta kid memorizzata per selezionare una chiave più vecchia in lettura. Risalva ogni secret del plugin prima di rimuovere la vecchia chiave, poi verifica quelle integrazioni da un deployment che contiene solo la nuova chiave. EmDash al momento non segnala quali ID chiave restano in uso, quindi tieni un inventario delle credenziali che risalvi e non rimuovere una vecchia chiave finché ogni integrazione non ha superato quella verifica.

Secret di sito generati

Due secret vengono generati automaticamente al primo uso e persistiti nella tabella options, così sono stabili tra richieste, deployment e isolate. La generazione è atomica: avvii a freddo concorrenti convergono su un valore.

Secret di preview

Firma gli URL di preview (HMAC). Memorizzato come emdash:preview_secret; 32 byte casuali, base64url.

• Override: imposta EMDASH_PREVIEW_SECRET (alias legacy: PREVIEW_SECRET) se ti serve lo stesso secret su più processi o vuoi fissarlo per audit. L’ambiente vince sempre sul valore memorizzato.
• Rotazione: elimina la riga emdash:preview_secret (o cambia la variabile env) e ridistribuisci. Impatto: i link di preview emessi in precedenza smettono di validare. Nient’altro si rompe: un secret fresco viene generato (o letto dall’env) alla successiva richiesta di preview.
• Se perso: niente è irrecuperabile. I link di preview sono di breve durata per progetto.

Vedi la guida al preview su come gli URL di preview vengono costruiti e verificati.

Sale IP

Sala l’hash SHA-256 degli indirizzi IP dei commentatori (ip_hash sui commenti) usato per il rate-limit dei commenti. Memorizzato come emdash:ip_salt. Specifico del sito, così gli hash non sono correlabili tra installazioni EmDash.

• Override: imposta EMDASH_IP_SALT. Per retrocompatibilità, vengono consultati anche EMDASH_AUTH_SECRET / AUTH_SECRET — le installazioni che storicamente derivavano il sale da quelli mantengono hash stabili.
• Rotazione: cambia la variabile env o elimina la riga emdash:ip_salt. Impatto: i nuovi invii di commenti fanno hash a valori diversi, così il conteggio del rate-limit riparte per tutti. I commenti esistenti e i loro hash memorizzati restano intatti.
• Se perso: nessuna perdita di dati. Si azzera solo la continuità del rate-limit.

Token di sessione e API

• Sessioni usano lo store di sessione di Astro (Workers KV su Cloudflare, filesystem su Node). Il cookie porta un ID di sessione opaco; non c’è un secret di firma da gestire. Esci per terminare una sessione, oppure svuota lo store di sessione (es. il namespace KV) per costringere tutti ad accedere di nuovo.
• Token API (prefissi ec_pat_, ec_oat_, ec_ort_) sono valori casuali opachi a 256 bit; viene memorizzato solo il loro hash SHA-256. Il testo in chiaro viene mostrato una volta alla creazione. Ruota revocando e ricreando nell’admin.
• Token di invito, magic-link e recupero sono monouso, memorizzati come hash SHA-256 in auth_tokens, e a tempo limitato (inviti 7 giorni, magic link 15 minuti).

Non c’è nulla di cui fare backup o da ruotare in modo proattivo: una fuga del database espone solo hash, e ogni token può essere revocato o riemesso dall’admin.

Credenziali di servizio fornite dall’utente

Le credenziali per servizi esterni si leggono dall’ambiente e non vengono mai scritte nel database. Ruotale presso il provider, aggiorna la variabile, ridistribuisci.

Su Cloudflare, impostale con wrangler secret put; per lo sviluppo locale, mettile in .env. Wrangler legge .dev.vars o .env, non entrambi, e .dev.vars ha la precedenza quando presente. R2 tramite un binding non necessita di variabili di access key perché il binding concede l’accesso a runtime. Vedi storage dei media.

Secret di plugin

Le impostazioni che un plugin dichiara con type: "secret" (chiavi API per provider email, CAPTCHA di form, ecc.) si inseriscono nell’UI admin e si cifrano nella tabella options sotto plugin:<id>:settings:<key>. L’admin riceve solo se un secret è impostato, anche quando la chiave di cifratura corrispondente non è disponibile, così un amministratore può sostituire una credenziale illeggibile. Il codice del plugin legge il testo in chiaro tramite ctx.settings nel suo runtime isolato. I valori memorizzati fuori da uno schema di impostazioni dichiarato, comprese voci KV e di stato arbitrarie del plugin, non usano questo percorso di cifratura.

• Rotazione delle credenziali: ruota la credenziale presso il provider e incolla il nuovo valore nella pagina delle impostazioni del plugin. Il salvataggio scrive una nuova busta cifrata.
• Migrazione del testo in chiaro: i secret memorizzati da una versione precedente di EmDash restano leggibili. Salva di nuovo ogni valore per cifrarlo.
• Se la chiave di cifratura è persa: ripristina l’EMDASH_ENCRYPTION_KEY corrispondente dal backup separato della chiave. Se non esiste alcuna copia, sostituisci ogni credenziale interessata presso il provider e inserisci i sostituti dopo aver configurato una nuova chiave di cifratura.

Credenziali CLI

La CLI emdash conserva due tipi di credenziali, entrambe in ~/.config/emdash/auth.json (rispettando XDG_CONFIG_HOME), create con permessi solo del proprietario (0600):

• Token di sito — emdash login autentica contro la tua istanza EmDash tramite un flusso dispositivo OAuth e memorizza il token risultante indicizzato per URL di istanza. emdash logout lo rimuove; per invocazione, --token o EMDASH_TOKEN sovrascrivono il token memorizzato.
• Token Marketplace — emdash plugin publish autentica sul Marketplace EmDash tramite un flusso dispositivo GitHub e memorizza il JWT risultante indicizzato per marketplace:<origin>. Per la pubblicazione CI, imposta invece EMDASH_MARKETPLACE_TOKEN — ha priorità sulla credenziale memorizzata.

Perdere il file è innocuo: esegui di nuovo emdash login (o emdash plugin publish, che riesegue il flusso dispositivo).

Credenziali CLI del registro plugin

La CLI separata emdash-plugin (pacchetto @emdash-cms/plugin-cli) punta al registro AT Protocol sperimentale. Pubblicare lì è legato alla tua identità AT Protocol (il tuo DID di publisher) — il sito stesso non detiene credenziali di pubblicazione, e le installazioni verificano gli artefatti rispetto ai checksum dei record di release attribuiti a quel DID.

• Si autentica tramite OAuth atproto. I blob di sessione/stato OAuth vivono in ~/.emdash/oauth/, e l’identità del publisher (DID, handle, PDS) è memorizzata in cache in ~/.emdash/credentials.json; entrambi sono scritti con permessi solo del proprietario.
• In CI, fornisci l’identità tramite EMDASH_PUBLISHER_DID, EMDASH_PUBLISHER_HANDLE e EMDASH_PUBLISHER_PDS; EMDASH_REGISTRY_URL sovrascrive l’host del registro. Il publish automatizzato da CI ha ancora bisogno dei file di sessione OAuth in ~/.emdash/oauth/ sul runner — le sole variabili env non portano la sessione OAuth.
• Ruotare o revocare l’accesso di pubblicazione avviene sul tuo account AT Protocol (es. password app), non in EmDash. Vedi auth Atmosphere.

Riferimento rapido di rotazione