web-app-launcher/plans/mvp-web-app-launcher/phase-3-authentication.md

Phase 3: Authentication System

Status: ✅ Complete Parent plan: PLAN.md Domain: fullstack

Objective

Implement the full local authentication flow: login, registration, session management with JWT + refresh tokens in HTTP-only cookies, auth middleware in hooks.server.ts, and guest mode support.

Tasks

• Task 1: Implement src/lib/server/utils/jwt.ts — thin re-export from authService (already implemented in Phase 2)
• Task 2: Implement src/lib/server/utils/password.ts — thin re-export from authService (already implemented in Phase 2)
• Task 3: Implement src/hooks.server.ts — auth middleware, session injection into event.locals
• Task 4: Create src/routes/login/+page.server.ts — login form action (Superforms + Zod)
• Task 5: Create src/routes/login/+page.svelte — login page UI
• Task 6: Create src/routes/register/+page.server.ts — registration form action (respects admin toggle)
• Task 7: Create src/routes/register/+page.svelte — registration page UI
• Task 8: Create src/routes/auth/refresh/+server.ts — token refresh endpoint
• Task 9: Create src/routes/+layout.server.ts — root layout load: inject user session
• Task 10: Create src/routes/+layout.svelte — root layout shell (minimal, polished in Phase 7)
• Task 11: Implement src/lib/server/middleware/authenticate.ts — reusable auth check helper
• Task 12: Implement src/lib/server/middleware/authorize.ts — role-based access check
• Task 13: Implement src/lib/server/middleware/guestAccess.ts — guest mode board visibility
• Task 14: Create src/routes/+page.svelte — root page (redirect to default board or login)
• Task 15: Create logout endpoint/action — invalidate refresh token, clear cookies

Files to Modify/Create

• src/hooks.server.ts — auth middleware
• src/lib/server/utils/jwt.ts — JWT utilities
• src/lib/server/utils/password.ts — password utilities
• src/lib/server/middleware/authenticate.ts
• src/lib/server/middleware/authorize.ts
• src/lib/server/middleware/guestAccess.ts
• src/routes/login/+page.svelte
• src/routes/login/+page.server.ts
• src/routes/register/+page.svelte
• src/routes/register/+page.server.ts
• src/routes/auth/refresh/+server.ts
• src/routes/+layout.server.ts
• src/routes/+layout.svelte
• src/routes/+page.svelte
• src/app.d.ts — augment Locals with user session type (already done in Phase 2)

Acceptance Criteria

• Users can register (when enabled) and log in with email/password
• JWT access token + refresh token issued in HTTP-only cookies
• hooks.server.ts validates tokens on every request and injects user into event.locals
• Refresh token rotation works (old token invalidated)
• Logout clears cookies and invalidates refresh token
• Guest mode: unauthenticated users can access guest-accessible boards
• Protected routes redirect to login
• Form validation with Superforms + Zod shows errors inline

Notes

• Access token expiry: 15 minutes; Refresh token expiry: 7 days
• Store refresh tokens in DB (User model) for server-side invalidation
• OAuth is deferred to Phase 2 of the project (post-MVP)
• Registration toggle is read from SystemSettings
• Big Bang: login page will be functional but unstyled/minimal until Phase 7

Review Checklist

• All tasks completed
• Code follows project conventions
• No unintended side effects
• Build passes
• Tests pass (new + existing)

Handoff to Next Phase

What's ready for Phase 4:

• Full local auth flow is implemented: login, registration, logout, token refresh.
• hooks.server.ts validates JWT access tokens on every request and injects event.locals.user and event.locals.session. Expired access tokens are silently refreshed via refresh token rotation.
• Protected routes (anything except /login, /register, /auth/*, /api/health) redirect unauthenticated users to /login.
• Guest mode support: guestAccess.ts middleware checks isGuestAccessible on boards; hooks allow unauthenticated access to guest-accessible board routes.
• Reusable middleware helpers available: requireAuth(), isAuthenticated(), requireRole(), requireAdmin().
• Login/register pages use Superforms + Zod with inline error display.
• Registration respects SystemSettings.registrationEnabled toggle.
• Root layout (+layout.server.ts) injects user into all page data.
• Root page (+page.server.ts) redirects to default board (authenticated) or guest board (unauthenticated) or /login.
• Logout endpoint at POST /auth/logout revokes refresh token and clears all auth cookies.
• jwt.ts and password.ts are thin re-exports from authService (no duplication).
• A refresh_user_id cookie is used alongside refresh_token to identify the user during token rotation (since refresh tokens are stored hashed per-user).