auth-doctor

Auth Doctor — Diagnostic Guide

Health check for existing authentication setups. Detects misconfigurations, missing files, security issues, and dangerous code patterns across Better Auth and Firebase Auth projects.

When to Use

• After running /shipwithai-auth:setup — final validation
• Auth is broken and you don't know why
• Before deploying to production — pre-flight check
• After upgrading auth packages or Next.js version
• Periodic maintenance check

Step 1: Auto-Discover Project Stack

Run the same discovery logic as skills/auth-setup/SKILL.md → Step 0. This ensures setup and doctor use identical detection.

Scan for:

1a. Framework & Versions (same as setup Step 0a/0b):

• next.config.* → Next.js (extract version from package.json)
• App Router vs Pages Router
• React version, Node.js version

1b. Auth Provider (same as setup Step 0d):

• better-auth in deps → Better Auth
• firebase in deps → Firebase
• @clerk/nextjs, next-auth, @supabase/ssr → respective provider
• If no auth detected → ❌ STOP: "No auth setup detected. Run /shipwithai-auth:setup first."

1c. ORM & Database (same as setup Step 0c):

• drizzle.config.ts → Drizzle | prisma/schema.prisma → Prisma
• Check database type from drizzle config or deps (SQLite, PostgreSQL, MySQL)

1d. Package Manager (same as setup Step 0f):

• Lockfile detection

1e. UI Library (same as setup Step 0g):

• components.json → shadcn/ui | Tailwind | MUI/Chakra/Mantine

1e. Existing Auth Pages & Routes (same as setup Step 0e):

• Check for auth pages: src/app/(auth)/login/, src/app/(auth)/register/, etc.
• Check for API routes: src/app/api/auth/
• Check for middleware: src/middleware.ts, middleware.ts

1f. Auth-specific detection:

• .env.local or .env → configured env vars
• OAuth providers: check env vars for GOOGLE_CLIENT_ID, GITHUB_CLIENT_ID, APPLE_CLIENT_ID
• Email: check for resend in deps or RESEND_API_KEY in env

Output the detection summary before proceeding:

🔍 Auth Doctor — Scanning project...

Framework:   Next.js 14.2.18 (App Router)
Provider:    Better Auth ([email protected])
ORM:         Drizzle ([email protected])
Database:    SQLite (better-sqlite3)
Package mgr: npm
UI:          shadcn/ui (new-york)
OAuth:       Google ✓, GitHub ✗
Email:       Resend ✓

Step 2: Run Diagnostic Checks

Run each category. If $ARGUMENTS specifies a category, run ONLY that one. Otherwise run all 8.

Category 1: Environment Variables (env)

Check .env.local exists:

• ❌ CRITICAL if missing entirely
• Read .env.local (or .env as fallback)

Check provider-specific required vars:

Provider	Required
Better Auth	BETTER_AUTH_SECRET, BETTER_AUTH_URL
Firebase	NEXT_PUBLIC_FIREBASE_API_KEY, NEXT_PUBLIC_FIREBASE_PROJECT_ID, NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN, FIREBASE_PROJECT_ID, FIREBASE_CLIENT_EMAIL, FIREBASE_PRIVATE_KEY

Check var quality (not just existence):

• BETTER_AUTH_SECRET — must be ≥32 chars (recommend 64 hex chars from openssl rand -hex 32)
• BETTER_AUTH_URL — must start with http:// or https://
• NEXT_PUBLIC_FIREBASE_API_KEY — must start with AIza
• FIREBASE_PRIVATE_KEY — must contain -----BEGIN

Check for test keys in production:

