Gestire secret e chiavi

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

Su Node.js, inserisci i secret di runtime nel secret manager della piattaforma di hosting in modo che entrino in process.env all’avvio del processo. Per un Worker, usa wrangler secret put. Non inserire valori segreti in astro.config.mjs, wrangler.jsonc o import.meta.env; Vite può incorporare i valori della build nel bundle del server.

Panoramica

La chiave di cifratura

EMDASH_ENCRYPTION_KEY cifra le impostazioni dei 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 destinato all’operatore, e le operazioni che richiedono impostazioni di plugin cifrate falliscono in modo chiuso. Le richieste del sito non correlate continuano a funzionare.

Il comando seguente genera un valore nel formato corretto. Memorizzalo nell’ambiente di runtime o come secret del Worker se il tuo deploy 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 in base64url senza padding. Il valore è fornito dall’operatore e non viene memorizzato nel database. Conservalo in un secret manager e in un backup di ripristino separato.

Per ruotare la chiave, anteponi un nuovo valore e mantieni il valore precedente dopo una virgola:

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

EmDash cifra i valori nuovi e quelli salvati di nuovo con la prima chiave. Usa l’impronta kid memorizzata per selezionare una chiave più vecchia in lettura. Salva di nuovo ogni secret di plugin prima di rimuovere la vecchia chiave, quindi verifica quelle integrazioni da un deploy che contenga solo la nuova chiave. Al momento EmDash non segnala quali ID di chiave sono ancora in uso, quindi tieni un inventario delle credenziali che salvi di nuovo 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 utilizzo e salvati in modo persistente nella tabella options, quindi sono stabili tra richieste, deploy e isolate. La generazione è atomica: avvii a freddo concorrenti convergono su un unico valore.

Secret di preview

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

• Sovrascrittura: imposta EMDASH_PREVIEW_SECRET (alias legacy: PREVIEW_SECRET) se ti serve lo stesso secret su più processi o vuoi fissarlo per motivi di audit. L’ambiente ha sempre la precedenza sul valore memorizzato.
• Rotazione: elimina la riga emdash:preview_secret (o modifica la variabile d’ambiente) ed esegui di nuovo il deploy. Impatto: i link di preview emessi in precedenza non vengono più convalidati. Nient’altro si rompe — alla successiva richiesta di preview viene generato un nuovo secret (o letto dall’ambiente).
• In caso di perdita: nulla è irrecuperabile. I link di preview hanno per progetto una breve durata.

Consulta la guida alla preview per sapere come vengono costruiti e verificati gli URL di preview.

Sale IP

Aggiunge il sale all’hash SHA-256 degli indirizzi IP di chi commenta (ip_hash sui commenti), usato per il rate limiting dei commenti. Memorizzato come emdash:ip_salt. È specifico del sito, quindi gli hash non sono correlabili tra installazioni di EmDash.

• Sovrascrittura: imposta EMDASH_IP_SALT. Per retrocompatibilità vengono consultati anche EMDASH_AUTH_SECRET / AUTH_SECRET — le installazioni che storicamente derivavano il sale da queste variabili mantengono hash stabili.
• Rotazione: modifica la variabile d’ambiente o elimina la riga emdash:ip_salt, quindi esegui di nuovo il deploy. Impatto: i nuovi invii di commenti producono hash diversi, quindi il conteggio del rate limit riparte da zero per tutti. I commenti esistenti e i relativi hash memorizzati non vengono toccati.
• In caso di perdita: nessuna perdita di dati. Viene azzerata solo la continuità del rate limit.

Token di sessione e API

• Le sessioni usano l’archivio delle sessioni di Astro (Workers KV su Cloudflare, filesystem su Node). Gli adapter che non configurano un archivio, come Vercel, richiedono un driver di sessione in astro.config.mjs; senza di esso, l’accesso fallisce con un errore che spiega che è richiesto un driver di sessione. Il cookie contiene un ID di sessione opaco; non c’è alcun secret di firma da gestire. Esci per terminare una sessione, oppure svuota l’archivio delle sessioni (ad es. il namespace KV) per costringere tutti ad accedere di nuovo.
• I 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 sola volta alla creazione. Ruota il token revocandolo e ricreandolo nell’admin.
• I token di invito, magic link e ripristino hanno un unico scopo, sono memorizzati come hash SHA-256 in auth_tokens e hanno una durata limitata (inviti 7 giorni, magic link 15 minuti).

Non c’è nulla da salvare né 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 dei servizi esterni vengono lette dall’ambiente e non vengono mai scritte nel database. Ruotale presso il provider, aggiorna la variabile ed esegui di nuovo il deploy.

Su Cloudflare, impostale con wrangler secret put; per lo sviluppo locale, inseriscile in .env. Wrangler legge .dev.vars oppure .env, non entrambi, e .dev.vars ha la precedenza quando è presente. R2 tramite binding non richiede variabili per le chiavi di accesso perché il binding concede l’accesso in fase di runtime. Consulta storage dei media.

Su Node, EmDash legge la chiave segreta di Turnstile dall’ambiente di processo del server quando arriva una richiesta, e né astro dev né il server compilato caricano .env al suo interno. Imposta la chiave nell’ambiente del tuo host, esportala nella shell che esegue astro dev, oppure avvia il server compilato con node --env-file=.env ./dist/server/entry.mjs.

Secret di plugin

Le impostazioni che un plugin dichiara con type: "secret" (chiavi API di provider email, CAPTCHA dei form, ecc.) vengono inserite nell’interfaccia dell’admin e cifrate nella tabella options sotto plugin:<id>:settings:<key>. L’admin riceve solo l’informazione 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 all’interno del suo runtime isolato. I valori memorizzati al di fuori di uno schema di impostazioni dichiarato, comprese le voci arbitrarie di KV e di stato 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 dal 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 viene persa: ripristina l’EMDASH_ENCRYPTION_KEY corrispondente dal backup separato delle chiavi. Se non esiste alcuna copia, sostituisci ogni credenziale interessata presso il suo provider e inserisci i valori sostitutivi dopo aver configurato una nuova chiave di cifratura.

Credenziali CLI

La CLI emdash memorizza i token del sito in ~/.config/emdash/auth.json (rispettando XDG_CONFIG_HOME) con permessi riservati al proprietario (0600). emdash login si autentica sulla tua istanza EmDash tramite un device flow OAuth e memorizza il token indicizzato per URL dell’istanza. emdash logout lo rimuove; a ogni invocazione, --token o EMDASH_TOKEN sovrascrive il token memorizzato.

Perdere il file è innocuo: esegui di nuovo emdash login.

Credenziali CLI del registro plugin

La CLI separata emdash-plugin (pacchetto @emdash-cms/plugin-cli) si rivolge al registro AT Protocol sperimentale. La pubblicazione lì è legata 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 risiedono in ~/.emdash/oauth/, e l’identità del publisher (DID, handle, PDS) è memorizzata nella cache in ~/.emdash/credentials.json; entrambi vengono scritti con permessi riservati al 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. Un publish automatizzato da CI richiede comunque i file di sessione OAuth in ~/.emdash/oauth/ sul runner — le sole variabili d’ambiente non trasportano la sessione OAuth.
• La rotazione o la revoca dell’accesso di pubblicazione avviene sul tuo account AT Protocol (ad es. le password per app), non in EmDash. Consulta Atmosphere auth.

Riferimento rapido di rotazione