Terminus LarePass Vault 双因素认证(2FA)指南:用 TOTP 验证器保护你的在线账户

原创2026-10-15 23:43:59340 阅读
文章标签:云原生后端运维

Terminus LarePass Vault 双因素认证(2FA)指南:用 TOTP 验证器保护你的在线账户

双因素身份验证(2FA)在密码之外再增加一层动态验证码校验,能显著提升 GitHub、OpenAI 等在线服务的账户安全。在 Terminus 生态中,LarePass 内置的 Vault 可以充当标准的身份验证应用:它基于 TOTP(基于时间的一次性密码)算法自动生成每 30 秒刷新一次的 6 位验证码,功能与 Google Authenticator、Microsoft Authenticator 一致,且与密码库统一保存在同一加密保险库中。本文将以 docs/zh/manual/larepass/two-factor-verification.md 为主线,带你完成「服务端开启 2FA → Vault 创建验证器 → 登录时取码」的完整闭环,并结合仓库源码剖析 TOTP 生成、Base32 密钥解码与 30 秒倒计时的底层实现。

2FA 与 TOTP:Vault 为什么能当验证器用

2FA 的原理是「知道什么(密码)+ 拥有什么(验证器)」。当你输入密码后,服务会额外要求一个动态验证码;验证码由你持有的验证器基于共享密钥和当前时间生成,服务端用同一算法校验,从而证明登录者确实持有该验证器。

Vault 生成的正是基于时间的一次性密码(Time-Based One-Time Password,TOTP)验证码。与推送通知型 2FA 不同,TOTP 完全离线工作:只要设备时钟准确,即使没有网络也能生成正确验证码。这也是 GitHub、OpenAI、Google 等绝大多数服务将「Authenticator App」作为标准 2FA 选项的原因。

前提条件

开始前请确认满足以下两点:

  • 已安装 LarePass:请在目标设备上安装最新版 LarePass 客户端(iOS / Android / macOS / Windows / Linux / Chrome 扩展),具体平台下载方式见 下载 LarePass 指南。
  • 能访问目标服务的安全设置:你需要能登录目标网站或应用,并进入其安全(Security)设置页面。

第一步:在目标服务上启用 2FA

  1. 登录你希望启用 2FA 的网站或应用,例如 GitHub 或 OpenAI。

  2. 进入安全设置页面,选择使用身份验证应用(Authenticator App)作为双因素验证方式。

    在 GitHub 安全设置中启用 2FA 并选择身份验证应用

  3. 保存服务提供的密钥(Secret Key)或二维码,下一步会用到。

:::tip 注意 如果服务同时提供了恢复代码(Recovery Codes),请务必妥善保存。当你无法访问 Vault(例如设备丢失或保险库未解锁)时,只能靠恢复代码找回账户。 :::

第二步:在 Vault 中创建验证器

打开 LarePass,进入 Vault 页面,按你的设备类型执行以下操作。

Olares / LarePass 桌面端

  1. 打开 Vault。
  2. 在右上角点击 + 添加。
  3. 选择验证器作为项目类型,然后点击创建。
  4. 填写必填字段:
    • 项目名称:输入可识别该服务的名称,例如 GitHub。
    • 一次性密码:粘贴上一步保存的密钥(Secret Key)。
  5. 点击保存。

LarePass 移动端

  1. 在你的设备上打开 LarePass,然后进入 Vault 页面。
  2. 在右上角点击 + 添加。
  3. 选择验证器作为项目类型,然后点击创建。
  4. 填写必填字段:
    • 项目名称:输入可识别该服务的名称,例如 GitHub。
    • 一次性密码:点击文本字段中的 二维码图标,直接扫描服务提供的二维码。
  5. 点击保存。

保存后,Vault 会立即开始为该账户生成验证码,无需等待任何同步或激活过程。

密钥与二维码:两种录入方式如何工作

无论粘贴密钥还是扫描二维码,本质都是向 Vault 录入同一份 TOTP 共享密钥。二维码的内容是一个标准的 otpauth:// URI,格式形如:

otpauth://totp/Issuer:account?secret=XXXX&issuer=Issuer&algorithm=SHA1&digits=6&period=30

从源码看,SDK 提供了对应的解析与构造能力:apps/packages/sdk/src/core/otp.ts 中的 parseURL 负责从 otpauth:// URI 中提取 secret 参数(若密钥非法会抛出 Invalid secret),generateURL 则负责按 secret、issuer、account、type、interval、digits、hash 参数拼装标准的 otpauth://totp/... 链接。此外,apps/packages/app/src/platform/addItem.ts 中的 decodeAuthenticatorMigrationUrl 还实现了对 Google Authenticator「导出账户」迁移链接(otpauth-migration://)的解码:它通过 protobuf 解析迁移载荷,将其中每个账户的 Base32 密钥还原为可导入的 otpauth://totp/... URI——这意味着你可以把已在 Google Authenticator 中绑定的全部账户一次性迁入 Vault,迁移过程中还会保留 SHA1/SHA256/SHA512 算法、digits 位数等参数。

第三步:登录时使用 2FA 验证码

  1. 使用你的用户名和密码登录网站。
  2. 当网站要求输入验证码时,打开 Vault,找到对应服务的当前 6 位验证码。
  3. 输入验证码完成登录。

