Mini2FA 🔑

安全的本地 TOTP 双因素认证管理工具 — Python 包。

安装

# 核心功能（TOTP、加密、list/get）
pip install mini2fa

# 需要从图片扫码添加账号时，安装扫码依赖
pip install "mini2fa[scan]"

Linux 上 pyzbar 还需要系统库：

sudo apt-get install libzbar0      # Debian/Ubuntu
sudo yum install zbar              # CentOS/RHEL
brew install zbar                  # macOS

使用

交互模式（TUI）

mini2fa

在真实终端中运行时使用轻量 TUI（备用屏幕整屏重绘）：退出后终端不留残留， 查看验证码时进度条与剩余秒数每秒自动刷新。非交互环境（管道/脚本/CI）自动降级 为纯文本输出；也可显式禁用：

mini2fa --no-tui
# 空闲 5 分钟后自动锁定（0=关闭，默认关闭）
mini2fa --lock-timeout 300

命令行模式（给 Agent 使用）

# 列出所有账号（ID + issuer + account）
mini2fa list -p <password>

# 获取验证码（简洁一行式）
mini2fa get -p <password> <id>
# 输出示例：GitHub - CharlesHahn: 681025 (12s)

# 机器可读输出
mini2fa list -p <password> --json
mini2fa get -p <password> <id> --json

# 诊断数据文件、格式版本、解密状态
mini2fa doctor -p <password> [--json]

# 显式升级旧格式（会先备份 DB + key）
mini2fa migrate -p <password> [--json]

设计原则：

• 命令行版给 agent 使用，零交互（无任何提示词）
• 密码仍只通过 -p 传入；注意 argv 可能出现在 shell 历史、进程列表和 agent 日志中
• 只读接口（list/get/doctor）；管理操作留在 TUI
• migrate 是显式写操作，不会被 list/get 静默触发

作为库

from mini2fa import generate_totp

code = generate_totp('JBSWY3DPEHPK3PXP')
print(code)  # 123456

mini2fa 核心包不再强制依赖 pyzbar/Pillow；扫码 API 仍可从 mini2fa.scanner 导入，但需要安装 mini2fa[scan]。

功能

• 📱 从图片扫码添加 2FA 账号（仅支持 TOTP）
• 🔑 生成符合 RFC 6238 的 TOTP 验证码
• 🔐 AES-256-GCM 双层加密（PBKDF2-SHA256 600k）
• 🧷 密文绑定账号身份（AAD），防止密文调包
• 💾 JSON 导入/导出备份（内嵌主密钥，支持跨机器迁移）
• 🔁 schema v1 → v2 / AAD 显式迁移，迁移前自动备份
• 🔒 修改主密码、密保提示
• 🖥️ 跨平台（Windows/Linux/macOS）
• 🤖 list/get/doctor/migrate 命令行接口，支持 --json

升级到 0.3.0

0.3.0 引入 schema v2 和带 AAD 的密文。旧 key/DB/备份仍可读，但建议升级：

# 先备份 ~/.mini2fa（或使用 TUI 的导出备份）
mini2fa migrate -p <password>

迁移会：

1. 在 ~/.mini2fa/backups/pre_migration_<timestamp>/ 备份 DB 和 key；
2. 重建 schema v2（增加 secret_version 与 CHECK 约束）；
3. 把旧密文重加密为带 AAD 的 v2 格式。

迁移后的数据库旧版 mini2fa 无法读取；如需回滚，使用迁移前备份。 TUI 启动时检测到旧格式也会提示迁移。

安全说明

• 数据目录固定为 ~/.mini2fa/，不读取环境变量。
• 目录权限 0700，key/DB/备份 0600（POSIX）。
• master.key 原子写入并保留 master.key.bak。
• 主密码丢失无法恢复；请定期导出备份。
• 命令行 -p 的密码可能被同用户进程或日志看到；不要在共享环境使用。

项目

• GitHub: https://github.com/Duroxi/Mini2FA
• License: GPL-3.0-or-later