t2000-env-gate

Env Validation Gate (cross-app standard)

CLAUDE.md rule 7 states the invariant and the zero-required-vars carve-out. This is the pattern behind it.

Why this rule exists

April 2026: an audric production deploy ran ~4 days with BLOCKVISION_API_KEY="" (empty string in the Vercel UI), silently degrading every BlockVision-backed feature. It surfaced as "the LLM thinks the user has no DeFi positions" — three layers below the actual misconfig. An empty string is truthy-adjacent enough to pass every if (!key) guard and every || fallback, so nothing failed loudly.

The contract

1. Define a lib/env.ts (Next apps) or src/env.ts (servers) Zod schema.
2. Required vars use z.string().trim().min(1, …) — empty string is invalid.
3. Optional vars normalize empty/whitespace → undefined.
4. Schema runs at first import; trigger that import from a boot-time hook:
   • Next.js → instrumentation.ts register()
   • Node server → top of server.ts / index.ts
5. Export a typed env proxy that throws on server-only access from the client.
6. Enforce: ESLint no-restricted-syntax on raw process.env.X outside the env module (gateway), or Biome + code review (audric web-v3).

Canonical reference implementation

audric/apps/web-v3/lib/env.ts + audric/apps/web-v3/instrumentation.ts.

import { z } from 'zod';

const requiredString = z.string().trim().min(1, 'must be a non-empty string');
const optionalString = z.string().optional().transform((v) =>
  v === undefined ? undefined : v.trim().length > 0 ? v.trim() : undefined,
);

const serverSchema = z.object({
  ANTHROPIC_API_KEY: requiredString,
  // …
});

const clientSchema = z.object({
  NEXT_PUBLIC_GOOGLE_CLIENT_ID: requiredString,
  // …
});

// Literal references — Next.js static replacement requires this shape:
const runtimeEnv = {
  ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
  NEXT_PUBLIC_GOOGLE_CLIENT_ID: process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID,
  // …
};

const isServer =
  typeof process !== 'undefined' &&
  (typeof process.versions?.node === 'string' ||
    process.env?.NEXT_RUNTIME === 'edge');

const fullSchema = z.object({ ...serverSchema.shape, ...clientSchema.shape });
const parsed = (isServer ? fullSchema : clientSchema).safeParse(runtimeEnv);

if (!parsed.success) {
  // Format ALL issues + the settings URL — operators fix in one click.
  throw new Error(/* formatted block */);
}

export const env = new Proxy(parsed.data, {
  get(target, prop) {
    if (!isServer && SERVER_ONLY_KEYS.has(prop as string)) {
      throw new Error(`[env] Cannot access server-only var '${String(prop)}' from the client`);
    }
    return target[prop as keyof typeof target];
  },
});