# @carecard/auth-util 中文文档

规范地址：https://npmcn.com/package/%40carecard/auth-util/

版本：3\.45\.0
npm 元数据更新时间：2026-11-02T19:19:55.661Z
中文译文更新时间：2026-11-09T08:38:49.313Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40carecard/auth-util
原文对照：https://npmcn.com/package/%40carecard/auth-util/?lang=original
项目主页：https://github.com/CareCard-ca/pkg-auth-util#readme
源码仓库：https://github.com/CareCard-ca/pkg-auth-util

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

- 包体积（解压后）：195 kB，42 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.21\.0 \<25
- 运行依赖：3 个
- 首次发布：2025-12-24T01:41:06.054Z
- 最新版本发布：2026-11-02T19:19:55.349Z
- 近 30 天下载量：3448（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

认证工具函数

## 安装

```sh
npm install @carecard/auth-util
```

也可以使用：`pnpm add @carecard/auth-util`、`yarn add @carecard/auth-util`、`bun add @carecard/auth-util`

## README

# @ carecard/ auth- util

## 1.1.1版和生产数据

CareCard Release 1.1.1是生产基准. 种子为 `--seed-release-data` 已经完成。 生产集群数据、数据库行、, 并保存存储的用户文件。 没有 完成用户数据擦拭和再创建.

未来生产变化必须使用数据保存迁移。 不重播 完成初始化或运行重置、回滚或种子工作流程 常规生产部署.

