@hanzo/iam

中文文档
0.21.42发布于 2026/11/08MITTypeScriptESM + CJS近 30 天下载 1.4万

TypeScript SDK for Hanzo IAM — OIDC auth, JWT validation, OAuth2 PKCE, user/org/project APIs

原始使用文档
文档目录20 节
  1. The one way to read identity
  2. The one-way model
  3. The canonical paths
  4. Install
  5. One canonical usage per integration
  6. Server (Next.js App Router / Node / Hono / Remix) — @hanzo/…
  7. JWT validation — @hanzo/iam (or @hanzo/iam/auth )
  8. better-auth — @hanzo/iam/betterauth
  9. NextAuth.js / Auth.js — @hanzo/iam/nextauth
  10. SvelteKit / Auth.js core — @hanzo/iam/sveltekit
  11. Remix — @hanzo/iam/remix
  12. Express / Connect — @hanzo/iam/express
  13. Hono — @hanzo/iam/hono
  14. React (SPA) — @hanzo/iam/react
  15. Browser (framework-free PKCE) — @hanzo/iam (or @hanzo/iam/b…
  16. Passport.js — @hanzo/iam/passport
  17. Validation — @hanzo/iam/validation
  18. Subpath map
  19. Configuration
  20. License

@hanzo/iam

The one-way TypeScript SDK for authenticating against Hanzo IAM — a a standards-first OIDC provider served per-brand from a configurable origin:

BrandserverUrl
Hanzohttps://hanzo.id
Luxhttps://lux.id
Zoohttps://zoolabs.id
Bootnodehttps://id.bootno.de
Parshttps://pars.id

The brand→origin map is exported as BRAND_SERVER_URLS / serverUrlForBrand(brand) from @hanzo/iam (and @hanzo/iam/paths) — one place, in code.

One OIDC path set. One name per thing. No backwards-compatibility shims.

The one way to read identity

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's sub is a user's UUID and a user token's owner is the app's org, so sub.split("/")[0], claims.owner and ?? orgName all map every user to one tenant. validateToken is the only reader:

  • iss is pinned by config (issuer, default serverUrl; a list for several brands) — never the token's own iss, never discovery's. Every brand is signed by the same keys; iss is what tells them apart.
  • aud is always enforced: clientId, or the audience allowlist.
  • User → orgs claim; app (type: "application") → owner. No orgs → reject.
  • A requested org (X-Org-Id) must be ∈ orgs → else iam_org_forbidden.
  • SuperAdmin ⟺ a person whose home org, orgs[0], is admin — superAdmin(claims), hanzoai/authz Claims.Sudo exactly. An admin membership further down the set, owner, isAdmin and role === "admin" are none of them platform authority.

Failure reasons: 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, same rules as hanzoai/ci) rejects the ways around it — ast-grep scan -c node_modules/@hanzo/iam/lint/sgconfig.yml: sub.split, ?? orgName, .owner off a verify result, jwtVerify without audience, an issuer taken from the token, X-Org-Id read outside this package.

The one-way model

IAM is adapted to each framework; frameworks keep their native auth routes. NextAuth/Auth.js hard-mount /api/auth (or /auth); Passport, Remix, Express, and Hono each have their own route conventions — this SDK never moves them onto /v1. The SDK's only job is to hand each framework a provider/adapter in its native shape whose authorize/token/userinfo point at our canonical /v1/iam/oauth/*. That translation lives here, in code, once (src/paths.ts); every adapter resolves endpoints through it and nowhere hard-codes a path. PKCE-S256 is always on; confidential clients use client_secret_basic.

The canonical paths

