@nihplod/sso-sdk 1.3.1 → 1.4.0

package/dist/react/index.d.ts

@@ -86,6 +86,21 @@ interface SsoUser {
     total_spent?: number;
     total_points?: number;
 }
+/** login() / getLoginUrl() 选项 */
+interface LoginOptions {
+    /**
+     * OIDC prompt 参数：
+     * - "none"：静默探测 SSO 会话。用户在 IdP 有会话时直接回跳完成登录；
+     *   无会话时 IdP 回跳 error=login_required（或 consent_required /
+     *   interaction_required），handleCallback() 识别后返回 null 而不抛错
+     *   （CallbackPage 默认跳回 returnUrl 并附 sso_probe=no_session）。
+     *   ⚠️ 不要在页面加载时自动探测（会打扰无会话用户并消耗请求），
+     *   应由用户点击等明确动作触发。
+     * - "login"：强制重新认证；
+     * - "consent"：强制重新授权确认。
+     */
+    prompt?: "none" | "login" | "consent";
+}
 /** OIDC Discovery 文档 */
 interface OidcDiscovery {
     issuer: string;
@@ -139,12 +154,15 @@ declare class SsoClient {
      *
      * @param returnUrl - 登录成功后的返回地址（可选，保存到 sessionStorage；
      *   仅允许相对路径或同源绝对 URL，否则忽略并告警）
+     * @param options.prompt - OIDC prompt 参数。传 "none" 为静默探测：
+     *   额外在存储中记录探测标记（该次请求的 state），回调无会话时
+     *   handleCallback() 返回 null 而不抛错。
      *
      * ⚠️ 不要与 getLoginUrl() 混用：两者都会重新生成并覆盖 sessionStorage 中的
      * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
      * 同一次登录只使用其中一个入口。
      */
-    login(returnUrl?: string): Promise<void>;
+    login(returnUrl?: string, options?: LoginOptions): Promise<void>;
     /**
      * 构建登录 URL（不跳转，返回 URL 字符串）
      *
@@ -154,7 +172,7 @@ declare class SsoClient {
      * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
      * 同一次登录只使用其中一个入口。
      */
-    getLoginUrl(returnUrl?: string): Promise<string>;
+    getLoginUrl(returnUrl?: string, options?: LoginOptions): Promise<string>;
     /**
      * 弹窗模式 SSO 登录
      *
@@ -200,9 +218,11 @@ declare class SsoClient {
      * 成功后 token 自动保存到 token 存储（默认 sessionStorage，可通过 setTokenStorage 定制）。
      *
      * @param callbackUrl - 完整的回调 URL（window.location.href）
-     * @returns TokenData 或 null
+     * @returns TokenData；prompt=none 静默探测且无 SSO 会话时返回 null
+     *   （IdP 回跳 login_required / consent_required / interaction_required
+     *   且回调 state 与探测标记匹配），此时临时数据已清理，调用方按"未登录"处理即可
      */
-    handleCallback(callbackUrl: string): Promise<TokenData>;
+    handleCallback(callbackUrl: string): Promise<TokenData | null>;
     /**
      * 刷新 Access Token
      *
@@ -270,7 +290,7 @@ declare class SsoClient {
  * 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" | "id_token_nonce_mismatch";
+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" | "id_token_nonce_mismatch" | "logout_token_invalid" | "logout_token_unsupported_alg" | "logout_token_invalid_signature" | "logout_token_issuer_mismatch" | "logout_token_audience_mismatch" | "logout_token_expired" | "logout_token_replay";
 /**
  * SSO SDK 自定义错误
  */

package/dist/react/index.js

@@ -120,6 +120,7 @@ var STATE_KEY = "oauth_state";
 var NONCE_KEY = "oidc_nonce";
 var RETURN_URL_KEY = "return_url";
 var LOGOUT_STATE_KEY = "logout_state";
+var SILENT_PROBE_KEY = "silent_probe";
 function buildKey(base, clientId) {
   return clientId ? `${base}:${clientId}` : base;
 }
@@ -227,6 +228,15 @@ function getReturnUrl(clientId) {
 function removeReturnUrl(clientId) {
   _transient.remove(buildKey(RETURN_URL_KEY, clientId));
 }
+function saveSilentProbe(state, clientId) {
+  _transient.set(buildKey(SILENT_PROBE_KEY, clientId), state);
+}
+function getSilentProbe(clientId) {
+  return _transient.get(buildKey(SILENT_PROBE_KEY, clientId));
+}
+function removeSilentProbe(clientId) {
+  _transient.remove(buildKey(SILENT_PROBE_KEY, clientId));
+}
 function clearAllSsoData(clientId) {
   if (clientId) {
     removeTokenData(clientId);
@@ -234,6 +244,7 @@ function clearAllSsoData(clientId) {
     removeOAuthNonce(clientId);
     removeReturnUrl(clientId);
     removeLogoutState(clientId);
+    removeSilentProbe(clientId);
     removePkceVerifier(clientId);
     removePkceVerifier(`${clientId}_popup_nonce`);
     return;
@@ -243,6 +254,7 @@ function clearAllSsoData(clientId) {
   removeOAuthNonce();
   removeReturnUrl();
   removeLogoutState();
+  removeSilentProbe();
   const prefix = STORAGE_PREFIX + VERIFIER_KEY_PREFIX;
   const stores = [
     typeof sessionStorage !== "undefined" ? sessionStorage : null,
@@ -502,6 +514,11 @@ async function validateIdToken(idToken, accessToken, expectedIssuer, expectedCli
 }
 
 // src/core/SsoClient.ts
+var SILENT_PROBE_ERRORS = /* @__PURE__ */ new Set([
+  "login_required",
+  "consent_required",
+  "interaction_required"
+]);
 var _SsoClient = class _SsoClient {
   constructor(config) {
     this._discovery = null;
@@ -595,12 +612,15 @@ var _SsoClient = class _SsoClient {
    *
    * @param returnUrl - 登录成功后的返回地址（可选，保存到 sessionStorage；
    *   仅允许相对路径或同源绝对 URL，否则忽略并告警）
+   * @param options.prompt - OIDC prompt 参数。传 "none" 为静默探测：
+   *   额外在存储中记录探测标记（该次请求的 state），回调无会话时
+   *   handleCallback() 返回 null 而不抛错。
    *
    * ⚠️ 不要与 getLoginUrl() 混用：两者都会重新生成并覆盖 sessionStorage 中的
    * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
    * 同一次登录只使用其中一个入口。
    */
-  async login(returnUrl) {
+  async login(returnUrl, options = {}) {
     const verifier = generateCodeVerifier();
     const challenge = await generateCodeChallenge(verifier);
     const state = generateState();
@@ -608,6 +628,11 @@ var _SsoClient = class _SsoClient {
     savePkceVerifier(this.config.clientId, verifier);
     saveOAuthState(state, this.config.clientId);
     saveOAuthNonce(nonce, this.config.clientId);
+    if (options.prompt === "none") {
+      saveSilentProbe(state, this.config.clientId);
+    } else {
+      removeSilentProbe(this.config.clientId);
+    }
     if (returnUrl) {
       this._saveReturnUrlIfTrusted(returnUrl);
     }
@@ -621,6 +646,9 @@ var _SsoClient = class _SsoClient {
     params.set("nonce", nonce);
     params.set("code_challenge", challenge);
     params.set("code_challenge_method", "S256");
+    if (options.prompt) {
+      params.set("prompt", options.prompt);
+    }
     window.location.href = `${authorizeEndpoint}?${params.toString()}`;
   }
   /**
@@ -632,7 +660,7 @@ var _SsoClient = class _SsoClient {
    * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
    * 同一次登录只使用其中一个入口。
    */
-  async getLoginUrl(returnUrl) {
+  async getLoginUrl(returnUrl, options = {}) {
     const verifier = generateCodeVerifier();
     const challenge = await generateCodeChallenge(verifier);
     const state = generateState();
@@ -640,6 +668,11 @@ var _SsoClient = class _SsoClient {
     savePkceVerifier(this.config.clientId, verifier);
     saveOAuthState(state, this.config.clientId);
     saveOAuthNonce(nonce, this.config.clientId);
+    if (options.prompt === "none") {
+      saveSilentProbe(state, this.config.clientId);
+    } else {
+      removeSilentProbe(this.config.clientId);
+    }
     if (returnUrl) this._saveReturnUrlIfTrusted(returnUrl);
     const authorizeEndpoint = await this._getAuthorizeEndpoint();
     const params = new URLSearchParams();
@@ -651,6 +684,9 @@ var _SsoClient = class _SsoClient {
     params.set("nonce", nonce);
     params.set("code_challenge", challenge);
     params.set("code_challenge_method", "S256");
+    if (options.prompt) {
+      params.set("prompt", options.prompt);
+    }
     return `${authorizeEndpoint}?${params.toString()}`;
   }
   /**
@@ -763,7 +799,15 @@ var _SsoClient = class _SsoClient {
           if (popup && !popup.closed) {
             popup.close();
           }
-          this.handleCallback(event.data.callbackUrl).then(resolve).catch(reject);
+          this.handleCallback(event.data.callbackUrl).then((tokenData) => {
+            if (tokenData === null) {
+              reject(
+                new SsoError("not_authenticated", "SSO \u4F1A\u8BDD\u4E0D\u5B58\u5728\uFF08\u9759\u9ED8\u63A2\u6D4B\u65E0\u4F1A\u8BDD\uFF09")
+              );
+              return;
+            }
+            resolve(tokenData);
+          }).catch(reject);
         };
         const pollTimer = setInterval(() => {
           if (popup.closed) {
@@ -801,16 +845,29 @@ var _SsoClient = class _SsoClient {
    * 成功后 token 自动保存到 token 存储（默认 sessionStorage，可通过 setTokenStorage 定制）。
    *
    * @param callbackUrl - 完整的回调 URL（window.location.href）
-   * @returns TokenData 或 null
+   * @returns TokenData；prompt=none 静默探测且无 SSO 会话时返回 null
+   *   （IdP 回跳 login_required / consent_required / interaction_required
+   *   且回调 state 与探测标记匹配），此时临时数据已清理，调用方按"未登录"处理即可
    */
   async handleCallback(callbackUrl) {
     const url = new URL(callbackUrl);
     const params = url.searchParams;
     const error = params.get("error");
     if (error) {
+      const returnedErrorState = params.get("state");
+      const probeState = getSilentProbe(this.config.clientId);
+      const savedStateForProbe = getOAuthState(this.config.clientId);
+      if (SILENT_PROBE_ERRORS.has(error) && probeState && savedStateForProbe && timingSafeEqualString(savedStateForProbe, returnedErrorState ?? "") && timingSafeEqualString(probeState, returnedErrorState ?? "")) {
+        removeOAuthState(this.config.clientId);
+        removeOAuthNonce(this.config.clientId);
+        removePkceVerifier(this.config.clientId);
+        removeSilentProbe(this.config.clientId);
+        return null;
+      }
       removeOAuthState(this.config.clientId);
       removeOAuthNonce(this.config.clientId);
       removePkceVerifier(this.config.clientId);
+      removeSilentProbe(this.config.clientId);
       const desc = params.get("error_description") || error;
       throw new SsoError(mapOAuthErrorToSsoCode(error), `\u6388\u6743\u5931\u8D25: ${desc}`);
     }
@@ -820,6 +877,7 @@ var _SsoClient = class _SsoClient {
       removeOAuthState(this.config.clientId);
       removeOAuthNonce(this.config.clientId);
       removePkceVerifier(this.config.clientId);
+      removeSilentProbe(this.config.clientId);
       throw new SsoError("token_request_failed", "\u56DE\u8C03 URL \u4E2D\u7F3A\u5C11 authorization code");
     }
     const savedState = getOAuthState(this.config.clientId);
@@ -827,6 +885,7 @@ var _SsoClient = class _SsoClient {
       removeOAuthState(this.config.clientId);
       removeOAuthNonce(this.config.clientId);
       removePkceVerifier(this.config.clientId);
+      removeSilentProbe(this.config.clientId);
       throw new SsoError(
         "state_mismatch",
         "State \u53C2\u6570\u4E0D\u5339\u914D\uFF0C\u53EF\u80FD\u5B58\u5728 CSRF \u653B\u51FB"
@@ -890,6 +949,7 @@ var _SsoClient = class _SsoClient {
     removeOAuthState(this.config.clientId);
     removeOAuthNonce(this.config.clientId);
     removePkceVerifier(this.config.clientId);
+    removeSilentProbe(this.config.clientId);
     const now = Date.now();
     const tokenData = {
       access_token: data.access_token,
@@ -1532,6 +1592,14 @@ function CallbackPage({ onSuccess, onError, renderError } = {}) {
       try {
         const tokenData = await client.handleCallback(window.location.href);
         if (cancelled) return;
+        if (tokenData === null) {
+          const clientId2 = client.config.clientId;
+          const probeReturnUrl = getReturnUrl(clientId2);
+          removeReturnUrl(clientId2);
+          const target = probeReturnUrl && isTrustedReturnUrl(probeReturnUrl, window.location.origin) ? probeReturnUrl : "/";
+          window.location.href = target + (target.includes("?") ? "&" : "?") + "sso_probe=no_session";
+          return;
+        }
         await refreshUser();
         if (cancelled) return;
         const clientId = client.config.clientId;