# @hanzo/iam 中文文档

规范地址：https://npmcn.com/package/%40hanzo/iam/

版本：0\.21\.42
npm 元数据更新时间：2026-11-08T06:26:16.703Z
中文译文更新时间：2026-11-17T08:23:19.692Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hanzo/iam
原文对照：https://npmcn.com/package/%40hanzo/iam/?lang=original
项目主页：https://docs.hanzo.ai/services/iam/sdk
源码仓库：https://github.com/hanzo-js/iam

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

- 包体积（解压后）：1.3 MB，77 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：4 个
- peer 依赖：react \>=17，react-dom \>=17
- 首次发布：2026-02-18T03:35:18.183Z
- 最新版本发布：2026-11-08T06:26:16.478Z
- 近 30 天下载量：14381（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：83（近 12 个月 83 个）

## 中文简介

汉佐 IAM 的 SDK 类型 – OIDC auth, JWT 验证, OAuth2 PKCE, 用户/org/ project API

## 安装

```sh
npm install @hanzo/iam
```

也可以使用：`pnpm add @hanzo/iam`、`yarn add @hanzo/iam`、`bun add @hanzo/iam`

## README

# @hanzo/iam (英语)

用于认证的单向类型SDK **汉佐 IAM** a 包括: 以标准为首的OIDC供应商服务于一个可配置来源的每个品牌:

| 品牌 | `serverUrl` |
| --- | --- |
| 汉三 | `https://hanzo.id` |
| 吕克思 | `https://lux.id` |
| 动物园 | `https://zoolabs.id` |
| 启动节点 | `https://id.bootno.de` |
| 参数 | `https://pars.id` |

品牌-原生地图导出为 `BRAND_SERVER_URLS` 编号 : `serverUrlForBrand(brand)` 从 `@hanzo/iam` (和 `@hanzo/iam/paths`)——一个 位置,代码.

一个OIDC路径设置. 每事取一一名相. 无倒相相相相相相相相相.

## 读取身份的唯一方法

```ts
const iam = { serverUrl: "https://hanzo.id", clientId: "my-app" };
const me = await getServerSession(req, iam); // Bearer/cookie + X-Org-Id; null → 401
// off HTTP: const r = await validateToken(token, iam, org); if (!r.ok) deny(r.reason);
me.sub;          // opaque id — never parse it
me.org;          // tenant: X-Org-Id if ∈ orgs, else orgs[0]; an app's owner
me.orgs;         // signed membership set, home first
me.role;         // coarse role in me.org — an ORG role
me.isSuperAdmin; // a person whose home org (orgs[0]) is `admin` — the only platform authority
me.app;          // machine principal (client_credentials)
```

IAM的(英语: `sub` 是用户的 UUID 和用户代号 `owner` 这是 **应用程序** 奥尔格,所以 `sub.split("/")[0]`, (中文(简体) ), `claims.owner` 财务报告和审定财务报表 `?? orgName` 所有用户都映射到一个 租户. `validateToken` 只有读者:

-   `iss` 以配置为主( q)`issuer`默认值 `serverUrl`; 多个列表 (品牌)——从来不是象征自己的 `iss`从来没有发现。 每个牌子都签了 同一键; `iss` 是什么告诉他们分开.
-   `aud` 总是执行: `clientId`,或 `audience` 许可列表 .
-   用户 + `orgs` 请求; 应用( a)`type: "application"`页:1 `owner`。无 `orgs` - 拒绝.
-   请求的`X-Org-Id`)必须是... `orgs` - 其它的吗 `iam_org_forbidden`。 。 。 .
-   SuperAdmin 一个人的家 Org, `orgs[0]`,为 `admin` —— 说 `superAdmin(claims)`, (中文(简体) ), 汉萨伊/奥斯 `Claims.Sudo` 没错 一个 `admin` 更下一组成员, `owner`, (中文(简体) ), `isAdmin` 财务报告和审定财务报表 `role === "admin"` 没有一个是平台权威.

