# @chax-at/totp 中文文档

规范地址：https://npmcn.com/package/%40chax-at/totp/

版本：1\.0\.0
npm 元数据更新时间：2025-09-24T11:13:30.336Z
中文译文更新时间：2026-11-09T11:57:07.198Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chax-at/totp
原文对照：https://npmcn.com/package/%40chax-at/totp/?lang=original
项目主页：https://github.com/chax-at/totp#readme
源码仓库：https://github.com/chax-at/totp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：24.1 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 20
- 运行依赖：0 个
- 首次发布：2024-03-01T02:57:06.685Z
- 最新版本发布：2025-06-17T11:55:44.274Z
- 近 30 天下载量：3639（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）

## 中文简介

一个简单的 TOTP 软件包

## 安装

```sh
npm install @chax-at/totp
```

也可以使用：`pnpm add @chax-at/totp`、`yarn add @chax-at/totp`、`bun add @chax-at/totp`

## README

# @ chax-at/totp (英语)

一个简单的软件包,可以用来执行TOTP 二要素代码. 执行默认使用大小写(6位码,30s分时步,20字节/160位碱基32-被编码后的秘密,使用SHA1),但不提供多少定制.

这些默认值是最常见的,应该在所有验证器应用中支持. 如果你想知道你为什么要用这个包而不是其他包, 请检查区域 [为什么又是TOTP软件包](https://npmcn.com/package/%40chax-at/totp/#readme-why-yet-another-totp-package) 在底层.

## 使用量

通过运行安装软件包

```
npm i @chax-at/totp
```

### Totp 管理器

然后,你可以创建一个 `TotpManager` 生成秘密和验证密码。 您可以创建 `TotpManager` 像这样:

```ts
import { TotpManager } from '@chax-at/totp';

const totpManager = new TotpManager({
  // This issuer will be shown in the user's authenticator app and should be something like your company/service name
  issuer: 'ExampleWebsite',
  // You can also specify `verifyWindow` here. Defaults to 2 which means that the TOTP code at current time is valid as well as the previous 2 and next 2
});
```

### 创建秘密

假设用户 `user@example.com` 想要使用他们的 TOTP 应用程序启用两个因子 。 您现在可以为此用户生成一个秘密 :

```ts
// Include the user's account name/email here which is shown in their authenticator app when scanning the QR code
const { secret, otpauthUri } = totpManager.generateSecret('user@example.com');
```

-   保存返回的内容 `secret` 用于数据库中的用户。 建议加密这个秘密(注意您不能散开,因为您需要用简写来验证代码).

> 我们还建议将钥匙安全地储存在验证系统中, 更具体地说,用防篡改的方法加密它们 硬件加密并仅在需要时披露: 例如,当需要校验检察官办公室值时会解密密钥,以及 立即重新加密,将内存中的曝光限制为短 期限. [RFC 6238、5.1](https://datatracker.ietf.org/doc/html/rfc6238#section-5.1)

-   生成包含返回的 QR 代码 `otpauthUri` 并显示给用户。 然后他们可以用他们的认证程序扫描它.
-   您也可以显示 `secret` 这样他们就可以手动注册您的应用程序,以防QR代码失效.
-   您应该要求用户在实际启用双要素认证之前输入一个有效的代码 .

### 正在验证 TOTP 代码

假设用户输入代码 `123456`,然后你可以这样验证:

```ts
// Returns whether the code is valid at the current time. Also returns true if it matches the previous/next [verifyWindow] codes as defined above
const isValid = totpManager.verify(secret, '123456');
```

-   您应该限制 TOTP 校验, 以便攻击者不能粗暴强制 TOTP 代码( 可能只有 1 000 000 个代码)
-   您至少应该为每个用户保存( 并拒绝) “ 使用” 的正确符号 `30s + 30s * verifyWindow [default 2]` 这样,您的一次性密码( TOTP 部分) 只能使用一次

> 注意证明人可在某一时间段内派出同一检察官办公室 窗口到验证器。 核查者必须不接受 检察官办公室在成功验证后的第二次尝试 为第一个检察官办公室印发,确保一次性只使用 检察官办公室. [RFC 6238、5.2](https://datatracker.ietf.org/doc/html/rfc6238#section-5.2)

## 为什么又一个TOTP包?

有一些被广泛使用的节点TOTP/2FA包可用. 然而,在我研究这些提议时,所有提议似乎都没有得到维护,有些领域可以改进(包括安全关键问题).

您的用法大小写可能有所不同(例如, 如果您需要比这个软件包更需要定制), 但这就是我为什么没有使用其他软件包, 决定自己写:

-   **爱说话** 似乎在教学中是最推荐的软件包。 然而,它不会产生安全的秘密.
    -   sayeasy 忘记了字母"j"的存在,因此它根本不出现在秘密中\[[来源](https://github.com/speakeasyjs/speakeasy/blob/cff2bb42cde5e74c43493a8f26b20e52960df531/index.js#L563)\[ . \]
    -   soneeasy在秘密中引入了偏见,防止它完全随机,使攻击变得容易. 有一个 [公关](https://github.com/speakeasyjs/speakeasy/pull/92) 试图修复它 - 但软件包没有维护 .
-   **atplib 函数** 每周的下载量甚至更多,在他们的秘密世代中没有偏见. 然而,它们产生的秘密太短(除非您指定了长度),甚至没有达到TOTP规格中定义的最小值.
    -   RFC 4226表示"共享秘密MUST的长度至少为128位. 这份文件建议共享160比特的秘密长度"
    -   这意味着一个秘密必须至少有16个字节长,并且被推荐为20个字节长(这个@chax-at/top使用)
    -   然而, otplib 更改了默认值( a [20k行更改任务](https://github.com/yeojz/otplib/commit/b088efe9da45e102e59b5cd2c0df5bddf80c5a92))在12.0.0中,从安全的20字节到仅仅10字节(80比特)\[[来源](https://github.com/yeojz/otplib/blob/v12.0.0/packages/otplib-core/src/authenticator.ts#L265-L267)\[ . \]
        -   升级指南未提及这一点
        -   这个 [这个问题](https://github.com/yeojz/otplib/issues/671) 从2022年起,维护者没有回复
    -   关于图书馆的其余部分,我不能多说,因为代码分成了12个套件(而两个文件在@chax-at/totp中各有40/70行),我无法通过点击GitHub中的文件来跟踪所有这些抽象层
-   **节点-2fa** 没有明显的安全问题。 然而,仍有一些东西阻止我使用.
    -   `generateSecret` 也返回一个有用的 QR 代码链接 - 即刻向 Google 发送您的秘密 。 你真的应该生成自己的QR代码,而不是向Google发送你的秘密.
    -   这取决于 `notp` 用于密钥生成
        -   `notp` 包含在节点被折旧的代码,例如 . `new Buffer(...)`这不是一个安全问题,但将对使用其包裹的所有人发出贬值警告。 有一个 [公关](https://github.com/guyht/notp/pull/59) 从2021年至今尚未合并.
    -   这个软件包没有更改日志( 至少我找不到)
-   没有其他软件包使用常时比较来检查代码. 我认为时机攻击不太可能,但使用常时比较功能可以阻止这些攻击.

## 常见问题

### @chax-at/totp 是什么？

一个简单的 TOTP 软件包

### 如何安装 @chax-at/totp？

在项目目录运行 npm install @chax-at/totp，或使用 pnpm add / yarn add / bun add。

### @chax-at/totp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @chax-at/totp 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @chax-at/totp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chax-at/totp 可以商用吗？

@chax-at/totp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chax-at/totp 的下载量有多少？

根据 npm 官方下载统计，@chax-at/totp 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,639 次，日均约 121 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chax-at/totp 还在维护吗？

最新版本 1\.0\.0 发布于 2025/06/17（1\.4 年前）；至今共发布 5 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/03/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。