# @codefusion-cc/workers-crypto 中文文档

规范地址：https://npmcn.com/package/%40codefusion-cc/workers-crypto/

版本：0\.1\.2
npm 元数据更新时间：2026-10-03T18:51:22.233Z
中文译文更新时间：2026-11-10T07:48:07.148Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：26.6 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-01T23:39:16.367Z
- 最新版本发布：2026-10-03T18:51:22.066Z
- 近 30 天下载量：2299（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

WebCrypto上的符号、签名和webhooks的字节和文本:base64url和base64 两种方式,六进制,文摘(MD5在工人中也有,用于支付网关),HMAC-SHA256签名和常时检查,标签为按键散列,恒时比较和

## 安装

```sh
npm install @codefusion-cc/workers-crypto
```

也可以使用：`pnpm add @codefusion-cc/workers-crypto`、`yarn add @codefusion-cc/workers-crypto`、`bun add @codefusion-cc/workers-crypto`

## README

# @ codumation-cc/ 工人- crypto

字节和文本 工人代码需要它们 对于符号,签名和网络呼号。 仅建在WebCrypto上,所以 运行在Workers,节点和浏览器中. 唯一的例外是MD5,只有工人才有.

```sh
npm install @codefusion-cc/workers-crypto
```

```ts
import { base64UrlToBytes, digestHex, hmacMatches, hmacSha256, keyedHash, randomToken, safeEqual } from '@codefusion-cc/workers-crypto'

const token = randomToken() // 32 random bytes, 43 characters of base64url
const bytes = base64UrlToBytes(header) // null when it is not base64url: no exception to catch
const ok = safeEqual(await digestHex('SHA-384', JSON.stringify(fields)), notification.sign)

// Sign a webhook body, and check the signature a provider sent, in constant time.
headers.set('x-signature', await hmacSha256(env.WEBHOOK_SECRET, body, 'hex'))
const genuine = await hmacMatches(env.WEBHOOK_SECRET, body, request.headers.get('x-signature') ?? '', 'hex')

// An id that cannot be traced back to the visitor, and matches nothing else the secret signs.
const visitor = await keyedHash(env.VISITOR_HASH_SECRET, 'console-visitor', visitorId, { bytes: 8 })
```

-   **每个解码器返回无效** 案文不改为: `base64UrlToBytes`, (中文(简体) ), `base64ToBytes`, (中文(简体) ), `hexToBytes` 财务报告和审定财务报表 `base64UrlToUtf8`。每个值有一个拼写。 白空格被拒绝, 上次设置的未使用位数也是如此 字符,一个宽松的解码器将读取为相同的字节.
-   **`base64UrlToBytes`** 拒绝 `=` 粘贴,除非 `{ padded: true }` 因为信使和JWT从没有过.
-   **`base64ToBytes`** 读取标准基数64并需要其加载,除非 `{ padding: 'optional' }` 通过.
-   **`hmacSha256(secret, data, encoding?)`** 将秘密作为文本(UTF-8, 即工人的秘密设置),字节,或 a 密码键。 它返回32个字节,或文字在 `'hex'`, (中文(简体) ), `'base64'` 或者说 `'base64url'`输入文本密钥一次 每个隔离。 空的或缺失的秘密,或用于另一种算法或散列的 CryptoKey,用 TypeError 拒绝 .
-   **`hmacMatches(secret, data, mac, encoding?)`** 以恒定时间比较。 永远不要将两个MAC与 `===`文本 MAC需要它的编码(一个没有编码的TypeError;一个错误编码或长度错误的MAC不匹配.
-   **`keyedHash(secret, label, value, { bytes, encoding })`** 为 HMAC 的 `label\nvalue`切为 `bytes`标签 保持一个用途的散列 与另一个用途的 在同一秘密之下。 这一定是一行.
-   **永远不要为两者使用一个秘密 `keyedHash` 财务报告和审定财务报表 `hmacSha256`。 。 。 .** `keyedHash` 这是 `hmacSha256` 标签,行 分解和值,所以一个MAC在数据上 形状等于按键散列。 各各献出自在秘密.
-   **`safeEqual`** 需要的时间并不取决于两个文本的不同之处。 只有长度差异显示.
-   **`digestHex('MD5' | 'SHA-1', …)`** 只针对其签名需要这些算法的供应商。 一些支付网关做.

## 在 WebCrypto 上构建的代码

进口密钥或打开密封数据需要的每包有两个东西,保存在这里一次.

```ts
import { createPromiseCache, nullIfRefused } from '@codefusion-cc/workers-crypto'

// Import each key once per isolate (or page), at most 64 of them.
const imported = createPromiseCache<CryptoKey>(64)
const keyFor = (raw: string) => imported(raw, () => crypto.subtle.importKey('raw', decode(raw), 'AES-GCM', false, ['decrypt']))

// null when the tag does not match (tampered, or another key); an outage rejects as itself.
const plain = await nullIfRefused(crypto.subtle.decrypt({ name: 'AES-GCM', iv }, await keyFor(raw), data), 'OperationError')
```

-   **`createPromiseCache<T>(limit)`** 返回时 `(key, make) => Promise<T>`。呼吁按键共享 `make(key)`,以及 其结果为以后的每一次呼吁服务。 它维持最多 `limit` 成果,工作仍在进行中,并让 最近用过的最好先用. **拒绝永远不会被保留:** 那些等待它的召唤者看见它,而下一个召唤就运行了 `make` 因此,一个失败的导入不会在隔离者的余生中打破那个键. 无效的结果是 一个答案,并被保存.
-   **`nullIfRefused(call, ...names)`** 解决WebCrypto调用的问题, 或当WebCrypto拒绝输入时无效 其中一个 `names`数字 : `OperationError` (不匹配的AES-GCM标记、ECDH或X25519点表示不) 秘密吗, `DataError` (不是关键数据), `InvalidAccessError` (与操作不同的密钥). 其它的失败(运行时间缺少的算法,断开绑定,断出)都拒绝自己. 捕捉 反之,一切都变成了"没有钥匙","被标记"或"被伪造", 以及用这些来操作的代码(写出新的) 键,删除数据,签名人退出),然后进行损坏. **`refusedWith(error, ...names)`** 是同一个测试 (单位:千美元) `catch` 块。 两者都只读出错误的名字,所以一个来自另一个域的 DOM Exception 仍然算数.

## 常见问题

### @codefusion-cc/workers-crypto 是什么？

WebCrypto上的符号、签名和webhooks的字节和文本:base64url和base64 两种方式,六进制,文摘\(MD5在工人中也有,用于支付网关\),HMAC-SHA256签名和常时检查,标签为按键散列,恒时比较和

### 如何安装 @codefusion-cc/workers-crypto？

在项目目录运行 npm install @codefusion-cc/workers-crypto，或使用 pnpm add / yarn add / bun add。

### @codefusion-cc/workers-crypto 支持 TypeScript 吗？

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

### @codefusion-cc/workers-crypto 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @codefusion-cc/workers-crypto 需要什么版本的 Node\.js？

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

### @codefusion-cc/workers-crypto 可以商用吗？

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

### @codefusion-cc/workers-crypto 的下载量有多少？

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

### @codefusion-cc/workers-crypto 还在维护吗？

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