5c75b935f0
Add comprehensive project documentation and Docker infrastructure for Paper Dynasty Real-Time Game Engine - a web-based multiplayer baseball simulation platform replacing the legacy Google Sheets system. Documentation Added: - Complete PRD (Product Requirements Document) - Project README with dual development workflows - Implementation guide with 5-phase roadmap - Architecture docs (backend, frontend, database, WebSocket) - CLAUDE.md context files for each major directory Infrastructure Added: - Root docker-compose.yml for full stack orchestration - Dockerfiles for backend and both frontends (multi-stage builds) - .dockerignore files for optimal build context - .env.example with all required configuration - Updated .gitignore for Python, Node, Nuxt, and Docker Project Structure: - backend/ - FastAPI + Socket.io game engine (Python 3.11+) - frontend-sba/ - SBA League Nuxt 3 frontend - frontend-pd/ - PD League Nuxt 3 frontend - .claude/implementation/ - Detailed implementation guides Supports two development workflows: 1. Local dev (recommended): Services run natively with hot-reload 2. Full Docker: One-command stack orchestration for testing/demos Next: Phase 1 implementation (backend/frontend foundations)
104 lines
2.8 KiB
Markdown
104 lines
2.8 KiB
Markdown
# 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. |