ims/.superpowers/sdd/phase-3-report.md

Phase 3 Report — Custom Auth (bcryptjs + jose)

Status: COMPLETE
Date: 2026-07-23
Branch: main

---

Summary

Replaced Supabase GoTrue authentication with a custom bcryptjs + jose stack. All 38 protected pages and API routes migrated. TypeScript clean, build clean, auth unit tests passing.

---

New Files Created

File	Purpose
lib/auth/session.ts	JWT sign/verify via jose; createSession, verifySession, SessionPayload
lib/auth/password.ts	hashPassword / verifyPassword via bcryptjs at cost 10
lib/auth/get-session.ts	Server-only cookie reader; returns SessionPayload | null
lib/notifications/mailer.ts	sendPasswordResetEmail via Brevo raw fetch
app/api/auth/login/route.ts	POST: bcrypt verify → JWT → set ims_session cookie
app/api/auth/logout/route.ts	POST: clear ims_session cookie
app/api/auth/reset-request/route.ts	POST: create password_reset_tokens row, send email
app/api/auth/reset-confirm/route.ts	POST: validate token hash, update password hash
app/api/auth/change-password/route.ts	POST: verify current password, update hash
supabase/migrations/20260724000001_password_reset_tokens.sql	password_reset_tokens table
tests/lib/auth/session.test.ts	Vitest: JWT create/verify round-trip, invalid token
tests/lib/auth/password.test.ts	Vitest: hash/verify, Supabase-style $2a$ hash compat

---

Modified Files

Core Auth Infrastructure

• lib/auth/require-admin.ts — rewritten: returns { session: SessionPayload | null } (was { supabase, user })
• middleware.ts — rewritten: edge-safe JWT-only verification, no DB imports
• lib/db/index.ts — lazy singleton Proxy pattern to prevent module-level throw during Next.js build static analysis when DATABASE_URL not set in build env
• lib/db/schema.ts — added passwordResetTokens table definition

UI Components

• components/auth/login-form.tsx — POST to /api/auth/login instead of supabase signIn
• components/layout/sidebar.tsx — POST to /api/auth/logout instead of supabase signOut
• app/(auth)/forgot-password/page.tsx — POST to /api/auth/reset-request
• app/(auth)/reset-password/page.tsx — POST to /api/auth/reset-confirm, reads token from search params
• components/account/change-password-form.tsx — POST to /api/auth/change-password

Admin User CRUD

• app/api/admin/users/route.ts — POST creates user with hashPassword + Drizzle insert; DELETE removes row directly; all handlers use { session } from requireAdmin()
• app/api/admin/sites/route.ts — updated to { session } pattern + explicit createClient() for .from() calls
• app/api/admin/trucks/route.ts — same

Storage

• lib/supabase/storage.ts — removed supabase.auth.getUser() call; added userId: string as 5th parameter to uploadEvidenceFile

38 Protected Pages and API Routes

Pattern applied to all:

• import { getSession } from '@/lib/auth/get-session'
• const session = await getSession() replaces supabase.auth.getUser()
• session.sub replaces user.id
• session.role replaces profile fetch from DB
• session.siteId replaces profile.site_id
• createClient() retained where .from() queries still exist (Phase 4 will remove these)

---

Issues Fixed During Implementation

1. app/api/admin/sites/route.ts and app/api/admin/trucks/route.ts — not in original brief scope but broken by requireAdmin signature change; fixed.
2. tests/lib/auth/password.test.ts — brief had describe(name, fn, options) which is wrong Vitest API; fixed to describe(name, fn).
3. tests/lib/supabase/storage.test.ts — uploadEvidenceFile signature added userId; all 3 call sites updated; removed now-unused auth.getUser mock.
4. .next/types/validator.ts — stale reference to deleted /api/auth/callback/route.ts; removed the block.
5. All 5 auth API routes — missing export const dynamic = 'force-dynamic'; added to prevent Next.js static pre-rendering.
6. lib/db/index.ts — module-level throw when DATABASE_URL unset failed build's "collect page data" phase even with force-dynamic; refactored to lazy Proxy singleton.
7. Test environment — vitest global config uses jsdom; jose and bcryptjs use native Uint8Array which fails instanceof check across jsdom/Node realms; fixed with // @vitest-environment node in both auth test files.

---

Invariants Preserved

• middleware.ts imports only jose and next/server — no pg, drizzle-orm, or DB connections
• All .from() Supabase queries retained untouched (Phase 4 scope)
• server-only import in get-session.ts prevents client-side use
• Passwords hashed at bcrypt cost 10 — compatible with existing Supabase GoTrue hashes

---

Verification

npx tsc --noEmit   → clean (0 errors)
npm run build      → clean (warnings only: img tag, unused UserDb type)
npm test -- tests/lib/auth/  → 4/4 passed

---

Env Vars Required at Runtime

Var	Purpose
JWT_SECRET	≥32 char random string for HMAC-SHA256 signing
DATABASE_URL	app_user pool (RLS enforced)
DATABASE_URL_ADMIN	app_admin pool (BYPASSRLS)
BREVO_API_KEY	Transactional email for password reset
BREVO_FROM_EMAIL	Sender address for password reset emails
APP_URL	Base URL for reset link generation (server-side only)