Metadata-Version: 2.1
Name: mini2fa
Version: 0.3.0
Summary: 安全的本地 TOTP 双因素认证管理工具
Author: Duroxi
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/Duroxi/Mini2FA
Project-URL: Repository, https://github.com/Duroxi/Mini2FA
Keywords: totp,2fa,otp,authenticator,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography >=41.0.0
Requires-Dist: wcwidth >=0.2.0
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: qrcode[pil] ; extra == 'dev'
Requires-Dist: pyzbar >=0.1.9 ; extra == 'dev'
Requires-Dist: Pillow >=10.0.0 ; extra == 'dev'
Provides-Extra: scan
Requires-Dist: pyzbar >=0.1.9 ; extra == 'scan'
Requires-Dist: Pillow >=10.0.0 ; extra == 'scan'

# Mini2FA 🔑

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

## 安装

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

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

Linux 上 pyzbar 还需要系统库：

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

## 使用

### 交互模式（TUI）

```bash
mini2fa
```

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

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

### 命令行模式（给 Agent 使用）

```bash
# 列出所有账号（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` 静默触发

### 作为库

```python
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/备份仍可读，但建议升级：

```bash
# 先备份 ~/.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
