feat: migrate from NextAuth v5 to Better Auth

[chriskehayias]

Summary

• Replace NextAuth v5 (beta) with Better Auth for OAuth authentication against Ministry Platform's OIDC endpoints. NextAuth v5 never reached stable release and is now in maintenance mode; Better Auth is the canonical successor.
• Stateless JWT sessions with cookie cache — no database required. OAuth sub claim (MP User_GUID) stored as user.userGuid via additionalFields + mapProfileToUser, since Better Auth generates its own internal user.id.
• Improved error propagation in server actions and HTTP client — real MP API error messages now surface instead of generic "Failed to fetch" messages.

Changes by area

New files:

• src/lib/auth.ts — Better Auth server config (genericOAuth, customSession, nextCookies plugins)
• src/lib/auth-client.ts — Client-side auth client
• src/app/api/auth/[...all]/route.ts — Better Auth route handler
• .claude/references/auth.md — Detailed auth reference documentation

Modified (auth migration):

• src/proxy.ts — getSessionCookie() replaces getToken() from next-auth/jwt
• src/app/providers.tsx — Removed SessionProvider, simplified to UserProvider only
• src/app/signin/page.tsx — Uses authClient.signIn.oauth2() / authClient.getSession()
• src/contexts/user-context.tsx — Uses authClient.useSession(), reads userGuid for profile loading
• src/contexts/session-context.tsx — Simplified to useAppSession() wrapper
• src/components/layout/auth-wrapper.tsx — Uses auth.api.getSession()
• src/components/user-menu/actions.ts — Custom OIDC logout via auth.api.signOut()
• Server actions (contact-logs, contact-lookup-details, user-tools-debug) — Use userGuid for MP lookups, improved error propagation
• src/lib/providers/ministry-platform/utils/http-client.ts — GET errors now include response body
• .env.example, CLAUDE.md, README.md — Updated for Better Auth

Deleted:

• src/auth.ts (NextAuth config)
• src/types/next-auth.d.ts (NextAuth type augmentation)
• src/lib/providers/ministry-platform/auth/auth-provider.ts (NextAuth-specific provider)

Tests rewritten:

• src/auth.test.ts — Tests customSession name splitting, userGuid mapping, OAuth config
• src/proxy.test.ts — Mocks better-auth/cookies instead of next-auth/jwt

Test plan

• Build passes (npm run build)
• All tests pass (npm run test:run) — 137 tests across 6 files
• OAuth login flow: visit app → redirect to signin → MP OAuth → callback → authenticated
• Verify user.userGuid is populated after login (check session in browser devtools)
• User profile loads in header (name, avatar via UserProvider)
• Session persists across page refresh
• OIDC logout: sign out → MP endsession → redirect back → signed out
• Route protection: unauthenticated access to protected route → redirect to signin
• Server actions work (e.g., create/edit contact log) — auth checks + userGuid lookups
• OAuth callback URL configured in MP: /api/auth/oauth2/callback/ministry-platform

---

Generated with Claude Code