Pattern — dev auth bypass

When to use

You need to run the app locally without provisioning OAuth credentials, but the app must remain production-safe (no inadvertent auth-bypass in prod).

Pattern

Gate behind an env flag that defaults off:

// lib/auth.ts
export async function currentUser() {
  if (process.env.DEV_AUTH_BYPASS === '1') {
    return { email: 'dev@example.com', id: 'dev-user' };
  }
  // ... real auth lookup
  return null;
}

The flag is set only in .env.local (gitignored) and never in deployed environments.

Gotchas

• DEV_AUTH_BYPASS must NOT be in lib/env.ts zod schema — keeping it as an unvalidated process.env read prevents accidental requirement in production.
• The sign-in route issues a placeholder cookie when bypass is on; downstream cookie reads must tolerate the placeholder shape.
• Document the flag in the project's AGENTS.md so future agents know why currentUser() returns non-null in dev.

Reference

• Mission Control's lib/auth.ts and the bypass note in mission-control/AGENTS.md.