Gestione dei segreti e variabili d’ambiente

In un'applicazione React, le variabili d'ambiente rientrano in due categorie: lato server (non vengono mai inviate al browser) e lato client (incorporate nel bundle JavaScript). Capire a quale categoria appartengono le variabili è il primo passo nella gestione dei segreti, perché le variabili lato client sono di fatto pubbliche una volta distribuito il bundle.

Nei progetti Vite, solo le variabili con prefisso VITE_ vengono incluse nel bundle client. VITE_PUBLIC_API_URL=https://api.example.com è accessibile nel codice del browser tramite import.meta.env.VITE_PUBLIC_API_URL. Tutte le altre variabili vengono rimosse dal bundle in fase di build e restano disponibili solo lato server.

In Next.js, il prefisso NEXT_PUBLIC_ espone una variabile al codice JavaScript del browser. NEXT_PUBLIC_ANALYTICS_ID=UA-123 viene incorporato nel bundle client. Le variabili prive del prefisso, come DATABASE_URL, sono accessibili solo nel codice lato server (Server Components, API routes, Server Actions) e non vengono mai inviate al browser.

Una variabile priva di prefisso può comunque diventare accessibile se viene serializzata accidentalmente. Ad esempio, se un Server Component passa il proprio oggetto di configurazione completo come prop a un Client Component e tale configurazione include DATABASE_URL, quel segreto compare nell'HTML inviato al browser. Un'attenta gestione dei prop e una verifica della serializzazione impediscono questo problema.

I seguenti elementi non devono mai comparire nel bundle client: stringhe di connessione e password dei database, chiavi segrete per le API di terze parti (chiave segreta di Stripe, chiave API di OpenAI), chiavi private RSA/EC, segreti per la firma dei JWT e token interni di autenticazione dei servizi. Se uno di questi elementi è necessario per una chiamata API, faccia passare la chiamata tramite un endpoint server.

Il pattern Backend for Frontend (BFF) inserisce un sottile livello server tra l'app React e i servizi esterni sensibili. Il client chiama /api/stripe/charge, il server BFF aggiunge la chiave segreta di Stripe e chiama l'API di Stripe, quindi il BFF restituisce solo i dati di risposta necessari. I segreti restano permanentemente sul server.

dotenv-vault crittografa il file .env e consente di condividerlo e distribuirlo in modo sicuro tra gli ambienti senza inserire segreti in chiaro nel controllo versione. Le alternative per la produzione includono HashiCorp Vault (aziendale), AWS Parameter Store (SSM) e GCP Secret Manager: tutti offrono il recupero dei segreti tramite API a runtime anziché in fase di build.

Le piattaforme CI/CD (GitHub Actions, GitLab CI) offrono un archivio cifrato per i segreti, accessibile come variabili d'ambiente durante le build. Conservi i segreti in GitHub Secrets e li richiami nei workflow come ${{ secrets.STRIPE_SECRET_KEY }}. I segreti vengono mascherati nei log e non vengono mai inclusi nell'artefatto generato.

Next.js e Vite supportano diversi file .env: .env (tutti gli ambienti), .env.local (override locali, esclusi da Git), .env.development e .env.production. Il file locale sostituisce i valori del file condiviso, consentendo una configurazione specifica per ogni sviluppatore senza influire sugli altri ambienti.

Dopo la build, verifichi il bundle JavaScript per individuare eventuali segreti esposti accidentalmente. Esegua grep -r "password|secret|api_key" dist/ oppure utilizzi uno strumento dedicato, come l'analisi con strings, sui file generati. Alcuni segreti inclusi accidentalmente sono facilmente identificabili dal loro formato (UUID, stringhe base64 o prefissi di chiavi come sk_live_).

Ogni ambiente e ogni servizio devono poter accedere solo ai segreti di cui hanno bisogno. Il client React non ha bisogno di alcun segreto: dovrebbe ricevere solo identificatori pubblici. Il server BFF ha bisogno esclusivamente dei segreti necessari per le API che chiama. Gli ambienti di sviluppo dovrebbero utilizzare chiavi API non di produzione, con autorizzazioni limitate e limiti di spesa.

Che cosa accade a una variabile d'ambiente di Next.js con il prefisso NEXT_PUBLIC_?

Vite utilizza VITE_ e Next.js utilizza NEXT_PUBLIC_ per esporre le variabili al bundle del browser. Tutte le altre variabili sono disponibili solo lato server. Non includa mai password di database, chiavi API segrete o segreti per la firma dei JWT nel codice client. Utilizzi il pattern BFF per inoltrare le chiamate API sensibili. Utilizzi dotenv-vault, AWS Parameter Store o GitHub Secrets per la gestione dei segreti in produzione. Verifichi i bundle generati per individuare eventuali segreti esposti accidentalmente.