# 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

- [x] Analyze current state
- [x] Write tests for session validation (updated auth.guard.spec.ts)
- [x] Update shared types to include workspace fields
- [x] Update API AuthGuard to use cookie-based sessions
- [x] Add /auth/session endpoint
- [x] Install and configure cookie-parser middleware
- [x] Update CurrentUser decorator to use AuthUser
- [x] Update tests for new session endpoint
- [ ] Web client already uses cookies correctly (no changes needed)
- [ ] Document session refresh mechanism (BetterAuth handles this automatically)
- [x] 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