Config Management

Validate once at startup, fail fast, never leak secrets.

Core Principle

Configuration is a potential source of runtime errors. Validate at startup so failures happen immediately, not at 3 AM when a code path finally executes.

Required Behaviors

1. Validate Config at Startup

Use node-env-resolver for multi-source configuration with validation:

import { resolveAsync } from 'node-env-resolver';
import { processEnv } from 'node-env-resolver/resolvers';
import { postgres, string, number } from 'node-env-resolver/validators';
import { awsSecrets } from 'node-env-resolver-aws';

const config = await resolveAsync({
  resolvers: [
    // Non-sensitive config from process.env (safe)
    [processEnv(), {
      PORT: number({ default: 3000 }),
      NODE_ENV: ['development', 'production'] as const,
    }],
    // Secrets loaded directly into memory from AWS (never touch process.env)
    [awsSecrets({ secretId: 'my-app' }), {
      DATABASE_URL: postgres(),
      API_KEY: string(),
    }],
  ],
  options: {
    preventProcessEnvWrite: true,  // Secrets never touch process.env
  },
});

Alternative: Use Zod directly for simpler setups:

// config/schema.ts
import { z } from 'zod';

const ConfigSchema = z.object({
  port: z.coerce.number().min(1).max(65535),
  database: z.object({
    host: z.string().min(1),
    port: z.coerce.number(),
    name: z.string().min(1),
  }),
  redis: z.object({
    url: z.string().url(),
  }),
  logLevel: z.enum(['debug', 'info', 'warn', 'error']),
});

export type Config = z.infer<typeof ConfigSchema>;

// main.ts - Validate immediately on startup
const config = ConfigSchema.parse({
  port: process.env.PORT,
  database: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    name: process.env.DB_NAME,
  },
  redis: {
    url: process.env.REDIS_URL,
  },
  logLevel: process.env.LOG_LEVEL,
});

// If we get here, config is valid and typed

2. Never Read Config During Requests

Config should be resolved ONCE at startup, then injected:

// WRONG - Reading env vars during request
async function getUser(args: { userId: string }, deps: GetUserDeps) {
  const timeout = parseInt(process.env.DB_TIMEOUT || '5000'); // Reads every call!
  return deps.db.findUser(args.userId, { timeout });
}

// CORRECT - Config injected via deps
type GetUserDeps = {
  db: Database;
  config: { dbTimeout: number };
};

async function getUser(args: { userId: string }, deps: GetUserDeps) {
  return deps.db.findUser(args.userId, { timeout: deps.config.dbTimeout });
}

3. Secrets in Memory Only

Never store secrets in environment variables. Load directly from secret managers into memory:

// WRONG - Secret in env, visible in process dumps, /proc/self/environ, child processes
const apiKey = process.env.API_KEY;

// CORRECT - Fetch from secret manager at startup, loaded into memory only
const config = await resolveAsync({
  resolvers: [
    [awsSecrets({ secretId: 'my-app' }), {
      API_KEY: string(),
      DATABASE_PASSWORD: string(),
    }],
  ],
  options: {
    preventProcessEnvWrite: true,  // Secrets never touch process.env
  },
});

// Secrets are in config object in memory, never in process.env
const deps = { db: createDb(config.DATABASE_PASSWORD), apiKey: config.API_KEY };

Why memory is safer:

• process.env is accessible to child processes
• On Linux, /proc/self/environ exposes all environment variables
• Error messages and logs may accidentally include environment variables
• Secrets in memory are isolated to your application process

3a. Ephemeral Credentials

Prefer short-lived, auto-rotating credentials over long-lived secrets:

const config = await resolveAsync({
  resolvers: [
    [awsSecrets({
      secretId: 'prod/db-creds',
      refreshInterval: 3600000,  // Refresh every hour
    }), {
      DB_USERNAME: string(),
      DB_PASSWORD: string(),  // Short-lived, auto-rotated
    }],
  ],
});

If a credential leaks, automatic expiration limits the blast radius.

3b. Secret Scanning in CI

