@nihplod/sso-sdk 1.1.0 → 1.2.1

package/dist/react/index.d.ts

@@ -4,8 +4,10 @@ import React, { ReactNode, ComponentType } from 'react';
  * Token 存储抽象层
  *
  * 分两类存储：
- * - Token 数据：默认使用内存存储，Public Client 浏览器中 refresh_token 不落盘，
- *   XSS 无法窃取长期凭证。对需要多 Tab 共享 token 或 BFF/Confidential Client 场景，
+ * - Token 数据：默认使用 sessionStorage（标签页级持久化）。登录回调后 CallbackPage
+ *   默认整页跳转，内存存储会丢失登录态，因此默认改为 sessionStorage：
+ *   整页跳转与刷新后登录态保留，关闭标签页自动清除；SSR / 隐私模式写入失败时
+ *   降级为内存 Map。对需要多 Tab 共享 token 或 BFF/Confidential Client 场景，
  *   可通过 setTokenStorage() 注入 localStorage 实现（如 createSecureStorage({ persist: true })）。
  * - 临时数据（PKCE verifier / state / returnUrl / popup nonce）：必须跨整页重定向存活
  *   （login() 会 302 跳转到 SSO 中心再回来），因此默认写入 sessionStorage；
@@ -66,7 +68,12 @@ interface SsoUser {
     sub: string;
     nickname?: string;
     avatar?: string;
+    /** 手机号（脱敏，兼容保留的非标准 claim，新代码请使用 phone_number） */
     phone?: string;
+    /** 手机号（脱敏，OIDC 标准 claim，与 phone 内容一致） */
+    phone_number?: string;
+    /** 生日（ISO 8601，需 birthday scope，未设置时为 null） */
+    birthday?: string | null;
     membership_level?: string;
     total_points?: number;
 }