出于易读性考虑,Vault 界面会把 6 位验证码按「前 3 位 + 空格 + 后 3 位」展示,并配有一个随时间走完的圆形进度指示器,提示当前验证码剩余的有效时间。

深入原理:Vault 的 TOTP 生成链路

从「密钥」到「屏幕上的 6 位验证码」,Vault 的完整计算链路可以拆解为三步,每一步都能在仓库源码中找到对应实现。

1. Base32 密钥解码

服务下发的密钥是 Base32 编码的字符串(字符集为 A-Z 与 2-7)。在 apps/packages/sdk/src/core/base32.ts 的 base32ToBytes 中,每个 Base32 字符被映射为 5 个二进制位,累积满 8 位即写入一个字节;若遇到字符集之外的字符,会抛出 Invalid Base32 character found 错误——这正是粘贴密钥出错时 Vault 提示无效代码的第一道防线。

2. HMAC 派生验证码

解码后的密钥字节与「时间计数器」一起参与 HMAC 运算。核心逻辑在 apps/packages/sdk/src/core/otp.ts:

  • hotp(secret, counter, opts) 用密钥对计数器(numToBytes(counter))做 HMAC 签名,默认采用 SHA-1 哈希、输出 6 位数字;
  • getToken 按 RFC 4226 的动态截断(Dynamic Truncation)规则,取 HMAC 结果最后一个字节的低 4 位作为偏移量,从中间截取 4 个字节,再对 10^digits 取模并前补零得到验证码;
  • totp(secret, time, opts) 将当前时间戳除以 interval(默认 30 秒)向下取整得到时间计数器,再交给 hotp 计算,即 counter = Math.floor(time / 1000 / 30)。

值得说明的是,TOTP 约定要求时间与 30 秒周期对齐,因此「验证码在整 30 秒边界刷新」是算法天然行为,而非 UI 的定时器在控制。

3. 30 秒周期与倒计时展示

桌面端与移动端的 TOTP 组件会以约 2 秒一次的频率轮询刷新,但只有跨过新的 30 秒周期(计数器变化)时才重新计算验证码,避免无谓的重复运算。相关实现可见:

计算中若密钥无法解码(Base32 非法),组件会捕获异常并显示「无效代码」提示,同时将进度归零。

4. 验证器条目在保险库中的存储形态

在数据模型层面,验证器是 Vault 中一种特殊类型的条目:apps/packages/sdk/src/core/item.ts 定义了 FieldType.Totp = 'totp' 字段类型,其字段定义位于 apps/packages/sdk/src/core/item.ts:值需匹配 Base32 正则 ^([A-Z2-7=]{8})+$,展示名称为「One-Time Password」,transform 方法即调用 totp(base32ToBytes(value)) 实时生成验证码。整个保险库(包括验证器密钥)随 LarePass 端到端加密保存,需要解锁保险库后才能查看验证码。

5. Olares 登录环节的自动联动

除手动为第三方服务添加验证器外,Vault 还与 Olares 自身的 2FA 打通:在 apps/packages/sdk/src/core/app.ts 中,登录 Olares 时若服务端返回了 MFA 信息(data.mfa),SDK 会自动查找 authenticator 条目模板,把 MFA 密钥写入模板的 totp 字段并创建保险库条目;同时会先遍历 VaultType.TerminusTotp 类型的既有条目做去重(apps/packages/sdk/src/core/app.ts),避免重复添加同一验证器。这说明验证器不仅是密码库的一个「附加功能」,而是与 Terminus 账户体系深度集成的基础安全组件。

安全建议与常见问题

  • 妥善保管恢复代码:无论在哪家服务开启 2FA,恢复代码都是你失去验证器访问权时唯一的补救手段。建议将其作为安全笔记或文件一并存入 Vault,而不是只留在邮箱或截图里。
  • 验证码无效时先核对时钟:TOTP 依赖设备时间。若 Vault 生成的验证码被服务拒绝,优先检查设备系统时间与网络时间是否同步(偏差超过约 1 个周期即 30 秒就可能校验失败)。这也是 SDK 中 validateHotp 会采用前后各 window 个计数器的滑动窗口来容忍轻微时钟偏差的原因(apps/packages/sdk/src/core/otp.ts)。
  • 粘贴密钥时注意字符:Base32 密钥不含 0/O、1/I 等易混淆字符,但应去除空格、连字符等分隔符后整体粘贴,否则会触发 Base32 解码失败。
  • 多设备同步:Vault 条目随 LarePass 账户端到端同步,在一台设备上创建验证器后,其他已登录设备同样可用,但请确认你的同步与备份策略(可参考 LarePass 手册中关于 同步与共享 的说明)。

总结

通过「服务端开启 2FA → Vault 创建验证器 → 登录取码」三步,你可以把 LarePass 的 Vault 打造成统一的 TOTP 验证中心,为 GitHub、OpenAI 等在线服务加上第二道安全锁。从源码层面看,Vault 的 TOTP 能力完整实现了标准算法链路:Base32 密钥解码(base32.ts)→ HMAC 动态截断生成 6 位码(otp.ts)→ 30 秒周期驱动与进度环展示(totp2.vue),并额外支持 Google Authenticator 迁移导入与 Olares 登录 MFA 自动绑定。所有验证器密钥都与其他密码一起存放在加密保险库中,让「密码 + 验证码」真正统一在一个受保护的安全中心里。

登录后查看全文
Terminus