失败原因 : `iam_token_missing`, (中文(简体) ), `iam_issuer_unset`, (中文(简体) ), `iam_audience_unset`, (中文(简体) ), `iam_discovery_failed`, (中文(简体) ), `iam_token_expired`, (中文(简体) ), `iam_issuer_invalid`, (中文(简体) ), `iam_audience_invalid`, (中文(简体) ), `iam_signature_invalid`, (中文(简体) ), `iam_subject_missing`, (中文(简体) ), `iam_org_missing`, (中文(简体) ), `iam_org_forbidden`。 。 。 .

`lint/` (单位:千美元)[ast- grep 图像](https://ast-grep.github.io/),与汉佐艾/西)相同的规则拒绝 绕道而来.. `ast-grep scan -c node_modules/@hanzo/iam/lint/sgconfig.yml`数字 : `sub.split`, (中文(简体) ), `?? orgName`, (中文(简体) ), `.owner` 证明结果, `jwtVerify` 无 `audience`一个发行人从信物, `X-Org-Id` 读于此包外.

## 单向模式

IAM是经过改造的 **改为** 每个框架;框架保持 **本地语言** 认证 路线。 下一个 Auth/ Auth.js 硬山 `/api/auth` (或 `/auth`\- 护照,Remix, Express,而Hono各自都有自己的路线惯例——这个SDK从不移动 它们进入 `/v1`SDK的唯一工作就是把每个框架交给一个 提供者/适应者 **原生形状** 授权/接听/用户信息点 在我们的峡谷 `/v1/iam/oauth/*`翻译在这里,代码,一次 (单位:千美元)`src/paths.ts`);每个适配器都会通过它解决端点而无处可去 硬码路径。 PKCE-S256一直使用;保密客户使用 `client_secret_basic`。 。 。 .

## 条条路

每个终点都通过一个单一的真相来源解决—— `OIDC_PATHS` (单位:千美元)`@hanzo/iam/paths`) (中文(简体) ). 这些是 **仅限** 路径; 没有遗留 `/oauth/*` 没有 `/api/login/*`。 。 。 .

| 终点 | 路径 |
| --- | --- |
| 发现 | `/.well-known/openid-configuration` |
| 授权 | `/v1/iam/oauth/authorize` |
| 符号 | `/v1/iam/oauth/token` |
| 用户信息 | `/v1/iam/oauth/userinfo` |
| 竖起 | `/v1/iam/.well-known/jwks` |
| 登录 | `/v1/iam/oauth/logout` |

> **抓到他们了** IAM服务于 `200 text/html` 任何未注册路径的SPA. 一个错误的路径返回 HTML,而不是一个 404 ——无声断裂. 这个SDK接头 准确的路径,永远不要让发现 解决错误的路径: OAuth 适配器完全跳过发现(显式终点), JWT 核查 **降入峡谷 `jwks` 路径** 当发现时 失败或返回 HTML 夹- 全部 —— 这样一个发现 blip 永远无法使用 关闭符号验证.

PKCE(S256)始终在运行. 使用保密客户 `client_secret_basic`。 。 。 . 范围是: `["openid", "profile", "email"]`。 。 。 .

## 安装

```bash
pnpm add @hanzo/iam
```

## 每个集成区使用一克南克

### 服务器(Next.js App路由器/节点/Hono/Remix) - `@hanzo/iam/server`

PaaS级应用软件需要的作品: 解决呼叫者的身份 无记名标志或会话饼干 与IAM的JWKS核对.

```ts
import { getServerSession, withSession } from "@hanzo/iam/server";

const iam = { serverUrl: "https://hanzo.id", clientId: process.env.IAM_CLIENT_ID! };

// Option A — read the session yourself
export async function GET(req: Request) {
  const session = await getServerSession(req, iam);
  if (!session) return new Response("unauthorized", { status: 401 });
  return Response.json({ user: session.sub, org: session.org, email: session.email });
}

// Option B — guard the handler (401 before your code runs)
export const POST = withSession(iam, (req, session) =>
  Response.json({ org: session.org }),
);
```

