TrueFA-Py - Secure TOTP Authenticator

TrueFA-Py is a secure, offline Two-Factor Authentication (2FA) application built with Python and Rust. It provides both a robust command-line interface (CLI) and a user-friendly graphical user interface (GUI) for managing TOTP authentication codes while keeping your security tokens encrypted and stored locally in a secure vault.

View Recent Development Status and Progress

Features

• 🔑 Encrypted local vault with master password
• 📷 QR code scanning from image files
• 🔐 Two-layer security architecture with envelope encryption
• 🛡️ High-performance Rust crypto with memory protection and automatic fallback
• 📤 Import and export functionality with encrypted JSON format
• 🔄 Interoperability with other authenticator applications
• 🔍 Intelligent vault location detection with permission handling
• 🐳 Docker compatibility for containerized environments

Security

TrueFA-Py implements a comprehensive security model to protect your authentication secrets:

• Two-layer encryption with PBKDF2 and AES-GCM
• Secure memory handling with automatic zeroing
• Rust implementation of critical cryptographic functions
• No network transmission of sensitive data

For detailed information about the security implementation, please refer to the Security Documentation.

Installation & Usage

Windows

Prerequisites

• Visual C++ Redistributable 2015-2022 - Required for the Rust cryptography module
  • Download from Microsoft
  • This is required for both the portable executable and installed versions

Pre-built Releases

Version 0.1.1 Now Available!

• Windows Installer: Setup wizard for easy installation with all dependencies
  • Note: The installed version creates an images directory at C:\Users\<USERNAME>\Documents\images for QR code scanning
• Portable Version: Standalone executable that can run without installation
  • Uses the local directory structure for more flexibility

Download the latest release

From Source

git clone https://github.com/zainibeats/truefa-py.git && cd truefa-py
python -m venv venv && .\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

Building the Application

# Build the portable executable with Rust crypto
.\dev-tools\build.ps1 -BuildRust -Clean -Portable

# Build with installer
.\dev-tools\build.ps1 -BuildRust -Clean -Installer

# Build with both portable and installer
.\dev-tools\build.ps1 -BuildRust -Clean -Portable -Installer

Docker (Recommended)

Quick Run (Non-Persistent)

# Basic run with temporary volumes (PowerShell)
.\docker\run_docker.ps1

Persistent Storage Run

# First-time run - builds image and creates persistent storage
.\docker\run_docker_persistent.ps1

# Subsequent runs - reuse existing Docker image without rebuilding
docker run -it --rm `
    -v "${PWD}/images:/app/images" `
    -v "${PWD}/vault_data:/home/truefa/.truefa" `
    -e "TRUEFA_PORTABLE=1" `
    -e "TRUEFA_DATA_DIR=/home/truefa/.truefa" `
    truefa-py

Docker Container Features

• Persistent Storage: Vault data and exports are stored in the host system's vault_data directory
• QR Code Support: Place images in the local images folder for scanning inside the container
• Secure Export: Exports are saved to the vault_data/exports directory on the host system
• Environment Configuration: Uses TRUEFA_DATA_DIR for consistent vault location between runs
• Cross-Platform: Works on Windows, macOS and Linux host systems

Manual Configuration

# Build the Docker image
docker build -t truefa-py -f docker/Dockerfile .

# Run with persistent storage
docker run -it --rm \
  -v "$(pwd)/vault_data:/home/truefa/.truefa" \
  -v "$(pwd)/images:/app/images" \
  -e "TRUEFA_PORTABLE=1" \
  -e "TRUEFA_DATA_DIR=/home/truefa/.truefa" \
  truefa-py

Note: The Windows Docker container in docker/windows is for development testing only and not intended for end users.

Cross-Platform Compatibility

TrueFA-Py is designed with robust cross-platform compatibility:

• Rust Cryptography Module: Provides high-performance, memory-safe cryptographic operations on Windows
• Python Fallback Implementation: Automatically activates when the Rust module cannot be loaded
• Intelligent Detection: Seamlessly switches between implementations based on your environment

This dual-implementation approach ensures the application works flawlessly across different systems and environments.

Documentation

• Development Status - Recent improvements and current state
• Developer Guide - Development setup, testing, and technical details
• Documentation Index - Overview of all available documentation

Basic Usage

# Start the command-line interface (CLI)
python main.py

# Start the graphical user interface (GUI)
python truefa_gui.py

# Show version information (CLI only)
python main.py --version

# Enable debugging / Disable logs (CLI only - see GUI section for GUI options)
python main.py --debug --no-log

This will start the command-line interface with the following options:

1. Load QR code from image
2. Enter secret key manually
3. Save current secret
4. View saved secrets
5. Export secrets
6. Import secrets
7. Clear screen
8. Delete vault
9. Exit

For details on all command-line options, logging configuration, and development information, please refer to the Developer Guide.

GUI Interface

TrueFA-Py now includes a modern, user-friendly GUI interface built with PyQt6. The GUI provides all the functionality of the CLI version with an intuitive interface:

• Secure vault with master password protection
• TOTP token generation with visual countdown
• Account management (add, view, delete)
• QR code scanning from image files
• Import/export functionality
• Dark mode support

Running the GUI

# Start the GUI application
python truefa_gui.py

# Enable dark mode
python truefa_gui.py --style dark

# Enable debugging
python truefa_gui.py --debug

For more information about the GUI, please refer to the Developer Guide.

License

This project is licensed under the MIT License.