# Know Foolery - Security Architecture

## Security Overview

Know Foolery implements a comprehensive security strategy that addresses authentication, authorization, data protection, application security, and compliance requirements. This document outlines security measures implemented across all system components.


## Security Detailed Requirements

### Authentication & Authorization
- **OAuth 2.0/OIDC**: Industry-standard authentication via Zitadel
- **JWT Tokens**: Secure token-based authentication with short expiration
- **MFA**: Multi-factor authentication required for admin accounts
- **Role-Based Access**: Granular permissions (player, admin roles)

### Data Security
- **Encryption**: AES-256 encryption for sensitive data at rest
- **TLS**: All communications encrypted in transit
- **Input Validation**: Comprehensive sanitization against XSS/injection
- **SQL Injection**: Prevention through parameterized queries (Ent)

### Application Security
- **Rate Limiting**: Per-user and global rate limits
- **CORS**: Strict cross-origin resource sharing policies
- **Security Headers**: CSP, HSTS, X-Frame-Options implementation
- **Audit Logging**: Comprehensive logging of security events

### Game Integrity
- **Server-Side Validation**: All game logic validated on backend
- **Anti-Cheating**: Session state verification and tampering detection
- **Score Validation**: Server-side score calculation and verification


## Security Architecture

### Defense in Depth Strategy

```
┌──────────────────────────────────────────────────────────────────────────┐
│                        Security Layers                                   │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                    Perimeter Security                               │ │
│  │  WAF • DDoS Protection • Rate Limiting • IP Filtering               │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                   │                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                  Application Security                               │ │
│  │  HTTPS • CORS • CSP • Security Headers • Input Validation           │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                   │                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                Authentication & Authorization                       │ │
│  │  OAuth 2.0 • JWT • MFA • RBAC • Session Management                  │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                   │                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                     Data Security                                   │ │
│  │  Encryption at Rest • TLS • Field Encryption • Anonymization        │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                   │                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │                 Infrastructure Security                             │ │
│  │  Container Security • Network Segmentation • Secrets Management     │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
```

### Zitadel Integration Architecture

#### Overview

Zitadel serves as the self-hosted OAuth 2.0/OpenID Connect authentication provider for Know Foolery, providing secure authentication for both players and administrators while maintaining complete control over user data and authentication flows.

#### Zitadel Deployment Architecture
```
┌─────────────────────────────────────────────────────────────────────┐
│                        Client Applications                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   Web App   │  │ Mobile iOS  │  │Mobile Android│ │Desktop Wails│ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                            OAuth 2.0/OIDC Flows
                                   │
┌─────────────────────────────────────────────────────────────────────┐
│                        API Gateway                                  │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │              JWT Validation Middleware                         │ │
│  │  • Token signature verification                                │ │
│  │  • Claims validation & role extraction                         │ │
│  │  • Token refresh handling                                      │ │
│  └────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                              Validated Requests
                                   │
┌─────────────────────────────────────────────────────────────────────┐
│                      Microservices Layer                            │
│              (Receives user context from JWT claims)                │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                            Zitadel Admin API
                                   │
┌─────────────────────────────────────────────────────────────────────┐
│                        Zitadel Instance                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   OAuth     │  │  Admin API  │  │ PostgreSQL  │  │  OIDC       │ │
│  │  Provider   │  │             │  │  Database   │  │ Discovery   │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```