@nihplod/sso-sdk 1.4.1 → 1.6.0

package/dist/react/index.d.mts

@@ -58,10 +58,26 @@ interface SsoClientConfig {
     redirectUri: string;
     /** SSO 中心地址，如 "https://nihplod.cn" */
     ssoBaseUrl: string;
+    /**
+     * 允许 Discovery 文档声明跨源端点（默认 false）。
+     *
+     * ⚠️ 安全警告：Discovery 文档若被篡改（如中间人/反向代理劫持），攻击者可把
+     * token_endpoint 指向自己的服务器窃取 authorization code / refresh_token。
+     * SDK 默认校验 authorization_endpoint 必须与 ssoBaseUrl 同源、
+     * token_endpoint / userinfo_endpoint 必须与 ssoBaseUrl（或 serverBaseUrl）同源，
+     * 不匹配时告警并回退到默认端点。仅当 SSO 中心确实把端点托管在其他域名时
+     * 才设置此开关，并自行确保 Discovery 通道可信。
+     */
+    allowCrossOriginDiscoveryEndpoints?: boolean;
     /** 请求的 scope（空格分隔），如 "openid profile phone" */
     scopes?: string;
     /** RP-Initiated Logout 返回地址（可选）。不传时回退到 redirectUri */
     postLogoutRedirectUri?: string;
+    /**
+     * 调试日志开关（默认 false）。开启后输出登录/回调/刷新/登出等关键流程日志，
+     * 便于接入方定位问题（生产默认关闭，避免日志噪音）。
+     */
+    debug?: boolean;
     /**
      * 服务端到服务端调用的内网地址（可选，如 http://127.0.0.1:3000）。
      * 仅用于 discovery / token / userinfo / revocation 等服务器间请求；
@@ -123,11 +139,28 @@ declare class SsoClient {
     private _discovery;
     private _discoveryFetchedAt;
     private _refreshLock;
+    /** Discovery 端点 origin 校验失败只告警一次（拒绝的文档不缓存，避免每次调用刷屏） */
+    private _discoveryOriginWarned;
     /** Discovery 文档缓存 TTL（5 分钟） */
     private static readonly DISCOVERY_TTL_MS;
     /** Discovery fetch 超时（10 秒） */
     private static readonly DISCOVERY_TIMEOUT_MS;
     constructor(config: SsoClientConfig);
+    /**
+     * 调试日志（config.debug=true 时输出，前缀 [SSO SDK]）：
+     * 覆盖登录发起 / 回调结果 / 刷新失败 / 登出等关键节点，便于接入方定位问题。
+     * 不会输出 token/授权码等敏感值。
+     */
+    debugLog(...args: unknown[]): void;
+    /**
+     * 校验 Discovery 文档端点 origin（防文档被篡改后 token/code 被导向攻击者服务器）：
+     * - authorization_endpoint 必须与 ssoBaseUrl 同源（浏览器跳转目标）；
+     * - token_endpoint / userinfo_endpoint 必须与 ssoBaseUrl 同源，
+     *   或（配置了 serverBaseUrl 时）与内网地址同源。
+     * 任一不匹配：告警并返回 null（上层回退到默认端点，fail-safe）。
+     * 可通过 config.allowCrossOriginDiscoveryEndpoints 关闭（见配置项警告）。
+     */
+    private _sanitizeDiscovery;
     /**
      * 获取 OIDC Discovery 文档（带缓存 + 超时）
      *
@@ -249,6 +282,9 @@ declare class SsoClient {
      * 检查是否已认证（不发起网络请求）
      *
      * 仅检查本地是否存在未过期的 access_token。
+     * 故意不做 EXPIRY_SKEW_MS 提前量：这是同步的 UI 提示判定（是否显示"已登录"），
+     * 提前 10s 翻转 false 会让调用方在 token 仍有效时误显示未登录；真正发请求的
+     * getAccessToken/getUserInfo 已带提前量。
      */
     isAuthenticated(): boolean;
     /**
@@ -339,6 +375,12 @@ interface SsoContextValue {
     refreshUser: () => Promise<void>;
     /** 获取 access_token（自动刷新过期 token） */
     getAccessToken: () => Promise<string | null>;
+    /**
+     * 会话已失效（refresh_token 被撤销/过期），需要用户重新登录。
+     * 与 `error` 不同：该标志在 loadUser 拿到"无 token"时不会被清空，
+     * 登录成功后才复位，便于子站稳定展示"登录已过期"提示。
+     */
+    sessionExpired: boolean;
     /** SsoClient 实例（高级用法） */
     client: SsoClient;
 }
