# @baukit/auth-native 中文文档

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

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

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

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

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

- 包体积（解压后）：207 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- peer 依赖：react ^19\.2\.3，@clerk/expo ^4\.8\.1，expo-web-browser ^57\.0\.3，expo-auth-session ^57\.0\.13，expo-secure-store ^57\.0\.4
- 首次发布：2026-08-25T18:45:52.991Z
- 最新版本发布：2026-11-07T02:36:06.224Z
- 近 30 天下载量：8431（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：67（近 12 个月 67 个）

## 中文简介

提供商中立本地的OIDC授权码客户端有S256 PKCE,安全存储和浏览器流量端口,并刷新旋转.

## 安装

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

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

## README

# `@baukit/auth-native`

提供商中立本地的OIDC授权码客户端与S256 PKCE,标准发现,安全存储和浏览器-流量端口,刷新自转,以及本地首个签出. 核心没有反应,路由器,或产品UI依赖.

```ts
import { createExpoOidcClient } from '@baukit/auth-native/expo';
import * as AuthSession from 'expo-auth-session';

const auth = createExpoOidcClient({
  issuer: 'https://identity.example.com/tenant',
  clientId: 'product-mobile',
  redirectUri: AuthSession.makeRedirectUri({ scheme: 'product', path: 'oauth' }),
  offlineAccess: true,
});

await auth.initialize();
const result = await auth.signIn();
if (result.status === 'cancelled') {
  // Restore focus or announce cancellation. This is not an authentication error.
}
```

发行人只能通过 `/.well-known/openid-configuration`; 提供者专用路径从未被制造. 在成功进行授权码交换后,再提出经认证的用户信息请求. 它没有空 `sub` 是存储在永久会话中的权威主题。 软件包不相信一个未经核实的,本地解码的ID-token的声称是身份.

`session()` 曝光主题,访问符,可选刷新和ID符,以及 `issuedAt` 财务报告和审定财务报表 `expiresAt` 以相差相差几毫秒计的时标。 当提供者省略时, 刷新回复保留先前的刷新符或ID符 。 当配置的刷新窗口内的会话没有刷新符号时, `accessToken()` 清除后返回 `undefined`; 呼叫者应再次报到.

`refreshOnRestore` 制造 `initialize()` 在解析前刷新已过期的存储会话 。 被拒绝的刷新结束会话, 而网络错误保留它 。 它默认为虚假 `createWorkOsNativeClient` 把它设定为真实的.

`refreshLeewaySeconds` 默认值为 30 秒; 刷新窗口是该值中较小的, 并且是符号寿命的一半, 按 `expiresAt - issuedAt`。 。 。 .

`offlineAccess` 故意默认 `false`; 设置为 `true` 仅在提供者被配置以发布刷新符号时 `offline_access`。 。 。 . `accessToken()` 共享一个刷新 并行的呼叫者。 过 `{ forceRefresh: true }` 在401后绕出主动失效窗口,同时仍然加入任何已经在飞行中的刷新.

终端刷新拒绝( E)`invalid_grant`, (中文(简体) ), `invalid_token`,或 HTTP 400/401 清除会话并决心 `undefined`。订阅 `subscribeSessionExpired()` 以停止排程并移动 UI 到签约状态。 网络、错误的响应、费率限制和提供者 5xx 故障保存存储会话并用消毒器拒绝 `OidcError` 谁 `retryable` 属性是 `true`。 。 。 .

`subscribeSessionExpired()` 报告 `refresh_rejected`, (中文(简体) ), `refresh_unavailable`,或 `profile_erased`在带有代码的后端 401 上 `profile_erased`电话 `clearSession({ reason: 'profile_erased' })`它澄清了当地会议的问题,并给出了每次通话的理由。 平面 `clearSession()` 释放什么。 OIDC 坚持在下方使用武力标记 `storageKeyPrefix`所以下一个 `signIn()` 请求 `prompt=login` 即使在重新装入之后 一个失败或被取消的登录会保存标记;一个成功的登录会删除它. 新的认证给予提供者新的 `auth_time` 重新登入配置文件.

`signOut()` 在提供者互动之前删除本地会话。 然后它尝试了发现的会场终点。 丢失、 取消或失败的供应商登录会持续显示一个故障安全旗, 所以下一次 `signIn()` 包含 `prompt=login`;只有在提供者登录或后来成功登录后才去除该旗帜. 腐败的安全存储状态,包括无 `issuedAt`,删除后按签出处理.

使用 `safeAuthErrorMessage(error)` 在UI边界。 错误只包含允许列表库代码/消息和可选的HTTP状态编号. 提供者机构,授权代码,令牌,以及适配器例外消息从不被复制成错误或日志.

默认的 Expo 切入点使用 `expo-auth-session`, (中文(简体) ), `expo-secure-store`,以及 `expo-web-browser`,这些是同伴的依赖关系。 用于确定性测试或其他原生堆栈,构造 `NativeOidcClient` 与你自己 `SecureStoragePort`, (中文(简体) ), `BrowserFlowPort`, (中文(简体) ), `fetch`和时钟.

会话和强制日志密钥使用点分隔符 。 默认前缀编码 发行人和客户端ID带有安全Store安全字符. 习惯 `storageKeyPrefix` 必须是非空的,只包含 ASCII 字母,数字, `.`, (中文(简体) ), `-` 财务报告和审定财务报表 `_`。 。 。 . 建筑在访问存储前拒绝无效的前缀 。 没有重写密钥 需要适配器。 旧密钥没有迁移 .

世博会产品可以通过 `storage` 端口为 `createExpoOidcEnvironment` 或者说 `createExpoOidcClient`。这支持网络 本地Storage适配器或产品自有兼容性/迁移包装器,同时 保留标准的 Expo 浏览器流 .

## 主题登录页面

登录主题可以匹配应用程序显示的主题 通过 OAuth `state`。将段落传递到 `signIn` 并赏赐博览会的流向 en源 :

```ts
import { appearanceStateDecoration } from '@baukit/auth-native';
import { createExpoOidcClient } from '@baukit/auth-native/expo';
import * as Crypto from 'expo-crypto';

const auth = createExpoOidcClient(config, {
  randomBytes: (size) => Crypto.getRandomBytesAsync(size),
});

await auth.signIn({ stateDecoration: appearanceStateDecoration({ mode: 'dark' }) });
```

国家变成 `ap1.d.<64 hex characters>`,或 `ap1.d.<PRIMARY>.<SECONDARY>.<nonce>` 当你通过两个 `#RRGGBB` 颜色. `decoratedAuthorizationState` 需要至少32个随机字节,只接受 ASCII 每个段的字母和数字. 非斯使国家令人厌恶,和 客户端仍然将返回状态与其发送状态进行比较.

装饰从不阻碍登录。 无 `randomBytes`,或当 en 源投出或片段结构不当, 流使用 Authsession 的自身状态 并登录页面显示其默认主题. `createExpoBrowserFlow` 一样 自动流动,用于生产 `NativeOidcEnvironment` 手边. 其它 `BrowserFlowPort` 执行可能忽略 `stateDecoration`。 。 。 .

状态在授权 URL 中行走, 因此提供者及其访问日志 见之. 把外观提示放在那里,从不使用数据. 来自全球之声的 Keycloak 主题 `baukit` CLI 的 OIDC 模板解码 `ap1` 格式.

## 边界

软件包拥有本地的 OIDC 流,会话存储并刷新. 没有屏幕,没有 导航,没有授权逻辑;登录用户可以做的是由产品和 由服务器执行 .

核心没有反应、路由器或产品UI依赖性,博览会入口是一个单独的入口 子路径。 构造 `NativeOidcClient` 与你自己 `SecureStoragePort`, (中文(简体) ), `BrowserFlowPort`, (中文(简体) ), `fetch`, (中文(简体) ), 和钟,当你在另一个本地堆栈 或想要一个决定性测试.

`@baukit/auth-web` 是浏览器的同一份合同.

## 提供者适配器

`@baukit/auth-native/clerk-expo` 创建一个 `ClerkNativeClient` 及其反应 `Provider` 一起来 安装可选选项 `@clerk/expo` 和反应对等器,应用 办事员博览会的配置插件,并将产品包装在返回的提供者中. 提供可出版的钥匙和 `SecureStoragePort`该桥使用办事员的 主机登录和符号缓存 . `@baukit/auth-native/clerk` 导出客户端 和SDK端口分别用于其他集成.

`@baukit/auth-native/workos` 出口 `createWorkOsNativeClient`供应 AuthKit 公共客户端ID和现有的博览会浏览器/存储环境. 它通过浏览器端口运行S256 PKCE并使用WorkOS的交换符 JSON公共客户API. 它在安全存储和清空中储存刷新符牌 在结束提供者会话之前。 应用程序中没有 API 密钥 . 供应商客户份额 `initialize`, (中文(简体) ), `session`, (中文(简体) ), `subscribe`, (中文(简体) ), `accessToken`, (中文(简体) ), `signIn`, (中文(简体) ), `signOut`, (中文(简体) ), `clearSession` 财务报告和审定财务报表 `subscribeSessionExpired` 与OIDC合作.

本地 WorkOS 用户 `NativeOidcClient` 并继承常住者 `prompt=login` 请求。 办事员发射 `profile_erased` 并清除本地会话,但是它的 SDK 桥梁不会坚持武力标记或强制重新认证. 办事员需要使用 JWT 模板 `auth_time` 重新登入和新供应商 在后端允许一个被删除的主题之前进行认证.

## 常见问题

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

提供商中立本地的OIDC授权码客户端有S256 PKCE,安全存储和浏览器流量端口,并刷新旋转\.

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

在项目目录运行 npm install @baukit/auth-native，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：expo-web-browser（^57\.0\.3）、expo-auth-session（^57\.0\.13）、expo-secure-store（^57\.0\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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

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

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