# @baukit/auth-node 中文文档

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

版本：0\.18\.3
npm 元数据更新时间：2026-11-07T02:36:33.935Z
中文译文更新时间：2026-11-07T18:47:13.645Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：235 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- 首次发布：2026-09-04T18:02:34.072Z
- 最新版本发布：2026-11-07T02:36:33.534Z
- 近 30 天下载量：8160（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

以 S256 PKCE 为节点的 OIDC 设备授权, 刷新旋转, 以及一个被锁定的符号缓存 .

## 安装

```sh
npm install @baukit/auth-node
```

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

## README

# @baukit/自动节点

`@baukit/auth-node` 是用于CLI和MCP客户端的节点24 OIDC设备流程包. 它处理发现,RFC 8628投票,S256 PKCE,刷新回转,以及一个本地配置缓存. 它没有运行时间依赖.

软件包不打印指令或打开浏览器. 为这些行动提供回调.

## 设备流程客户端

```ts
import { DeviceFlowClient } from '@baukit/auth-node/device-flow';

const auth = new DeviceFlowClient(
  {
    issuer: process.env['OIDC_ISSUER'] ?? '',
    clientId: process.env['OIDC_CLIENT_ID'] ?? '',
    scopes: ['openid', 'profile', 'offline_access'],
    audience: 'notes-api',
    cache: {
      namespace: 'notes-mcp',
    },
  },
  {
    environmentToken: () => process.env['NOTES_API_TOKEN'],
  },
);

await auth.login({
  presentation: {
    showVerification: ({ verificationUri, userCode }) => {
      process.stderr.write(`Open ${verificationUri}\nEnter ${userCode}\n`);
    },
    showStatus: (status) => {
      process.stderr.write(`Login status: ${status}\n`);
    },
    openBrowser: (url) => openProductBrowser(url),
  },
});

const token = await auth.accessToken();
```

`accessToken()` 先检查注入环境的源头。 然后读取所选缓存配置文件并刷新已近过期的符号 。 刷新过程中共享一个承诺并持有相邻 `.lock` 正在读取和替换缓存.

`refreshLeewaySeconds` 默认为 60 秒; 刷新窗口是该值中较小的部分, 半个符号寿命, 以 `expiresAt - issuedAt`。 。 。 .

通过一个 `AbortSignal` 改为 `login`, (中文(简体) ), `accessToken`,或 `logout`。发现和符号请求有一个15秒的默认超时。 登录总超时10分钟. 两种限制都是可以确定的.

## 终点政策

配置的发行者必须匹配发现元数据 。 将已知发行人别名放入 `endpointPolicy.issuerAllowlist`。Token 和设备端点必须共享发行者的来源和路径。 将提供者的有记录的端点来源输入 `endpointOriginAllowlist` 当它使用单独的来源.

所有发售者,设备,符号,和校验URL都需要HTTPS. 地方发展可以确定 `allowLoopbackHttp: true`; 仅允许 `localhost`, (中文(简体) ), `127.0.0.0/8`,以及 `::1`。 。 。 .

发现和象征体默认限制在64 KiB. 出错包含一个稳定的代码,一个允许上市的消息,一个可选的HTTP状态,没有提供者机构. 客户端不登录.

## API 来源

`parseApiOrigin(value, { allowLoopbackHttp, label })` 检查已配置的 API 基础 URL, 如 MCP 服务器 `PRODUCT_API_URL`,与终点政策相同的计划规则。 它会修剪白空间,接受一个后行斜线,然后返回 `url.origin`。 。 。 .

```ts
import { parseApiOrigin } from '@baukit/auth-node';

const apiUrl = parseApiOrigin(process.env['PRODUCT_API_URL'] ?? 'http://localhost:8080', {
  allowLoopbackHttp: process.env['NODE_ENV'] !== 'production',
  label: 'PRODUCT_API_URL',
});
```

它会扔 `ApiOriginError`页:1 `TypeError`,带有 `reason` 联 合 国 `invalid_url`, (中文(简体) ), `insecure_scheme`,或 `not_an_origin`。证书、路径、查询或碎片计数为: `not_an_origin`。 。 。 . `allowLoopbackHttp` 默认为虚假。 消息将标签和被打破的规则命名,永远不表示值,因此可以安全地日志.

## Keycloak 测试助手

`@baukit/auth-node/keycloak-testing` 设置用户对可支配开发的 Keycloak 进行端到端测试. 它运行在节点24,使用全球 `fetch`,不需要 Playwright 依赖.

副航道舰只作为无害环境管理, 就像每一个Baukit包。 节点 24 从普通JS 装入 `require(esm)`,所以普通JS测试项目不需要动态 `import()`模式 `"module": "node20"` 或者说 `"nodenext"`; 下节 `"node16"` 它报告TS1479的进口,因为 `node16` 描述无法打开的节点释放 `require` 无害环境管理.

