email-organizer/docs/design/authentication-system.md

# Authentication System Design

## Overview

The Email Organizer implements a complete user authentication system using Flask-Login for session management and Werkzeug for password security. This document provides a detailed overview of the authentication architecture, components, and implementation details.

## System Architecture

```mermaid
graph TB
    subgraph "Authentication Flow"
        A[User Browser] --> B[Login Page]
        B --> C[Submit Credentials]
        C --> D[Validate Input]
        D --> E[Check Password Hash]
        E --> F[Create Session]
        F --> G[Redirect to Dashboard]
    end
    
    subgraph "Backend Components"
        H[Auth Blueprint] --> I[Validation Logic]
        H --> J[Password Hashing]
        H --> K[Session Management]
        I --> L[User Model]
        J --> L
        K --> M[Flask-Login]
    end
    
    subgraph "Security Measures"
        N[Password Validation] --> O[Complexity Requirements]
        N --> P[Hashing Algorithm]
        Q[Session Security] --> R[Cookie Protection]
        Q --> S[Timeout Handling]
    end
    
    C --> D
    D --> I
    I --> J
    J --> K
    K --> F
```

## Components

### 1. Auth Blueprint ([`app/auth.py`](app/auth.py:1))

The authentication blueprint handles all authentication-related routes and logic:

#### Routes
- `/auth/login`: GET/POST - User login page and authentication
- `/auth/signup`: GET/POST - User registration page and account creation
- `/auth/logout`: GET - User logout and session termination

#### Key Functions
- `login()`: Handles user authentication with form validation
- `signup()`: Manages user registration with server-side validation
- `logout()`: Terminates user sessions and clears authentication state
- `validate_password()`: Enforces password complexity requirements

### 2. User Model ([`app/models.py`](app/models.py:13))

The User model extends Flask-Login's UserMixin to provide authentication functionality:

#### Authentication Methods
- `set_password()`: Hashes and stores passwords
- `check_password()`: Verifies password against hash

#### Security Attributes
- Password hashing using Werkzeug's secure hashing algorithm
- Email uniqueness constraint
- Timestamp tracking for account management

### 3. Flask-Login Integration

The application uses Flask-Login for session management:

#### Configuration
```python
login_manager = LoginManager()
login_manager.login_view = 'auth.login'
login_manager.login_message = 'Please log in to access this page.'
login_manager.login_message_category = 'warning'
```

#### User Loader
```python
@login_manager.user_loader
def load_user(user_id):
    return User.query.get(int(user_id))
```

## Authentication Flow

### User Registration

```mermaid
sequenceDiagram
    participant U as User
    participant B as Browser
    participant A as Auth Blueprint
    participant DB as Database
    
    U->>B: Navigate to /auth/signup
    B->>A: GET /auth/signup
    A->>B: Return signup form
    U->>B: Fill and submit form
    B->>A: POST /auth/signup
    
    loop Validation
        A->>A: Validate input fields
        A->>A: Check email uniqueness
        A->>A: Validate password complexity
    end
    
    A->>DB: Create new user record
    DB-->>A: User created
    A->>A: Hash and store password
    A->>B: Login user
    B->>U: Redirect to dashboard
```

### User Login

```mermaid
sequenceDiagram
    participant U as User
    participant B as Browser
    participant A as Auth Blueprint
    participant DB as Database
    
    U->>B: Navigate to /auth/login
    B->>A: GET /auth/login
    A->>B: Return login form
    U->>B: Submit credentials
    B->>A: POST /auth/login
    
    A->>DB: Query user by email
    DB-->>A: User data
    
    alt User exists
        A->>A: Verify password hash
        alt Password correct
            A->>A: Create session
            A->>B: Redirect to dashboard
        else Password incorrect
            A->>B: Show error message
        end
    else User not found
        A->>B: Show error message
    end
```

### Password Validation

The system enforces strong password requirements:

```python
def validate_password(password):
    """Validate password strength."""
    if len(password) < 8:
        return False, "Password must be at least 8 characters long"
    if not re.search(r'[A-Z]', password):
        return False, "Password must contain at least one uppercase letter"
    if not re.search(r'[a-z]', password):
        return False, "Password must contain at least one lowercase letter"
    if not re.search(r'\d', password):
        return False, "Password must contain at least one digit"
    return True, "Password is valid"
```

### Session Management

