stack/docs/scratchpads/193-auth-alignment.md

Issue #193: Align authentication mechanism between API and web client

Objective

Align authentication mechanism between API and web client to ensure consistent JWT/session handling, type definitions, and token management.

Current State Analysis

Problems Identified

1. Type Mismatch:

   • API uses AuthenticatedUser from apps/api/src/common/types/user.types.ts
   • Web uses AuthUser from @mosaic/shared/src/types/auth.types.ts
   • Fields differ: AuthenticatedUser has optional workspaceId, currentWorkspaceId, workspaceRole
   • AuthenticatedUser.name is string | null, AuthUser.name is string

2. Session Handling Inconsistency:

   • API expects Bearer tokens in Authorization header (AuthGuard line 11-15)
   • Web client uses credentials: "include" for cookie-based auth (client.ts line 37)
   • BetterAuth supports both, but we're mixing approaches

3. Missing Session Endpoint:

   • Web calls /auth/session (auth-context.tsx line 23)
   • API only has /auth/profile endpoint (auth.controller.ts line 11-19)

4. Token Refresh:

   • No token refresh mechanism implemented
   • Session expiry is 24 hours but no automatic refresh

Approach

1. Standardize on Cookie-Based Sessions (BetterAuth default)

• BetterAuth handles sessions via cookies automatically
• Remove Bearer token extraction from AuthGuard
• Use BetterAuth's built-in session validation

2. Align Type Definitions

• Update AuthUser in @mosaic/shared to include workspace fields
• Make API use AuthUser instead of AuthenticatedUser
• Ensure consistency across all auth-related types

3. Add Missing Endpoints

• Add /auth/session endpoint to return current session
• Implement proper session refresh endpoint

4. Update Web Client

• Ensure consistent use of cookie-based auth
• Add proper error handling for session expiry
• Implement session refresh logic

Implementation Plan

• Analyze current state
• Write tests for session validation (updated auth.guard.spec.ts)
• Update shared types to include workspace fields
• Update API AuthGuard to use cookie-based sessions
• Add /auth/session endpoint
• Install and configure cookie-parser middleware
• Update CurrentUser decorator to use AuthUser
• Update tests for new session endpoint
• Web client already uses cookies correctly (no changes needed)
• Document session refresh mechanism (BetterAuth handles this automatically)
• Test auth flow (all 20 auth tests passing)

Testing Strategy

Unit Tests

• AuthGuard validates sessions correctly
• Session endpoint returns proper data
• Type compatibility across API and web

Integration Tests

• Login flow with cookies
• Session validation
• Token refresh
• Logout flow

Notes

• BetterAuth handles most session management automatically
• Need to ensure CORS and cookie settings are correct for cross-origin requests
• Session expiry should trigger automatic refresh or redirect to login