```ts
import {
  allowKeycloakWebOrigin,
  createKeycloakTestUser,
  keycloakStack,
  signInWithKeycloak,
} from '@baukit/auth-node/keycloak-testing';

const stack = keycloakStack({
  url: 'http://localhost:8081',
  realm: 'notes',
  webClientId: 'notes-web',
});

await allowKeycloakWebOrigin(stack, 'http://localhost:5183');
const user = await createKeycloakTestUser(stack);
await page.getByRole('button', { name: 'Sign in' }).click();
await signInWithKeycloak(page, user, stack);
```

`keycloakStack(defaults, environment = process.env)` 返回产品的默认值,除非 `E2E_KEYCLOAK_URL`, (中文(简体) ), `E2E_KEYCLOAK_REALM`, (中文(简体) ), `E2E_KEYCLOAK_ADMIN_USERNAME`, (中文(简体) ), `E2E_KEYCLOAK_ADMIN_PASSWORD`,或 `E2E_KEYCLOAK_WEB_CLIENT_ID` 已经设定。 管理员证书默认为 `admin` 财务报告和审定财务报表 `admin`,然后从 URL 中删除尾条.

`createKeycloakTestUser(stack, user?, options?)` 进入主域 `admin-cli` 并创建经验证、启用的用户,并设置永久密码。 无 `user`,用户名为 `e2e-<uuid>` 并且密码是随机的,所以并行的测试永远不会共享一个身份. 过 `username`, (中文(简体) ), `email`,或 `password` 当王国通过电子邮件签名时。 它回来了 `{ username, password, email, subject }`· ; `subject` 是 Keycloak 用户代号,它成为 `sub` 索赔.

`revokeKeycloakUserSessions(stack, subject)` 结束用户的每次会话, 因此应用程序的下一个刷新失败 . `allowKeycloakWebOrigin(stack, origin)` 添加 `<origin>/*` 到网络客户端的重定向 URI 及其 `post.logout.redirect.uris` 属性,以及 `origin` 到它的网络起源。 它保留了客户端的其他属性,当三个都在场时则无所作为. 保存的日志后列表 `+` 已经重用重定向的 URI, 所以帮助者将它放过 . `signInWithKeycloak(page, user, stack, { timeoutMs })` 等待页面出现在 Keycloak 来源上,填写 `#username` 财务报告和审定财务报表 `#password`,单击 `#kc-login`;这些ID不会随登录地块而改变. `page` 是 Playwright 的任何对象 `waitForURL` 财务报告和审定财务报表 `locator`,例如 `Page` 或登机弹出.

每个管理员的电话都要接 `{ fetch, timeoutMs }`; 超时默认为 `DEFAULT_KEYCLOAK_REQUEST_TIMEOUT_MS` (30秒) (英语). 失败投出 `Error` 来命名步骤和 HTTP 状态, 并且从不包含响应机构或管理员密码。 创建的用户和添加的起源留在了域中,因此将帮助者只指向一个发展域.

## 缓存合同

JSON 缓存将命名的配置文件保存在一个命名空间下. `defaultTokenCachePath(namespace)` 决定: `$XDG_CONFIG_HOME/<namespace>/tokens.json`,或 `~/.config/<namespace>/tokens.json` 何时 `XDG_CONFIG_HOME` 未设定.

配置文件记录 `issuedAt` 财务报告和审定财务报表 `expiresAt` ; 没有配置文件 `issuedAt` 失败 `cache_corrupt`。 。 。 .

在 POSIX 系统中,缓存文件必须具有模式 `0600` 而其直接目录必须具有模式 `0700`。现有的不安全权限失败 `cache_permission`。缓存拒绝同源路径组件。 写作使用新的临时文件,同步,并在解剖上重新命名,所以在重命名之前,一个写作失败离开旧文件完好无损. Windows跳过POSIX模式检查并依赖于主机ACLs.

对不能共享证书的账户使用单独的命名空间或配置文件 . `logout()` 删除选中的配置文件并保留其他配置文件.

## 仅显示索赔

`displayClaims()` 财务报告和审定财务报表 `decodeDisplayOnlyClaims()` 解码 JWT 字段的小型许可列表,而不检查签名 。 仅对像 a 这样的标签使用结果 `whoami` 显示。 永远不要用它来授权,存储分区,审计身份,或者分析身份.

## 从产品本地认证迁移

将本地发现、设备投票、刷新和缓存功能替换为一个 `DeviceFlowClient`在应用程序中保留这些产品投入:

-   环境变量名称和默认值;
-   发行人、客户身份、范围、受众;
-   CLI 文本和浏览器启动行为;
-   API 基址和无记名接线;以及
-   缓存命名空间、路径和配置文件选择 .

## 常见问题

### @baukit/auth-node 是什么？

以 S256 PKCE 为节点的 OIDC 设备授权, 刷新旋转, 以及一个被锁定的符号缓存 \.

### 如何安装 @baukit/auth-node？

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

### @baukit/auth-node 支持 TypeScript 吗？

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

### @baukit/auth-node 支持 ESM 还是 CommonJS？

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

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

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

### @baukit/auth-node 可以商用吗？

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

### @baukit/auth-node 的下载量有多少？

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

### @baukit/auth-node 还在维护吗？

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