NOTP - One-Time Password Library

🔒 轻量级JavaScript库，实现HOTP(RFC 4226)和TOTP(RFC 6238)一次性密码算法，提供双因素认证(2FA)解决方案，兼容Google Authenticator等主流验证器。

安全提示

• 🚨 密钥存储：禁止硬编码密钥，推荐使用环境变量或密钥管理服务
• ⚠️ 算法选择：SHA-1存在安全风险，高安全场景请使用SHA-256/SHA-512/SM3

DEMO地址

NOTP 动态口令生成器

仓库地址

目录

• 核心特性
• 安装指南
• 快速开始
• API参考
• 算法支持
• 兼容性
• 许可证

核心特性

• 🔐 标准化实现
  严格遵循 RFC 4226 (HOTP) 和 RFC 6238 ( TOTP) 规范
• ⚡ 多环境支持
  Node.js | 浏览器
  提供CommonJS、ES Module、UMD三种模块格式
• 🌐 跨平台兼容
  ✅ Google Authenticator ✅ Microsoft Authenticator ✅ Authy
• 🛡️ 安全增强
  支持SHA-1、SHA-256、SHA-512和国密SM3哈希算法，提供验证窗口动态调整

安装指南

npm install @yutons/notp
# 或者
yarn add @yutons/notp
# 或者
pnpm add @yutons/notp

<!--浏览器安装-->
<script src="./dist/notp.min.js"></script>

快速开始

1. 生成TOTP验证码（Node.js）

import notp from '@yutons/notp';
// 生成Base32密钥（实际使用应动态生成）
const secret = 'JBSWY3DPEHPK3PXP';
// 生成当前时间的一次性密码
const code = new notp.TOTP(secret).generate();
console.log(`您的验证码：${code}`);

2. 生成TOTP验证码（浏览器）

<script src="https://cdn.jsdelivr.net/npm/notp/dist/notp.umd.min.js"></script>
<script>
    // 生成Base32密钥（实际使用应动态生成）
    const secret = 'JBSWY3DPEHPK3PXP';
    // 生成当前时间的一次性密码
    const code = new notp.TOTP(secret).generate();
    console.log(`您的验证码：${code}`);
</script>

API参考

Base32 类

Base32编码、解码和生成随机密钥的工具类。

Base32.generate(length)

生成指定长度的Base32随机密钥

• length (number): 密钥长度（字节），默认为20字节
• 返回: Base32编码的密钥字符串

Base32.encode(bytes)

对字节数组进行Base32编码

• bytes (Uint8Array): 需要编码的字节数组
• 返回: Base32编码的字符串

Base32.decode(secret)

对Base32编码的字符串进行解码

• secret (string): Base32编码的字符串
• 返回: 解码后的字节数组

HOTP 类

HOTP (HMAC-based One-Time Password) 算法实现，遵循 RFC 4226 标准。

构造函数

new HOTP(secret: string, counter?: number, digits?: number, algorithm?: Algorithm)

• secret (string): 共享密钥 (Base32编码)
• counter (number): 计数器初始值，默认为0
• digits (number): 生成的一次性密码的位数，默认为6
• algorithm (Algorithm): HMAC哈希算法，默认为'sha1'

HOTP.generate(counter?)

生成指定计数器值的一次性密码

• counter (number): 指定的计数器值 (可选，如果不提供则使用实例的counter)
• 返回: 生成的一次性密码 (字符串)

HOTP.verify(otp, counter)

验证提供的OTP是否与指定计数器值生成的OTP匹配

• otp (string): 要验证的OTP
• counter (number): 用于生成预期OTP的计数器值
• 返回: 验证结果 (boolean)

HOTP.next()

生成下一个计数器值的一次性密码，并递增计数器

• 返回: 生成的一次性密码 (字符串)

HOTP.getConfiguration()

获取当前配置信息

• 返回: 包含secret、counter、digits和algorithm的对象

属性

• secret: 获取/设置共享密钥
• counter: 获取/设置计数器值
• digits: 获取/设置密码位数 (6-10)
• algorithm: 获取/设置哈希算法

TOTP 类

TOTP (Time-based One-Time Password) 算法实现，基于 HOTP，使用时间戳作为计数器，遵循 RFC 6238 标准。