`getServerSession(req, config, options?)` 返回 a `Principal` 或者说 `null`。 读取 `Authorization: Bearer …` 首先,然后是 `hanzo_iam_access_token` 饼干 (与 `options.cookieName`))和行为 `X-Org-Id` org,必须 成为.. `orgs` (次数) `null`) (中文(简体) ).

### JWT 验证 - `@hanzo/iam` (或 `@hanzo/iam/auth`(中文(简体) )

```ts
import { validateToken } from "@hanzo/iam";

const result = await validateToken(accessToken, {
  serverUrl: "https://hanzo.id",
  clientId: "my-app",
}, org); // optional; must be ∈ orgs

if (result.ok) {
  // result.sub, result.org, result.orgs, result.isSuperAdmin, result.app
}
```

见 [读取身份的唯一方法](https://npmcn.com/package/%40hanzo/iam/#readme-the-one-way-to-read-identity)。 。 。 .

JWKS URI来自OIDC的发现,当可达到和 **降解为 犬类 `/v1/iam/.well-known/jwks` 路径** 否则(发现5xx, 暂停,或 `200 text/html` SPA call- all). 符号签名是 总是对照取来JWKS进行校验——倒计时不是绕行.

### 更好一点.. `@hanzo/iam/betterauth`

```ts
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { iamProvider } from "@hanzo/iam/betterauth";

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [
        iamProvider({
          serverUrl: process.env.IAM_ENDPOINT!,
          clientId: process.env.IAM_CLIENT_ID!,
          clientSecret: process.env.IAM_CLIENT_SECRET!,
        }),
      ],
    }),
  ],
});
```

`iamProvider` 返回真实 `genericOAuth` 配置条目 (单位:千美元)`providerId: "hanzo"`,绑定授权/托肯/用户信息 URL, `pkce: true`, (中文(简体) ), `authentication: "basic"`) (中文(简体) ). 没有 `discoveryUrl`。 。 。 .

### 下一个 Auth.js / Auth.js - `@hanzo/iam/nextauth`

```ts
import NextAuth from "next-auth";
import { HanzoIamProvider } from "@hanzo/iam/nextauth";

export default NextAuth({
  providers: [
    HanzoIamProvider({
      serverUrl: process.env.IAM_SERVER_URL!,
      clientId: process.env.IAM_CLIENT_ID!,
      clientSecret: process.env.IAM_CLIENT_SECRET,
    }),
  ],
});
```

提供者 id 默认为 `"hanzo-iam"`。终点是 **明确** —— 说 `authorization`编号 :`token`编号 :`userinfo`编号 :`jwks_endpoint` 直接从 `OIDC_PATHS`; 存在 **没有 `wellKnown`/发现来回旅行** (发现) 获取失败或解答错误会击出 IAM HTML SPA 全部 —— 寂灭相断相. `issuer` + 键 `jwks_endpoint` 提供如此开放的客户端 仍然验证 id token 不被发现. `checks` 默认为 `["state", "pkce"]`; 符号认证为 `client_secret_basic`。 。 。 . `IamProvider` 是一个 稳定同函数的别名;导出配置文件类型为 `HanzoIamProfile`。 。 。 .

### SvelteKit / Auth.js 核心 —— `@hanzo/iam/sveltekit`

`@auth/core` (SvelteKit、SolidStart, ) (SvelteKit、SolidStart, `@auth/express`,)消耗同样 作为 NextAuth 的提供者形状,所以 SvelteKit 适配器是在 under a Auth.js-idiomatic name——一个构建器,相同的显式终点.

```ts
import { SvelteKitAuth } from "@auth/sveltekit";
import { HanzoIam } from "@hanzo/iam/sveltekit";
import { env } from "$env/dynamic/private";

export const { handle, signIn, signOut } = SvelteKitAuth({
  providers: [
    HanzoIam({
      serverUrl: env.IAM_SERVER_URL,
      clientId: env.IAM_CLIENT_ID,
      clientSecret: env.IAM_CLIENT_SECRET,
    }),
  ],
});
```

