Implementando mejores practicas de gestion de variables de entorno con Claude Code

Por que es importante la gestion de variables de entorno

En el desarrollo de aplicaciones, es necesario gestionar de forma segura informacion confidencial como claves de API e informacion de conexion a bases de datos. Las variables de entorno son el medio basico para esto, pero suelen carecer de seguridad de tipos y validacion. Con Claude Code, puede construir rapidamente un sistema robusto de gestion de variables de entorno.

Carga de variables de entorno con seguridad de tipos

> Crea un modulo que valide las variables de entorno con zod y las cargue con seguridad de tipos.
> Que permita distinguir entre obligatorias y opcionales, y establecer valores por defecto.

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']).default('development'),
  PORT: z.coerce.number().int().positive().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional(),
  API_KEY: z.string().min(1, 'API_KEY es obligatoria'),
  JWT_SECRET: z.string().min(32, 'JWT_SECRET debe tener al menos 32 caracteres'),
  CORS_ORIGINS: z.string().transform((s) => s.split(',')).default('http://localhost:3000'),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

export type Env = z.infer<typeof envSchema>;

function loadEnv(): Env {
  const result = envSchema.safeParse(process.env);

  if (!result.success) {
    const formatted = result.error.format();
    console.error('Error de validacion de variables de entorno:');
    for (const [key, value] of Object.entries(formatted)) {
      if (key !== '_errors' && value && '_errors' in value) {
        console.error(`  ${key}: ${(value as any)._errors.join(', ')}`);
      }
    }
    process.exit(1);
  }

  return result.data;
}

export const env = loadEnv();

Gestion de plantillas de archivos .env

> Crea un script que genere automaticamente .env.example.
> Sin incluir valores reales, pero con comentarios descriptivos.

import fs from 'fs';
import path from 'path';

function generateEnvExample(envPath: string, outputPath: string) {
  const envContent = fs.readFileSync(envPath, 'utf-8');
  const lines = envContent.split('\n');

  const exampleLines = lines.map((line) => {
    if (line.startsWith('#') || line.trim() === '') return line;

    const [key] = line.split('=');
    const descriptions: Record<string, string> = {
      DATABASE_URL: '# URL de conexion a la base de datos (ej: postgresql://user:pass@localhost:5432/db)',
      API_KEY: '# Clave de API (gestionar de forma segura en produccion)',
      JWT_SECRET: '# Secreto para firma JWT (minimo 32 caracteres)',
    };

    const comment = descriptions[key?.trim()] || '';
    return `${comment}\n${key?.trim()}=`;
  });

  fs.writeFileSync(outputPath, exampleLines.join('\n'));
}

Cambio de configuracion por entorno

> Crea una clase Config que gestione configuraciones diferentes por entorno.
> Compatible con 3 entornos: development, staging y production.

interface AppConfig {
  database: { pool: number; ssl: boolean };
  cache: { ttl: number; enabled: boolean };
  logging: { level: string; format: string };
}

const configs: Record<string, AppConfig> = {
  development: {
    database: { pool: 5, ssl: false },
    cache: { ttl: 60, enabled: false },
    logging: { level: 'debug', format: 'pretty' },
  },
  production: {
    database: { pool: 20, ssl: true },
    cache: { ttl: 3600, enabled: true },
    logging: { level: 'warn', format: 'json' },
  },
};

export function getConfig(): AppConfig {
  const nodeEnv = env.NODE_ENV;
  return configs[nodeEnv] ?? configs.development;
}

Soporte para rotacion de secretos

Para realizar la rotacion de informacion confidencial de forma segura, tambien puede construir un mecanismo que mantenga multiples versiones de secretos simultaneamente.

class SecretManager {
  private secrets: Map<string, string[]> = new Map();

  register(key: string, ...values: string[]) {
    this.secrets.set(key, values.filter(Boolean));
  }

  getCurrent(key: string): string {
    const values = this.secrets.get(key);
    if (!values || values.length === 0) {
      throw new Error(`Secreto no encontrado: ${key}`);
    }
    return values[0];
  }

  verify(key: string, token: string, verifyFn: (secret: string, token: string) => boolean): boolean {
    const values = this.secrets.get(key) ?? [];
    return values.some((secret) => verifyFn(secret, token));
  }
}

const secrets = new SecretManager();
secrets.register('JWT_SECRET', env.JWT_SECRET, process.env.JWT_SECRET_PREVIOUS ?? '');

Resumen

Con Claude Code, puede construir de manera integral un sistema de gestion de variables de entorno que incluye validacion con seguridad de tipos usando zod, configuracion por entorno y gestion de secretos. Como fundamento de seguridad, consulte tambien la guia de implementacion de autenticacion. Para la automatizacion de pruebas, se explica en detalle en el articulo sobre estrategias de pruebas.

Para mas detalles sobre zod, consulte la documentacion oficial de Zod. Sobre seguridad en la gestion de variables de entorno, la guia de configuracion de OWASP tambien es una referencia util.