Comment corriger l'oubli de validation des variables d'environnement par l'IA

Les agents IA lisent les valeurs process.env directement sans validation, ce qui provoque des bugs silencieux d'undefined et des erreurs de démarrage manquantes lorsque les variables d'environnement sont absentes.

L’agent accède directement à process.env.SOME_KEY, donc lorsque la variable est absente, l’application démarre silencieusement cassée — pas de plantage, pas d’avertissement, juste undefined qui circule dans la logique métier.

Le symptôme

Des lectures brutes de process.env dispersées dans la base de code sans schéma, sans sécurité de type et sans assertion au démarrage.

// lib/stripe.ts — WRONG
import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});
// If STRIPE_SECRET_KEY is undefined, Stripe SDK accepts it and every
// charge silently fails at runtime instead of at startup.

Pourquoi cela se produit

L’agent optimise la brièveté et l’obtention rapide d’un code fonctionnel. La validation des variables d’environnement est un code passe-partout qui n’apparaît pas dans la plupart des exemples d’entraînement, donc le modèle l’ignore et va directement à l’intégration.

Comment le repérer

process.env.FOO utilisé sans assertion non-nulle ou vérification de repli.
Aucun fichier de validation env.ts / env.mjs dans le projet.
Le type TypeScript d’une valeur d’env est string | undefined au site d’appel.
L’application démarre sans erreur même lorsque .env.local est vide.

Comment le corriger

Validez toutes les variables d’env requises au démarrage à l’aide d’un schéma Zod afin que le processus plante avec un message clair avant de servir une seule requête.

// lib/env.ts — CORRECT
import { z } from "zod";

const envSchema = z.object({
  STRIPE_SECRET_KEY: z.string().min(1),
  DATABASE_URL: z.string().url(),
  NEXTAUTH_SECRET: z.string().min(32),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
});

export const env = envSchema.parse(process.env);
//                             ^^^^^ throws at startup if any var is missing

// lib/stripe.ts — CORRECT (import validated env)
import Stripe from "stripe";
import { env } from "@/lib/env";

export const stripe = new Stripe(env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

[ ] Create lib/env.ts with a Zod schema covering every required variable
[ ] Import env from lib/env everywhere — never use process.env directly
[ ] Add lib/env.ts to the module graph so it runs at server startup (import in next.config.ts)
[ ] Document all variables in .env.example with placeholder values
[ ] Use z.string().url() / z.string().min(n) for format constraints, not just presence

Invite de correction

Every raw process.env access in this file is unvalidated. Create a lib/env.ts
module that parses and validates all required environment variables with Zod at
startup. Replace every process.env.FOO reference in the codebase with the
typed env.FOO import. Add a .env.example file listing every variable with a
placeholder value and comment.

Test

# Find any remaining raw process.env reads outside of lib/env.ts
grep -rn "process\.env\." --include="*.ts" --include="*.tsx" . \
  | grep -v "lib/env.ts" \
  | grep -v "next.config" \
  | grep -v "node_modules" \
  && echo "FAIL: raw process.env reads found" || echo "OK"