### 调和 - `@hanzo/iam/remix`

登录通过 `remix-auth` + 键 `remix-auth-oauth2` (你设计战略,所以) 它的版本会保留你的版本);通过框架不可知核查器进行守卫.

```ts
// app/auth.server.ts — login strategy
import { Authenticator } from "remix-auth";
import { OAuth2Strategy } from "remix-auth-oauth2";
import { hanzoIamStrategyOptions } from "@hanzo/iam/remix";

export const authenticator = new Authenticator(sessionStorage);
authenticator.use(
  new OAuth2Strategy(
    hanzoIamStrategyOptions({
      serverUrl: process.env.IAM_SERVER_URL!,
      clientId: process.env.IAM_CLIENT_ID!,
      clientSecret: process.env.IAM_CLIENT_SECRET!,
      redirectURI: "https://app.hanzo.ai/auth/hanzo-iam/callback",
    }),
    async ({ tokens }) => tokens,
  ),
  "hanzo-iam",
);
```

```ts
// guarded loader/action
import { requireSession } from "@hanzo/iam/remix";

const iam = { serverUrl: "https://hanzo.id", clientId: process.env.IAM_CLIENT_ID! };

export async function loader({ request }: { request: Request }) {
  const session = await requireSession(request, iam); // throws 401 Response if absent
  return Response.json({ org: session.org });
}
```

### Express / 连接 - `@hanzo/iam/express`

```ts
import express from "express";
import { requireAuth, getIamSession } from "@hanzo/iam/express";

const iam = { serverUrl: "https://hanzo.id", clientId: process.env.IAM_CLIENT_ID! };
const app = express();

app.get("/me", requireAuth(iam), (req, res) => {
  const session = getIamSession(req); // typed, present after requireAuth
  res.json({ user: session.sub, org: session.org });
});
```

`requireAuth(config)` 401次无符号请求并附上已核实 页 次 `req.iamSession`。用于可选自动线路 `getSession(req, config)` (回报) `null` (在缺席时).

### 浩诺.. `@hanzo/iam/hono`

```ts
import { Hono } from "hono";
import { requireAuth, getIamSession } from "@hanzo/iam/hono";

const iam = { serverUrl: "https://hanzo.id", clientId: process.env.IAM_CLIENT_ID! };
const app = new Hono();

app.use("/api/*", requireAuth(iam));
app.get("/api/me", (c) => {
  const session = getIamSession(c);
  return c.json({ user: session.sub, org: session.org });
});
```

### 反应(SPA) - `@hanzo/iam/react`

`<Login>` 是 DEFAULT 登录 UI — 一个组件, 安装在您的 应用。 每个方法都保留 IN-PLACE(应用程序窗口从不导航到 主机登录页面:通过弹出+进行社交 `postMessage`,钱包通过内部 SIWx, 电子邮件/密码字/OTP通过PKCE绑定的代码.

```tsx
import { IamProvider, useIam, Login, completePopupSignin } from "@hanzo/iam/react";

function App() {
  return (
    <IamProvider config={{
      serverUrl: "https://hanzo.id",
      clientId: "my-app",
      redirectUri: `${window.location.origin}/auth/callback`,
    }}>
      <Main />
    </IamProvider>
  );
}

function Main() {
  const { user, isAuthenticated } = useIam();
  if (!isAuthenticated)
    return (
      <Login
        serverUrl="https://hanzo.id"
        clientId="my-app"
        redirectUri={`${location.origin}/auth/callback`}
        state=""
        providers={["google", "github", "wallet"]}
        onSuccess={(token) => { /* signed in, in-place */ }}
      />
    );
  return <div>Welcome, {user?.displayName}</div>;
}
```

挂起弹出回调桥 `redirect_uri` 路线——一行. 这个 将代码递回打开器,用于弹出签名和无操作(返回) `false`为了正常的导航,所以你通常 `handleCallback()` 运行 :

```tsx
// pages/auth/callback
import { completePopupSignin, handleCallback } from "@hanzo/iam/browser";

if (!completePopupSignin()) {
  await handleCallback(); // normal top-level redirect callback
}
```

`useIam().login()` (全页) `signinRedirect`) 仅作为明示 独立倒计时——偏好 `<Login>` 或者说 `loginPopup` 因此,登录保留 在现场.