这个 [已完成的种子库存和核查记录](https://github.com/CareCard-ca/plans/blob/main/cc-seed-data/production-seed-result.md) 记录所接受的释放基准和核查限制.

不可转让的测试令不规则:每一次测试必须独立通过之前或之后的测试,每一次执行指令的套房都必须通过. 每个测试必须建立它所需要的状态,隔离可变状态,并清理它拥有的状态;它绝不能依赖另一个测试的设置,突变,或清理. 默认测试,CI,和Husky命令必须使用测试框架的普通命令,不得强迫随机命令. 随机顺序执行只是一种明确的诊断,它所暴露出的每一出故障都必须被固定在根源上.

不可谈判的"根源-原因"解决方案规则:总是识别并解决已核实的根源,使用更强的解决方案,并给出正确,持久,生产质量的结果. 绝不将临时工作、资源增加、重试、压制、绕行或只表现的补丁视为补丁。 验证根-原因 固定真实失败的工作流程 并证明结束状态.

![Tests Passing](https://github.com/CareCard-ca/pkg-auth-util/actions/workflows/ci.yml/badge.svg) ![Coverage](https://img.shields.io/badge/Coverage-97%25-green)

CareCard生态系统中认证和授权的通用软件包.

## 发展规则

不可转让的TDD规则:总是先写出失败的测试,运行以确认它因预期原因失败,然后执行代码并重跑测试直到通过. 所有编码工作都需要测试驱动开发,不得跳过. 仅用于文档或技能编辑,运行相关的焦点非测试 更改道词前验证; 不添加检查的自动测试 出品人、文件或寄存器结构.

不可转让寄存器隔离规则:每个寄存器必须只使用寄存器内包含的文件,代码,定着物,依赖以及服务来运行其Husky钩和测试. 测试和Husky脚本不得导入,要求,阅读,执行,或以其他方式依赖寄存器根外的兄弟姐妹寄存器或路径. app-e2e-测试是唯一的例外,因为交叉存储端到端测试是其明确的责任.

不可转让错误和警告规则:从不压制,沉默,隐藏,降级,过滤,忽略,跳过,或绕过代码,测试,工具,编译器,linters,或验证错误或警告. 修补根源,再重新运行受影响的检查并需要干净的结果. 预期出错路径测试可能断言出错,但绝不能掩盖出乎意料的失败.

不可转让类型脚本类型规则: 永远不要使用类型脚本类型 `any`; 总是使用特定域类型、通用项目类型、现有项目类型,或 `unknown` 在所有类型Script- family文件中明确缩小(`.ts`, (中文(简体) ), `.tsx`, (中文(简体) ), `.mts`, (中文(简体) ), `.cts`,以及 `.d.ts`) (中文(简体) ).

非可转让代码组织规则:具有相同或等同行为的函数必须在整个CareCard寄存器中使用相同或明显对应的描述性名称,等同的功能必须活在每个寄存器既定架构中同名的文件中. 不允许向后兼容名称,别名,或重复位置.

## 特征

-   **JWT 公用事业**:通过严格的Ed25519 JWK和JWKS配置来创建并验证EdDSA JWTs.
-   **密码工具**:旋转已版本的Argon2id密码花椒,同时保留严格的保存-证书格式.
-   **加密公用事业**:低等密码原始,用于签名,验证和散列.
-   **字符串公用事业**: 基地64和基地64Url 安全编码/解码,以及自定义字符串解析.

## 安装

```bash
npm install @carecard/auth-util
```

## 使用量

### JWT 公用事业`jwtUtilAuth`(中文(简体) )

```javascript
const {
  jwtCreateSignedToken,
  jwtGetHeaderPayload,
  jwtVerifySignedToken,
  parseJwtSigningJwk,
  parseJwtVerificationJwks,
} = require('@carecard/auth-util');

const payload = { sub: '1234567890', name: 'John Doe' };
const signingJwk = parseJwtSigningJwk(process.env.JWT_SIGNING_JWK);
const verificationJwks = parseJwtVerificationJwks(process.env.JWT_VERIFICATION_JWKS);

const token = jwtCreateSignedToken(payload, signingJwk);

const isValid = jwtVerifySignedToken(token, verificationJwks);

// Get header and payload from a JWT
const { header: decodedHeader, payload: decodedPayload } = jwtGetHeaderPayload(token);
```

### JWT 创建服务对服务

```javascript
const {
  jwtCreateServiceAuthorizationHeader,
  jwtCreateServiceToken,
} = require('@carecard/auth-util');

const token = jwtCreateServiceToken({
  issuer: 'worker',
  audience: 'receiver',
  signingJwk: institutionsSigningJwk,
});

const authorization = jwtCreateServiceAuthorizationHeader({
  issuer: 'worker',
  audience: 'receiver',
  signingJwk: institutionsSigningJwk,
});
```

### 密码工具

```javascript
const {
  createPasswordCredential,
  parsePasswordHashKeyring,
  verifyPasswordCredential,
} = require('@carecard/auth-util');

const password = 'correct horse battery staple';
const keyring = parsePasswordHashKeyring(
  process.env.MS_AUTH_PASSWORD_HASH_ACTIVE_KEY_ID,
  process.env.MS_AUTH_PASSWORD_HASH_KEYRING,
);

const credential = await createPasswordCredential(password, keyring);

const result = await verifyPasswordCredential(password, credential, keyring);
if (result.isValid && result.needsRehash) {
  const replacement = await createPasswordCredential(password, keyring);
  // Persist replacement.hash and replacement.hashKeyId atomically.
}
```

密钥环条目使用 `key-id:canonical-base64-32-byte-key`,用逗号分隔. 证书行持续着PHC散列及其 `hashKeyId`; 胡椒键保留 外界一直持有证书和日志。 密码剪接边缘白空和 将形状良好的Unicode规范为NFC,保留内部空间. `@carecard/validate` 拥有密码策略。 签名签名验证和 不重写签名的符号内容而分解外白空间的分解 .

JWT签名配置是一款严格的私人Ed25519 JWK. 核查 配置为RFC 7517 JWKS,包含一个或多个公用Ed25519 JWK. 每个关键用途 `alg: "EdDSA"`, (中文(简体) ), `use: "sig"`,一个精确 `key_ops` 操作,以及 rFC 7638 SHA-256 拇指印 `kid`中添加替换公钥 切换签名符, 并保留退休的公共密钥以获取最大签名符 终身加时钟.

### 弦乐器械( T)`stringUtilAuth`(中文(简体) )

```javascript
const { stringUtilAuth } = require('@carecard/auth-util');

const base64 = stringUtilAuth.asciiToBase64('Hello World');
const original = stringUtilAuth.base64ToAscii(base64);

const urlSafe = stringUtilAuth.makeStringUrlSafe('a+b/c==');
// Result: a-b_c
```

## 不透明自定义索赔

签名和核查保存不作解释的按客户要求提供的客户要求 他们的名字、价值或权威。 授权、数据库调用语境和 申请索赔合同属于其所有人。 密码散列手柄 犬科字节和证书格式;接受政策属于呼叫者.

## 测试

使用 :

```bash
npm test
```

运行类型测试 :

```bash
npm run test:types
```

## 建筑

该软件包分为几个模块:

-   `jwkUtilAuth`:严格剖析私人签名JWK和公开验证JWKS值.
-   `jwtUtilAuth`: 创建固定标题 Ed25519 JWT 并验证签名 `kid`。 。 。 .
-   `pwdUtilAuth`: 创建并验证已版本的Argon2id密码证书.
-   `cryptoUtilAuth`: 使用Node.js进行核心加密操作 `crypto` 模块.
-   `stringUtilAuth`:字符串操纵和格式转换.

所有模块都通过主导出 `index.js`。 。 。 .

## 测试周期审计失败

当前的软件包测试没有 HTTP 听取器,数据库池, Kafka 客户端, 背景计时器,或完成后的儿童进程。 Mocha的测试超时失败 一个停滞的aync测试, 套房运行 没有保释或强制退出,和npm 保留每个命令的非零状态。 将自然进程退出作为打开 处理回归检查; 校验不能用重复操作隐藏失败, 强制 成功,跳过测试,或输出抑制.

不将未发布的可执行验证代码添加到一个 `pkg-*` 仓库。 如果有的话 未来测试拥有长寿资源, 或显示套期后悬挂, 添加一个 通过协调软件包版本对合同过程进行监督, 以及消费者传播工作流程。 那个看门人必须回来 当没有帮助者留下时, 立即只允许一个250ms的边界定居点 窗口,用于已停止的帮助者,失败的持久性后人,保存 失败和输出, 使用退出代码 `124` 仅限真实的外延期限 仍然是最后的后卫,而不是替代明确的清理.

## TDD 认证

测试驱动开发是一项不可谈判的要求.

自动测试的唯一目的是验证可观察到的功能和外部可见的行为. 测试必须验证系统通过其公共界面和预期结果所做的工作.

测试不得坚持、检查或依赖实施细节,包括但不限于:

-   存在代码,语句,函数,类,文件或模块等特定行.
-   具体的算法,控制流,可变名称,方法调用,代码片段,或内部执行选择.
-   任何可以改变而不改变外部可观察到的行为的内部结构.

正确的执行可以完全重写或重构而不需要更改功能测试,只要其外部可观察到的行为保持不变.

仅仅因为执行发生变化而外部观察到的行为仍然正确而未能成功的任何测试都是错误设计的,必须重写或去除.

这一要求对所有新的试验都是强制性的,在修改现有试验时必须适用.

## 常见问题

### @carecard/auth-util 是什么？

认证工具函数

### 如何安装 @carecard/auth-util？

在项目目录运行 npm install @carecard/auth-util，或使用 pnpm add / yarn add / bun add。

### @carecard/auth-util 支持 TypeScript 吗？

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

### @carecard/auth-util 支持 ESM 还是 CommonJS？

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

### @carecard/auth-util 需要什么版本的 Node\.js？

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

### @carecard/auth-util 可以商用吗？

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

### @carecard/auth-util 的下载量有多少？

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

### @carecard/auth-util 还在维护吗？

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