Rustelo/docs/2fa-implementation.md

Two-Factor Authentication (2FA) Implementation

This document describes the implementation of Time-based One-Time Password (TOTP) two-factor authentication in the Rustelo application.

Overview

The 2FA implementation provides an additional layer of security for user accounts by requiring a second form of authentication beyond username and password. This implementation uses TOTP (Time-based One-Time Password) compatible with popular authenticator apps like Google Authenticator, Authy, and Microsoft Authenticator.

Features

• TOTP Authentication: Standards-compliant TOTP implementation (RFC 6238)
• QR Code Generation: Automatic QR code generation for easy setup
• Backup Codes: Recovery codes for account access if authenticator device is lost
• Rate Limiting: Protection against brute force attacks
• Audit Trail: Logging of 2FA attempts for security monitoring
• Graceful Degradation: Existing users can continue using the system without 2FA until they opt-in

Architecture

Backend Components

Database Schema

• user_2fa: Stores TOTP secrets and configuration
• user_2fa_recovery_codes: Individual recovery codes for better tracking
• user_2fa_attempts: Audit trail of authentication attempts
• users: Extended with two_factor_required flag
• sessions: Extended with two_factor_verified flag

Core Services

• TwoFactorService: Main 2FA business logic
• AuthService: Extended to handle 2FA login flow
• AuthRepository: Database operations for user management

API Endpoints

• POST /api/auth/login: First step login (returns 2FA requirement)
• POST /api/auth/login/2fa: Second step login with 2FA code
• POST /api/auth/2fa/setup: Initialize 2FA setup
• POST /api/auth/2fa/verify: Verify and enable 2FA
• GET /api/auth/2fa/status: Get current 2FA status
• POST /api/auth/2fa/disable: Disable 2FA
• POST /api/auth/2fa/backup-codes: Generate new backup codes

Frontend Components

React Components

• TwoFactorSetup: Complete 2FA setup flow
• TwoFactorLoginForm: 2FA code input during login
• TwoFactorLoginPage: Full page 2FA login
• GenerateBackupCodesComponent: Backup code management
• DisableTwoFactorComponent: 2FA disabling interface

Auth Context

• Extended AuthContext to handle 2FA states
• requires_2fa flag to track 2FA requirement
• pending_2fa_email to store email during 2FA flow

Setup Process

1. User Initiates 2FA Setup

POST /api/auth/2fa/setup
{
  "password": "current_password"
}

2. Server Response

{
  "success": true,
  "data": {
    "secret": "BASE32_ENCODED_SECRET",
    "qr_code_url": "data:image/svg+xml;base64,QR_CODE_DATA",
    "backup_codes": ["12345678", "87654321", ...]
  }
}

3. User Scans QR Code

• User scans QR code with authenticator app
• Alternatively, manually enters the secret key

4. User Verifies Setup

POST /api/auth/2fa/verify
{
  "code": "123456"
}

5. 2FA Enabled

• TOTP verification successful
• 2FA is now enabled for the account
• Backup codes are active

Login Flow

1. Standard Login

POST /api/auth/login
{
  "email": "user@example.com",
  "password": "password",
  "remember_me": false
}

2. 2FA Required Response

{
  "success": true,
  "data": {
    "user": { ... },
    "access_token": "",
    "requires_2fa": true
  }
}

3. 2FA Code Submission

POST /api/auth/login/2fa
{
  "email": "user@example.com",
  "code": "123456",
  "remember_me": false
}

4. Complete Authentication

{
  "success": true,
  "data": {
    "user": { ... },
    "access_token": "JWT_TOKEN",
    "refresh_token": "REFRESH_TOKEN",
    "requires_2fa": false
  }
}

Security Features

Rate Limiting

• Maximum 5 failed attempts per 15-minute window
• Prevents brute force attacks on 2FA codes

Backup Codes

• 8-digit recovery codes
• Hashed storage in database
• Single-use only
• Can be regenerated

Audit Trail

• All 2FA attempts are logged
• Includes IP address, user agent, and timestamp
• Distinguishes between TOTP and backup code usage

Secret Management

• TOTP secrets are Base32 encoded
• Secrets are unique per user
• Secrets are generated using cryptographically secure random number generation

Configuration

Environment Variables

# Database connection
DATABASE_URL=postgresql://localhost/rustelo_dev

