Go 里用 github.com/pquerna/otp 生成和校验 TOTP
绝大多数 Web 端 MFA 实现依赖 TOTP（基于时间的一次性密码），Go 生态里最稳定、文档最清晰的库就是 github.com/pquerna/otp。它不依赖 CGO，兼容 Go modules，且严格遵循 RFC 6238。
常见错误是直接拿用户邮箱或用户名当密钥生成 OTP URI —— 这会导致密钥可预测、易被批量破解。必须用加密安全的随机字节生成密钥：
-
key, err := otp.GenerateKey("myapp:user123", 20)（20 字节足够，别手动生成字符串） - 密钥必须安全存储：服务端存哈希后的密钥（如
sha256(key)）或加密后存 DB，绝不能明文落盘 - 生成 URI 时传入正确的
issuer和accountName，否则 Google Authenticator 扫码后显示混乱，例如：otp.NewURL("myapp", "user123@example.com", key, otp.AlgorithmSHA1, 30)
Web 登录流程中如何安全集成 TOTP 校验
不能在主登录成功后立刻跳转 MFA 页面再校验——这会让攻击者通过响应时间或状态码判断用户是否存在。MFA 必须作为登录流程的原子环节之一，且所有分支都返回一致的延迟与错误提示。
典型错误是把 TOTP 校验逻辑写在 HTTP handler 里但没做速率限制，导致暴力穷举。正确做法：
立即学习“go语言免费学习笔记（深入）”；
- 校验前先查用户是否已启用 MFA（字段如
mf_enabled），未启用则走传统流程，启用则必须过 TOTP - 用
key.Validate(input, time.Now().Unix())，第三个参数是当前 Unix 时间戳，不是字符串；返回true表示匹配，false不代表失败（可能是时间偏移），需结合误差窗口处理 - 设置滑动窗口：比如允许 ±1 个周期（即 ±30 秒），调用
key.ValidateCustom(input, now, 1, 1)，避免因客户端时间不准导致频繁失败 - 每次失败记录 IP + 用户 ID + 时间，5 分钟内超 5 次就临时锁定该账号的 MFA 校验入口（注意：不是主密码登录）
为什么不能自己实现 Base32 编解码或 HMAC-SHA1
有人为“轻量”自己写 Base32 解码，结果因大小写、填充符（=）、字符映射表（RFC 4648 vs RFC 3548）不一致，导致密钥解析失败；也有人用 crypto/hmac 手算 TOTP 值，却忽略时间步长（T = floor((T_cur − T_0) / X)）里的整数截断和字节序问题。
这些细节在 github.com/pquerna/otp 里已严格对齐标准，自行实现几乎必然出错：
- Base32 编码必须用
encoding/base32的StdEncoding（非URLEncoding），否则扫码工具无法识别 - HMAC-SHA1 输出必须是 20 字节 raw bytes，再经动态截断（DT）算法取 4 字节，最后 mod 10^6 —— 少一步就会和所有主流验证器不兼容
- 时间计算必须用 UTC，不能用本地时区；
time.Now().UTC().Unix()是唯一可靠起点
前端扫码后怎么让后端知道用户已配对成功
用户用 Authy 或 Google Authenticator 扫完二维码，并输入第一个验证码，这时前端要提交这个验证码给后端做最终绑定确认。关键不是“验证对不对”，而是“确认密钥归属且未被复用”。
容易忽略的点：
- 绑定接口必须要求提供原始密钥（base32 编码字符串）+ 首次 TOTP 输入值，后端用该密钥重新生成并校验，通过才将密钥哈希写入用户记录
- 不能只校验一次就认为绑定完成：要连续校验 2~3 个不同时间点的码（比如 now, now+30, now+60），防止用户扫错码、时钟偏差大却误判成功
- 绑定成功后立即失效该密钥的“预绑定态”，避免重复提交；同时清除前端内存中的原始密钥（不要存在
localStorage）
真正的难点不在生成或校验，而在于整个流程的状态一致性 —— 密钥何时生成、何时展示、何时提交、何时持久化、何时作废，每一步都要有幂等性和失败回滚。漏掉任意一环，MFA 就只是个摆设。