Flask-Login handles session security:

- **Session Cookies**: Secure, HttpOnly cookies for session storage
- **CSRF Protection**: Built-in CSRF protection for form submissions
- **Session Timeout**: Automatic session expiration
- **Remember Me**: Optional persistent login functionality

## Security Measures

### 1. Password Security

#### Hashing Algorithm
- Uses Werkzeug's `generate_password_hash()` and `check_password_hash()`
- Implements PBKDF2 with SHA256 for secure password storage
- Random salt generation for each password

#### Password Complexity
- Minimum 8 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one digit
- No maximum length limit

### 2. Input Validation

#### Client-Side Validation
- HTML5 form validation
- JavaScript feedback for user experience

#### Server-Side Validation
- Comprehensive input sanitization
- Email format validation
- Length restrictions for all fields
- SQL injection prevention through SQLAlchemy ORM

### 3. Session Security

#### Cookie Protection
- Secure flag for HTTPS environments
- HttpOnly flag to prevent JavaScript access
- SameSite policy for cross-site request protection

#### Session Management
- Automatic session regeneration on login
- Session timeout handling
- Logout cleanup

### 4. Error Handling

#### User-Friendly Messages
- Clear validation error messages
- General error messages for security-sensitive operations
- No exposure of internal system details

#### Logging
- Authentication attempt logging
- Security event tracking
- Error debugging information

## API Endpoints

### Authentication Endpoints

| Endpoint | Method | Description | Authentication Required |
|----------|--------|-------------|---------------------------|
| `/auth/login` | GET/POST | User login | No |
| `/auth/signup` | GET/POST | User registration | No |
| `/auth/logout` | GET | User logout | Yes |

### Response Formats

#### Login Success
```http
HTTP/1.1 302 Found
Location: /
Set-Cookie: session=<session_id>; HttpOnly; Secure; Path=/
```

#### Login Failure
```http
HTTP/1.1 200 OK
Content-Type: text/html

```

#### Registration Success
```http
HTTP/1.1 302 Found
Location: /
Set-Cookie: session=<session_id>; HttpOnly; Secure; Path=/
```

#### Registration Failure
```http
HTTP/1.1 200 OK
Content-Type: text/html

```

## Configuration

### Environment Variables

| Variable | Description | Default Value |
|----------|-------------|--------------|
| `SECRET_KEY` | Flask secret key for session encryption | `dev-secret-key` |

### Flask-Login Configuration

```python
login_manager = LoginManager()
login_manager.login_view = 'auth.login'
login_manager.login_message = 'Please log in to access this page.'
login_manager.login_message_category = 'warning'
```

### Blueprint Registration

The auth blueprint is registered with URL prefix `/auth/`:

```python
from app.auth import auth
app.register_blueprint(auth, url_prefix='/auth')
```

## Testing Strategy

### Unit Tests

#### Authentication Tests
- Test password validation logic
- Test password hashing and verification
- Test user creation and validation
- Test session creation and management

#### Integration Tests
- Test login flow with valid credentials
- Test login flow with invalid credentials
- Test registration flow with valid data
- Test registration flow with invalid data
- Test session persistence and timeout

### Security Tests

- Test SQL injection attempts
- Test XSS vulnerabilities
- Test session hijacking prevention
- Test CSRF protection

## Performance Considerations

### Database Optimization
- Index on email column for fast login lookups
- Efficient password hashing with proper salting
- Session data stored in server-side session store

### Security vs. Usability Balance
- Reasonable password complexity requirements
- Clear error messages for failed login attempts
- Session timeout balanced with user convenience

## Future Enhancements

### 1. Multi-Factor Authentication
- SMS-based 2FA
- TOTP (Time-based One-Time Password) support
- Hardware token integration

### 2. OAuth Integration
- Google OAuth
- Facebook OAuth
- GitHub OAuth

### 3. Password Reset
- Email-based password reset
- Secure token generation
- Expiration handling

### 4. Account Management
- User profile management
- Email address changes
- Password change functionality

### 5. Security Enhancements
- Rate limiting for login attempts
- Account lockout after failed attempts
- Suspicious activity monitoring
- IP-based security checks

### 6. Current Implementation Status
- User authentication with session management fully implemented
- Password complexity validation operational
- Server-side form validation complete
- Error handling with user-friendly messages
- Blueprint-based routing with proper URL prefixes