desktop-2fa

What is it and why it was built

desktop‑2fa is an offline TOTP authenticator for people who want their second factor to live in a local encrypted vault. There is no cloud sync or account-based service.

It is CLI-first and includes an early Textual terminal UI prototype. The project uses password-based vault encryption, configurable vault paths, and commands for managing TOTP entries.

It does not replace hardware tokens or protect a compromised device. Review thesecurity model to understand its limits.

Install

Requires Python 3.11 or newer. Install from PyPI:

python -m pip install desktop-2fa

Or install the command-line app with pipx:

pipx install desktop-2fa

Basic usage:

# Create a vault and add a TOTP entry
d2fa vault init
d2fa add GitHub GitHub JBSWY3DPEHPK3PXP

# Generate a code
d2fa code GitHub

# List all entries
d2fa list

Installation guide · CLI reference

Features

How it works

1. Choose or create a vault

Use the default local vault or select another path with --vault or DESKTOP_2FA_VAULT.

2. Add TOTP entries

Use d2fa add to store an account's TOTP secret in the encrypted vault.

3. Generate and copy codes

Run d2fa code <name>; use --copy or --copy-only to copy the code.

4. Back up your vault

Create an encrypted backup with d2fa backup and store it somewhere safe. Backups are not automatic.

Security model

• AES-256-GCM authenticated encryption protects vault contents.
• Argon2id derives encryption keys from passwords (time cost 4, memory cost 128 MiB, parallelism 2).
• zxcvbn evaluates passwords; weak-password warnings or rejection can be configured.
• Vault contents require password authentication; there are no session-based unlocks.
• Vault files and backups remain local; there is no cloud sync or password recovery.

Desktop-2FA does not protect secrets on a compromised device or while they are in use. See the security model and threat limits.

CLI examples

# Add a new entry (example secret)
d2fa add GitHub GitHub JBSWY3DPEHPK3PXP

# Generate a code
d2fa code GitHub --copy

# List entries
d2fa list

# Create an encrypted backup
d2fa backup

See the CLI reference for vault options and other commands.

Who is it for?

• Developers who prefer CLI workflows
• Sysadmins managing secure workstations and VMs
• Privacy-focused users avoiding cloud sync
• People working on air-gapped machines
• Anyone who wants 2FA without a phone

Is desktop-2fa right for you?

This describes desktop-2fa's documented design and trade-offs, not a ranking against other authenticators.

FAQ

Does desktop-2fa sync across devices?

No. Vaults are stored locally. You can create an encrypted backup and transfer it yourself.

Can I recover a forgotten vault password?

No. Keep a secure backup and password; there is no recovery key or reset service.

Does it have a user interface?

It has a full CLI and an early Textual terminal UI prototype (d2fa ui). The prototype can list entries, generate codes, and copy codes, but does not manage entries or create a missing vault.

Can I add a token from an otpauth URL?

Yes. The CLI accepts otpauth:// URLs with d2fa add. QR scanning is not listed as a current feature.

Which Python versions are supported?

Python 3.11 or newer. Once installed, the app works with its local vault and does not need cloud services.

Where is the vault stored?

By default at ~/.desktop-2fa/vault. Choose another file with --vault or set DESKTOP_2FA_VAULT.

Current project status

Desktop-2FA is at version 0.8.3. The CLI is the primary interface; the Textual terminal UI is explicitly an early prototype, not a full desktop GUI.

• CLI commands for vault, TOTP entries, backups, import/export, and password management
• Early d2fa ui prototype for listing entries, generating codes, and copying them
• See the upstream-synced changelog and source repository for current development