@@ -359,8 +401,13 @@ interface SsoProviderProps {
      * SDK 不会据此自动重试先前失败的 API 请求，重试需由调用方自行实现。
      */
     onTokenRefreshed?: (token: string) => void;
+    /**
+     * 会话失效回调（可选）。refresh_token 被撤销/过期时触发一次，
+     * 子站可据此展示"登录已过期，请重新登录"或埋点上报。
+     */
+    onSessionExpired?: (error: SsoError) => void;
 }
-declare function SsoProvider({ config, children, refreshThreshold, onTokenRefreshed, }: SsoProviderProps): React.FunctionComponentElement<React.ProviderProps<SsoContextValue | null>>;
+declare function SsoProvider({ config, children, refreshThreshold, onTokenRefreshed, onSessionExpired, }: SsoProviderProps): React.FunctionComponentElement<React.ProviderProps<SsoContextValue | null>>;
 /**
  * useSso Hook
  *
@@ -481,6 +528,8 @@ declare function DefaultCallbackError({ error }: {
         justifyContent: "center";
         minHeight: string;
         fontFamily: "system-ui, sans-serif";
+        padding: string;
+        textAlign: "center";
     };
 }, HTMLElement>;
 declare function CallbackPage({ onSuccess, onError, renderError }?: CallbackPageProps): React.FunctionComponentElement<React.FragmentProps> | React.FunctionComponentElement<{

package/dist/react/index.d.ts

@@ -58,10 +58,26 @@ interface SsoClientConfig {
     redirectUri: string;
     /** SSO 中心地址，如 "https://nihplod.cn" */
     ssoBaseUrl: string;
+    /**
+     * 允许 Discovery 文档声明跨源端点（默认 false）。
+     *
+     * ⚠️ 安全警告：Discovery 文档若被篡改（如中间人/反向代理劫持），攻击者可把
+     * token_endpoint 指向自己的服务器窃取 authorization code / refresh_token。
+     * SDK 默认校验 authorization_endpoint 必须与 ssoBaseUrl 同源、
+     * token_endpoint / userinfo_endpoint 必须与 ssoBaseUrl（或 serverBaseUrl）同源，
+     * 不匹配时告警并回退到默认端点。仅当 SSO 中心确实把端点托管在其他域名时
+     * 才设置此开关，并自行确保 Discovery 通道可信。
+     */
+    allowCrossOriginDiscoveryEndpoints?: boolean;
     /** 请求的 scope（空格分隔），如 "openid profile phone" */
     scopes?: string;
     /** RP-Initiated Logout 返回地址（可选）。不传时回退到 redirectUri */
     postLogoutRedirectUri?: string;
+    /**
+     * 调试日志开关（默认 false）。开启后输出登录/回调/刷新/登出等关键流程日志，
+     * 便于接入方定位问题（生产默认关闭，避免日志噪音）。
+     */
+    debug?: boolean;
     /**
      * 服务端到服务端调用的内网地址（可选，如 http://127.0.0.1:3000）。
      * 仅用于 discovery / token / userinfo / revocation 等服务器间请求；
@@ -123,11 +139,28 @@ declare class SsoClient {
     private _discovery;
     private _discoveryFetchedAt;
     private _refreshLock;
+    /** Discovery 端点 origin 校验失败只告警一次（拒绝的文档不缓存，避免每次调用刷屏） */
+    private _discoveryOriginWarned;
     /** Discovery 文档缓存 TTL（5 分钟） */
     private static readonly DISCOVERY_TTL_MS;
     /** Discovery fetch 超时（10 秒） */
     private static readonly DISCOVERY_TIMEOUT_MS;
     constructor(config: SsoClientConfig);
