How mrfrazer25/2fa-app works
Project Type and Purpose
• This is a standalone Python desktop application for managing two-factor authentication (2FA) tokens.
• It provides a modern GUI (CustomTkinter), secure secret storage (OS keyring), PIN protection, encrypted backup/restore, and TOTP code generation.
File Structure
Top-level files & folders:
• main.py – application entrypoint and bootstrap
• core/ – business logic layer
– app_lock.py (PIN management, auto-lock)
– secure_storage.py (keyring wrapper, backup encryption)
• ui/ – presentation layer (CustomTkinter views & dialogs)
– add_token_dialog.py, pin_dialog.py, password_dialog.py, recovery_codes_dialog.py, settings_frame.py, sidebar.py, token_card.py
• requirements.txt – dependencies (CustomTkinter, keyring, cryptography, etc.)
Extract Architecture Insights from README
• Security through OS keyring + PBKDF2-SHA256 + AES-GCM
• UI theming (Light/Dark/System)
• Features tied to core services: token CRUD, clipboard auto-clear, auto-lock, encrypted JSON backup
Main Components & Their Relationships
A. UI Layer (CustomTkinter)
• Windows, dialogs, frames under ui/
• Presents token cards, forms, settings, PIN prompts
• Calls core services via well-defined method interfaces
B. Core Logic
1. AppLock (core/app_lock.py)
• Manages PIN hash & salt (PBKDF2)
• Tracks inactivity, triggers auto-lock events
2. SecureStorage (core/secure_storage.py)
• Reads/writes TOTP secrets & recovery codes to OS keyring
• Exports/imports encrypted JSON backups (AES-256-GCM)
C. System Services & External Dependencies
• OS Keyring backend (Windows Credential Manager, macOS Keychain, Linux Secret Service)
• File system for encrypted backup files (.json)
• Cryptography library (AES-GCM, PBKDF2)
• Clipboard service for copying codes
Interaction Flow Examples:
• Startup: main.py → AppLock.check_or_set_pin() → UI.pin_dialog → on success → UI.main_window
• Token: UI.add_token_dialog → SecureStorage.store_secret(keyring) → UI.token_card refresh
• Generate Code: UI.token_card → TOTP algorithm in core/secure_storage → UI display
• Backup: UI.settings_frame “Export” → SecureStorage.export_backup() (derive key via PBKDF2 → AES-GCM → write file)
Architectural Patterns & Design Principles
• Layered Separation: UI (View) ↔ Core (Model/Services) ↔ External (OS & FS)
• Single Responsibility: each module handles one concern (PIN logic, storage, presentation)
• Dependency Inversion: core code depends on keyring/cryptography abstracts, not UI
• Secure by Design: clear boundary between untrusted input (UI) and sensitive operations (core + OS services)
[ ] Separate UI, Core, External lanes
[ ] Label modules & show their file paths (e.g., ui/token_card.py)
[ ] Include all critical operations: PIN management, keyring storage, TOTP generation, backup encryption, clipboard clearing