Wat zijn omgevingsvariabelen en secrets? Een duidelijke uitleg

Een omgevingsvariabele is een benoemde instelling, zoals DATABASE_URL of STRIPE_SECRET_KEY, die aan je app wordt meegegeven wanneer hij draait, in plaats van dat hij in de code staat. Een secret is een omgevingsvariabele waarvan de waarde privé moet blijven: een API-sleutel, een wachtwoord, een ondertekeningssleutel. Door deze waarden buiten de code te houden, kun je ze wijzigen zonder de app aan te passen, verschillende waarden gebruiken voor testen en voor echte klanten, en voorkomen dat ze uitlekken wanneer je je code deelt of publiceert.

Waarom het ertoe doet als je met AI bouwt

Zodra je app iets nuttigs doet met een andere dienst (een betaling verwerken, een e-mail versturen, een AI-model aanroepen), heeft hij een sleutel nodig. AI-appbouwers vragen daar regelmatig om, en waar die sleutel terechtkomt, bepaalt of je app veilig is.

In AI-gebouwde apps gaat vaak iets mis op twee punten:

• De sleutel wordt in de chat of in de code geplakt. Hij belandt dan in de chatgeschiedenis, de projectbestanden en elke export of repository. Wie hem ziet, kan je account gebruiken.
• De sleutel wordt in de browser gebruikt. Als de code die Stripe of OpenAI aanroept in de pagina draait, wordt de sleutel naar elke bezoeker gestuurd. Mensen kijken daar ook echt naar, en geautomatiseerde scanners zoeken voortdurend naar blootgestelde sleutels.

Als je omgevingsvariabelen begrijpt, zie je beide problemen en kun je om de oplossing vragen.

Een alledaagse vergelijking: de hotelkluis

De code van je app is als de hotelkamer. Gasten (en schoonmakers, en iedereen die je een sleutelkaart geeft) lopen erdoorheen. Je laat je paspoort ook niet op het bureau liggen.

Omgevingsvariabelen zijn de kluis op de kamer. De kamer weet dat er een kluis is en hoe die open moet wanneer dat nodig is, maar het paspoort ligt niet rond. En als je naar een andere kamer verhuist, van je testopzet naar je live site, leg je een ander paspoort in de kluis van die kamer, zonder de kamer opnieuw in te richten.

Hoe het werkt

Je code verwijst naar een naam, niet naar een waarde. In JavaScript op een server ziet dat eruit als process.env.STRIPE_SECRET_KEY. Wanneer de app start, vult het platform waarop hij draait de waarde voor die naam in. Pas de waarde aan in de instellingen van het platform, herstart of deploy opnieuw, en de app gebruikt de nieuwe waarde, zonder codewijziging.

Waar de waarden vandaan komen, hangt af van waar de app draait:

Openbare versus geheime variabelen

Niet elke omgevingsvariabele is geheim. Het helpt om ze in twee groepen in te delen:

Webframeworks maken deze splitsing expliciet. In Vite worden alleen variabelen waarvan de naam begint met VITE_ in de browsercode opgenomen; in Next.js is het voorvoegsel NEXT_PUBLIC_. Dat is een veiligheidsfunctie: alles met die voorvoegsels belandt in de bestanden die elke bezoeker downloadt, dus een secret mag er nooit een krijgen.

Een uitgewerkt voorbeeld: een knop voor AI-samenvatting

Je wilt een knop “Vat deze notitie samen” die een AI-model aanroept.

De onveilige versie: de code van de knop, die in de browser draait, roept de AI-provider rechtstreeks aan, met de API-sleutel erin geschreven. Het werkt in de preview. Maar iedereen kan de ontwikkelaarstools van de browser openen, de sleutel kopiëren en op jouw account een rekening laten oplopen.

De veilige versie:

1. Je maakt de sleutel aan bij de AI-provider en slaat hem op als secret met de naam OPENAI_API_KEY (of iets vergelijkbaars) in de instellingen van je project.
2. De backend krijgt een route, POST /api/summarise, die process.env.OPENAI_API_KEY leest, controleert of de gebruiker is ingelogd, en de provider aanroept.
3. De knop roept jouw route aan, niet de provider. De browser ziet de sleutel nooit.
4. Je voegt dezelfde secret toe aan de instellingen van de gepubliceerde app en deployt opnieuw, zodat de live site hem ook heeft.