### 浏览器(无框架 PKCE) - `@hanzo/iam` (或 `@hanzo/iam/browser`(中文(简体) )

```ts
import { IAM, completePopupSignin } from "@hanzo/iam";

const iam = new IAM({
  serverUrl: "https://hanzo.id",
  clientId: "my-spa",
  redirectUri: "https://myapp.com/auth/callback",
});

// In-place social (Google/GitHub can't be iframed → popup + postMessage):
const token = await iam.signinPopup({ additionalParams: { provider: "google" } });
// In-place wallet (SIWx / EIP-4361, no redirect, no loop):
const walletToken = await iam.loginWithWallet();
// Standalone fallback only — full-page redirect to the hosted page:
await iam.signinRedirect();
const t = await iam.handleCallback();      // on the callback route
await iam.logout();
```

`signinPopup` 校验回电信息 `origin`, (中文(简体) ), `source` 标签,以及 `state` 在它接触密码之前; `completePopupSignin` (挂在 `redirect_uri` 路径) `targetOrigin` 被绑在自己的地盘上, 永远 `"*"`。光码没有开口的 PKCE 验证器是没用的 永远不要离开打开器.

#### 登录的IAM持有,在应用程序自己的页面上完成

一个第一党的站点 自己签入并张贴IAM的证书 自己来源的登录端点( n)`proxyBaseUrl`)),而IAM则在此举行届会 挑战饼干 当IAM持有的登录, 证书电话扔 所欠的, 页面完成它:

```ts
import { EmailRequired, IAM, Refused, SecondFactor } from "@hanzo/iam";

try {
  location.assign(await iam.loginWithPassword(email, password));
} catch (err) {
  if (err instanceof SecondFactor) err.factors; // [{ type: "app" | "email" | "sms", sent, remember }]
  if (err instanceof EmailRequired) err.email; // where IAM sent a code, "" for none
  if (err instanceof Refused) err.code; // "login_required", "email_code_sent", or ""
}
await iam.verifyFactor(held, { type: "app", passcode }); // or { recovery }
await iam.confirmEmail(held, code); // or changeEmail(held, address), then confirmEmail
await iam.resetPassword(email, code, password); // code from sendLoginCode(email)
await iam.acceptInvite(owner, inviteCode, emailCode); // with the signed-in access token
```

`resume()` 当登录的 IAM 持有此浏览器时, 询问什么 待定:一个没有证书的职位被读作答案,并将花费 第二个因素的挑战.

一个通过 Google 或 GitHub 的登录,其账户有第二个因素 返回 改为 `/login/mfa` 提供商返回的宿主 面对IAM的挑战 那边只有主机饼干 那页回答,然后走到IAM说的地方:

```ts
location.assign(await iam.finishFederation({ type: "app", passcode })); // or { recovery }
```

#### 另一个应用程序的登录, 完成在这个页面

另一个应用打开网站自己的登录页面,并附带标准授权查询: 本地应用程序( 桌面窗口、 CLI 、 电话) 或另一个来源的站点保存 及其PKCE核查员和保密服务器不得发出质疑并赎回 它的秘诀。 页面读取请求 `asked` (数量) `nonce` (列入)和 把它交给 `ask`页面上的每一个登录,然后将应用程序的代码和 返回回调,IAM对照客户端注册的回调进行核对。 这个 在应用程序的应用程序和组织中注册,如 `/v1/iam/auth/application` 以及地址查询、方法和 发送的代码是应用软件的太, 所以在应用签名的人 用于:

