[Gap-Audit] 015 OAuth Display Name: populate display_name from provider + cascade fallback + migrate existing users

[TortoiseWolfe]

Summary

OAuth users land in the app with empty display_name. The OAuth callback handler in src/lib/auth/ likely populates the profile, but the spec's fallback cascade isn't verified end-to-end and no migration exists for users who joined before the fix.

What might be shipped

• OAuth callback in src/lib/auth/ likely creates profile rows; display_name population unverified

Gaps

• OAuth display_name extraction not verified in callback
• Fallback cascade (full_name → username → email_prefix → "Anonymous") not tested
• Migration for existing OAuth users with empty display_name not implemented

Reference

• Spec: features/auth-oauth/015-oauth-display-name/spec.md

[TortoiseWolfe]

Next-session primer

Goal: ensure OAuth users get a populated display_name on first sign-in via fallback cascade; migrate existing users with empty display names.

Effort: small (~2-3h)
Blocked on: nothing

The problem

OAuth callbacks today land users in the app with empty display_name. The spec defines a cascade:
full_name → username → email_prefix → "Anonymous"

Files to touch

• src/app/auth/callback/ — the OAuth callback handler. Inspect what's read from user.user_metadata (OAuth providers populate full_name, name, user_name, preferred_username differently)
• src/lib/auth/oauth-utils.ts — likely the right place for a deriveDisplayName(user) helper
• src/services/auth/audit-logger.ts — optionally log the display-name derivation for debug

Cascade implementation sketch

function deriveDisplayName(user: User): string {
  const meta = user.user_metadata ?? {};
  return (
    meta.full_name?.trim() ||
    meta.name?.trim() ||
    meta.user_name?.trim() ||
    meta.preferred_username?.trim() ||
    user.email?.split('@')[0] ||
    'Anonymous'
  );
}

Migration for existing users

• Query: SELECT id, email, user_metadata FROM auth.users WHERE display_name IS NULL OR display_name = ''
• For each: compute via the cascade, UPDATE
• Run via Supabase Management API per CLAUDE.md (NOT a migration file)
• Idempotent: subsequent runs are no-ops because cascade returns same value

Verification

• Sign up via GitHub OAuth → user_profiles row should have a non-empty display_name
• Sign up via Google OAuth → same
• Sign up with raw email/password → should derive from email prefix
• Run migration script against a sandbox DB, verify NULL displays_names get populated
• New unit tests at src/lib/auth/oauth-utils.test.ts covering all cascade branches

Watch-outs

• Don't overwrite a user's manually-set display_name (UPDATE ... WHERE display_name IS NULL OR display_name = '')
• Different OAuth providers populate user_metadata fields with different keys; test with real GitHub + Google flows, not just unit fixtures