Threat Model

Threat Model

desktop‑2fa is a local‑first TOTP authenticator designed for users who want full control over their second factor without relying on cloud services, mobile ecosystems, or platform‑locked keystores. This document describes the security assumptions, goals, and limitations of the project. It is intended for users, auditors, and contributors who want to understand how the tool protects TOTP secrets and what risks remain.

1. Assets

desktop‑2fa protects the following assets:

• TOTP secrets — shared secrets used to generate one‑time passwords.
• Vault file — encrypted JSON file containing all entries and metadata.
• Master password — user‑chosen password used to derive the encryption key.
• Application configuration — non‑sensitive settings stored separately.

The TOTP secrets and vault file are the primary security‑critical assets.

2. Security Goals

2.1 Confidentiality of TOTP secrets at rest

TOTP secrets must never be stored unencrypted on disk.
The vault is encrypted using AES‑256‑GCM, with keys derived from the master password using Argon2id.

2.2 Integrity of vault contents

AES‑GCM provides authenticated encryption, ensuring that tampering with ciphertext is detectable.

2.3 Portability and transparency

The vault is a documented, stable JSON structure. Users can move it between machines, back it up manually, inspect it, version it, and audit it. No hidden OS‑level keystores or proprietary formats are used.

2.4 No plaintext backups

Every backup is an encrypted vault. There is no UI path that exports secrets in plaintext.

2.5 Predictable, deterministic CLI behavior

The tool must behave identically across platforms and versions. No cloud sync, no background services, no remote dependencies.

3. Out of Scope

desktop‑2fa does not attempt to protect against:

• Compromised or fully controlled host systems
  If an attacker can run arbitrary code, they can capture the master password, read decrypted secrets from memory, or modify the binary.

• Hardware‑level attacks
  Side‑channels, firmware tampering, DMA attacks, etc.

• Malicious users with access to the master password
  Anyone who knows the password is assumed to have full access.

• Remote attackers without access to the vault file
  The tool does not expose any network surface.

• Social engineering or phishing
  desktop‑2fa does not attempt to detect or mitigate these.

4. Threats Considered

desktop‑2fa is designed to protect against:

4.1 Disk theft or offline access

If an attacker copies the vault file, they must break Argon2id and AES‑GCM to recover secrets.

4.2 Accidental plaintext exposure

The vault format ensures that secrets are never written to disk unencrypted.

4.3 Weak OS‑level isolation

Unlike mobile authenticators that rely on Android/iOS keystores, desktop‑2fa does not depend on platform‑specific key storage. Security depends on the master password and Argon2id, not on OS internals.

4.4 Tampering with vault contents

AES‑GCM prevents undetected modification of ciphertext.

4.5 Misconfigured backups

Backups are always encrypted vaults, not plaintext exports.

5. Design Choices

5.1 Argon2id for key derivation

The master password is processed with Argon2id to derive the encryption key, increasing the cost of offline brute‑force attacks.

5.2 AES‑256‑GCM for authenticated encryption

Provides confidentiality and integrity for vault contents.

5.3 No OS‑managed keystores

The vault key is derived from the password, not stored in Windows Credential Manager, macOS Keychain, GNOME Keyring, or mobile keystores. This avoids silent key recovery mechanisms and platform lock‑in.

5.4 Local‑first, no cloud sync

No remote servers, no telemetry, no automatic data movement.

5.5 Minimal attack surface

No background processes, no network stack, no plugins.

6. Residual Risks

Even with these protections, the following risks remain:

6.1 Memory exposure

While the vault is unlocked, TOTP secrets exist in process memory. A compromised host can extract them.

6.2 Weak master password

A short or reused password weakens Argon2id and makes offline attacks more feasible.

6.3 User‑managed backups

If the encrypted vault is stored in insecure locations (e.g., cloud drives without proper access control), confidentiality depends on both the vault and the environment.

6.4 Shoulder surfing / physical observation

desktop‑2fa does not mitigate physical observation of the screen or keyboard.

6.5 Malware targeting the CLI

Keyloggers, clipboard scrapers, and memory scrapers remain out of scope.

7. Summary

desktop‑2fa is designed for users who want a transparent, auditable vault format, strong password‑based encryption, deterministic CLI behavior, no cloud sync, no OS‑level keystore dependencies, and full control over where their TOTP secrets live.

It does not attempt to solve every threat model. Instead, it focuses on doing one thing well: keeping your TOTP secrets encrypted at rest, portable, and under your control.