Runtime policies protect production, but what about the .env file that should never exist? Run secret scanning in CI:

# .github/workflows/security.yml
name: Security Checks

on: [push, pull_request]

jobs:
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for thorough scanning

      - name: TruffleHog Secret Scan
        uses: trufflesecurity/trufflehog@main
        with:
          extra_args: --only-verified

Tools like TruffleHog and Gitleaks scan commit history, catching secrets that were committed and then "deleted" (but still exist in git history).

4. Fail Fast on Missing Config

// WRONG - Default values hide misconfiguration
const port = process.env.PORT || 3000;
const dbHost = process.env.DB_HOST || 'localhost';

// CORRECT - Fail immediately if missing
const ConfigSchema = z.object({
  port: z.coerce.number(),  // No default - must be provided
  dbHost: z.string().min(1),  // No default - must be provided
});

// Throws ZodError at startup if missing
const config = ConfigSchema.parse(process.env);

5. Type-Safe Config Access

Use Zod inference to ensure type safety:

// Config type is inferred from schema
export type Config = z.infer<typeof ConfigSchema>;

// Deps include typed config
type GetUserDeps = {
  db: Database;
  config: Pick<Config, 'dbTimeout' | 'maxRetries'>;
};

Environment-Specific Config

const EnvSchema = z.enum(['development', 'staging', 'production']);

const BaseConfigSchema = z.object({
  env: EnvSchema,
  port: z.coerce.number(),
});

// Environment-specific overrides
const ProductionConfigSchema = BaseConfigSchema.extend({
  env: z.literal('production'),
  sslEnabled: z.literal(true),
});

const DevelopmentConfigSchema = BaseConfigSchema.extend({
  env: z.literal('development'),
  sslEnabled: z.literal(false).default(false),
});

const ConfigSchema = z.discriminatedUnion('env', [
  ProductionConfigSchema,
  DevelopmentConfigSchema,
]);

Dependency Injection for Testability

Configuration resolution should accept resolvers as parameters:

// config.ts
import { resolveAsync, type Resolver } from 'node-env-resolver';
import { processEnv } from 'node-env-resolver/resolvers';
import { awsSecrets } from 'node-env-resolver-aws';
import { postgres, string, number } from 'node-env-resolver/validators';

const schema = {
  PORT: number({ default: 3000 }),
  DATABASE_URL: postgres(),
  API_KEY: string(),
};

export async function getConfig(
  resolvers: Resolver[] = [
    processEnv(),
    awsSecrets({ secretId: 'my-app' }),
  ]
) {
  return resolveAsync({
    resolvers: resolvers.map(r => [r, schema]),
  });
}

Now your tests can inject mock resolvers:

// config.test.ts
import { getConfig } from './config';

it('should resolve configuration', async () => {
  const mockResolver = {
    name: 'test-env',
    load: async () => ({
      DATABASE_URL: 'postgres://test:5432/testdb',
      API_KEY: 'test-key',
    }),
    loadSync: () => ({
      DATABASE_URL: 'postgres://test:5432/testdb',
      API_KEY: 'test-key',
    }),
  };

  const config = await getConfig([mockResolver]);

  expect(config.DATABASE_URL).toBe('postgres://test:5432/testdb');
  expect(config.API_KEY).toBe('test-key');
  expect(config.PORT).toBe(3000); // default value
});

No vi.mock() needed. Just pass a resolver object. This is the same dependency injection pattern we've been using throughout.

Config in Tests

import { mock } from 'vitest-mock-extended';

const testConfig: Pick<Config, 'dbTimeout'> = {
  dbTimeout: 100, // Fast for tests
};

const deps = {
  db: mock<Database>(),
  config: testConfig,
};

const result = await getUser({ userId: '123' }, deps);

Quick Reference

Rule	Implementation
Validate at startup	Zod schema.parse() in main.ts
Never read during request	Inject config via deps
Secrets in memory	SecretManager.get(), not process.env
Fail fast	No defaults for required config
Type safety	z.infer<typeof Schema>