Skip to content
bCreeper156Public

About

156 2FA is a purely local, multi-user isolated, zero-cloud TOTP authenticator that stores encrypted keys on your own machine and never uploads anything.

Resources

Stars

11 stars

Watchers

0 watching

Forks

Repository files navigation

156-2FA · 本地优先的动态验证码工具

本地优先、多用户 + 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:端口 或远程地址)与登录用户。
  • 用户名不存在时也执行一次口令哈希校验,避免通过响应耗时枚举用户名。

安装与运行

1. 安装依赖

pip install -r requirements.txt

依赖:

  • pywebview — 登录 / 主界面窗口
  • cryptography — AES-GCM 加解密
  • argon2-cffi — Argon2id 口令哈希与密钥派生
  • opencv-python / Pillow / numpy — 二维码解码

2. 启动

python main.py

首次运行:登录窗口会自动切到「创建首个账户」,输入用户名与口令(至少 8 位)即可进入。 之后每次启动:选择/输入用户名 + 口令登录。

启动命令:

python main.py              # 桌面模式(等同 python main.py gui)
python main.py serve        # 服务端模式:无界面,常驻对外提供 REST API
python main.py --help       # 查看全部参数

启动流程(桌面模式):

  1. 弹出用户登录窗口(pywebview):已有账户则登录,否则创建首个账户。
  2. Argon2id 校验口令 → 解密该用户自己的加密保险库,启动本地 HTTP 服务(随机端口)。
  3. 程序在同一个 pywebview 进程中新建主窗口并加载验证码页面,同时关闭登录窗口; 主界面左上角显示 127.0.0.1:端口 与当前用户名。
  4. 在设置页点「切换用户」可返回登录窗口换用其他账户(各自数据独立)。
  5. 关闭主窗口 → 服务停止,内存中的口令与密钥被清理。

不再需要设置任何环境变量来提供主密码;早期的 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

自定义监听 IP 与端口

「设置 → 连接与 API」可修改本地服务的监听地址,保存时按以下顺序处理, 确保改完仍然可用(而非改完就打不开):

  1. 先校验:地址必须能解析、属于本机;端口必须在 1~65535 且未被占用 (Windows 上 SO_REUSEADDR 会放行重复绑定,因此额外用 connect 探测 + SO_EXCLUSIVEADDRUSE 复核)。
  2. 再启动:新地址真正监听成功后才写入配置,避免出现「配置改了但服务起不来」。
  3. 失败回滚:任何一步失败都会用原地址恢复服务(含重置回调),并给出可直接展示的原因。
  4. 配置未变化时不重启服务;地址变化时界面由程序带着新令牌重新加载,避免半新半旧。

若端口在启动时已被占用,程序会改用可用端口并修正配置,而不是启动失败。

连接远程 API

服务端在持有数据的机器上运行:

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

About

156 2FA is a purely local, multi-user isolated, zero-cloud TOTP authenticator that stores encrypted keys on your own machine and never uploads anything.

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages