# @ai-matrx/auth 中文文档

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

版本：0\.4\.19
npm 元数据更新时间：2026-10-28T12:24:47.256Z
中文译文更新时间：2026-11-05T19:09:46.429Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ai-matrx/auth
原文对照：https://npmcn.com/package/%40ai-matrx/auth/?lang=original
项目主页：https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/auth#readme
源码仓库：https://github.com/AI-Matrix-Engine/aidream

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

- 包体积（解压后）：810 kB，91 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：react \>=18\.0\.0，@supabase/supabase-js \>=2\.0\.0
- 首次发布：2026-08-29T17:58:44.009Z
- 最新版本发布：2026-10-28T12:24:47.065Z
- 近 30 天下载量：42870（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

AI Matrx 每个应用程序的签名、会话和组织:每个平台(浏览器、Next.js、扩展、桌面、节点)的签名/退出、会话存储和刷新、当前人物、他们的组织和最喜爱的组织、一个活跃的组织(持有的复刻器)

## 安装

```sh
npm install @ai-matrx/auth
```

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

## README

# @ai- matrx/ auth (英语)

每个 AI Mattrx 应用程序的签名、会话和组织——最顶端的小软件包 app. 无框架核心; `/react` 财务报告和审定财务报表 `/next` 区域; 只为导入的区域付费.

```ts
import { createAuthClient, signInWithPassword, sessionCredentials, signOut } from "@ai-matrx/auth";
import { createActiveOrganization, readMemberships } from "@ai-matrx/auth/organizations";

const supabase = createAuthClient({ url: "https://db.matrxserver.com", key: PUBLISHABLE_KEY });
const { person } = await signInWithPassword(supabase, { email, password });
const active = createActiveOrganization({ client: supabase });
const orgId = await active.ensureOrgId();           // held until the ladder answers
const credentials = sessionCredentials(supabase);   // hand to @ai-matrx/api's createApi
```

| 节次 | 什麽 |
| --- | --- |
| `@ai-matrx/auth` | 注册/退出、会话、刷新、, `sessionCredentials`,每个平台存储, `createAuthClient` |
| `/organizations` | 成员、最爱、积极组织阶梯和 `createActiveOrganization` |
| `/credentials` | 5种证书类型和1种证书 – 头图 |
| `/session-identity` | 现场直播 |
| `/cookies` | 全域认证饼干和活跃的组织饼干 |
| `/next` | 每个 Next.js Supabase 客户端(浏览器, RSC, 路由, 中间软件) |
| `/browser` | 在共享的 aut cookie( 非下一个应用程序) 上设置无框架浏览器 Supabase 客户端 |
| `/react` | `useSession`, (中文(简体) ), `useActiveOrganization`, (中文(简体) ), `useSessionIdentity` |
| `/node` | `fileStorage` ——一个脚本会话在运行之间存活 |
| `/testing` | 测试的假会话 |

会话存储: 浏览器 `browserStorage()`,扩展名 `extensionStorage()`、 桌面 `keyValueStorage(store)`节点 `fileStorage(path)` 或者说 `memoryStorage()`下一个.js `/next`。 。 。 .

活动组织从来不是一个列表过滤器: 读取显示个人能看到的一切 活动组织只是保存新事物的地方,以及服务器调用在哪个组织.

## 在0.2.0中增加各节——各一个入门点