@@ -121,12 +128,20 @@ declare class SsoClient {
      *
      * @param returnUrl - 登录成功后的返回地址（可选，保存到 sessionStorage；
      *   仅允许相对路径或同源绝对 URL，否则忽略并告警）
+     *
+     * ⚠️ 不要与 getLoginUrl() 混用：两者都会重新生成并覆盖 sessionStorage 中的
+     * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
+     * 同一次登录只使用其中一个入口。
      */
     login(returnUrl?: string): Promise<void>;
     /**
      * 构建登录 URL（不跳转，返回 URL 字符串）
      *
      * 适用于需要手动处理跳转的场景。
+     *
+     * ⚠️ 不要与 login() 混用：两者都会重新生成并覆盖 sessionStorage 中的
+     * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
+     * 同一次登录只使用其中一个入口。
      */
     getLoginUrl(returnUrl?: string): Promise<string>;
     /**
@@ -171,7 +186,7 @@ declare class SsoClient {
      * 处理 OAuth 回调
      *
      * 解析回调 URL，校验 state 参数，用授权码交换 token。
-     * 成功后 token 自动保存到 token 存储（默认内存，可通过 setTokenStorage 定制）。
+     * 成功后 token 自动保存到 token 存储（默认 sessionStorage，可通过 setTokenStorage 定制）。
      *
      * @param callbackUrl - 完整的回调 URL（window.location.href）
      * @returns TokenData 或 null
@@ -209,9 +224,28 @@ declare class SsoClient {
      * 登出
      *
      * 清除本地所有 token 和临时数据，并尝试撤销服务端 refresh_token。
-     * @param redirectToSso - 是否重定向到 SSO 登出页（默认 false）
+     * @param redirectToSso - 是否重定向到 SSO 登出页（默认 false）。
+     *   为 true 时携带 state 参数（已保存到 sessionStorage），
+     *   回跳页面应调用 validateLogoutState() 校验防登出 CSRF。
      */
     logout(redirectToSso?: boolean): Promise<void>;
+    /**
+     * 校验 RP-Initiated Logout 回跳的 state 参数（登出 CSRF 防护）
+     *
+     * 在 post_logout_redirect_uri 指向的页面加载时调用；
+     * 仅在 URL 携带 state 且与 logout(redirectToSso=true) 保存的值一致时返回 true，
+     * 校验后清除已保存的 logout state（一次性）。
+     *
+     * @param url - 当前页面完整 URL（window.location.href）
+     *
+     * @example
+     * ```typescript
+     * if (sso.validateLogoutState(window.location.href)) {
+     *   // 来自 SSO 登出的可信回跳
+     * }
+     * ```
+     */
+    validateLogoutState(url: string): boolean;
     /**
      * 获取 OIDC Discovery 文档
      *
@@ -221,6 +255,21 @@ declare class SsoClient {
     getDiscovery(): Promise<OidcDiscovery | null>;
 }
 
+/**
+ * SSO SDK 错误类型
+ */
+/** SSO 错误码 */
+type SsoErrorCode = "invalid_config" | "state_mismatch" | "pkce_required" | "token_request_failed" | "session_expired" | "no_refresh_token" | "userinfo_failed" | "not_authenticated" | "authorization_code_expired" | "authorization_code_used" | "client_disabled" | "user_denied_authorization" | "account_disabled" | "sso_server_error" | "rate_limited" | "network_error" | "popup_blocked" | "popup_closed" | "id_token_invalid" | "id_token_unsupported_alg" | "id_token_hs256_unsupported" | "id_token_missing_secret" | "id_token_invalid_signature" | "id_token_issuer_mismatch" | "id_token_audience_mismatch" | "id_token_expired" | "id_token_missing_sub" | "id_token_at_hash_mismatch";
+/**
+ * SSO SDK 自定义错误
+ */
+declare class SsoError extends Error {
+    readonly code: SsoErrorCode;
+    readonly description: string;
+    readonly cause?: unknown;
+    constructor(code: SsoErrorCode, description: string, cause?: unknown);
+}
+
 /**
  * SsoProvider - React Context Provider
  *
@@ -230,6 +279,12 @@ declare class SsoClient {
  * - 提供 useSso() hook
  */
 
+/**
+ * 认证状态为三态：
+ * - isLoading=true：初始化/刷新中，user 与 error 均可能为 null
+ * - error 非 null：加载用户信息失败（如会话已失效），user 为 null
+ * - isAuthenticated=true 且 user 非 null：已登录
+ */
 interface SsoContextValue {
     /** 当前用户信息 */
     user: SsoUser | null;
@@ -237,6 +292,8 @@ interface SsoContextValue {
     isAuthenticated: boolean;
     /** 是否正在加载（初始化/刷新中） */
     isLoading: boolean;
+    /** 最近一次加载用户信息失败的错误（成功或登出后为 null） */
+    error: SsoError | null;
     /** 发起登录（同页重定向） */
     login: (returnUrl?: string) => Promise<void>;
     /** 弹窗模式登录（保持当前页面状态不丢失） */
@@ -266,8 +323,9 @@ interface SsoProviderProps {
      */
     refreshThreshold?: number;
     /**
-     * API 请求函数（可选）
-     * 用于在 token 刷新后自动重试失败的 API 请求。
+     * Token 静默刷新成功后的回调（可选）。
+     * 每次刷新成功时以新的 access_token 调用，可用于同步 token 到外部状态；
+     * SDK 不会据此自动重试先前失败的 API 请求，重试需由调用方自行实现。
      */
     onTokenRefreshed?: (token: string) => void;
 }
@@ -309,11 +367,22 @@ interface RequireAuthProps {
      * 仅在 autoLogin=true 时生效。弹窗被拦截时自动回退到同页重定向。
      */
     usePopup?: boolean;
+    /**
+     * 登录发起失败时的回调（如弹窗被关闭 popup_closed）。
+     * 失败后组件会展示重试入口，不会永久停在"请先登录"。
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * 自定义登录失败 UI。不传时显示默认的错误提示与"重试"按钮。
+     * retry() 会重新发起登录。
+     */
+    renderLoginError?: (error: unknown, retry: () => void) => React.ReactNode;
 }
 /**
  * 路由保护组件
  *
  * 未登录时自动触发登录跳转或显示回退内容。
+ * 登录发起失败（如弹窗被关闭）时显示重试入口，并通过 onError 上报。
  *
  * @example
  * ```tsx
@@ -323,7 +392,7 @@ interface RequireAuthProps {
  * </RequireAuth>
  * ```
  */
-declare function RequireAuth({ children, fallback, autoLogin, usePopup, }: RequireAuthProps): string | number | bigint | true | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.FunctionComponentElement<React.FragmentProps>;
+declare function RequireAuth({ children, fallback, autoLogin, usePopup, onError, renderLoginError, }: RequireAuthProps): string | number | bigint | true | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | React.FunctionComponentElement<React.FragmentProps>;
 /**
  * 高阶组件：包装页面组件，要求认证后才能访问
  *
@@ -339,7 +408,8 @@ declare function withAuth<P extends object>(Component: ComponentType<P>): Compon
  * CallbackPage — 通用 OAuth 回调页面组件
  *
  * 子项目只需在回调路由渲染此组件即可完成 code → token 交换。
- * 交换成功后自动跳转到 returnUrl 或首页。
+ * 交换成功后默认整页跳转到 returnUrl 或首页；
+ * 传入 onSuccess 可跳过默认跳转，由 SPA 路由接管（保持应用状态）。
  *
  * @example
  * ```tsx
@@ -349,9 +419,42 @@ declare function withAuth<P extends object>(Component: ComponentType<P>): Compon
  *   return <CallbackPage />;
  * }
  * ```
+ *
+ * @example SPA 路由接管跳转（不整页刷新）：
+ * ```tsx
+ * <CallbackPage onSuccess={() => navigate("/dashboard", { replace: true })} />
+ * ```
  */
 
-declare function CallbackPage(): React.DetailedReactHTMLElement<{
+interface CallbackPageProps {
+    /**
+     * 登录成功回调。传入后跳过默认的整页跳转（window.location.href），
+     * 由调用方用 SPA 路由接管跳转，避免丢失应用内状态。
+     */
+    onSuccess?: (tokenData: TokenData) => void;
+    /** 登录失败回调（错误同时会展示在错误页，除非提供了 renderError） */
+    onError?: (error: Error) => void;
+    /**
+     * 自定义错误页渲染。不传时使用默认错误 UI（DefaultCallbackError）。
+     */
+    renderError?: (error: string) => React.ReactNode;
+}
+/** 默认错误页 UI（可通过 renderError 完全替换） */
+declare function DefaultCallbackError({ error }: {
+    error: string;
+}): React.DetailedReactHTMLElement<{
+    style: {
+        display: "flex";
+        flexDirection: "column";
+        alignItems: "center";
+        justifyContent: "center";
+        minHeight: string;
+        fontFamily: "system-ui, sans-serif";
+    };
+}, HTMLElement>;
+declare function CallbackPage({ onSuccess, onError, renderError }?: CallbackPageProps): React.FunctionComponentElement<React.FragmentProps> | React.FunctionComponentElement<{
+    error: string;
+}> | React.DetailedReactHTMLElement<{
     style: {
         display: "flex";
         alignItems: "center";
@@ -361,4 +464,4 @@ declare function CallbackPage(): React.DetailedReactHTMLElement<{
     };
 }, HTMLElement> | null;
 
-export { CallbackPage, RequireAuth, SsoProvider, useSso, withAuth };
+export { CallbackPage, type CallbackPageProps, DefaultCallbackError, RequireAuth, SsoProvider, useSso, withAuth };

package/dist/react/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var react_exports = {};
 __export(react_exports, {
   CallbackPage: () => CallbackPage,
+  DefaultCallbackError: () => DefaultCallbackError,
   RequireAuth: () => RequireAuth,
   SsoProvider: () => SsoProvider,
   useSso: () => useSso,
@@ -117,6 +118,7 @@ var TOKEN_KEY = "token";
 var VERIFIER_KEY_PREFIX = "pkce_verifier_";
 var STATE_KEY = "oauth_state";
 var RETURN_URL_KEY = "return_url";
+var LOGOUT_STATE_KEY = "logout_state";
 function buildKey(base, clientId) {
   return clientId ? `${base}:${clientId}` : base;
 }
@@ -163,7 +165,7 @@ function createSessionStorageAdapter() {
   };
 }
 var _transient = createSessionStorageAdapter();
-var _storage = memoryStorageAdapter;
+var _storage = createSessionStorageAdapter();
 function saveTokenData(data, clientId) {
   _storage.set(buildKey(TOKEN_KEY, clientId), JSON.stringify(data));
 }
@@ -197,6 +199,15 @@ function getOAuthState(clientId) {
 function removeOAuthState(clientId) {
   _transient.remove(buildKey(STATE_KEY, clientId));
 }
+function saveLogoutState(state, clientId) {
+  _transient.set(buildKey(LOGOUT_STATE_KEY, clientId), state);
+}
+function getLogoutState(clientId) {
+  return _transient.get(buildKey(LOGOUT_STATE_KEY, clientId));
+}
+function removeLogoutState(clientId) {
+  _transient.remove(buildKey(LOGOUT_STATE_KEY, clientId));
+}
 function saveReturnUrl(url, clientId) {
   _transient.set(buildKey(RETURN_URL_KEY, clientId), url);
 }
@@ -211,6 +222,7 @@ function clearAllSsoData(clientId) {
     removeTokenData(clientId);
     removeOAuthState(clientId);
     removeReturnUrl(clientId);
+    removeLogoutState(clientId);
     removePkceVerifier(clientId);
     removePkceVerifier(`${clientId}_popup_nonce`);
     return;
@@ -218,6 +230,7 @@ function clearAllSsoData(clientId) {
   removeTokenData();
   removeOAuthState();
   removeReturnUrl();
+  removeLogoutState();
   const prefix = STORAGE_PREFIX + VERIFIER_KEY_PREFIX;
   const stores = [
     typeof sessionStorage !== "undefined" ? sessionStorage : null,
@@ -240,6 +253,7 @@ function clearAllSsoData(clientId) {
 // src/core/security.ts
 function isTrustedReturnUrl(url, currentOrigin) {
   if (!url) return false;
+  if (url.includes("\\")) return false;
   if (url.startsWith("/") && !url.startsWith("//")) return true;
   try {
     return new URL(url).origin === currentOrigin;
@@ -445,7 +459,7 @@ async function validateIdToken(idToken, accessToken, expectedIssuer, expectedCli
   if (typeof payload.exp !== "number") {
     throw new SsoError("id_token_invalid", "ID Token \u7F3A\u5C11 exp \u58F0\u660E");
   }
-  if (Date.now() >= payload.exp * 1e3) {
+  if (Date.now() >= payload.exp * 1e3 + 6e4) {
     throw new SsoError("id_token_expired", "ID Token \u5DF2\u8FC7\u671F");
   }
   if (typeof payload.iat === "number" && payload.iat * 1e3 > Date.now() + 6e4) {
@@ -538,7 +552,7 @@ var _SsoClient = class _SsoClient {
    */
   _saveReturnUrlIfTrusted(returnUrl) {
     if (isTrustedReturnUrl(returnUrl, window.location.origin)) {
-      saveReturnUrl(returnUrl);
+      saveReturnUrl(returnUrl, this.config.clientId);
     } else {
       console.warn(`[SSO SDK] returnUrl \u672A\u901A\u8FC7\u540C\u6E90\u6821\u9A8C\uFF0C\u5DF2\u5FFD\u7565: ${returnUrl}`);
     }
@@ -554,6 +568,10 @@ var _SsoClient = class _SsoClient {
    *
    * @param returnUrl - 登录成功后的返回地址（可选，保存到 sessionStorage；
    *   仅允许相对路径或同源绝对 URL，否则忽略并告警）
+   *
+   * ⚠️ 不要与 getLoginUrl() 混用：两者都会重新生成并覆盖 sessionStorage 中的
+   * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
+   * 同一次登录只使用其中一个入口。
    */
   async login(returnUrl) {
     const verifier = generateCodeVerifier();
@@ -579,6 +597,10 @@ var _SsoClient = class _SsoClient {
    * 构建登录 URL（不跳转，返回 URL 字符串）
    *
    * 适用于需要手动处理跳转的场景。
+   *
+   * ⚠️ 不要与 login() 混用：两者都会重新生成并覆盖 sessionStorage 中的
+   * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
+   * 同一次登录只使用其中一个入口。
    */
   async getLoginUrl(returnUrl) {
     const verifier = generateCodeVerifier();
@@ -731,7 +753,7 @@ var _SsoClient = class _SsoClient {
    * 处理 OAuth 回调
    *
    * 解析回调 URL，校验 state 参数，用授权码交换 token。
-   * 成功后 token 自动保存到 token 存储（默认内存，可通过 setTokenStorage 定制）。
+   * 成功后 token 自动保存到 token 存储（默认 sessionStorage，可通过 setTokenStorage 定制）。
    *
    * @param callbackUrl - 完整的回调 URL（window.location.href）
    * @returns TokenData 或 null
@@ -741,12 +763,16 @@ var _SsoClient = class _SsoClient {
     const params = url.searchParams;
     const error = params.get("error");
     if (error) {
+      removeOAuthState(this.config.clientId);
+      removePkceVerifier(this.config.clientId);
       const desc = params.get("error_description") || error;
-      throw new SsoError("token_request_failed", `\u6388\u6743\u5931\u8D25: ${desc}`);
+      throw new SsoError(mapOAuthErrorToSsoCode(error), `\u6388\u6743\u5931\u8D25: ${desc}`);
     }
     const code = params.get("code");
     const returnedState = params.get("state");
     if (!code) {
+      removeOAuthState(this.config.clientId);
+      removePkceVerifier(this.config.clientId);
       throw new SsoError("token_request_failed", "\u56DE\u8C03 URL \u4E2D\u7F3A\u5C11 authorization code");
     }
     const savedState = getOAuthState(this.config.clientId);
@@ -798,8 +824,6 @@ var _SsoClient = class _SsoClient {
       );
     }
     const data = await res.json();
-    removeOAuthState(this.config.clientId);
-    removePkceVerifier(this.config.clientId);
     if (data.id_token) {
       try {
         await validateIdToken(
@@ -813,6 +837,8 @@ var _SsoClient = class _SsoClient {
         throw err;
       }
     }
+    removeOAuthState(this.config.clientId);
+    removePkceVerifier(this.config.clientId);
     const now = Date.now();
     const tokenData = {
       access_token: data.access_token,
@@ -981,7 +1007,9 @@ var _SsoClient = class _SsoClient {
    * 登出
    *
    * 清除本地所有 token 和临时数据，并尝试撤销服务端 refresh_token。
-   * @param redirectToSso - 是否重定向到 SSO 登出页（默认 false）
+   * @param redirectToSso - 是否重定向到 SSO 登出页（默认 false）。
+   *   为 true 时携带 state 参数（已保存到 sessionStorage），
+   *   回跳页面应调用 validateLogoutState() 校验防登出 CSRF。
    */
   async logout(redirectToSso = false) {
     const tokenData = getTokenData(this.config.clientId);
@@ -1024,10 +1052,36 @@ var _SsoClient = class _SsoClient {
         logoutUrl.searchParams.set("id_token_hint", idTokenHint);
       }
       const state = generateState();
+      saveLogoutState(state, this.config.clientId);
       logoutUrl.searchParams.set("state", state);
       window.location.href = logoutUrl.toString();
     }
   }
+  /**
+   * 校验 RP-Initiated Logout 回跳的 state 参数（登出 CSRF 防护）
+   *
+   * 在 post_logout_redirect_uri 指向的页面加载时调用；
+   * 仅在 URL 携带 state 且与 logout(redirectToSso=true) 保存的值一致时返回 true，
+   * 校验后清除已保存的 logout state（一次性）。
+   *
+   * @param url - 当前页面完整 URL（window.location.href）
+   *
+   * @example
+   * ```typescript
+   * if (sso.validateLogoutState(window.location.href)) {
+   *   // 来自 SSO 登出的可信回跳
+   * }
+   * ```
+   */
+  validateLogoutState(url) {
+    const returnedState = new URL(url).searchParams.get("state");
+    if (!returnedState) return false;
+    const savedState = getLogoutState(this.config.clientId);
+    if (!savedState) return false;
+    if (!timingSafeEqualString(savedState, returnedState)) return false;
+    removeLogoutState(this.config.clientId);
+    return true;
+  }
   /**
    * 获取 OIDC Discovery 文档
    *
@@ -1111,6 +1165,7 @@ function SsoProvider({
   const [user, setUser] = (0, import_react.useState)(null);
   const [isLoading, setIsLoading] = (0, import_react.useState)(true);
   const [isAuthenticated, setIsAuthenticated] = (0, import_react.useState)(false);
+  const [error, setError] = (0, import_react.useState)(null);
   const [client] = (0, import_react.useState)(() => new SsoClient(config));
   const refreshTimerRef = (0, import_react.useRef)(null);
   const loadedRef = (0, import_react.useRef)(false);
@@ -1119,6 +1174,7 @@ function SsoProvider({
     if (!tokenData) {
       setUser(null);
       setIsAuthenticated(false);
+      setError(null);
       setIsLoading(false);
       return;
     }
@@ -1126,9 +1182,13 @@ function SsoProvider({
       const u = await client.getUserInfo();
       setUser(u);
       setIsAuthenticated(true);
-    } catch {
+      setError(null);
+    } catch (err) {
       setUser(null);
       setIsAuthenticated(false);
+      setError(
+        err instanceof SsoError ? err : new SsoError("userinfo_failed", err instanceof Error ? err.message : String(err))
+      );
       removeTokenData(client.config.clientId);
     } finally {
       setIsLoading(false);
@@ -1223,6 +1283,7 @@ function SsoProvider({
       await client.logout(redirectToSso);
       setUser(null);
       setIsAuthenticated(false);
+      setError(null);
     },
     [client]
   );
@@ -1236,6 +1297,7 @@ function SsoProvider({
     user,
     isAuthenticated,
     isLoading,
+    error,
     login,
     loginPopup,
     logout,
@@ -1259,29 +1321,62 @@ function RequireAuth({
   children,
   fallback,
   autoLogin = true,
-  usePopup = false
+  usePopup = false,
+  onError,
+  renderLoginError
 }) {
   const { isAuthenticated, isLoading, login, loginPopup } = useSso();
   const loginTriggeredRef = (0, import_react2.useRef)(false);
+  const [loginError, setLoginError] = (0, import_react2.useState)(null);
+  const triggerLogin = () => {
+    loginTriggeredRef.current = true;
+    const currentPath = window.location.pathname + window.location.search;
+    const handleFailure = (err) => {
+      loginTriggeredRef.current = false;
+      setLoginError(err);
+      onError?.(err);
+    };
+    if (usePopup) {
+      loginPopup({ returnUrl: currentPath }).catch((err) => {
+        if (err.code === "popup_blocked") {
+          login(currentPath).catch(handleFailure);
+          return;
+        }
+        handleFailure(err);
+      });
+    } else {
+      login(currentPath).catch(handleFailure);
+    }
+  };
+  const retry = () => {
+    setLoginError(null);
+    triggerLogin();
+  };
   (0, import_react2.useEffect)(() => {
     if (!isLoading && !isAuthenticated && autoLogin && !loginTriggeredRef.current) {
-      loginTriggeredRef.current = true;
-      const currentPath = window.location.pathname + window.location.search;
-      if (usePopup) {
-        loginPopup({ returnUrl: currentPath }).catch((err) => {
-          if (err.code === "popup_blocked") {
-            login(currentPath);
-          }
-        });
-      } else {
-        login(currentPath);
-      }
+      triggerLogin();
     }
   }, [isLoading, isAuthenticated, autoLogin, usePopup, login, loginPopup]);
   if (isLoading) {
     return fallback || import_react2.default.createElement("div", null, "\u6B63\u5728\u9A8C\u8BC1\u767B\u5F55\u72B6\u6001...");
   }
   if (!isAuthenticated) {
+    if (loginError) {
+      if (renderLoginError) {
+        return import_react2.default.createElement(
+          import_react2.default.Fragment,
+          null,
+          renderLoginError(loginError, retry)
+        );
+      }
+      const message = loginError instanceof Error ? loginError.message : "\u767B\u5F55\u5931\u8D25";
+      return import_react2.default.createElement(
+        "div",
+        null,
+        import_react2.default.createElement("p", null, `\u767B\u5F55\u672A\u5B8C\u6210\uFF1A${message}`),
+        import_react2.default.createElement("button", { onClick: retry }, "\u91CD\u8BD5\u767B\u5F55")
+      );
+    }
     if (fallback) return import_react2.default.createElement(import_react2.default.Fragment, null, fallback);
     return import_react2.default.createElement("div", null, "\u8BF7\u5148\u767B\u5F55");
   }
@@ -1302,10 +1397,41 @@ function withAuth(Component) {
 
 // src/react/CallbackPage.tsx
 var import_react3 = __toESM(require("react"));
-function CallbackPage() {
+function DefaultCallbackError({ error }) {
+  return import_react3.default.createElement(
+    "div",
+    {
+      style: {
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        minHeight: "100vh",
+        fontFamily: "system-ui, sans-serif"
+      }
+    },
+    import_react3.default.createElement(
+      "p",
+      { style: { color: "#dc2626", marginBottom: "1rem" } },
+      error
+    ),
+    import_react3.default.createElement(
+      "a",
+      { href: "/", style: { color: "#2563eb", textDecoration: "underline" } },
+      "\u8FD4\u56DE\u9996\u9875"
+    )
+  );
+}
+function CallbackPage({ onSuccess, onError, renderError } = {}) {
   const { client, refreshUser } = useSso();
   const [error, setError] = (0, import_react3.useState)(null);
   const [processing, setProcessing] = (0, import_react3.useState)(true);
+  const onSuccessRef = (0, import_react3.useRef)(onSuccess);
+  const onErrorRef = (0, import_react3.useRef)(onError);
+  (0, import_react3.useEffect)(() => {
+    onSuccessRef.current = onSuccess;
+    onErrorRef.current = onError;
+  });
   (0, import_react3.useEffect)(() => {
     if (window.opener && !window.opener.closed) {
       const nonce = new URL(window.location.href).searchParams.get("popup_nonce");
@@ -1324,22 +1450,27 @@ function CallbackPage() {
     let cancelled = false;
     async function handleCallback() {
       try {
-        await client.handleCallback(window.location.href);
+        const tokenData = await client.handleCallback(window.location.href);
         if (cancelled) return;
         await refreshUser();
-        const returnUrl = getReturnUrl();
-        removeReturnUrl();
+        if (cancelled) return;
+        const clientId = client.config.clientId;
+        const returnUrl = getReturnUrl(clientId);
+        removeReturnUrl(clientId);
+        const onSuccessCb = onSuccessRef.current;
+        if (onSuccessCb) {
+          onSuccessCb(tokenData);
+          return;
+        }
         window.location.href = returnUrl && isTrustedReturnUrl(returnUrl, window.location.origin) ? returnUrl : "/";
       } catch (err) {
         if (cancelled) return;
-        if (err instanceof SsoError) {
-          setError(err.description || `SSO \u9519\u8BEF (${err.code})`);
-        } else if (err instanceof TypeError && err.message.includes("fetch")) {
-          setError("\u7F51\u7EDC\u8FDE\u63A5\u5931\u8D25\uFF0C\u8BF7\u68C0\u67E5\u7F51\u7EDC\u540E\u91CD\u8BD5");
-        } else if (err instanceof Error) {
-          setError(`\u767B\u5F55\u56DE\u8C03\u5904\u7406\u5931\u8D25: ${err.message}`);
+        const errorObj = err instanceof Error ? err : new Error(String(err));
+        onErrorRef.current?.(errorObj);
+        if (errorObj instanceof SsoError) {
+          setError(errorObj.description || `SSO \u9519\u8BEF (${errorObj.code})`);
         } else {
-          setError("\u767B\u5F55\u56DE\u8C03\u5904\u7406\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5");
+          setError(`\u767B\u5F55\u56DE\u8C03\u5904\u7406\u5931\u8D25: ${errorObj.message}`);
         }
         setProcessing(false);
       }
@@ -1350,29 +1481,8 @@ function CallbackPage() {
     };
   }, [client, refreshUser]);
   if (error) {
-    return import_react3.default.createElement(
-      "div",
-      {
-        style: {
-          display: "flex",
-          flexDirection: "column",
-          alignItems: "center",
-          justifyContent: "center",
-          minHeight: "100vh",
-          fontFamily: "system-ui, sans-serif"
-        }
-      },
-      import_react3.default.createElement(
-        "p",
-        { style: { color: "#dc2626", marginBottom: "1rem" } },
-        error
-      ),
-      import_react3.default.createElement(
-        "a",
-        { href: "/", style: { color: "#2563eb", textDecoration: "underline" } },
-        "\u8FD4\u56DE\u9996\u9875"
-      )
-    );
+    if (renderError) return import_react3.default.createElement(import_react3.default.Fragment, null, renderError(error));
+    return import_react3.default.createElement(DefaultCallbackError, { error });
   }
   if (processing) {
     return import_react3.default.createElement(
@@ -1394,6 +1504,7 @@ function CallbackPage() {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CallbackPage,
+  DefaultCallbackError,
   RequireAuth,
   SsoProvider,
   useSso,