Metadata-Version: 2.4
Name: fido2-totp-vault
Version: 0.2.0
Summary: A cross-platform FIDO2 security-key-gated TOTP vault
Author: Christhofer Cardona
Maintainer: Christhofer Cardona
License-Expression: GPL-3.0-or-later
Project-URL: Repository, https://github.com/Christhofer-Cardona/fido2-totp-vault
Project-URL: Issues, https://github.com/Christhofer-Cardona/fido2-totp-vault/issues
Keywords: FIDO2,TOTP,security key,KeePass
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pykeepass<5,>=4.2
Requires-Dist: fidovault<0.3,>=0.2
Requires-Dist: portalocker<5,>=3.1; sys_platform == "win32"
Requires-Dist: pywin32>=308; sys_platform == "win32"
Dynamic: license-file

# 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](https://github.com/tmo1/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](https://github.com/tmo1/fidovault) 0.2.x; this project does not
patch it. Install the CLI from [PyPI](https://pypi.org/project/fido2-totp-vault/):

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

On Windows PowerShell:

```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](docs/VALIDATION.md).
macOS native and hardware testing is still pending.

## First use

```text
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](https://www.rfc-editor.org/rfc/rfc9106.html#section-7.4).
`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](docs/RECOVERY.md) 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](docs/RECOVERY.md) 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](docs/THREAT_MODEL.md)
- [Recovery and backups](docs/RECOVERY.md)
- [Security reporting](SECURITY.md)
- [Maintainers](MAINTAINERS.md)
- [Contributing and local tests](CONTRIBUTING.md)
- [Release validation](docs/VALIDATION.md)

The project is maintained by **Christhofer Cardona**
([GitHub profile](https://github.com/Christhofer-Cardona)). Related projects
include [KeePassXC](https://github.com/keepassxreboot/keepassxc), which can
manage TOTP within a KDBX database;
[Passlane](https://github.com/anssip/passlane), a KeePass-compatible CLI with
TOTP and YubiKey challenge-response; the Windows KeePass
[KeePassPasskeyKeyProvider](https://github.com/brlumen/KeePassPasskeyKeyProvider)
plugin; and [keyroost](https://github.com/framefilter/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.
