Zarządzanie sekretami i zmiennymi środowiskowymi

W aplikacji React zmienne środowiskowe dzielą się na dwie klasy: serwerowe (nigdy nie są wysyłane do przeglądarki) i klienckie (są osadzane w bundlu JavaScript). Zrozumienie, do której klasy należą zmienne, to pierwszy krok w zarządzaniu sekretami, ponieważ zmienne klienckie stają się w praktyce publiczne po wdrożeniu bundla.

W projektach Vite w bundlu klienckim są uwzględniane tylko zmienne z prefiksem VITE_. VITE_PUBLIC_API_URL=https://api.example.com jest dostępna w kodzie przeglądarki za pośrednictwem import.meta.env.VITE_PUBLIC_API_URL. Wszystkie pozostałe zmienne są usuwane z bundla podczas budowania i pozostają dostępne wyłącznie po stronie serwera.

W Next.js prefiks NEXT_PUBLIC_ udostępnia zmienną kodowi JavaScript uruchamianemu w przeglądarce. NEXT_PUBLIC_ANALYTICS_ID=UA-123 jest osadzana w bundlu klienckim. Zmienne bez tego prefiksu (takie jak DATABASE_URL) są dostępne wyłącznie w kodzie po stronie serwera (Server Components, API routes, Server Actions) i nigdy nie są wysyłane do przeglądarki.

Zmienna bez prefiksu nadal może zostać ujawniona, jeśli zostanie przypadkowo zserializowana. Na przykład gdy Server Component przekaże cały obiekt konfiguracji jako props do Client Component, a konfiguracja będzie zawierać DATABASE_URL, sekret pojawi się w kodzie HTML wysłanym do przeglądarki. Ostrożne przekazywanie propsów i audyt serializacji zapobiegają temu problemowi.

W bundlu klienckim nigdy nie mogą znaleźć się: ciągi połączeń z bazą danych i hasła, tajne klucze API usług zewnętrznych (Stripe secret key, OpenAI API key), prywatne klucze RSA/EC, sekrety podpisywania JWT oraz tokeny uwierzytelniające usług wewnętrznych. Jeśli coś z tych danych jest potrzebne do wywołania API, należy przekierować to wywołanie przez endpoint serwerowy.

Wzorzec Backend for Frontend (BFF) umieszcza cienką warstwę serwerową między aplikacją React a wrażliwymi usługami zewnętrznymi. Klient wywołuje /api/stripe/charge, serwer BFF dołącza tajny klucz Stripe i wywołuje API Stripe, a następnie BFF zwraca tylko niezbędne dane odpowiedzi. Sekrety na stałe pozostają na serwerze.

dotenv-vault szyfruje plik .env i umożliwia jego bezpieczne udostępnianie oraz wdrażanie w różnych środowiskach bez zapisywania jawnych sekretów w systemie kontroli wersji. Produkcyjne alternatywy obejmują HashiCorp Vault (dla przedsiębiorstw), AWS Parameter Store (SSM) i GCP Secret Manager — wszystkie zapewniają pobieranie sekretów za pośrednictwem API w czasie działania, a nie podczas budowania.

Platformy CI/CD (GitHub Actions, GitLab CI) zapewniają szyfrowane przechowywanie sekretów dostępnych jako zmienne środowiskowe podczas budowania. Sekrety należy przechowywać w GitHub Secrets i odwoływać się do nich w workflow za pomocą ${{ secrets.STRIPE_SECRET_KEY }}. Sekrety są maskowane w logach i nigdy nie są dołączane do zbudowanego artefaktu.

Next.js i Vite obsługują wiele plików .env: .env (wszystkie środowiska), .env.local (lokalne nadpisania, ignorowany przez git), .env.development i .env.production. Plik lokalny nadpisuje wartości ze współdzielonego pliku, umożliwiając konfigurację właściwą dla danego dewelopera bez wpływu na inne środowiska.

Po zbudowaniu aplikacji należy sprawdzić bundle JavaScript pod kątem przypadkowo ujawnionych sekretów. Można uruchomić grep -r "password|secret|api_key" dist/ lub użyć dedykowanego narzędzia, takiego jak analiza strings na zbudowanych plikach. Niektóre sekrety, jeśli zostaną przypadkowo dołączone, można łatwo rozpoznać po formacie (UUID, ciągi base64 lub prefiksy kluczy, takie jak sk_live_).

Każde środowisko i każda usługa powinny mieć dostęp wyłącznie do sekretów, których potrzebują. Klient React nie potrzebuje żadnych sekretów — powinien otrzymywać tylko publiczne identyfikatory. Serwer BFF potrzebuje wyłącznie sekretów wymaganych przez wywoływane przez niego API. Środowiska deweloperskie powinny używać nieprodukcyjnych kluczy API z ograniczonymi uprawnieniami i limitami wydatków.

Co dzieje się ze zmienną środowiskową Next.js mającą prefiks NEXT_PUBLIC_?

Vite używa VITE_, a Next.js używa NEXT_PUBLIC_, aby udostępniać zmienne w bundlu przeglądarki. Wszystkie pozostałe zmienne są dostępne wyłącznie po stronie serwera. Nigdy nie należy umieszczać w kodzie klienckim haseł do baz danych, tajnych kluczy API ani sekretów podpisywania JWT. Wzorzec BFF umożliwia przekierowywanie wrażliwych wywołań API przez serwer. Do zarządzania sekretami w środowisku produkcyjnym należy używać dotenv-vault, AWS Parameter Store lub GitHub Secrets. Zbudowane bundle należy sprawdzać pod kątem przypadkowo ujawnionych sekretów.