+    /**
+     * 调试日志（config.debug=true 时输出，前缀 [SSO SDK]）：
+     * 覆盖登录发起 / 回调结果 / 刷新失败 / 登出等关键节点，便于接入方定位问题。
+     * 不会输出 token/授权码等敏感值。
+     */
+    debugLog(...args: unknown[]): void;
+    /**
+     * 校验 Discovery 文档端点 origin（防文档被篡改后 token/code 被导向攻击者服务器）：
+     * - authorization_endpoint 必须与 ssoBaseUrl 同源（浏览器跳转目标）；
+     * - token_endpoint / userinfo_endpoint 必须与 ssoBaseUrl 同源，
+     *   或（配置了 serverBaseUrl 时）与内网地址同源。
+     * 任一不匹配：告警并返回 null（上层回退到默认端点，fail-safe）。
+     * 可通过 config.allowCrossOriginDiscoveryEndpoints 关闭（见配置项警告）。
+     */
+    private _sanitizeDiscovery;
     /**
      * 获取 OIDC Discovery 文档（带缓存 + 超时）
      *
@@ -249,6 +282,9 @@ declare class SsoClient {
      * 检查是否已认证（不发起网络请求）
      *
      * 仅检查本地是否存在未过期的 access_token。
+     * 故意不做 EXPIRY_SKEW_MS 提前量：这是同步的 UI 提示判定（是否显示"已登录"），
+     * 提前 10s 翻转 false 会让调用方在 token 仍有效时误显示未登录；真正发请求的
+     * getAccessToken/getUserInfo 已带提前量。
      */
     isAuthenticated(): boolean;
     /**
@@ -339,6 +375,12 @@ interface SsoContextValue {
     refreshUser: () => Promise<void>;
     /** 获取 access_token（自动刷新过期 token） */
     getAccessToken: () => Promise<string | null>;
+    /**
+     * 会话已失效（refresh_token 被撤销/过期），需要用户重新登录。
+     * 与 `error` 不同：该标志在 loadUser 拿到"无 token"时不会被清空，
+     * 登录成功后才复位，便于子站稳定展示"登录已过期"提示。
+     */
+    sessionExpired: boolean;
     /** SsoClient 实例（高级用法） */
     client: SsoClient;
 }
@@ -359,8 +401,13 @@ interface SsoProviderProps {
      * SDK 不会据此自动重试先前失败的 API 请求，重试需由调用方自行实现。
      */
     onTokenRefreshed?: (token: string) => void;
+    /**
+     * 会话失效回调（可选）。refresh_token 被撤销/过期时触发一次，
+     * 子站可据此展示"登录已过期，请重新登录"或埋点上报。
+     */
+    onSessionExpired?: (error: SsoError) => void;
 }
-declare function SsoProvider({ config, children, refreshThreshold, onTokenRefreshed, }: SsoProviderProps): React.FunctionComponentElement<React.ProviderProps<SsoContextValue | null>>;
+declare function SsoProvider({ config, children, refreshThreshold, onTokenRefreshed, onSessionExpired, }: SsoProviderProps): React.FunctionComponentElement<React.ProviderProps<SsoContextValue | null>>;
 /**
  * useSso Hook
  *
@@ -481,6 +528,8 @@ declare function DefaultCallbackError({ error }: {
         justifyContent: "center";
         minHeight: string;
         fontFamily: "system-ui, sans-serif";
+        padding: string;
+        textAlign: "center";
     };
 }, HTMLElement>;
 declare function CallbackPage({ onSuccess, onError, renderError }?: CallbackPageProps): React.FunctionComponentElement<React.FragmentProps> | React.FunctionComponentElement<{