```ts
import { asked } from "@hanzo/iam";

iam.ask(asked(new URLSearchParams(location.search))); // null: the page's own
location.assign(await iam.loginWithPassword(email, password)); // hanzo://oauth/hanzo?code=…&state=…
```

滴入登录 + 登入视图也运行于 `@hanzo/iam/views` (单位:千美元)`Login`, (中文(简体) ), `SocialButton`, (中文(简体) ), `WalletButton`, (中文(简体) ), `EmailPasswordForm`, (中文(简体) ), `OTPStep`, (中文(简体) ), `OnboardingFlow`,以及5个登机阶原始人).

### 护照.js - `@hanzo/iam/passport`

```ts
import passport from "passport";
import { createIamPassportStrategy } from "@hanzo/iam/passport";

passport.use("iam", createIamPassportStrategy({
  serverUrl: "https://hanzo.id",
  clientId: "my-app",
  clientSecret: process.env.IAM_CLIENT_SECRET!,
  callbackUrl: "https://app.hanzo.ai/v1/sso/oidc/callback",
}));
```

### 鉴定 - `@hanzo/iam/validation`

```ts
import { isValidPhone, isValidEmail } from "@hanzo/iam/validation";

isValidPhone("6178888888", "+1"); // true — E.164 +16178888888
isValidEmail("user@example.com"); // true
```

## 子路径图

| 导入 | 表面 |
| --- | --- |
| `@hanzo/iam` | `IamClient`, (中文(简体) ), `IamApiError`, (中文(简体) ), `validateToken`, (中文(简体) ), `clearJwksCache`, (中文(简体) ), `IAM`, (中文(简体) ), `toIAMToken`, (中文(简体) ), `completePopupSignin`, (中文(简体) ), `POPUP_WINDOW_NAME`, (中文(简体) ), `generatePKCEChallenge`, (中文(简体) ), `generateState`, (中文(简体) ), `configureIam`, (中文(简体) ), `startLogin`, (中文(简体) ), `getLoginUrl`, (中文(简体) ), `handleCallback`, (中文(简体) ), `getSession`, (中文(简体) ), `getUser`, (中文(简体) ), `logout`, (中文(简体) ), `OIDC_PATHS`, (中文(简体) ), `IAM_PATHS`, (中文(简体) ), `BRAND_SERVER_URLS`, (中文(简体) ), `iamUrl`, (中文(简体) ), `serverUrlForBrand`,所有类型 |
| `@hanzo/iam/paths` | `OIDC_PATHS`, (中文(简体) ), `IAM_PATHS`, (中文(简体) ), `BRAND_SERVER_URLS`, (中文(简体) ), `iamUrl`, (中文(简体) ), `trimServerUrl`, (中文(简体) ), `serverUrlForBrand` |
| `@hanzo/iam/session` | `configureIam`, (中文(简体) ), `startLogin`, (中文(简体) ), `getLoginUrl`, (中文(简体) ), `handleCallback`, (中文(简体) ), `getSession`, (中文(简体) ), `getUser`, (中文(简体) ), `logout`, (中文(简体) ), `getIam` |
| `@hanzo/iam/server` | `getServerSession`, (中文(简体) ), `withSession`, (中文(简体) ), `getBearerToken`, (中文(简体) ), `SESSION_COOKIE`, (中文(简体) ), `ServerSession` |
| `@hanzo/iam/auth` | `validateToken`, (中文(简体) ), `clearJwksCache` |
| `@hanzo/iam/browser` | `IAM` (单位:千美元)`signinPopup`, (中文(简体) ), `loginWithWallet`, (中文(简体) ), `signinRedirect`, (中文(简体) ), `handleCallback`, (中文(简体) ), `completePopupSignin`, (中文(简体) ), `POPUP_WINDOW_NAME`, (中文(简体) ), `toIAMToken`, (中文(简体) ), `IAMConfig`, (中文(简体) ), `IAMUser`, (中文(简体) ), `IAMToken`, (中文(简体) ), `Eip1193Provider` |
| `@hanzo/iam/react` | `IamProvider`, (中文(简体) ), `useIam`, (中文(简体) ), `useOrganizations`, (中文(简体) ), `useIamToken`, (中文(简体) ), `OrgProjectSwitcher`, (中文(简体) ), `Login`, (中文(简体) ), `SocialButton`, (中文(简体) ), `WalletButton`, (中文(简体) ), `EmailPasswordForm`, (中文(简体) ), `OTPStep`, (中文(简体) ), `OnboardingFlow`, (中文(简体) ), `useAuthMethods`, (中文(简体) ), `completePopupSignin` |
| `@hanzo/iam/views` | `Login`, (中文(简体) ), `SocialButton`, (中文(简体) ), `WalletButton`, (中文(简体) ), `EmailPasswordForm`, (中文(简体) ), `OTPStep`, (中文(简体) ), `OnboardingFlow`, (中文(简体) ), `IdentityStep`, (中文(简体) ), `DocumentsStep`, (中文(简体) ), `BiometricStep`, (中文(简体) ), `ScreenStep`, (中文(简体) ), `SubmitStep`, (中文(简体) ), `useAuthMethods` |
| `@hanzo/iam/betterauth` | `iamProvider` |
| `@hanzo/iam/nextauth` | `HanzoIamProvider`, (中文(简体) ), `IamProvider` (别名), `HanzoIamProfile` |
| `@hanzo/iam/sveltekit` | `HanzoIam`, (中文(简体) ), `HanzoIamProvider`, (中文(简体) ), `IamProvider` |
| `@hanzo/iam/remix` | `hanzoIamStrategyOptions`, (中文(简体) ), `requireSession`, (中文(简体) ), `getSession` |
| `@hanzo/iam/express` | `requireAuth`, (中文(简体) ), `getSession`, (中文(简体) ), `getIamSession` |
| `@hanzo/iam/hono` | `requireAuth`, (中文(简体) ), `getSession`, (中文(简体) ), `getIamSession` |
| `@hanzo/iam/passport` | `createIamPassportStrategy` |
| `@hanzo/iam/types` | 所有类型 |
| `@hanzo/iam/validation` | `isValidPhone`, (中文(简体) ), `isValidEmail` |