| 需求 | 导入 |
| --- | --- |
| 是谁打电话( 本地要求; 浏览器去dup) | `getClaimsUser`, (中文(简体) ), `createClaimsCache` 从 `@ai-matrx/auth` |
| 下一个应用程序中的服务器身份 | `createServerAuth({ createClient, supabaseUrl, cache })` 从 `@ai-matrx/auth/next` |
| API 路由调用器( Bearer 或 cookie) | `verifyRequest(request, { url, publishableKey, cookieClient })` 从 `@ai-matrx/auth/node` (或 `/next`(中文(简体) ) |
| 只有服务器的密钥客户端 | `createServiceClient({ url, secretKey })` 从 `@ai-matrx/auth/node` (或 `/next`(中文(简体) ) |
| "需要组织"拒绝 | `isOrganizationRequiredError`, (中文(简体) ), `organizationRequired`, (中文(简体) ), `organizationRequiredResponse` 从 `@ai-matrx/auth/organizations` |
| 用 AI Matrx 签名( 扩展、 桌面、 CLI) | `createMatrxOAuth(config, { storage, openAuthorization })` 从 `@ai-matrx/auth/matrx-oauth` |
| 这个人是管理者吗 `admin.admins` 行; 管理员+级别 / not admin / 未知) | `readAdminStatus(client, userId)` 从 `@ai-matrx/auth/admin` |
| 解码 JWT 段( base64url ~ 字节 / UTF-8 文本; 没有签名检查) | `base64UrlToBytes`, (中文(简体) ), `base64UrlToText` 从 `@ai-matrx/auth/jwt` (无依赖) |

## `@ai-matrx/auth/spa` - 拥有自己标志的Vite SPA

对于一个不是Next/cookie应用程序(admin仪表板,Workflow Studio)的主持人: 登录到来作为一个 一次性 `handoff` aidream OAuth hop的代码, 访问符住在 `localStorage`,则a 在同一顶端上签名的 sign-in amoatrx.com 会话通过会话桥刷新.

```ts
import { sendMatrxRequest } from "@ai-matrx/api";
import { createSpaSession, createSpaSupabase, adminWhoamiVerifier } from "@ai-matrx/auth/spa";

export const session = createSpaSession({
  request: sendMatrxRequest,
  onBeforeTokenChange: (prev, next) => transitionQueryIdentity(prev, next),
  onTokenChange: () => refreshOrganizationIdentity(),
  bridge: { verifyToken: adminWhoamiVerifier(AIDREAM_API_URL) }, // dashboard only: admin gate
});
export const supabase = createSpaSupabase({ url, publishableKey, session, headers: { "x-matrx-admin-lane": "1" } });
```

回调路由 : `classifyCallback(location.search)` - > (中文) `exchangeHandoff(api, handoff, sendMatrxRequest)` - > (中文) `session.setToken(token)`。通过同一请求 `reportTokenInQuery(api, params, where, sendMatrxRequest)`要求: `@ai-matrx/auth/spa` 不通过 global 进行网络呼叫 `fetch`。 。 。 . 选项 : `tokenKey` (默认) `matrx_admin_token`, (中文(简体) ), `storage`, (中文(简体) ), `loginPath` (单位:千美元)`/login`, (中文(简体) ), `navigate`, (中文(简体) ), `bridge.sessionTokenUrl`, (中文(简体) ), `bridge.sameSiteOnly` (对), `bridge.attemptLimit` (3个) `attemptWindowMs` (20000) (英语).

活跃的组织: `createSpaOrganizationContext({ legacyStorageKey, apexDomains, tokenKey, serverUrl, db, sendRequest, bindOrganizationHeader, onIdentityChanged })` 返回时 `withOrganizationHeader`, (中文(简体) ), `peekOrganizationId`, (中文(简体) ), `chooseOrganization`, (中文(简体) ), `listMemberOrganizations`饼干和其余的,通过 `sendMatrxRequest` 财务报告和审定财务报表 `applyOrganizationContextHeader` 从 `@ai-matrx/api`。 。 。 .

## 常见问题

### @ai-matrx/auth 是什么？

AI Matrx 每个应用程序的签名、会话和组织:每个平台\(浏览器、Next\.js、扩展、桌面、节点\)的签名/退出、会话存储和刷新、当前人物、他们的组织和最喜爱的组织、一个活跃的组织\(持有的复刻器\)

### 如何安装 @ai-matrx/auth？

在项目目录运行 npm install @ai-matrx/auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@supabase/supabase-js（\>=2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ai-matrx/auth 支持 TypeScript 吗？

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

### @ai-matrx/auth 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

### @ai-matrx/auth 可以商用吗？

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

### @ai-matrx/auth 的下载量有多少？

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

### @ai-matrx/auth 还在维护吗？

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