FIDO2 TOTP Vault

A cross-platform CLI for people who have a FIDO2 security key but still need TOTP codes for sites that do not accept passkeys. It keeps TOTP seeds in a separate KeePass KDBX database. FidoVault wraps that database's password with a FIDO2 key, so unlocking the database requires the enrolled key and any PIN or additional password chosen during enrollment.

The security key does not store or calculate TOTP codes. This project uses FidoVault and PyKeePass for vault and database operations; its own code handles strict otpauth://totp parsing, TOTP generation, safe local file checks, and the command-line workflow. It does not implement encryption.

What it does

• Creates a dedicated KDBX database unlocked through FidoVault.
• Adds standard TOTP seeds through a hidden terminal prompt or a single otpauth://totp URI supplied on stdin.
• Preflights a line-delimited URI migration for duplicate names and seeds, then writes the new entries in one encrypted database update when --apply is given.
• Prints a code only when requested. Listing entries also requires unlocking.
• Supports a second key through FidoVault's key-enrollment flow.
• Checks POSIX ownership and permissions or Windows owner and ACLs before using local files.
• Validates key-based decryption and stored TOTP records with verify, without printing seeds or codes.
• Updates the encrypted FidoVault file atomically during second-key enrollment, preserving the original if the new enrollment fails.

Version 0.2.0 supports standard TOTP with SHA1, SHA256, or SHA512, 6–8 digits, and periods of 15–120 seconds. Steam Guard, QR capture, clipboard handling, browser automation, and VM-specific helpers remain outside this project.

Install

Requires Windows, macOS, or Linux, Python 3.11 or newer, and a FIDO2 key with the hmac-secret extension. The Python package depends on FidoVault 0.2.x; this project does not patch it. Install the CLI from PyPI:

# Linux/macOS
python3 -m venv .venv
.venv/bin/python -m pip install fido2-totp-vault
.venv/bin/fido2-totp-vault --help

On Windows PowerShell:

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install fido2-totp-vault
.\.venv\Scripts\fido2-totp-vault.exe --help

On Windows, FidoVault's direct HID access may require administrator privileges or an appropriate device policy. Native Windows offline tests and a Linux physical-key test are recorded in release validation. macOS native and hardware testing is still pending.

First use

fido2-totp-vault init
fido2-totp-vault add-key
fido2-totp-vault add github --issuer GitHub --account you@example.com
fido2-totp-vault verify
fido2-totp-vault code github

Activate the virtual environment first, or use its full executable path as shown above.

Each command unlocks the vault independently. A sequence such as init, import-uris --apply, verify, and code therefore asks for the key, PIN, and any additional password more than once.

The host clock must be correct for TOTP codes to match the site's clock. If a code is about to expire, the CLI waits briefly for the next one.

init invokes FidoVault's interactive setup without its optional --generate mode. When FidoVault asks for a secret, use a fresh, strong random value from a trusted offline password generator or password manager; do not reuse a login password. FidoVault also asks you to enroll the key and choose whether each unlock requires PIN verification and an additional password. The tool then unlocks once more to create totp.kdbx.

FidoVault's default Argon2id setting needs 2 GiB of RAM for each unlock. On a memory-constrained machine, use init --kdf-profile low-memory instead. That profile uses the 64 MiB, three-pass Argon2id option from RFC 9106. add-key accepts the same option for its new key section; existing key sections keep their original settings. If you used the low-memory profile at initialization, use add-key --kdf-profile low-memory when enrolling a backup key too. Run doctor to check FidoVault's presence and local file permissions without a key, and verify to confirm that a key can unlock and parse the KDBX database.

Add a second key while the first is available. Keep each site's recovery codes outside this vault. See recovery before relying on it for an account. The encrypted vault and KDBX files live under the operating system's per-user data directory; see recovery for exact paths and the explicit location override.

To import a standard URI from a trusted local QR decoder or another program, pipe exactly one line to import-uri NAME, or use import-uris for a bounded line-delimited batch. import-uris performs a dry run by default; pass --apply to commit new entries atomically. Exact repeats are counted and skipped; conflicting names or reused seeds are rejected. A batch is limited to 200 lines. Avoid putting an otpauth URI or seed in shell arguments, shell history, tickets, or issue reports. A test-only example with a public, non-account RFC-style secret is in the test suite.

Security and maintenance

• Security model and limits
• Recovery and backups
• Security reporting
• Maintainers
• Contributing and local tests
• Release validation

The project is maintained by Christhofer Cardona (GitHub profile). Related projects include KeePassXC, which can manage TOTP within a KDBX database; Passlane, a KeePass-compatible CLI with TOTP and YubiKey challenge-response; the Windows KeePass KeePassPasskeyKeyProvider plugin; and keyroost, a broader hardware-key toolkit. This tool focuses on a separate FIDO2-gated TOTP database and a checked batch migration path for CLI users.