裸体 `@hanzo/iam` 解决浏览器在浏览器捆绑器下构建 和节点下通过软件包构建的节点 `exports` 条件.

## 配置

| 选项 | 需求 | 说明 |
| --- | --- | --- |
| `serverUrl` | 对 | IAM起源(例如:. `https://hanzo.id`(中文(简体) ) |
| `clientId` | 对 | OAuth2 客户端标识 |
| `clientSecret` | 没有 | 保密客户的秘密 |
| `orgName` | 没有 | 键 `IamClient` API 呼叫——从未读过 `validateToken` |
| `appName` | 没有 | 应用程序名称 |
| `issuer` | 没有 | 获得接受 `iss` (字符串或品牌列表);默认 `serverUrl` |
| `audience` | 没有 | 获得接受 `aud` 允许列表; 默认 `clientId`; 总是执行 |
| `jwksUri` | 没有 | JWKS 端点, 跳过发现( 集群); 设置 `issuer` 还有 |

## 许可证

麻省理工学院 - [大赦国际](https://hanzo.ai/)

## 常见问题

### @hanzo/iam 是什么？

汉佐 IAM 的 SDK 类型 – OIDC auth, JWT 验证, OAuth2 PKCE, 用户/org/ project API

### 如何安装 @hanzo/iam？

在项目目录运行 npm install @hanzo/iam，或使用 pnpm add / yarn add / bun add。

### @hanzo/iam 支持 TypeScript 吗？

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

### @hanzo/iam 支持 ESM 还是 CommonJS？

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

### @hanzo/iam 需要什么版本的 Node\.js？

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

### @hanzo/iam 可以商用吗？

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

### @hanzo/iam 的下载量有多少？

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

### @hanzo/iam 还在维护吗？

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

