Release Notes - v0.1.15

Two-Factor Authentication (2FA) Implementation

Overview

This implementation adds TOTP-based (Time-based One-Time Password) two-factor authentication support to the application, compatible with standard authenticator apps like Google Authenticator, Authy, and others.

Features

• TOTP-based authentication (RFC 6238 compliant)
• QR code setup for easy enrollment
• Backup codes for account recovery
• Rate-limited verification attempts
• Secure secret storage

Database Changes

The following fields have been added to the users table:

• two_factor_secret: Stores the TOTP secret key (encrypted using AES-256-GCM)
• two_factor_enabled: Boolean flag indicating if 2FA is enabled
• backup_codes: Stores recovery backup codes (bcrypt hashed and comma-separated)

Setup Process

1. Navigate to /profile/2fa/setup
2. Scan the displayed QR code with your authenticator app
3. Enter the verification code to confirm setup
4. Save your backup codes in a secure location

Login Flow

1. Enter email and password as usual
2. If 2FA is enabled:
   • Enter the 6-digit code from your authenticator app
   • Alternatively, use a backup code if you can't access your authenticator

Backup Codes

Purpose

Backup codes serve as a fallback authentication method when users cannot access their authenticator app (e.g., lost phone, device reset, or app uninstalled).

Implementation Details

• Generation: 8 random backup codes are created during 2FA setup
• Format: Each code is 8 characters long (hexadecimal format)
• Storage: Codes are bcrypt-hashed and stored as a comma-separated string
• Usage: Each backup code can only be used once and is removed after use
• Security: Codes are hashed with bcrypt to prevent extraction from the database

User Experience

• Users are shown their backup codes only once during 2FA setup
• Users are advised to store backup codes securely (printed copy in a safe location)
• During login, users can click "Use backup code" to authenticate with a backup code
• After using a backup code, users should set up 2FA again if they won't regain access to their authenticator

Management

• Administrators cannot recover or view user backup codes
• Users can regenerate backup codes from their profile page, invalidating all previous codes
• For security reasons, backup codes cannot be displayed again after initial setup

Security Considerations

• Backup codes provide a balance between security and recovery options
• Organizations should have a policy for handling situations where users lose both their authenticator app and backup codes
• Security audit logs should track authentication via backup codes separately from regular 2FA