本地优先、多用户 + Argon2id 口令体系、支持 TOTP 动态验证码的 2FA 工具。
- 后端:Python,负责本地登录校验、解密、TOTP 计算与 REST 接口服务。
- 界面:pywebview 桌面窗口内嵌纯 HTML + CSS + JS,只负责展示验证码和倒计时(不使用外部浏览器);前端也可脱离后端独立部署。
- 数据:每个用户一份自行保管的加密 JSON 保险库。
- 用户系统:本地用户表(
data/users.json),口令仅以 Argon2id 哈希保存,明文不落盘、不进浏览器。
- 口令在登录窗口输入,经 Argon2id 校验后只存在于程序内存中,关闭程序即释放。
- 账户数据以 AES-GCM 加密 JSON 形式保存在本地,
secret字段绝不落盘为明文。 - 前端不接触口令,也拿不到明文 Secret,只拿到计算好的验证码。
- 主界面运行在 pywebview 桌面窗口中,不调用系统浏览器。
- 默认本地服务只监听
127.0.0.1,使用随机端口(30000-60000),不暴露公网; 监听 IP 与端口可在「设置 → 连接与 API」自定义,且会先校验再生效(详见下文)。 - 前后端分离:后端只提供
/api/*接口,前端通过统一客户端web/api.js访问数据, 可连接本机服务,也可连接远程 API。 - 页面左上角显示当前数据源(本地
IP:端口或远程地址)与登录用户。 - 用户名不存在时也执行一次口令哈希校验,避免通过响应耗时枚举用户名。
pip install -r requirements.txt依赖:
pywebview— 登录 / 主界面窗口cryptography— AES-GCM 加解密argon2-cffi— Argon2id 口令哈希与密钥派生opencv-python/Pillow/numpy— 二维码解码
python main.py首次运行:登录窗口会自动切到「创建首个账户」,输入用户名与口令(至少 8 位)即可进入。 之后每次启动:选择/输入用户名 + 口令登录。
启动命令:
python main.py # 桌面模式(等同 python main.py gui)
python main.py serve # 服务端模式:无界面,常驻对外提供 REST API
python main.py --help # 查看全部参数启动流程(桌面模式):
- 弹出用户登录窗口(pywebview):已有账户则登录,否则创建首个账户。
- Argon2id 校验口令 → 解密该用户自己的加密保险库,启动本地 HTTP 服务(随机端口)。
- 程序在同一个 pywebview 进程中新建主窗口并加载验证码页面,同时关闭登录窗口;
主界面左上角显示
127.0.0.1:端口与当前用户名。 - 在设置页点「切换用户」可返回登录窗口换用其他账户(各自数据独立)。
- 关闭主窗口 → 服务停止,内存中的口令与密钥被清理。
不再需要设置任何环境变量来提供主密码;早期的
TOTP_MASTER_PASS机制已被移除 (重置程序时仍会顺带清理该变量在系统中可能残留的旧值)。
整个界面都在 pywebview 窗口内完成,不会弹出系统浏览器。 若运行环境缺少图形依赖导致窗口无法创建,程序会自动回退为「控制台登录 + 系统浏览器」模式。
默认数据根目录:data/(可用环境变量 TOTP_DATA_FILE 指定其他目录/文件所在目录)。
data/
├── users.json # 用户表:用户名 + Argon2id 口令哈希 + 保险库标识
├── vaults/
│ └── <vaultId>.json # 每个用户独立的加密保险库
├── server.json # 连接配置:监听 IP / 端口、远程 API 地址与令牌
└── webview/ # 界面偏好(主题等),不含任何密钥
连接配置示例:
{
"version": 2,
"mode": "local",
"host": "127.0.0.1",
"port": null,
"remoteUrl": "",
"remoteToken": "",
"accessToken": ""
}
host/port为本地监听地址(port为空表示随机);mode=remote时前端改走remoteUrl+remoteToken;accessToken是本机对外提供 API 的令牌(远程客户端用它访问),也可用环境变量TOTP_API_TOKEN覆盖。
用户表结构:
{
"version": 1,
"users": [
{
"username": "alice",
"password": "$argon2id$v=19$m=65536,t=3,p=4$...",
"vaultId": "9f2c...",
"createdAt": "2026-09-12T08:00:00Z",
"lastLoginAt": "2026-09-12T09:30:00Z"
}
]
}
vaultId是随机标识,用作保险库文件名,因此用户名可以是中文且不会影响文件路径。 口令明文字段不存在于用户表,只有 Argon2id 的 PHC 哈希串。
保险库加密文件结构:
{
"version": 2,
"encrypted": true,
"kdf": "argon2id",
"kdfParams": { "timeCost": 3, "memoryCost": 65536, "parallelism": 4, "hashLen": 32 },
"salt": "base64 编码的 32 字节随机盐(每个文件独立生成)",
"iv": "base64 编码的初始化向量",
"data": "AES-GCM 加密后的密文"
}升级说明:早期版本的单用户
data/vault.json(PBKDF2 派生)仍可被读取。 首次用同一个口令登录新版本时,程序会尝试把它接管为当前用户的保险库, 并以 Argon2id 重新加密保存,随后删除旧文件。
程序会在自身目录生成
.2fa-state.json,记录当前及历史上使用过的数据根目录: 始终以最新的TOTP_DATA_FILE为准,此前设置过的旧目录不再作为当前目录(被弃用), 但仍被保留记录,以便「重置程序」时一并清理。
解密后的账户数组:
[
{
"id": 1,
"name": "GitHub",
"secret": "JBSWY3DPEHPK3PXP",
"issuer": "GitHub",
"createdAt": "2026-09-11T21:00:00Z",
"algorithm": "SHA1",
"digits": 6,
"period": 30
}
]id:纯数字唯一标识,用于删除 / 编辑 / 排序。name:用户可读的备注名称。secret:TOTP 密钥,加密存储。issuer/createdAt:可选,用于展示和排序。
- 展示账户列表、当前 6 位验证码与剩余秒数。
- 每 30 秒自动刷新,倒计时环形进度提示。
- 点击验证码或复制按钮即可复制。
- 按
name/issuer搜索过滤账户。 - 手动添加账户,或从二维码图片 / otpauth 链接导入。
- 按
id编辑 / 删除账户。 - 主题与外观模式设置(
settings.html)。 - 多用户:本地用户表保存用户名 + Argon2id 口令哈希,每个用户一份独立加密保险库; 设置页可「切换用户」,运行时各自解锁,互不可见。
- 重置程序:在设置页点击「重置并退出」,二次确认后删除全部用户及其数据与界面偏好并关闭程序,回到首次使用状态。
删除采用「多次重试 + 待清理标记」机制:即使文件被占用、或 WebView2 在退出时把缓存目录写回,
下次启动也会自动补齐清理并彻底移除数据目录;同时清除早期版本遗留的
TOTP_MASTER_PASS(当前进程、Windows 用户级/系统级变量、*nix shell 配置)。 若曾多次修改TOTP_DATA_FILE,重置会连同所有历史数据目录一起删除, 不残留旧路径下的账户数据。 - 数据导出 / 导入:导出加密备份(
.json)或 otpauth 明文文本(.txt), 并从备份文件或 otpauth 文本批量恢复,支持合并追加(按密钥去重)与覆盖全部。 - 页面提示统一使用内置 Toast 组件(
web/toast.js),不使用原生alert/confirm。
后端(server.py)只对外提供 /api/* 接口,前端(web/)是纯静态页面,两者通过 HTTP 通信:
┌────────────────┐ HTTP /api/* ┌──────────────────┐
│ web/index.html│ ───────────────▶│ Python 后端 │
│ web/api.js │◀─────────────── │ server.py │
└────────────────┘ JSON 响应 └──────────────────┘
静态资源,可任意托管 REST 接口 + 数据
- 前端所有请求都经过
web/api.js的ApiClient:本地同机会话走相对路径/api, 远程模式走http(s)://host:port并携带Authorization: Bearer <令牌>。 - 连接配置统一放在
data/server.json(见apiconfig.py),桌面端与浏览器端共用。 - 接口自述文档由
openapi.py生成:/api/openapi.json(OpenAPI 3.1)与/api/docs(HTML 页面)。
接口文档:docs/API.md
「设置 → 连接与 API」可修改本地服务的监听地址,保存时按以下顺序处理, 确保改完仍然可用(而非改完就打不开):
- 先校验:地址必须能解析、属于本机;端口必须在 1~65535 且未被占用
(Windows 上
SO_REUSEADDR会放行重复绑定,因此额外用connect探测 +SO_EXCLUSIVEADDRUSE复核)。 - 再启动:新地址真正监听成功后才写入配置,避免出现「配置改了但服务起不来」。
- 失败回滚:任何一步失败都会用原地址恢复服务(含重置回调),并给出可直接展示的原因。
- 配置未变化时不重启服务;地址变化时界面由程序带着新令牌重新加载,避免半新半旧。
若端口在启动时已被占用,程序会改用可用端口并修正配置,而不是启动失败。
服务端在持有数据的机器上运行:
python main.py serve --host 0.0.0.0 --port 8765 --token <令牌>客户端在桌面端「设置 → 连接与 API」选择「远程 API」,填写地址与令牌,可先点「测试连接」验证。 前端也可独立托管(Nginx / CDN),通过地址参数直连:
http://前端地址/index.html?api=http://192.168.1.9:8765&apiToken=<令牌>
建议仅在可信网络或 HTTPS 反向代理后使用远程模式。
| 项目 | 做法 |
|---|---|
| 用户口令 | 只在登录窗口输入,Argon2id 校验后仅存于程序内存 |
| 口令存储 | Argon2id PHC 哈希(m=65536, t=3, p=4,随机盐),参数落后时自动重哈希 |
| 用户名枚举防护 | 用户名不存在时也执行一次哈希校验,抹平响应耗时差异 |
| 密钥派生 | Argon2id,随机盐,参数随文件保存以便平滑升级 |
| 数据加密 | AES-256-GCM(认证加密,可检测篡改) |
| 服务监听 | 默认仅 127.0.0.1 + 随机端口;自定义 IP/端口会先校验归属与占用情况 |
| 界面载体 | pywebview 桌面窗口,不启动系统浏览器 |
| 来源校验 | 校验 Host 头,并校验 Origin 头,阻止其他网页与 DNS Rebinding 调用 |
| 前端隔离 | 前端只接收验证码与当前用户名,不接收 Secret 与口令 |
| 远程访问 | 仅当显式配置 accessToken 后才允许远程调用(Bearer 令牌 + CORS),默认关闭 |
| 接口自述 | /api/openapi.json 与 /api/docs 为公开只读文档,不暴露任何账户数据 |
| 导出备份 | 备份文件沿用该用户口令加密(单层结构:与保险库同为 Argon2id 派生 + AES-256-GCM 认证加密,32 字节随机盐、参数写入文件元数据),可安全落盘;导出的 otpauth 文本为明文,需自行妥善保管 |
| 退出清理 | 关闭主窗口 / Ctrl+C 后清理内存中的口令与密钥 |
安全边界:本工具假设当前电脑为可信设备。如果电脑已被黑客控制,任何本地工具都无法保证密钥安全。
156--2FA/
├── main.py # 主程序:数据根目录、登录窗口、桌面端 / 服务端编排
├── server.py # HTTP 服务与 REST 接口(后端)
├── apiconfig.py # 连接配置:监听地址、端口、远程 API 与令牌
├── openapi.py # OpenAPI 3.1 规范(接口自述的唯一数据源)
├── users.py # 本地多用户账户(用户表 + Argon2id 口令校验)
├── storage.py # 加密数据仓库(Vault)
├── crypto_utils.py # Argon2id 口令哈希 / 密钥派生与 AES-GCM 加解密
├── totp_utils.py # TOTP / HOTP 计算
├── qr_utils.py # 二维码解码与 otpauth 解析
├── requirements.txt # Python 依赖
├── docs/
│ └── API.md # 接口文档(中文)
├── web/ # 前端(纯静态,可独立部署)
│ ├── index.html # 验证码展示主页
│ ├── login.html # 用户登录 / 注册窗口
│ ├── splash.html # 启动窗口(加载进度条)
│ ├── settings.html # 主题、连接与 API、切换用户、重置程序
│ ├── apidocs.html # 接口文档页(服务端 /api/docs 提供)
│ ├── api.js # 前端统一 API 客户端(本地 / 远程数据源)
│ ├── toast.js # 全站统一的 Toast 提示组件
│ └── fonts/ # 本地自托管的 Material Symbols 图标字体(离线可用)
└── data/ # 用户表、各用户保险库与 server.json(运行时生成)
- Windows:运行
Windows其他版本用户使用这个.bat - Linux / macOS:运行
Linux用户和Mac OS用户使用这个.sh
打包产物位于 dist/2FA-Tool(Windows 下为 2FA-Tool.exe)。
- 多设备:
serve模式已支持自建服务器,下一步可做 paired 机器间的端到端加密同步。 - 多用户会话:远程服务端可按用户名 + 口令换取会话令牌,而无需共享单一
accessToken。 - 批量导入:兼容常见验证器导出格式。
- 导出备份:一键导出加密 JSON 自行保管。
- 账户管理:修改口令、删除指定用户等界面操作。
MIT License · Copyright (c) 2026