mini2fa 0.2.3__tar.gz → 0.3.0__tar.gz

mini2fa-0.3.0/PKG-INFO

@@ -0,0 +1,144 @@
+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
+Provides-Extra: scan
+Provides-Extra: dev
+License-File: LICENSE
+
+# 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

mini2fa-0.3.0/README.md

@@ -0,0 +1,122 @@
+# 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

mini2fa-0.3.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mini2fa"
+version = "0.3.0"
+description = "安全的本地 TOTP 双因素认证管理工具"
+readme = "README.md"
+license = {text = "GPL-3.0-or-later"}
+requires-python = ">=3.10"
+authors = [{name = "Duroxi"}]
+keywords = ["totp", "2fa", "otp", "authenticator", "security"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Security",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "cryptography>=41.0.0",
+    "wcwidth>=0.2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Duroxi/Mini2FA"
+Repository = "https://github.com/Duroxi/Mini2FA"
+
+[project.scripts]
+mini2fa = "mini2fa._cli:main"
+
+[project.optional-dependencies]
+scan = ["pyzbar>=0.1.9", "Pillow>=10.0.0"]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "qrcode[pil]",
+    "pyzbar>=0.1.9",
+    "Pillow>=10.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

mini2fa-0.3.0/src/mini2fa/__init__.py

@@ -0,0 +1,35 @@
+"""Mini2FA - 安全的本地 TOTP 双因素认证管理工具"""
+
+from .totp import generate_totp, verify_totp, get_remaining_seconds
+from .crypto import CryptoManager, account_aad
+from .storage import StorageManager
+from .models import Account, OTPAccountInfo
+from .errors import (
+    Mini2FAError, AuthError, BackupFormatError, KeyFileCorruptedError,
+    NotFoundError, UnsupportedOTPTypeError, ValidationError,
+    VaultCorruptedError, VaultLockedError,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "generate_totp", "verify_totp", "get_remaining_seconds",
+    "CryptoManager", "account_aad", "StorageManager", "Account",
+    "OTPAccountInfo", "Mini2FAError", "AuthError", "BackupFormatError",
+    "KeyFileCorruptedError", "NotFoundError", "UnsupportedOTPTypeError",
+    "ValidationError", "VaultCorruptedError", "VaultLockedError",
+    "__version__",
+]
+
+_SCAN_EXPORTS = {
+    "scan_qrcode", "scan_qrcode_from_raw_data", "parse_otp_uri",
+    "preprocess_image",
+}
+
+
+def __getattr__(name):
+    """扫码 API 保持旧导入路径，但只在真正使用时加载 pyzbar/Pillow。"""
+    if name in _SCAN_EXPORTS:
+        from . import scanner
+        return getattr(scanner, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")