two-factor

用途

双因素认证（Two-Factor Authentication，2FA）在用户输入密码之后增加第二重验证步骤，要求用户提供“拥有之物”（手机、安全密钥或认证器应用）的证明，而不仅仅是“知道之物”（密码）。这能大幅降低凭据被盗后遭未授权访问的风险。该模式同时覆盖设置流程（注册第二因素）和验证流程（登录时输入验证码或使用设备）。

何时使用

当需要为账户在用户名和密码之外增加额外验证层时使用双因素认证。常见场景包括：

金融应用、银行和支付平台
邮件服务和通信平台
管理后台和特权用户账户
处理敏感数据的医疗和法律应用
可访问基础设施和代码仓库的开发者平台

何时避免

低风险应用，2FA 的成本超过其安全收益
面向技术熟练度有限用户的应用（可考虑基于风险的身份验证）
2FA 的摩擦会显著降低消费产品采用率时（应设为可选）
自助终端或共享设备环境，基于设备的因素不切实际

实施流程

在复制示例前，先确认该模式与问题和约束相匹配。
从 references/pattern.md 中的结构和示例入手，然后选择最小可行的变体。
在叠加视觉打磨之前，先应用无障碍、性能和交互护栏。
使用测试指南验证键盘、屏幕阅读器、响应式和失败场景下的行为。

无障碍护栏

应做 ✅

在验证码输入框上使用 inputmode="numeric"，以便移动端调出数字键盘
使用 autocomplete="one-time-code"，让浏览器和密码管理器可自动填充短信验证码
为二维码图片提供描述其用途的替代文本
输入无效验证码时用 role="alert" 播报错误
提供二维码的文本替代方案（手动输入密钥）

不应做 ❌

不要让二维码成为设置 TOTP 的唯一方式——始终提供手动输入
不要使用时间压力来惩罚需要更多时间输入验证码的用户
不要仅依赖颜色来表示验证码输入的成功/错误反馈

性能护栏

目标指标

二维码生成：服务端 < 200ms
验证码校验：服务端 < 300ms
短信送达：< 10 秒
验证码输入响应：按键到显示 < 50ms
自动提交：从第 6 位数字到提交 < 100ms

优化策略

客户端生成二维码：

const qrDataUrl = await QRCode.toDataURL(totpUri);

常见错误

没有备用码恢复

问题：丢失认证器设备的用户无法访问其账户。

修复方法：在 2FA 设置期间生成 8-10 个一次性备用码。明确提示用户保存。在验证界面提供备用码输入选项。

仅将短信作为 2FA 方式

问题：短信验证码易受 SIM 卡交换、SS7 拦截和送达延迟的影响。

修复方法：将 TOTP（认证器应用）作为主要方式。仅将短信作为后备。对高安全账户可考虑支持安全密钥。

时间偏移拒绝

问题：由于用户设备时钟与服务器略有不同步，TOTP 验证码被拒绝。

修复方法：接受当前时间窗口以及前后各一个窗口（±30 秒）的验证码。这是标准的 TOTP 容差。

技能介绍

用途