Dat patroon (de browser roept jouw server aan, en jouw server houdt de sleutel vast en roept de dienst aan) geldt voor betalingen, e-mail, kaarten en elke andere betaalde API. De gids over het gebruik van LLM-API's gaat dieper in op het AI-geval.

Belangrijke begrippen

• .env-bestand: een tekstbestand met NAAM=waarde-regels, gebruikt bij lokale ontwikkeling. Zet het in .gitignore, zodat het niet wordt meegecommit.
• .env.example: een kopie met de namen maar zonder echte waarden, die wel wordt gecommit zodat anderen weten welke variabelen ze moeten instellen.
• Roteren: een secret vervangen door een nieuwe en de oude intrekken.
• Scope / rechten: veel providers laten je sleutels maken die alleen bepaalde dingen kunnen. Een sleutel die alleen e-mail kan versturen is minder gevaarlijk dan een sleutel die alles kan.
• Test- versus live-sleutels: providers zoals Stripe geven aparte sleutels voor testen en voor echt geld. Gebruik testsleutels tot je lanceert.
• Ondertekeningssecret: een secret waarmee je controleert dat een bericht, zoals een webhook, echt van de afzender komt.

Veelgemaakte fouten en misverstanden

• “Mijn repository is privé, dus sleutels erin zijn prima.” Privérepositories worden gedeeld, geforkt, geëxporteerd en naar laptops gekloond. Sleutels horen daar nog steeds niet. Als je een project koppelt aan GitHub, controleer dan dat er geen .env-bestand in staat.
• “Ik heb hem verwijderd, dus hij is weg.” Git bewaart de geschiedenis en chatlogs bewaren berichten. Als een sleutel ooit is blootgesteld, moet je hem roteren.
• Een openbaar voorvoegsel op een secret gebruiken. VITE_OPENAI_KEY zet je sleutel in de browserbundel.
• Vergeten opnieuw te deployen. Een wijziging van een variabele in de instellingen werkt meestal pas nadat de app opnieuw is gestart of opnieuw is gepubliceerd.
• Eén sleutel voor alles. Aparte sleutels voor test en live, en per app, maken het mogelijk er één in te trekken zonder de rest te breken.
• Geen uitgavenlimiet. Stel bij betaalde API's een budget of limiet in het dashboard van de provider in, voor het geval een sleutel lekt.

Wat je aan je AI-appbouwer kunt vragen

• “Lees de Stripe-secret-sleutel uit een omgevingsvariabele met de naam STRIPE_SECRET_KEY. Gebruik hem alleen op de server.”
• “Zorg dat geen enkele secret in client-side code wordt gebruikt of een VITE_- / NEXT_PUBLIC_-voorvoegsel krijgt.”
• “Maak een .env.example met elke variabele die de app nodig heeft, zonder waarden, en zorg dat .env door git wordt genegeerd.”
• “Controleer de gebouwde frontend-bestanden op tekst die op een API-sleutel lijkt.”

Onze beveiligingschecklist voor AI-gebouwde apps behandelt secrets naast de andere controles die je vóór de lancering moet doen.

Secrets op Mythex

Op Mythex zijn secrets projectomgevingsvariabelen die worden ingevoegd in zowel de preview-sandbox als je gepubliceerde app. Je voegt ze toe onder projectinstellingen → Secrets of met /secrets in de chat, en wanneer de agent een sleutel nodig heeft, toont hij een secrets-kaart in de chat, zodat de waarde in een invoerveld komt en niet in het chatverloop. Als je een secret voor een live app wijzigt, publiceer dan opnieuw zodat de deploy hem oppikt. Projectexports laten secrets weg, en geïmporteerde .env-bestanden worden leeggemaakt, zodat je ze opnieuw instelt in de instellingen. Zie omgevingsvariabelen en secrets en secrets in de chat in de documentatie.

Veelgestelde vragen