构造函数

new TOTP(secret: string, period?: number, digits?: number, algorithm?: Algorithm)

• secret (string): 共享密钥 (Base32编码)
• period (number): 时间步长（周期），单位为秒，默认为30秒
• digits (number): 生成的一次性密码的位数，默认为6
• algorithm (Algorithm): HMAC哈希算法，默认为'sha1'

TOTP.generate()

生成当前时间窗口的一次性密码

• 返回: 生成的一次性密码 (字符串)

TOTP.verify(otp, window)

验证提供的OTP是否有效

• otp (string): 要验证的OTP
• window (number): 允许的时间窗口偏差（向前和向后），默认为1
• 返回: 验证结果 (boolean)

TOTP.timeRemaining()

获取当前时间窗口的剩余有效时间

• 返回: 剩余有效时间（秒）

TOTP.currentPeriodStart()

获取当前时间窗口的开始时间

• 返回: 当前时间窗口的开始时间（Unix时间戳，秒）

TOTP.getConfiguration()

获取当前配置信息

• 返回: 包含secret、period、digits、algorithm和timestamp的对象

属性

• secret: 获取/设置共享密钥
• period: 获取/设置时间步长 (正整数)
• digits: 获取/设置密码位数 (6-10)
• algorithm: 获取/设置哈希算法
• timestamp: 获取/设置模拟时间戳 (null表示使用系统当前时间)

Algorithm 枚举

支持的哈希算法类型:

• Algorithm.SHA1: 'sha1'
• Algorithm.SHA256: 'sha256'
• Algorithm.SHA512: 'sha512'
• Algorithm.SM3: 'sm3'

Default 类

默认配置值:

• Default.ALGORITHM: 默认算法 'sha1'
• Default.PERIOD: 默认周期 30秒
• Default.DIGITS: 默认位数 6
• Default.WINDOW: 默认窗口 0
• Default.SUPPORTED_ALGORITHMS: 支持的算法列表
• Default.isSupportedAlgorithm(value): 检查字符串是否为支持的算法

算法支持

NOTP支持多种哈希算法，以满足不同的安全需求和兼容性要求。

| 算法 | 安全性 | Google Authenticator | Microsoft Authenticator | Authy | 推荐场景 | |---------|---------|---------------------|------------------------|-------|-----------| | SHA-1 | ⚠️ 一般 | ✅ 完全兼容 | ✅ 完全兼容 | ✅ 完全兼容 | 兼容性要求高的场景 | | SHA-256 | 🔒 高 | ❌ 不兼容 | ❌ 不兼容 | ❌ 不兼容 | 安全性要求高的场景 | | SHA-512 | 🔒 高 | ❌ 不兼容 | ❌ 不兼容 | ❌ 不兼容 | 安全性要求高的场景 | | SM3 | 🔒 高 | ❌ 不兼容 | ❌ 不兼容 | ❌ 不兼容 | 国密合规场景 |

算法选择建议

1. SHA-1: 作为默认算法，与大多数主流验证器应用完全兼容，适合需要广泛兼容性的场景。
2. SHA-256/SHA-512: 提供更高的安全性，但会失去与主流验证器应用的兼容性，适合内部系统或自定义验证器应用。
3. SM3: 中国国家密码管理局发布的密码杂凑算法，符合国密标准，适用于有国密合规要求的场景。

使用示例

import {TOTP, Algorithm} from 'notp';
// 使用默认的SHA-1算法 
const totpSha1 = new TOTP('YOUR_SECRET_HERE');
// 使用SHA-256算法 
const totpSha256 = new TOTP('YOUR_SECRET_HERE', 30, 6, Algorithm.SHA256);
// 使用SM3算法 
const totpSm3 = new TOTP('YOUR_SECRET_HERE', 30, 6, Algorithm.SM3);

注意事项

• 更改算法后，生成的OTP将与之前算法生成的不同
• 在生产环境中更改算法需要重新配置所有用户的验证器应用
• 国密算法(SM3)仅在中国境内有强制要求的场景下推荐使用

许可证

MIT License ©yutons
允许商业使用、修改和私有部署，需保留版权声明。