🛡️ Desktop-2FA

一款面向桌面环境的安全离线双因素认证（2FA）管理器。基于 Python 构建，具备强加密特性且无云端依赖。

🌐 官方网站：desktop-2fa.org

✨ 功能特性

📸 截图

以交互方式添加新的 TOTP 条目

为某个条目生成 TOTP 验证码

重命名条目并进行重复检测

查看版本信息并列出所有条目

🚀 快速开始

安装

pip install desktop-2fa

验证安装：

python -c "import desktop_2fa; print(desktop_2fa.__version__)"
# Output: 0.8.1dev

基本用法

# Initialize a new vault
d2fa vault init

# Add a new TOTP token
d2fa vault add GitHub GitHub JBSWY3DPEHPK3PXP

# List all entries
d2fa vault list

# Generate a code
d2fa code GitHub

非交互式用法

# Provide password via command line
d2fa vault add GitHub GitHub JBSWY3DPEHPK3PXP --password mypassphrase

# Provide password via file
d2fa vault add GitHub GitHub JBSWY3DPEHPK3PXP --password-file /path/to/passphrase.txt

📁 保险库生命周期

保险库是一个加密存储文件，位于 ~/.desktop-2fa/vault。

创建保险库

当命令需要保险库但尚未存在时：

1. CLI 会提示输入新密码（交互模式），或要求提供 --password/--password-file（非交互模式）
2. 创建空的加密保险库
3. 始终会打印一条确认消息： Vault created at <path>

加载保险库

当命令需要保险库且该保险库已存在时：

1. CLI 会提示输入现有密码（交互模式），或要求提供凭据（非交互模式）
2. 保险库被解密并加载
3. 如果密码无效，CLI 将以 typer.Exit(1) 退出

重复条目处理

当多个条目与目标名称匹配时，rename 命令强制执行确定性行为：

• 如果多个条目与提供的名称（issuer 或 account_name）匹配，则重命名会被中止
• 错误消息：Error: Multiple entries named '<name>' exist. Operation aborted. Resolve duplicates first.
• 在这种情况下，不会重命名任何条目
• 此检查发生在任何修改之前

📖 CLI 命令

核心命令

保险库管理

全局选项

🔒 安全性

保险库使用：

• AES-256-GCM 用于认证加密
• Argon2id 用于密钥派生（time_cost=4, memory_cost=128MiB, parallelism=2）
• zxcvbn 用于密码强度评估
• 版本化头部用于前向兼容

每条命令都需要显式密码认证。不提供基于会话的访问。

密码强度评估

Desktop-2FA 在创建或更改保险库密码时使用 zxcvbn 评估密码强度：

• 评分 0-2（弱）：容易被猜到的密码（例如 "password123"）
• 评分 3-4（强）：能够抵御常见攻击（推荐）

示例：

• ❌ 弱：password、123456、qwerty、admin2024
• ✅ 强：Battery-Horse-Staple-Correct、Mountain@River*2024、MySecureVault#42

配置（~/.config/d2fa/config.toml）：

[security]
# Require strong passwords (score >= 3)
reject_weak_passwords = false  # warn but allow | true: reject weak passwords

当 reject_weak_passwords = false 时：

• 弱密码会触发黄色警告
• 系统会提示用户确认是否继续
• 密码接受过程为非阻塞式

当 reject_weak_passwords = true 时：

• 弱密码会被立即拒绝
• 命令以错误退出
• 用户必须选择更强的密码

向后兼容性： 如果你的配置中设置了 min_password_entropy（旧版选项），它会被识别并视为等同于要求 zxcvbn 评分 >= 3。

安全加固（v0.8.0）

0.8.0 版本保留了 v0.7.3 中所有此前的安全加固措施，并引入了模块化架构以实现更好的代码隔离：

• 空密码会立即被拒绝，并显示清晰的错误消息
• 权限错误与保险库文件缺失被区分对待
• 不会向用户显示 Python 堆栈跟踪
• 针对文件系统权限问题提供用户友好的错误消息
• 模块化设计将 CLI 与核心密码学组件分离，以增强安全边界
• 基于 zxcvbn 的密码强度评估（v0.8.0 新增）

📚 文档

🧪 测试

pytest tests/              # Run all tests
pytest --cov=src/desktop_2fa  # Run with coverage

🏗️ 项目结构

src/desktop_2fa/
├── app/           # Application components
├── cli/           # Command-line interface
├── crypto/        # Encryption utilities
├── totp/          # TOTP generation
├── ui/            # User interface components
├── vault/         # Vault management
└── utils/         # Utilities

📄 许可证

Apache License 2.0。请参阅 LICENSE 文件。

👤 作者

Łukasz Perek

🏆 赞助

desktop‑2fa 通过 Kilo OSS 赞助计划获得支持。

📧 联系方式

如有疑问或需要支持，请通过 [email protected] 联系我们

💖 支持本项目

Desktop‑2FA 是一款独立的开源工具，专注于自主性、透明性和离线安全。 如果你觉得它有用，并希望支持持续开发，可以通过以下平台进行支持：

• Ko‑fi：https://ko-fi.com/lukaszperek
• Buy Me a Coffee：https://buymeacoffee.com/lukaszperek
• AirTM：https://airtm.me/lukper