时序口令演示

解决什么问题

在接入 TOTP 两步验证时，团队往往先纠结于「这个 6 位码到底怎么算出来的」。翻 otplib 文档能知道有 authenticator.generate 和 authenticator.check 两个入口，但把密钥输入、时钟步长、校验返回值串成一条可跑的最小链路，仍然要花时间试错。更常见的坑是：演示用的 Secret 被硬编码进了仓库，日志里明文打印了 seed，或者校验失败直接抛异常把主流程打断。

这个技能针对的就是本地试算与自测场景：不搭建账号体系，不写服务端，只回答「当前这一秒的码是什么」「用户输入的这 6 位对不对」。

它如何工作

核心能力只有两步，直接复用 otplib 的公开 API：

• 生成：调用 authenticator.generate(secret) 得到当前 6 位码，用于在 Demo 界面上实时展示；
• 校验：调用 authenticator.check(input, secret) 返回布尔值或错误信息，供表单做本地比对。

推荐的演示闭环是：

1. 运行时由输入框提供 newSecret，绝不落盘、不进 git；
2. 展示当前窗口的 genTotp 结果，方便观察码随时间变化；
3. 用户在输入框提交后走 verifyTotp，通过则放行，失败返回明确的失败信息；
4. 自测三例：正确码通过、改一位失败、空密钥给出报错而非崩溃。

时钟偏差通过 window 参数控制，即允许前后若干个时间步的容忍度，默认取较小的合理值，避免把安全裕度开得过大。

适用边界与注意点

• 只做本地 Demo：本包不包含完整账号体系，不提供密钥托管、多用户存储或服务端校验接口，不要拿它直接当生产认证方案。
• Secret 只在内存：演示密钥由运行时输入提供，禁止写死进仓库，也不要在前端长期明文展示给无关人员。
• 失败要优雅：校验不通过时返回布尔值或错误信息，不要抛未捕获异常挡住主流程。
• 实现要点：原创部分（密钥注入与校验调用的组合方式）在代码注释中以 小四原创 标出，灵感来自 otp-totp 能力工具箱。
• 依赖边界：仅依赖 otplib 或其文档推荐的兼容导入方式，不引入额外的加密栈。