# Authentication Specification

## Job to Be Done

When I access PhaseFlow, I want to securely log in with my email, so that my personal health data remains private.

## Auth Provider

Using PocketBase for authentication and data storage.

**Connection:**
- `POCKETBASE_URL` environment variable
- `src/lib/pocketbase.ts` initializes client

## Login Flow

### Email/Password Authentication

1. User enters email and password on `/login`
2. App calls PocketBase `authWithPassword`
3. On success, PocketBase sets auth cookie
4. User redirected to dashboard

### Session Management

- PocketBase manages session tokens automatically
- Auth state persisted in browser (cookie/localStorage)
- Session expires after 14 days of inactivity

## Pages

### `/login`

**Elements:**
- Email input
- Password input
- "Sign In" button
- Error message display
- Link to password reset (future)

**Behavior:**
- Redirect to `/` on successful login
- Show error message on failed attempt
- Rate limit: 5 attempts per minute

### Protected Routes

All routes except `/login` require authentication.

**Middleware Check:**
1. Check for valid PocketBase auth token
2. If invalid/missing, redirect to `/login`
3. If valid, proceed to requested page

## API Authentication

### User Context

API routes access current user via:
```typescript
const pb = new PocketBase(process.env.POCKETBASE_URL);
// Auth token from request cookies
const user = pb.authStore.model;
```

### Protected Endpoints

All `/api/*` routes except:
- `/api/calendar/[userId]/[token].ics` (token-based auth)
- `/api/cron/*` (CRON_SECRET auth)

## User API

### GET `/api/user`

Returns current authenticated user profile.

**Response:**
```json
{
  "id": "user123",
  "email": "user@example.com",
  "garminConnected": true,
  "cycleLength": 31,
  "lastPeriodDate": "2024-01-01",
  "notificationTime": "07:00",
  "timezone": "America/New_York"
}
```

### PATCH `/api/user`

Updates user profile fields.

**Request Body (partial update):**
```json
{
  "cycleLength": 28,
  "notificationTime": "06:30"
}
```

## User Schema

See `src/types/index.ts` for full `User` interface.

**Auth-related fields:**
- `id` - PocketBase record ID
- `email` - Login email

**Profile fields:**
- `cycleLength` - Personal cycle length (days)
- `notificationTime` - Preferred notification hour
- `timezone` - User's timezone

## PocketBase Client (`src/lib/pocketbase.ts`)

**Exports:**
- `pb` - Initialized PocketBase client
- `getCurrentUser()` - Get authenticated user
- `isAuthenticated()` - Check auth status

## Settings Page (`/settings`)

User profile management:
- View/edit cycle length
- View/edit notification time
- View/edit timezone
- Link to Garmin settings

## Success Criteria

1. Login completes in under 2 seconds
2. Session persists across browser refreshes
3. Unauthorized access redirects to login
4. User data isolated by authentication

## Acceptance Tests

- [ ] Valid credentials authenticate successfully
- [ ] Invalid credentials show error message
- [ ] Session persists after page refresh
- [ ] Protected routes redirect when not authenticated
- [ ] GET `/api/user` returns current user data
- [ ] PATCH `/api/user` updates user record
- [ ] Logout clears session completely
- [ ] Auth cookie is HttpOnly and Secure