--- title: "Secret e ambiente: .env, .gitignore, deploy key e cifratura" description: "Gestire i segreti in sicurezza su dev e prod: file env, gitignore, riprendersi da un segreto trapelato, deploy key e cifrare le chiavi utente memorizzate" type: "lesson" locale: "it" course: "Lo stack applicativo moderno - Auth, dati e pagamenti" number: "3.4" canonical: "https://agenticschool.dev/it/corsi/modern-app-stack/secrets-and-environment-env-gitignore-deploy-keys-and-encryption" datePublished: "2026-06-12" dateModified: "2026-06-12" --- # Secret e ambiente: .env, .gitignore, deploy key e cifratura - Course: Lo stack applicativo moderno - Auth, dati e pagamenti - Lesson: 3.4 - Duration: 26 min - Level: fortgeschritten - Status: published - Canonical URL: https://agenticschool.dev/it/corsi/modern-app-stack/secrets-and-environment-env-gitignore-deploy-keys-and-encryption - Locale: it > Gestire i segreti in sicurezza su dev e prod: file env, gitignore, riprendersi da un segreto trapelato, deploy key e cifrare le chiavi utente memorizzate ## Summary Ogni servizio che aggiungi viene con chiavi segrete, e farne trapelare una puo essere catastrofico. Questa lezione e la versione disciplinata della gestione dei segreti: cos'e un file .env, perche .gitignore non e negoziabile, cosa fare esattamente se hai PUBBLICATO un segreto (farlo ruotare, non solo cancellarlo), come funzionano le deploy key Convex e perche devi cifrare a riposo le chiavi API fornite dagli utenti invece di memorizzarle in chiaro. ## What you learn - Cos'e un file .env, perche .gitignore non e negoziabile e chiavi separate per ambiente - Cosa fare se hai gia pubblicato un segreto: farlo ruotare, perche cancellare il commit non basta - Le deploy key Convex e cifrare le chiavi API utente a riposo invece di memorizzarle in chiaro ## Panoramica Ora destreggi chiavi per Clerk, Convex, presto Stripe e probabilmente un provider di IA. Ognuna e una chiave verso qualcosa di prezioso - i tuoi servizi, il tuo denaro, i dati dei tuoi clienti. Gestirle bene non e opzionale appena denaro reale e veri utenti sono in gioco. Questa lezione e la versione rigorosa dell'abitudine dei segreti che hai cominciato nel Corso 1: dove vivono i segreti, come tenerli fuori da Git per sempre, la procedura d'emergenza quando uno scappa, come le deploy key danno accesso al tuo hosting senza esporre le tue credential principali, e perche ogni chiave che i tuoi utenti ti danno deve essere cifrata, non memorizzata in testo leggibile. ## Cosa imparerai Imparerai cos'e un file env e perche esiste, come usare .gitignore perche un segreto non possa mai essere committato, perche ogni ambiente riceve le sue chiavi, i passi esatti di recupero se hai gia pubblicato un segreto, come funzionano le deploy key Convex e dove vanno, e come cifrare a riposo le chiavi API fornite dagli utenti, perche una fuga di database non metta le credential dei tuoi clienti nelle mani degli attaccanti. ## Prerequisiti Le basi dei segreti del Corso 1 (chiavi in .env, .env in .gitignore) e un'app multi-servizio dalla parte precedente di questo corso, perche il rischio cresce con ogni integrazione che aggiungi. La pagina dei fondamenti su cos'e un file env copre le basi assolute se vuoi averle in dettaglio prima di andare oltre. ## Il problema I segreti trapelati sono una delle catastrofi da principiante piu frequenti e costose, e arrivano in silenzio. Incolli una chiave in un file per testare qualcosa, la committi senza riflettere, pubblichi su GitHub, e ora quella chiave e per sempre nella cronologia del tuo repository - leggibile da chiunque possa vedere il repo, e in pochi minuti raschiata da bot che frugano GitHub pubblico esattamente per questo. Persone con una chiave Stripe o cloud trapelata si sono svegliate davanti a migliaia di dollari di addebiti fraudolenti. E memorizzare le chiavi API dei tuoi utenti in chiaro significa che una sola violazione di database espone tutte le credential clienti in una volta. Niente di tutto cio richiede sfortuna. Richiede un commit distratto. Questa lezione rende la distrazione strutturalmente difficile. ## Cos'e un file .env e gitignore fatto bene Un file .env e un semplice file di testo che tiene i tuoi segreti in coppie KEY=value, separato dal tuo codice, perche il codice possa leggerli all'esecuzione senza che i valori siano in chiaro in file committati. Tutto il senso e la separazione: il codice dice "leggi la chiave Stripe dall'ambiente", e la vera chiave siede in .env, che non lascia mai la tua macchina. Cio che rende cio sicuro e .gitignore - un file che elenca cio che Git non deve mai tracciare. Il tuo .env e tutte le sue varianti ci stanno, sempre, in ogni progetto, senza eccezione. Fallo bene una volta per progetto, e un segreto non puo fisicamente essere committato. ```bash # .env.local - vos vrais secrets. NE JAMAIS committer. CLERK_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx CONVEX_DEPLOY_KEY=prod:your-deployment|xxxxxxxxxxxxxxxxxxxx ENCRYPTION_KEY=base64-32-byte-random-value-here ``` Un vero file .env: un segreto per riga, mai committato. ```bash # .gitignore - le righe non negoziabili per ogni progetto node_modules .env .env.local .env.*.local .DS_Store dist ``` Queste righe di .gitignore impediscono che un file .env entri mai in Git. Un'abitudine utile: committa un file .env.example (con le chiavi ma valori vuoti o fittizi), perche chiunque metta in atto il progetto sappia quali variabili sono necessarie senza mai committare un vero segreto. Il file esempio e sicuro da committare proprio perche non contiene nessun vero valore. ## Chiavi separate per ambiente Development e produzione devono usare chiavi diverse. L'hai visto con Clerk (pk_test contro pk_live), e Stripe fa lo stesso (chiavi test contro live). La ragione e il raggio d'impatto: se una chiave di development trapela, puo toccare solo dati di test e la modalita test, quindi i danni sono limitati. Una chiave di produzione trapelata tocca veri clienti e denaro reale. Tenerle strettamente separate significa che un errore durante la costruzione non puo mai raggiungere dati live, e puoi dare le tue chiavi di development a un compagno di squadra o un agente senza rischiare il business. Non usare mai una chiave di produzione in development "per guadagnare tempo" - e esattamente cosi che uno script di test addebita per sbaglio una vera carta o cancella un vero utente. - Chiavi di development (modalita test): sicure da usare costruendo, toccano solo dati di test. - Chiavi di produzione (modalita live): denaro reale, veri utenti - tienile e usale solo nel tuo ambiente in deploy. - Poni i segreti di produzione nei dashboard del tuo host (Vercel) e del tuo backend (Convex), non in un file committato. - Una chiave dev trapelata e un fastidio; una chiave prod trapelata puo essere una catastrofe. Tienile separate. ## Cosa fare se hai PUBBLICATO un segreto E la sezione piu importante della lezione, perche ti capitera, o capitera a qualcuno con cui lavori, prima o poi. L'istinto e cancellare la riga e ri-committare, o cancellare il commit. Cio non basta ed e pericoloso, perche il segreto vive ancora nella tua cronologia Git e, se il repo e mai stato pubblico o pubblicato da qualche parte, e forse gia raschiato. La sola ipotesi sicura e che un segreto pubblicato sia compromesso. Quindi il vero fix e farlo ruotare: vai al servizio, revoca la chiave trapelata e generane una nuova. Ripulire la cronologia Git e secondario e opzionale una volta che la chiave e morta. Tratta la rotazione come il primo e piu urgente passo, ogni volta. - Supponi il segreto compromesso dall'istante in cui e stato pubblicato. I bot scansionano GitHub pubblico in pochi minuti. - FALLO RUOTARE PRIMA: vai al servizio (Stripe, Clerk, Convex, il tuo provider di IA), revoca la vecchia chiave, creane una nuova. - Aggiorna la nuova chiave nel tuo .env e nelle variabili d'ambiente del tuo host/backend. - Solo dopo, opzionalmente, ripulisci la cronologia (strumenti come git filter-repo o BFG) - ma una chiave morta non puo comunque piu nuocerti. - Verifica sul servizio ogni attivita non autorizzata (addebiti, nuovi utenti, chiamate API) mentre la chiave era esposta. Diciamolo chiaramente: cancellare il commit non annulla la fuga del segreto. Far ruotare la chiave, si. Se ricordi una cosa di questa lezione, ricorda: far ruotare prima, ripulire dopo. ## Deploy key Convex Quando il tuo hosting (Vercel) fa il build e il deploy della tua app, ha bisogno del permesso di pubblicare le tue funzioni backend e il tuo schema verso Convex. Sarebbe sbagliato dare al tuo ambiente di build il tuo login personale. Invece, Convex emette una deploy key: una credential delimitata che lascia un ambiente automatizzato pubblicare verso un deployment Convex preciso e niente di piu. La generi nel dashboard Convex per il tuo deployment di produzione poi la memorizzi come variabile d'ambiente in Vercel (mai nel codice). Il principio si generalizza: gli ambienti automatizzati ricevono credential strette e delimitate, non il tuo account principale, perche una deploy key trapelata abbia un raggio d'impatto limitato e possa essere rigenerata senza toccare nient'altro che ti appartiene. ```bash # Da porre in Vercel come variabile d'ambiente (NON in un file committato). # Generata nel dashboard Convex per il tuo deployment di PRODUZIONE. CONVEX_DEPLOY_KEY=prod:your-deployment-name|xxxxxxxxxxxxxxxxxxxxxxxx # Il tuo comando di build la usa poi per fare il deploy del backend durante il build Vercel : # bunx convex deploy --cmd "bun run build" ``` Una deploy key Convex e una credential delimitata per i deployment automatizzati, memorizzata nel tuo host, mai committata. ## Cifrare a riposo le chiavi fornite dagli utenti Ecco uno scenario a cui questo corso porta direttamente: il tuo prodotto lascia gli utenti portare la loro chiave API (la loro chiave OpenAI, la loro chiave Stripe, la loro chiave per un servizio che integri). La memorizzi per poter agire per loro conto. Se memorizzi questa chiave in chiaro nel tuo database, allora una sola violazione da a un attaccante le credential di ogni cliente in una volta - una catastrofe che trasforma un incidente in centinaia. Il fix e cifrare i valori sensibili prima che entrino nel database, e decifrarli solo nel momento in cui li usi. Anche se qualcuno ruba il tuo database, i blob cifrati sono inutili senza la chiave di cifratura, che vive separatamente nel tuo ambiente, non nel database. E la differenza tra "abbiamo avuto una violazione" e "abbiamo avuto una violazione e fatto trapelare le chiavi di ogni cliente". ```typescript // Cifrare prima di memorizzare, decifrare solo all'uso. La ENCRYPTION_KEY vive nel // tuo ambiente, NON nel database, perche un database rubato da solo sia inutile. import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto' const key = Buffer.from(process.env.ENCRYPTION_KEY!, 'base64') // 32 bytes export function encryptSecret(plain: string) { const iv = randomBytes(12) const cipher = createCipheriv('aes-256-gcm', key, iv) const enc = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]) const tag = cipher.getAuthTag() // Memorizzare iv + tag + ciphertext insieme ; nessuno di essi e segreto di per se. return Buffer.concat([iv, tag, enc]).toString('base64') } export function decryptSecret(stored: string) { const raw = Buffer.from(stored, 'base64') const iv = raw.subarray(0, 12) const tag = raw.subarray(12, 28) const enc = raw.subarray(28) const decipher = createDecipheriv('aes-256-gcm', key, iv) decipher.setAuthTag(tag) return Buffer.concat([decipher.update(enc), decipher.final()]).toString('utf8') } ``` AES-256-GCM: cifrare le chiavi utente prima di memorizzare, decifrare solo al punto d'uso. La chiave resta nell'ambiente. Non hai bisogno di essere crittografo per usare un algoritmo ben testato come AES-256-GCM tramite la libreria crypto standard della tua piattaforma, come qui sopra. La regola pratica: non inventare mai la tua cifratura, usa sempre la libreria standard e tieni la chiave di cifratura nel tuo ambiente, totalmente separata dai dati che protegge. ## Errori frequenti I dolorosi: committare un .env perche .gitignore mancava o era sbagliato; cancellare un segreto trapelato da un file credendo che sia al sicuro quando vive ancora nella cronologia ed e gia raschiato; riutilizzare una chiave di produzione in development e toccare per sbaglio dati live; mettere una deploy key o una credential principale in codice committato; e memorizzare le chiavi API utente in chiaro, cosicche una violazione le fa trapelare tutte. Ognuno e evitato dalla stessa disciplina: segreti fuori da Git, chiavi separate per ambiente, far ruotare in caso di fuga, cifrare i dati sensibili a riposo. ## ROI business La disciplina dei segreti e un'assicurazione economica contro una categoria di catastrofi che ha rovinato piccoli prodotti: una fattura cloud che sfugge a causa di una chiave trapelata, un incidente di frode a causa di una chiave di pagamento trapelata, o una violazione che espone le credential clienti e innesca una responsabilita giuridica sotto il GDPR e le leggi di protezione dei dati statunitensi. Il costo di fare bene e qualche minuto di setup per progetto e una funzione di cifratura standard che scrivi una volta. Il costo di fare male si misura in migliaia di dollari, esposizione giuridica e fiducia persa che forse non riguadagnerai mai. Per un fondatore, e una delle abitudini al piu alto rendimento per sforzo di tutto lo stack. ## Checklist Sei abbastanza sicuro per aggiungere i pagamenti quando tutto questo e vero su ogni progetto che pubblichi. - Ogni progetto ha un .gitignore corretto e nessun .env e mai stato committato. - Development e produzione usano chiavi separate, con i segreti di prod posti nei tuoi dashboard di host e di backend. - Conosci la regola: un segreto pubblicato si fa ruotare prima, la cronologia si ripulisce dopo. - Ogni chiave API fornita da un utente e cifrata a riposo, la chiave di cifratura tenuta fuori dal database. ## Risorse Tieni nei preferiti le pagine di chiavi API e di rotazione dei tuoi servizi, per poter revocare una chiave trapelata in secondi quando arriva il momento. GitHub propone anche il secret scanning, che puo allertarti delle chiavi trapelate - attivalo. La pagina dei fondamenti su cos'e un file env copre le basi. Con il tuo stack messo in sicurezza, le due prossime lezioni aggiungono il denaro: Stripe Checkout e Subscription, poi i dettagli di fatturazione piu delicati. ## La tua missione Fai un audit di uno dei tuoi veri progetti proprio ora. Conferma che .gitignore esclude ogni variante di .env, fruga la cronologia del repo per una chiave committata per sbaglio, e se ne trovi una, falla ruotare immediatamente. Poi aggiungi un .env.example con valori vuoti, perche il progetto documenti i suoi segreti richiesti in sicurezza. Se la tua app memorizza una chiave fornita da un utente, avvolgila con le funzioni encrypt/decrypt qui sopra. Questo audit e il genere di cosa che i fondatori rimandano finche non e troppo tardi - fallo oggi. ## Prossima lezione Il tuo stack e messo in sicurezza. Ora fagli guadagnare denaro. La prossima lezione aggiunge Stripe: Hosted contro Embedded Checkout, prodotti e prezzi, subscription con fatturazione mensile e annuale e la stretta disciplina test contro produzione che ti lascia costruire i pagamenti senza mai rischiare un vero addebito. ## Transcript Ogni servizio che aggiungi viene con chiavi segrete, e farne trapelare una puo essere catastrofico. Questa lezione e la versione disciplinata della gestione dei segreti: cos'e un file .env, perche .gitignore non e negoziabile, cosa fare esattamente se hai PUBBLICATO un segreto (farlo ruotare, non solo cancellarlo), come funzionano le deploy key Convex e perche devi cifrare a riposo le chiavi API fornite dagli utenti invece di memorizzarle in chiaro.