
A secure offline desktop application for generating and managing TOTP 2FA codes. Features encrypted vault storage, modern cryptography (Argon2 + AES‑GCM), modular architecture, and a local‑first approach with no cloud dependencies. Designed for reliability, extensibility, and future cross‑platform UI.
A secure, offline two-factor authentication (2FA) manager for desktop environments. Built with Python, featuring strong encryption and no cloud dependencies.
🌐 Landing Page: desktop-2fa.org
| Feature | Description |
|---|---|
| 🔐 Vault Security | AES-256-GCM encryption with Argon2id key derivation |
| ⏱️ TOTP Generation | RFC 6238 compliant code generation |
| 💻 Full CLI | Complete command-line interface for managing tokens |
| 📋 Clipboard Support | Automatic copying of TOTP codes to clipboard |
| 🔓 Session Control | CLI authenticates each command; UI reauthenticates writes and locks after five minutes without input |
| 🛡️ Password Policy | Configurable password strength enforcement with zxcvbn |
| 🧪 Well Tested | Regression tests include RFC 6238 vectors and historical vault fixtures |
| 📖 Security Model | Detailed threat analysis and cryptographic design documentation |
| 🖥️ Textual UI | Account and vault forms, live TOTP countdowns and clipboard actions (0.11.0) |
English dark-terminal CLI captures from Desktop-2FA 0.10.0, followed by the 0.11.0 Textual UI. All accounts and credentials are synthetic. Terminal images render actual command output; interactive prompts use a test runner and Textual runs headlessly. See the capture notes and report.
Adding an entry without displaying its secret.
Initializing a vault and listing synthetic accounts.
Human-readable, raw and JSON code output.
Encrypted export, overwrite refusal and recovery into a separate vault.
Textual UI: live codes and full account/vault operations. Capture method and limits.
pip install desktop-2fa
Verify installation:
python -c "import desktop_2fa; print(desktop_2fa.__version__)"
# Output: 0.11.0
# Initialize a new vault
d2fa vault init
# Add a new TOTP token
d2fa add GitHub GitHub JBSWY3DPEHPK3PXP
# Or add a provisioning URI (quote it so the shell preserves '&')
d2fa add "otpauth://totp/Example:alice?secret=JBSWY3DPEHPK3PXP&issuer=Example&algorithm=SHA256&digits=8&period=60"
# List all entries
d2fa list
# Generate a code
d2fa code GitHub
The vault is stored by default at ~/.desktop-2fa/vault. Select a different
file for any command with the global --vault option, or set
DESKTOP_2FA_VAULT to choose one by default. An explicit --vault takes
precedence over the environment variable; without either, the default remains
~/.desktop-2fa/vault.
# Use a separate vault for this command
d2fa --vault ./development-vault list
# Show the currently selected vault path
d2fa --vault ./development-vault vault path
# Launch the Textual terminal UI with that vault
d2fa --vault ./development-vault ui
URI-based add preserves algorithm, digits and period; omitted parameters default to SHA1, 6 digits and 30 seconds. Labels are percent-decoded, and an issuer query parameter must agree with any issuer prefix. Unsupported or contradictory provisioning data exits with status 6 before vault access. Interactive add also accepts a URI at the issuer prompt and skips the separate secret prompt. The URI label supplies the account name.
Interactive add hides input at the dedicated Secret prompt; name and issuer
remain visible. Secrets/URIs passed as arguments can appear in shell history or
process inspection, and a URI pasted into the visible issuer prompt can be
echoed. Prefer a plain issuer name plus the hidden secret prompt to avoid those
exposures. See interactive add.
The 0.11.0 Textual UI supports account management, vault
creation/unlocking, encrypted import/export/backup and password changes. Codes
refresh automatically with a countdown and validity bar. Start with d2fa ui;
without supplied credentials it opens a locked screen. Writes ask for a password
again; Ctrl+L or five minutes of inactivity locks the session. See the UI guide.
Version 0.10.0 contained the earlier prototype; upgrade to 0.11.0 for these
account and vault workflows.
# Provide password via command line
d2fa --password mypassphrase add GitHub GitHub JBSWY3DPEHPK3PXP
# Provide password via file
d2fa --password-file /path/to/passphrase.txt add GitHub GitHub JBSWY3DPEHPK3PXP
The vault is an encrypted storage file located by default at
~/.desktop-2fa/vault; use --vault or DESKTOP_2FA_VAULT to select another
path. Vault files must be regular files no larger than 10 MiB.
The current loader supports vault format version 1. Future releases are not guaranteed to support every older format. Before upgrading, create an encrypted backup and store it securely.
Desktop-2FA 0.9.0 changes the public Python API: Vault.save() and
Vault.load() require an explicit, non-empty password. Vaults created by
earlier Python API versions with no password must be opened and re-saved with a
non-empty password using the previous release before upgrading. CLI and
Textual UI flows already require a non-empty password.
d2fa backup