Every endpoint resolves through a single source of truth — OIDC_PATHS (@hanzo/iam/paths). These are the only paths; there is no legacy /oauth/* and no /api/login/*.

EndpointPath
discovery/.well-known/openid-configuration
authorize/v1/iam/oauth/authorize
token/v1/iam/oauth/token
userinfo/v1/iam/oauth/userinfo
jwks/v1/iam/.well-known/jwks
logout/v1/iam/oauth/logout

Gotcha IAM serves a 200 text/html SPA for any unregistered path. A wrong path returns HTML, not a 404 — silent breakage. This SDK pins the exact paths and never lets discovery resolve to a wrong one: the OAuth adapters skip discovery entirely (explicit endpoints), and JWT verification degrades to the canonical jwks path when discovery fails or returns the HTML catch-all — so a discovery blip can never take down token validation.

PKCE (S256) is always on. Confidential clients use client_secret_basic. Scopes are ["openid", "profile", "email"].

Install

pnpm add @hanzo/iam

One canonical usage per integration

Server (Next.js App Router / Node / Hono / Remix) — @hanzo/iam/server

The piece PaaS-class apps need: resolve the caller's identity from the bearer token or session cookie, verified against IAM's JWKS.

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?) returns a Principal or null. It reads Authorization: Bearer … first, then the hanzo_iam_access_token cookie (override with options.cookieName), and acts in the X-Org-Id org, which must be ∈ orgs (else null).

JWT validation — @hanzo/iam (or @hanzo/iam/auth)

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
}

See the one way to read identity.

The JWKS URI comes from OIDC discovery when reachable and degrades to the canonical /v1/iam/.well-known/jwks path otherwise (discovery 5xx, timeout, or the 200 text/html SPA catch-all). The token signature is always verified against the fetched JWKS — the fallback is not a bypass.

better-auth — @hanzo/iam/betterauth

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 returns a real genericOAuth config entry (providerId: "hanzo", pinned authorize/token/userinfo URLs, pkce: true, authentication: "basic"). No discoveryUrl.

NextAuth.js / Auth.js — @hanzo/iam/nextauth

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,
    }),
  ],
});

The provider id defaults to "hanzo-iam". Endpoints are explicit — authorization/token/userinfo/jwks_endpoint come straight from OIDC_PATHS; there is no wellKnown/discovery round-trip (a discovery fetch that fails or resolves wrong would hit the IAM HTML SPA catch-all — silent breakage). issuer + jwks_endpoint are supplied so openid-client still verifies the id_token without discovery. checks default to ["state", "pkce"]; token auth is client_secret_basic. IamProvider is a stable alias for the same function; the exported profile type is HanzoIamProfile.

SvelteKit / Auth.js core — @hanzo/iam/sveltekit

@auth/core (SvelteKit, SolidStart, @auth/express, …) consumes the same provider shape as NextAuth, so the SvelteKit adapter is that provider under an Auth.js-idiomatic name — one builder, the same explicit endpoints.

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,
    }),
  ],
});

Remix — @hanzo/iam/remix

Login via remix-auth + remix-auth-oauth2 (you construct the strategy, so its version stays yours); guards via the framework-agnostic verifier.

// 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",
);
// 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 / Connect — @hanzo/iam/express

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) 401s tokenless requests and attaches the verified session to req.iamSession. For optional-auth routes use getSession(req, config) (returns null when absent).

Hono — @hanzo/iam/hono

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 });
});

React (SPA) — @hanzo/iam/react

<Login> is the DEFAULT login UI — one component, mounted embedded in your app. Every method stays IN-PLACE (the app window never navigates to the hosted login page): social via popup + postMessage, wallet via inline SIWx, email/password/OTP via a PKCE-bound code.

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>;
}

Mount the popup callback bridge on your redirect_uri route — one line. It hands the code back to the opener for popup sign-ins, and no-ops (returns false) for a normal navigation so your usual handleCallback() runs:

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

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

useIam().login() (full-page signinRedirect) remains only as an explicit standalone fallback — prefer <Login> or loginPopup so login stays in-place.

Browser (framework-free PKCE) — @hanzo/iam (or @hanzo/iam/browser)

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 verifies the callback message's origin, source tag, and state before it will touch the code; completePopupSignin (mounted on the redirect_uri route) posts back with targetOrigin pinned to its own origin, never "*". A bare code is useless without the opener's PKCE verifier, which never leaves the opener.

A sign-in IAM holds, finished on the app's own page

A first-party site draws its own sign-in and posts the credential to IAM's login endpoint on its own origin (proxyBaseUrl), where IAM keeps its session and challenge cookies. When IAM holds the sign-in, the credential call throws what is owed, and the page finishes it there:

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() asks nothing while a sign-in IAM holds for this browser may still be pending: a post with no credential is read as the answer to it, and would spend a second factor's challenge.

A sign-in through Google or GitHub whose account has a second factor comes back to /login/mfa on the host the provider returned to, with IAM's challenge in a host-only cookie there. That page answers it and goes where IAM says:

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

Another app's sign-in, finished on this page

Another app opens the site's own sign-in page with a standard authorize query: a native app (a desktop window, a CLI, a phone) or a site on another origin keeps its PKCE verifier, and a confidential server may send no challenge and redeem with its secret. The page reads the request with asked (its nonce included) and hands it to ask; every sign-in on the page then mints the code for that app and returns its callback, which IAM checks against the client's registered ones. The sign-in is made in that app's application and organization, as /v1/iam/auth/application states them, and the address lookup, the methods and the code sent are that app's too, so a person is found where the app signs people in:

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=…

Drop-in login + onboarding views also live at @hanzo/iam/views (Login, SocialButton, WalletButton, EmailPasswordForm, OTPStep, OnboardingFlow, and the five onboarding step primitives).

Passport.js — @hanzo/iam/passport

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",
}));

Validation — @hanzo/iam/validation

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

isValidPhone("6178888888", "+1"); // true — E.164 +16178888888
isValidEmail("[email protected]"); // true

Subpath map

ImportSurface
@hanzo/iamIamClient, 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, all types
@hanzo/iam/pathsOIDC_PATHS, IAM_PATHS, BRAND_SERVER_URLS, iamUrl, trimServerUrl, serverUrlForBrand
@hanzo/iam/sessionconfigureIam, startLogin, getLoginUrl, handleCallback, getSession, getUser, logout, getIam
@hanzo/iam/servergetServerSession, withSession, getBearerToken, SESSION_COOKIE, ServerSession
@hanzo/iam/authvalidateToken, clearJwksCache
@hanzo/iam/browserIAM (signinPopup, loginWithWallet, signinRedirect, handleCallback), completePopupSignin, POPUP_WINDOW_NAME, toIAMToken, IAMConfig, IAMUser, IAMToken, Eip1193Provider
@hanzo/iam/reactIamProvider, useIam, useOrganizations, useIamToken, OrgProjectSwitcher, Login, SocialButton, WalletButton, EmailPasswordForm, OTPStep, OnboardingFlow, useAuthMethods, completePopupSignin
@hanzo/iam/viewsLogin, SocialButton, WalletButton, EmailPasswordForm, OTPStep, OnboardingFlow, IdentityStep, DocumentsStep, BiometricStep, ScreenStep, SubmitStep, useAuthMethods
@hanzo/iam/betterauthiamProvider
@hanzo/iam/nextauthHanzoIamProvider, IamProvider (alias), HanzoIamProfile
@hanzo/iam/sveltekitHanzoIam, HanzoIamProvider, IamProvider
@hanzo/iam/remixhanzoIamStrategyOptions, requireSession, getSession
@hanzo/iam/expressrequireAuth, getSession, getIamSession
@hanzo/iam/honorequireAuth, getSession, getIamSession
@hanzo/iam/passportcreateIamPassportStrategy
@hanzo/iam/typesall types
@hanzo/iam/validationisValidPhone, isValidEmail

Bare @hanzo/iam resolves to the browser build under a browser bundler and the Node build under Node, via package exports conditions.

Configuration

OptionRequiredDescription
serverUrlYesIAM origin (e.g. https://hanzo.id)
clientIdYesOAuth2 client ID
clientSecretNoSecret for confidential clients
orgNameNoOrg for IamClient API calls — never read by validateToken
appNameNoApplication name
issuerNoAccepted iss (string or brand list); default serverUrl
audienceNoAccepted aud allowlist; default clientId; always enforced
jwksUriNoJWKS endpoint, skipping discovery (in-cluster); set issuer too

License

MIT — Hanzo AI

版本与发布记录

@hanzo/iam 共发布 83 个版本,首次发布于 2026/02/18;过去 12 个月发布了 83 个版本。

版本发布日期距今
0.21.42latest2026/11/089 天前
0.21.412026/10/3117 天前
0.21.402026/10/3117 天前
0.21.392026/10/3017 天前
0.21.382026/10/3017 天前
0.21.372026/10/2721 天前

关于 @hanzo/iam 的常见问题

@hanzo/iam 是什么?

TypeScript SDK for Hanzo IAM — OIDC auth, JWT validation, OAuth2 PKCE, user/org/project APIs

如何安装 @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 和提交记录判断。