# Authentication System

## Overview

The authentication system handles user registration, login, logout, password reset, and email verification. It uses Flask-Login for session management and Werkzeug for secure password hashing.

## Components

### Models

**User Model** (`app/models.py`)
```python
class User(UserMixin, db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(64), index=True, unique=True, nullable=False)
    email = db.Column(db.String(120), index=True, unique=True, nullable=False)
    password_hash = db.Column(db.String(256), nullable=False)
    is_admin = db.Column(db.Boolean, default=False)
    is_verified = db.Column(db.Boolean, default=False)
    verification_token = db.Column(db.String(256))
    reset_token = db.Column(db.String(256))
    reset_token_expiration = db.Column(db.DateTime)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)
```

### Forms

**LoginForm** (`app/auth/forms.py`)
- Username field
- Password field
- Remember me checkbox
- Submit button

**RegistrationForm** (`app/auth/forms.py`)
- Username field (min 4, max 64 characters)
- Email field with validation
- Password field (min 8 characters)
- Password confirmation field
- Submit button

**ResetPasswordRequestForm** (`app/auth/forms.py`)
- Email field
- Submit button

**ResetPasswordForm** (`app/auth/forms.py`)
- Password field (min 8 characters)
- Password confirmation field
- Submit button

### Routes

**Login Route** (`/auth/login`)
- Method: GET, POST
- Rate limit: 10 requests per minute
- Validates credentials
- Creates session with Flask-Login
- Supports "Remember Me" functionality

**Registration Route** (`/auth/register`)
- Method: GET, POST
- Rate limit: 3 requests per hour
- Creates new user account
- Generates verification token
- Sends verification email (token displayed for testing)
- Password is hashed before storage

**Logout Route** (`/auth/logout`)
- Destroys session
- Redirects to home page

**Password Reset Request** (`/auth/reset_password_request`)
- Method: GET, POST
- Rate limit: 3 requests per hour
- Generates secure reset token
- Token expires after 1 hour
- Sends email with reset link (token displayed for testing)

**Password Reset** (`/auth/reset_password/<token>`)
- Method: GET, POST
- Rate limit: 5 requests per hour
- Validates token and expiration
- Updates password
- Clears reset token

**Email Verification** (`/auth/verify/<token>`)
- Validates verification token
- Marks user as verified
- Clears verification token

**Resend Verification** (`/auth/resend_verification`)
- Method: GET, POST
- Rate limit: 3 requests per hour
- Regenerates verification token
- Sends verification email

## Security Features

### Password Hashing
- Uses Werkzeug's `generate_password_hash()`
- PBKDF2 with SHA-256 algorithm
- Salt is automatically generated
- Hashes are one-way (cannot be reversed)

### Session Management
- Flask-Login handles session creation
- Sessions are secure with HttpOnly flag
- Session timeout can be configured
- "Remember Me" extends session duration

### CSRF Protection
- All forms include CSRF tokens
- Tokens are validated on submission
- Prevents cross-site request forgery

### Rate Limiting
- Login: 10 requests per minute
- Registration: 3 requests per hour
- Password reset: 3 requests per hour
- Prevents brute force attacks

### Token Security
- Verification tokens: 32-byte URL-safe random strings
- Reset tokens: 32-byte URL-safe random strings
- Tokens expire after 1 hour
- Tokens are single-use

## Email Verification Flow

1. User registers account
2. System generates verification token
3. Token is stored in user record
4. Email sent with verification link (token displayed for testing)
5. User clicks verification link
6. System validates token
7. User marked as verified
8. Token cleared from database

## Password Reset Flow

1. User requests password reset
2. System validates email exists
3. Generates reset token with 1-hour expiration
4. Email sent with reset link (token displayed for testing)
5. User clicks reset link
6. System validates token and expiration
7. User enters new password
8. Password is hashed and updated
9. Token cleared from database

## Configuration

### Environment Variables
- `SECRET_KEY`: Flask secret key for session encryption
- `SECURITY_PASSWORD_SALT`: Salt for password hashing (optional)

### Session Configuration
- Session lifetime: configurable via Flask settings
- Cookie security: HttpOnly, Secure flags (production)

## Best Practices

### For Users
- Use strong, unique passwords
- Enable email verification
- Use password reset when needed
- Keep email address current

### For Administrators
- Monitor failed login attempts
- Enforce password complexity
- Regular security audits
- Keep Flask secret key secure
- Use HTTPS in production

## Troubleshooting

### Login Issues
- **Problem**: "Invalid username or password"
  - Check credentials are correct
  - Verify email is verified
  - Ensure account exists

- **Problem**: Session expires too quickly
  - Check session configuration
  - Enable "Remember Me" option
  - Increase session timeout

### Registration Issues
- **Problem**: Email already registered
  - Use password reset instead
  - Contact admin for account recovery

- **Problem**: Username taken
  - Choose a different username
  - Username is case-insensitive

### Password Reset Issues
- **Problem**: Invalid or expired token
  - Request a new reset link
  - Token expires after 1 hour

- **Problem**: Email not received
  - Check spam folder
  - Verify email address is correct
  - Token is displayed in flash message for testing

## Future Enhancements

- Two-factor authentication (2FA)
- OAuth2 integration (Google, GitHub)
- Social login support
- Password strength meter
- Account lockout after failed attempts
- IP-based access control
- Session management UI for users