Cosa sono le variabili d'ambiente e i segreti? Una guida semplice

Una variabile d'ambiente è un'impostazione con un nome, come DATABASE_URL o STRIPE_SECRET_KEY, che viene passata alla tua app quando viene eseguita, invece di essere scritta nel codice. Un segreto è una variabile d'ambiente il cui valore deve restare privato: una chiave API, una password, una chiave di firma. Tenere questi valori fuori dal codice significa poterli cambiare senza modificare l'app, usarne di diversi per i test e per i clienti reali, e impedire che vengano divulgati quando condividi o pubblichi il tuo codice.

Perché è importante quando crei app con l'AI

Nel momento in cui la tua app fa qualcosa di utile con un altro servizio — accetta un pagamento, invia un'email, chiama un modello di AI — ha bisogno di una chiave. I creatori di app con l'AI chiedono queste chiavi di continuo, e il punto in cui finisce la chiave decide se la tua app è sicura.

Nelle app create con l'AI accadono spesso due problemi:

• La chiave viene incollata nella chat o nel codice. Finisce così nella cronologia della chat, nei file del progetto e in qualsiasi esportazione o repository. Chiunque la veda può usare il tuo account.
• La chiave viene usata nel browser. Se il codice che chiama Stripe o OpenAI gira nella pagina, la chiave viene inviata a ogni visitatore. Le persone guardano, e gli scanner automatici cercano continuamente chiavi esposte.

Capire le variabili d'ambiente ti permette di individuare entrambi i problemi e di chiedere la correzione.

Un'analogia di tutti i giorni: la cassaforte dell'hotel

Il codice della tua app è come la stanza d'albergo. Gli ospiti (e le donne delle pulizie, e chiunque tu abbia dato una tessera) ci passano. Non lasceresti il passaporto sulla scrivania.

Le variabili d'ambiente sono la cassaforte in camera. La stanza sa che c'è una cassaforte e come aprirla quando serve, ma il passaporto non è in giro. E se ti sposti da una stanza a un'altra — dalla configurazione di test al sito live — metti un passaporto diverso nella cassaforte di quella stanza, senza ridecorarla.

Come funziona

Il tuo codice fa riferimento a un nome, non a un valore. In JavaScript sul server, si scrive così: process.env.STRIPE_SECRET_KEY. Quando l'app parte, la piattaforma su cui gira riempie il valore di quel nome. Cambi il valore nelle impostazioni della piattaforma, riavvii o rilasci di nuovo, e l'app usa quello nuovo — senza modifiche al codice.

Da dove arrivano i valori dipende da dove gira l'app:

Variabili pubbliche e segrete

Non tutte le variabili d'ambiente sono segrete. Conviene dividerle in due gruppi:

I framework web rendono esplicita questa divisione. In Vite, solo le variabili il cui nome inizia con VITE_ finiscono nel codice del browser; in Next.js il prefisso è NEXT_PUBLIC_. È una funzione di sicurezza: tutto ciò che ha questi prefissi finisce nei file che ogni visitatore scarica, quindi a un segreto non va mai assegnato uno di questi prefissi.

Un esempio pratico: un pulsante di riepilogo con l'AI

Vuoi un pulsante "Riassumi questa nota" che chiama un modello di AI.

La versione non sicura: il codice del pulsante, eseguito nel browser, chiama direttamente il fornitore di AI con la chiave API scritta al suo interno. Nell'anteprima funziona. Significa però che chiunque può aprire gli strumenti per sviluppatori del browser, copiare la chiave ed esaurire il credito del tuo account.

La versione sicura:

1. Crei la chiave presso il fornitore di AI e la salvi come segreto chiamato OPENAI_API_KEY (o simile) nelle impostazioni del progetto.
2. Il backend ha una route, POST /api/summarise, che legge process.env.OPENAI_API_KEY, verifica che l'utente abbia effettuato l'accesso e chiama il fornitore.
3. Il pulsante chiama la tua route, non il fornitore. Il browser non vede mai la chiave.
4. Aggiungi lo stesso segreto alle impostazioni dell'app pubblicata e rilasci di nuovo, così anche il sito live lo ha.

Questo schema — il browser chiama il tuo server, il tuo server custodisce la chiave e chiama il servizio — vale per pagamenti, email, mappe e ogni altra API a pagamento. La guida all'uso delle API LLM approfondisce il caso dell'AI.

Termini chiave

• File .env: un file di testo con righe NOME=valore usato nello sviluppo locale. Inseriscilo in .gitignore perché non venga incluso nel commit.
• .env.example: una copia con i nomi ma senza valori reali, da includere nel repository così gli altri sanno quali variabili impostare.
• Ruotare: sostituire un segreto con uno nuovo e revocare quello vecchio.
• Ambito / permessi: molti fornitori permettono di creare chiavi che possono fare solo alcune cose. Una chiave che può solo inviare email è meno pericolosa di una che può fare tutto.
• Chiavi di test e chiavi live: fornitori come Stripe danno chiavi separate per i test e per i soldi veri. Usa le chiavi di test finché non vai online.
• Segreto di firma: un segreto usato per verificare che un messaggio, come un webhook, arrivi davvero dal mittente.

Errori comuni e idee sbagliate

• "Il mio repository è privato, quindi le chiavi al suo interno vanno bene." I repository privati vengono condivisi, duplicati, esportati e clonati sui portatili. Le chiavi non devono stare lì. Se colleghi un progetto a GitHub, verifica che nessun file .env sia incluso.
• "L'ho cancellata, quindi non esiste più." Git conserva la cronologia e i log delle chat conservano i messaggi. Se una chiave è mai stata esposta, ruotala.
• Usare un prefisso pubblico su un segreto. VITE_OPENAI_KEY mette la tua chiave nel bundle del browser.
• Dimenticare di rilasciare di nuovo. Cambiare una variabile nelle impostazioni di solito ha effetto solo dopo il riavvio dell'app o una nuova pubblicazione.
• Una sola chiave per tutto. Chiavi separate per test e live, e per app, permettono di revocarne una senza rompere le altre.
• Nessun limite di spesa. Per le API a pagamento, imposta un budget o un limite nella dashboard del fornitore, nel caso una chiave venga divulgata.

Cosa chiedere al tuo creatore di app con l'AI

• "Leggi la chiave segreta di Stripe da una variabile d'ambiente chiamata STRIPE_SECRET_KEY. Usala solo sul server."
• "Assicurati che nessun segreto sia usato nel codice lato client o abbia un prefisso VITE_ / NEXT_PUBLIC_."
• "Crea un .env.example che elenchi ogni variabile necessaria all'app, senza valori, e verifica che .env sia escluso da git."
• "Controlla nei file del frontend compilati ogni stringa che somigli a una chiave API."

La nostra checklist di sicurezza per le app create con l'AI tratta i segreti insieme agli altri controlli da fare prima del lancio.

I segreti su Mythex

Su Mythex, i segreti sono variabili d'ambiente del progetto che vengono inserite sia nell'anteprima sia nell'app pubblicata. Le aggiungi in impostazioni del progetto → Segreti oppure con /secrets in chat, e quando l'agente ha bisogno di una chiave mostra una scheda dei segreti in chat, così il valore va in un campo del modulo invece che nella trascrizione del messaggio. Se cambi un segreto per un'app live, pubblica di nuovo perché il rilascio lo recepisca. Le esportazioni di progetto escludono i segreti, e i file .env importati vengono ripuliti, quindi li aggiungi di nuovo nelle impostazioni. Vedi variabili d'ambiente e segreti e segreti in chat nella documentazione.

Domande