# JWT configuration
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRATION=3600

# Application settings
APP_NAME=Rustelo
ISSUER_NAME=Rustelo Authentication

Dependencies

[dependencies]
# 2FA specific
totp-rs = "5.6"
qrcode = { version = "0.15", features = ["svg"] }
base32 = "0.5"
sha2 = "0.10"
base64 = "0.22"

Usage Examples

Enable 2FA for a User

// Setup 2FA
let request = Setup2FARequest {
    password: "user_password".to_string(),
};
let response = auth_service.setup_2fa(user_id, request).await?;

// Verify and enable
let verify_request = Verify2FARequest {
    code: "123456".to_string(),
};
auth_service.verify_2fa_setup(user_id, verify_request, None, None).await?;

Login with 2FA

// First step: regular login
let login_request = LoginCredentials {
    email: "user@example.com".to_string(),
    password: "password".to_string(),
    remember_me: false,
};
let response = auth_service.login(login_request, None).await?;

if response.requires_2fa {
    // Second step: 2FA verification
    let twofa_request = Login2FARequest {
        email: "user@example.com".to_string(),
        code: "123456".to_string(),
        remember_me: false,
    };
    let final_response = auth_service.login_with_2fa(twofa_request, None, None, None).await?;
}

Testing

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_2fa_setup() {
        let service = TwoFactorService::new(pool, "Test".to_string(), "Test".to_string());
        let response = service.setup_2fa(user_id, "user@test.com", request).await;
        assert!(response.is_ok());
    }

    #[tokio::test]
    async fn test_totp_verification() {
        // Test TOTP code verification
        let service = TwoFactorService::new(pool, "Test".to_string(), "Test".to_string());
        let result = service.verify_2fa_for_login(user_id, "123456", None, None).await;
        // Assert based on test conditions
    }
}

Integration Tests

#[tokio::test]
async fn test_full_2fa_flow() {
    // Test complete 2FA setup and login flow
    // 1. Setup 2FA
    // 2. Verify setup
    // 3. Login with 2FA
    // 4. Verify successful authentication
}

Migration Guide

Database Migration

-- Run migration 002_add_2fa_support.sql
-- This adds all necessary 2FA tables and columns

Existing Users

• Existing users can continue using the system without 2FA
• 2FA is opt-in for existing users
• two_factor_enabled field defaults to false

Deployment Steps

1. Deploy database migration
2. Deploy backend code with 2FA support
3. Deploy frontend code with 2FA components
4. Update documentation and user guides

Troubleshooting

Common Issues

QR Code Not Displaying

• Check that SVG rendering is enabled
• Verify QR code generation dependencies
• Check browser console for errors

Invalid 2FA Code

• Ensure device time is synchronized
• Verify secret key entry
• Check for typos in manual entry

Backup Code Not Working

• Verify code hasn't been used before
• Check for typing errors
• Ensure user has remaining backup codes

Debug Commands

# Check 2FA status for user
psql -d rustelo_dev -c "SELECT * FROM user_2fa WHERE user_id = 'USER_ID';"

# View recent 2FA attempts
psql -d rustelo_dev -c "SELECT * FROM user_2fa_attempts WHERE user_id = 'USER_ID' ORDER BY created_at DESC LIMIT 10;"

# Check backup codes
psql -d rustelo_dev -c "SELECT code_hash, used_at FROM user_2fa_recovery_codes WHERE user_id = 'USER_ID';"

Security Considerations

Best Practices

• Use HTTPS in production
• Implement proper session management
• Regular security audits
• Monitor 2FA attempt logs
• User education on 2FA security

Compliance

• TOTP implementation follows RFC 6238
• Backup codes follow industry best practices
• Audit logging supports compliance requirements

Future Enhancements

Planned Features

• SMS-based 2FA as alternative
• Hardware security key support (WebAuthn)
• Admin-enforced 2FA policies
• Bulk 2FA management for organizations
• Advanced reporting and analytics

Performance Optimizations

• Caching of 2FA status
• Async processing of audit logs
• Database query optimization
• CDN for QR code generation

Support

For issues or questions regarding 2FA implementation:

1. Check this documentation
2. Review server logs
3. Check database state
4. Contact development team

---

Last Updated: 2024-01-XX Version: 1.0.0