• ⚠️ WARNING if BETTER_AUTH_URL=http://localhost in a project with NODE_ENV=production indicators
• ⚠️ WARNING if RESEND_API_KEY=re_test_ (test key can't send to real emails)

Check OAuth var pairs:

• If GOOGLE_CLIENT_ID exists → GOOGLE_CLIENT_SECRET must also exist (and vice versa)
• If GITHUB_CLIENT_ID exists → GITHUB_CLIENT_SECRET must also exist
• If APPLE_CLIENT_ID exists → APPLE_CLIENT_SECRET must also exist
• ❌ CRITICAL if one exists without the other

Check email vars (if Resend detected):

• RESEND_API_KEY — must start with re_
• EMAIL_FROM — must be a valid email format
• ⚠️ WARNING if [email protected] — can only send to account owner email

Category 2: File Structure (files)

Check all required files per provider:

Better Auth required files:

src/db/schema.ts                              — Drizzle schema with auth tables
src/lib/db.ts                                 — Drizzle client
src/lib/auth.ts                               — Better Auth server config
src/lib/auth-client.ts                        — Better Auth client
src/app/api/auth/[...all]/route.ts            — API route handler
src/middleware.ts                              — Route protection middleware
src/app/(auth)/login/page.tsx                 — Login page
src/app/(auth)/register/page.tsx              — Register page
src/app/(auth)/forgot-password/page.tsx       — Forgot password page
src/app/(auth)/reset-password/page.tsx        — Reset password page
src/app/(protected)/layout.tsx                — Protected layout with session check
src/app/(protected)/dashboard/page.tsx        — Dashboard page
src/app/(protected)/dashboard/dashboard-client.tsx — Dashboard client component
src/components/icons.tsx                      — OAuth provider icons
.env.example                                  — Env var template
drizzle.config.ts                             — Drizzle Kit config

Firebase required files:

src/lib/firebase.ts                           — Client SDK init
src/lib/firebase-admin.ts                     — Admin SDK init
src/lib/firebase-session.ts                   — Session cookie helpers
src/lib/auth-server.ts                        — getServerUser() helper
src/app/api/auth/session/route.ts             — Session API with CSRF
src/middleware.ts                              — Route protection middleware
src/app/(auth)/login/page.tsx                 — Login page
src/app/(auth)/register/page.tsx              — Register page
src/app/(auth)/forgot-password/page.tsx       — Forgot password page
src/app/(auth)/reset-password/page.tsx        — Reset password page
src/app/(protected)/layout.tsx                — Protected layout with session verification
src/app/(protected)/dashboard/page.tsx        — Dashboard page
src/app/(protected)/dashboard/dashboard-client.tsx — Dashboard client component
src/components/icons.tsx                      — OAuth provider icons
.env.example                                  — Env var template

For each missing file: Report ❌ with the source asset path to copy from.

Cross-reference imports: For each existing file, check that its imports resolve:

• Read the file, extract import ... from "..." statements
• Check that aliased imports (@/lib/auth, @/components/icons, etc.) have corresponding files
• ❌ CRITICAL if an import target doesn't exist (build will fail)

Category 3: Dependencies (deps)

Check provider packages installed:

• Read package.json dependencies + devDependencies
• Verify provider package exists and check version compatibility

Check for known breaking versions:

• better-auth < 0.4.0 — major API changes
• drizzle-kit with driver field instead of dialect — deprecated in 0.21+
• shadcn > 2.1.0 with Tailwind v3 — incompatible (pitfall #44)
• next >= 16 with middleware.ts — deprecated in favor of proxy.ts (pitfall #37)

Check peer dependency conflicts:

npm ls 2>&1 | grep "peer dep" | head -20

Check node_modules exists:

• ❌ CRITICAL if missing

Category 4: Security (security)

Check .gitignore:

• .env and .env.local must be listed
• sqlite.db should be listed (if SQLite)
• ❌ CRITICAL if .env not in .gitignore

Scan for hardcoded secrets in source files:

• Scan src/ for patterns: sk_live_, sk_test_, re_, AIza, -----BEGIN, whsec_
• Exclude .env* files and node_modules/
• ❌ CRITICAL if found in .ts/.tsx source files

Check next.config for security headers:

• ⚠️ WARNING if no security headers configured (X-Frame-Options, HSTS, CSP)
• Reference: assets/config/next.config.ts

Check for better-sqlite3 in serverComponentsExternalPackages (Better Auth + SQLite):

• Next.js 14: must be in experimental.serverComponentsExternalPackages
• Next.js 15+: must be in serverExternalPackages
• ❌ CRITICAL if missing — causes "Cannot find module" at runtime

Category 5: Dangerous Code Patterns (patterns)

These checks map directly to SKILL.md Critical Code Rules R1–R8.

R1 — Module-scope SDK instantiation:

• Scan src/lib/email.ts for new Resend( at module scope (outside functions)
• Scan src/lib/auth.ts for new Stripe( or new Resend( at module scope
• ❌ CRITICAL — crashes during build/SSR because env vars unavailable at module evaluation

R4 — Better Auth middleware using auth() wrapper:

• Scan src/middleware.ts for export { auth as middleware } or export default auth(
• ❌ CRITICAL — auth() is Auth.js (NextAuth v5), not Better Auth

R5 — Firebase middleware decoding JWT:

• Scan src/middleware.ts for atob(, Buffer.from(.*base64, firebase-admin, verifyIdToken, verifySessionCookie
• ❌ CRITICAL — Edge Runtime cannot run Firebase Admin SDK

R2 — Redirect before session cookie (Firebase):

• Scan login/register pages for router.push without preceding await createSessionCookie
• ⚠️ WARNING — session may not persist

R3 — Sign-out order (Firebase):

• Scan dashboard-client for sign-out logic
• Server cookie delete should happen BEFORE client signOut()
• ⚠️ WARNING if order is reversed

R7 — Missing Suspense wrapper:

• Scan reset-password/page.tsx for useSearchParams() without <Suspense>
• ❌ CRITICAL — next build fails in Next.js 14+

R8 — Missing files from checklist:

• Already covered in Category 2, but double-check auth-client.ts specifically
• ❌ CRITICAL — cascading import errors

Category 6: Middleware (middleware)

Check middleware exists:

• Look for src/middleware.ts or middleware.ts
• ⚠️ WARNING if missing

Check middleware pattern matches provider:

Provider	Correct pattern	Wrong pattern
Better Auth	request.cookies.get("better-auth.session_token")	auth(), getSession(), headers()
Firebase	request.cookies.get("__session")	verifyIdToken, firebase-admin, atob

Check route matcher:

• ⚠️ WARNING if no export const config = { matcher: [...] } — middleware runs on all routes including static assets
• Verify matcher includes protected routes (/dashboard, /profile, etc.)
• Verify matcher excludes auth routes (/login, /register, /api/auth)

Check for headers() import (Better Auth):

• headers() from next/headers is NOT available in Edge Runtime middleware
• ❌ CRITICAL if imported

Category 7: OAuth Configuration (oauth)

For each detected OAuth provider (Google, GitHub, Apple):

Check env vars complete:

• Client ID + Client Secret must both be set
• ❌ CRITICAL if one missing

Check auth config includes the provider:

• Better Auth: socialProviders in src/lib/auth.ts should list the provider
• Firebase: Provider must be enabled in Firebase Console (can't auto-check, but warn user)

Check callback URL format:

• Better Auth: {BETTER_AUTH_URL}/api/auth/callback/{provider}
• Firebase: https://{PROJECT}.firebaseapp.com/__/auth/handler
• ⚠️ WARNING: remind user to verify callback URL is registered in provider console

Check for common Google OAuth mistakes (Firebase):

• ⚠️ WARNING: remind about 5-step OAuth setup checklist in references/05-firebase-auth-guide.md
• Testing mode: test user emails must be added in Google Cloud Console

Category 8: Database (database)

Better Auth + Drizzle:

Check drizzle.config.ts:

• Must exist at project root
• Must use dialect: "sqlite" (NOT driver: "better-sqlite")
• ❌ CRITICAL if uses deprecated driver field

Check schema has auth tables:

• Read src/db/schema.ts
• Must contain: user, session, account, verification tables
• ❌ CRITICAL if any missing

Check db.ts passes schema:

• drizzle(client, { schema }) — schema must be imported and passed
• ❌ CRITICAL if schema not passed — queries will fail

Check auth.ts passes schema to adapter:

• drizzleAdapter(db, { provider: "sqlite", schema }) — schema must be passed
• ❌ CRITICAL if schema missing in adapter config

Check database file exists (SQLite):

• ⚠️ WARNING if sqlite.db doesn't exist — needs npx drizzle-kit push to create tables

Check migration status:

• If drizzle/ directory has migration files, check they've been applied
• ⚠️ WARNING if migrations exist but database doesn't have the tables

Step 3: Produce Health Report

After all checks complete, produce a scored report:

╔══════════════════════════════════════════════════╗
║          🔐 Auth Doctor — Health Report          ║
╠══════════════════════════════════════════════════╣
║ Provider:  Better Auth                           ║
║ Score:     18/22 checks passed                   ║
╚══════════════════════════════════════════════════╝

Category                 Status    Issues
─────────────────────────────────────────
1. Environment Variables   ✅       0
2. File Structure          ❌       2 missing files
3. Dependencies            ✅       0
4. Security                ⚠️       1 warning
5. Code Patterns           ✅       0
6. Middleware              ✅       0
7. OAuth Configuration     ❌       1 critical
8. Database                ⚠️       1 warning

──── CRITICAL (fix immediately) ─────────

❌ src/components/icons.tsx missing
   → Copy from plugin: assets/components/shared/icons.tsx

❌ GITHUB_CLIENT_ID set but GITHUB_CLIENT_SECRET missing
   → Add GITHUB_CLIENT_SECRET to .env.local

──── WARNINGS (review recommended) ──────

⚠️  No security headers in next.config
   → Merge from plugin: assets/config/next.config.ts

⚠️  sqlite.db not found — run: npx drizzle-kit push

Ordering rules:

1. ❌ CRITICAL items first (will break at runtime)
2. ⚠️ WARNING items second (works but risky)
3. ✅ PASS items last (or omit for brevity)

Step 4: Offer to Fix

After presenting the report:

Found {N} issues ({X} critical, {Y} warnings).

Would you like me to fix them?
A) Fix all — apply all safe fixes automatically
B) Fix critical only — fix only ❌ items
C) Show me the fixes first — explain what I'd change, then confirm
D) Skip — I'll fix them manually

CRITICAL rules for fixing:

• NEVER modify .env.local values without user confirmation (may contain real secrets)
• NEVER delete files — only create missing ones or patch existing
• For env var issues: show what needs to change, let user update
• For missing files: copy from plugin assets (show source path)
• For code pattern issues: show the diff before applying
• For drizzle.config.ts driver → dialect: safe to auto-fix

Step 5: Post-Fix Verification

After fixes are applied, re-run ONLY the failed categories to confirm they now pass.

If all checks pass:

✅ All issues resolved! Auth setup is healthy.

Next steps:
- Run `npm run build` to verify the full build
- Test the auth flow: register → verify email → login → dashboard → sign out
- Review references/09-common-pitfalls.md for 60 production pitfalls