# Authentication & Authorization System

**Status**: Placeholder
**Cross-Cutting Concern**: All Phases

---

## Overview

Discord OAuth-based authentication system with JWT session management and role-based access control for game actions.

## Key Components

### 1. Discord OAuth Flow

**Authorization Request**:
```
https://discord.com/api/oauth2/authorize
  ?client_id={CLIENT_ID}
  &redirect_uri={REDIRECT_URI}
  &response_type=code
  &scope=identify
```

**Token Exchange** (Backend):
- Receive authorization code from callback
- Exchange code for access token
- Fetch user profile from Discord API
- Lookup/create user record
- Generate JWT token
- Return JWT to frontend

**JWT Payload**:
```json
{
  "user_id": "discord_snowflake_id",
  "username": "DiscordUser#1234",
  "teams": [42, 99],  // Team IDs user owns
  "exp": 1735689600,  // Expiration timestamp
  "iat": 1735603200   // Issued at timestamp
}
```

### 2. Session Management

**Frontend**:
- Store JWT in localStorage or cookie
- Include JWT in WebSocket auth header
- Include JWT in HTTP API requests (Authorization: Bearer)
- Auto-refresh before expiration (optional)
- Clear on logout

**Backend**:
- Verify JWT signature on every request
- Check expiration
- Extract user_id and teams from payload
- Attach to request context

### 3. Authorization Rules

**Game Actions**:
- User must own the team to make decisions
- Spectators have read-only access
- No actions allowed after game completion

**API Endpoints**:
- `/api/games` - Authenticated users only
- `/api/games/:id` - Public if game visibility is public
- `/api/games/:id/join` - Must own a team in the game

**WebSocket Events**:
- All action events require team ownership validation
- Spectators can only receive events, not emit actions

### 4. Security Considerations

- **Token Storage**: HttpOnly cookies preferred over localStorage
- **Token Expiration**: 24 hours, refresh after 12 hours
- **Rate Limiting**: Per-user action limits
- **Logout**: Invalidate token (blacklist or short expiry)
- **HTTPS Only**: All communication encrypted

## Implementation Files

**Backend**:
- `backend/app/api/routes/auth.py` - OAuth endpoints
- `backend/app/utils/auth.py` - JWT utilities
- `backend/app/middleware/auth.py` - Request authentication
- `backend/app/websocket/auth.py` - WebSocket authentication

**Frontend**:
- `frontend-{league}/pages/auth/login.vue` - Login page
- `frontend-{league}/pages/auth/callback.vue` - OAuth callback
- `frontend-{league}/store/auth.ts` - Auth state management
- `frontend-{league}/middleware/auth.ts` - Route guards

## Reference Documents

- [PRD Lines 135-146](../prd-web-scorecard-1.1.md) - Authentication requirements
- [PRD Lines 686-706](../prd-web-scorecard-1.1.md) - Security requirements

---

**Note**: This is a placeholder to be expanded with detailed implementation code during Phase 1.