@nihplod/sso-sdk 1.0.1 → 1.2.0

package/dist/react/index.d.ts

@@ -3,9 +3,15 @@ import React, { ReactNode, ComponentType } from 'react';
 /**
  * Token 存储抽象层
  *
- * 默认使用 localStorage，以支持多 Tab 间自动同步 token 并避免并发刷新。
- * 对 XSS 敏感的子项目可通过 setTokenStorage() 注入更安全的自定义实现
- *（如内存存储、Service Worker 封装、或带加密的 storage）。
+ * 分两类存储：
+ * - 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；
+ *   SSR 等无 sessionStorage 环境自动降级为内存 Map。
  *
  * 多 client 隔离：
  * - token / state / return_url 均支持按 clientId 隔离 key
@@ -54,6 +60,8 @@ interface SsoClientConfig {
     ssoBaseUrl: string;
     /** 请求的 scope（空格分隔），如 "openid profile phone" */
     scopes?: string;
+    /** RP-Initiated Logout 返回地址（可选）。不传时回退到 redirectUri */
+    postLogoutRedirectUri?: string;
 }
 /** 用户信息 */
 interface SsoUser {
@@ -102,26 +110,78 @@ declare class SsoClient {
     private _getTokenEndpoint;
     /** 获取 userinfo 端点 URL（优先 Discovery，回退默认） */
     private _getUserinfoEndpoint;
+    /**
+     * 开放重定向防护：仅保存相对路径或与当前页面同源的 returnUrl，
+     * 其余（如 https://evil.com）忽略并告警，防止回调后跳转到钓鱼站点。
+     */
+    private _saveReturnUrlIfTrusted;
     /**
      * 发起 SSO 登录
      *
      * 生成 PKCE code_verifier/code_challenge 和 state 参数，
      * 构建 authorize URL，通过 302 跳转到 SSO 登录页。
      *
-     * @param returnUrl - 登录成功后的返回地址（可选，保存到 sessionStorage）
+     * @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>;
+    /**
+     * 弹窗模式 SSO 登录
+     *
+     * 打开一个小窗口进行登录，认证完成后窗口自动关闭，
+     * 主页面不丢失状态（适用于 SPA 中需要保持表单/浏览上下文的场景）。
+     *
+     * 流程：
+     * 1. window.open() 打开授权 URL 到弹窗
+     * 2. 用户在弹窗中完成登录
+     * 3. 弹窗加载 CallbackPage 时检测到 window.opener，通过 postMessage 回传回调 URL
+     * 4. 主页面收到消息后调用 handleCallback() 交换 token
+     * 5. 弹窗自动关闭
+     *
+     * @param options - 弹窗配置
+     * @param options.returnUrl - 登录成功后的返回地址
+     * @param options.width - 弹窗宽度（默认 480）
+     * @param options.height - 弹窗高度（默认 640）
+     * @returns TokenData
+     *
+     * @example
+     * ```typescript
+     * const client = new SsoClient({ clientId: "xxx", redirectUri: "https://myapp.com/callback", ssoBaseUrl: "https://nihplod.cn" });
+     * try {
+     *   const tokenData = await client.loginPopup({ returnUrl: "/dashboard" });
+     *   console.log("登录成功", tokenData);
+     * } catch (err) {
+     *   if (err instanceof SsoError && err.code === "popup_blocked") {
+     *     // 弹窗被拦截，回退到同页重定向
+     *     await client.login("/dashboard");
+     *   }
+     * }
+     * ```
+     */
+    loginPopup(options?: {
+        returnUrl?: string;
+        width?: number;
+        height?: number;
+    }): Promise<TokenData>;
     /**
      * 处理 OAuth 回调
      *
      * 解析回调 URL，校验 state 参数，用授权码交换 token。
-     * 成功后 token 自动保存到 sessionStorage。
+     * 成功后 token 自动保存到 token 存储（默认 sessionStorage，可通过 setTokenStorage 定制）。
      *
      * @param callbackUrl - 完整的回调 URL（window.location.href）
      * @returns TokenData 或 null
@@ -159,9 +219,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 文档
      *
@@ -171,6 +250,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
  *
@@ -180,6 +274,12 @@ declare class SsoClient {
  * - 提供 useSso() hook
  */
 
+/**
+ * 认证状态为三态：
+ * - isLoading=true：初始化/刷新中，user 与 error 均可能为 null
+ * - error 非 null：加载用户信息失败（如会话已失效），user 为 null
+ * - isAuthenticated=true 且 user 非 null：已登录
+ */
 interface SsoContextValue {
     /** 当前用户信息 */
     user: SsoUser | null;
@@ -187,8 +287,16 @@ interface SsoContextValue {
     isAuthenticated: boolean;
     /** 是否正在加载（初始化/刷新中） */
     isLoading: boolean;
-    /** 发起登录 */
+    /** 最近一次加载用户信息失败的错误（成功或登出后为 null） */
+    error: SsoError | null;
+    /** 发起登录（同页重定向） */
     login: (returnUrl?: string) => Promise<void>;
+    /** 弹窗模式登录（保持当前页面状态不丢失） */
+    loginPopup: (options?: {
+        returnUrl?: string;
+        width?: number;
+        height?: number;
+    }) => Promise<TokenData>;
     /** 登出 */
     logout: (redirectToSso?: boolean) => Promise<void>;
     /** 刷新用户信息 */
@@ -210,8 +318,9 @@ interface SsoProviderProps {
      */
     refreshThreshold?: number;
     /**
-     * API 请求函数（可选）
-     * 用于在 token 刷新后自动重试失败的 API 请求。
+     * Token 静默刷新成功后的回调（可选）。
+     * 每次刷新成功时以新的 access_token 调用，可用于同步 token 到外部状态；
+     * SDK 不会据此自动重试先前失败的 API 请求，重试需由调用方自行实现。
      */
     onTokenRefreshed?: (token: string) => void;
 }
@@ -247,20 +356,38 @@ interface RequireAuthProps {
     fallback?: React.ReactNode;
     /** 是否在检测到未登录时自动发起登录跳转 */
     autoLogin?: boolean;
+    /**
+     * 是否使用弹窗模式登录（保持当前页面状态不丢失）
+     *
+     * 仅在 autoLogin=true 时生效。弹窗被拦截时自动回退到同页重定向。
+     */
+    usePopup?: boolean;
+    /**
+     * 登录发起失败时的回调（如弹窗被关闭 popup_closed）。
+     * 失败后组件会展示重试入口，不会永久停在"请先登录"。
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * 自定义登录失败 UI。不传时显示默认的错误提示与"重试"按钮。
+     * retry() 会重新发起登录。
+     */
+    renderLoginError?: (error: unknown, retry: () => void) => React.ReactNode;
 }
 /**
  * 路由保护组件
  *
  * 未登录时自动触发登录跳转或显示回退内容。
+ * 登录发起失败（如弹窗被关闭）时显示重试入口，并通过 onError 上报。
  *
  * @example
  * ```tsx
- * <RequireAuth>
+ * // 弹窗模式：不中断用户当前操作
+ * <RequireAuth autoLogin usePopup>
  *   <Dashboard />
  * </RequireAuth>
  * ```
  */
-declare function RequireAuth({ children, fallback, autoLogin, }: 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>;
 /**
  * 高阶组件：包装页面组件，要求认证后才能访问
  *
@@ -276,7 +403,8 @@ declare function withAuth<P extends object>(Component: ComponentType<P>): Compon
  * CallbackPage — 通用 OAuth 回调页面组件
  *
  * 子项目只需在回调路由渲染此组件即可完成 code → token 交换。
- * 交换成功后自动跳转到 returnUrl 或首页。
+ * 交换成功后默认整页跳转到 returnUrl 或首页；
+ * 传入 onSuccess 可跳过默认跳转，由 SPA 路由接管（保持应用状态）。
  *
  * @example
  * ```tsx
@@ -286,9 +414,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";
@@ -298,4 +459,4 @@ declare function CallbackPage(): React.DetailedReactHTMLElement<{
     };
 }, HTMLElement> | null;
 
-export { CallbackPage, RequireAuth, SsoProvider, useSso, withAuth };
+export { CallbackPage, type CallbackPageProps, DefaultCallbackError, RequireAuth, SsoProvider, useSso, withAuth };