@nihplod/sso-sdk 1.3.0 → 1.4.0

package/README.md

@@ -50,29 +50,47 @@ Create an SSO client instance.
 | `scopes` | `string` | ❌ | Space-separated scopes, default `"openid profile"` |
 | `clientSecret` | `string` | ❌ | **Only for Confidential Clients**. Do NOT pass this in browser SPA (Public Client) to avoid leaking secrets. BFF / Next.js Route Handlers may pass it. |
 
-### `sso.login(returnUrl?)`
+### `sso.login(returnUrl?, options?)`
 
 Initiate SSO login. Generates PKCE parameters and redirects to the SSO login page.
 
 | Parameter | Type | Description |
 |------|------|------|
 | `returnUrl` | `string` | Optional URL to return to after login |
+| `options.prompt` | `"none" \| "login" \| "consent"` | Optional OIDC `prompt` parameter, passed through to the authorize URL |
 
-### `sso.getLoginUrl(returnUrl?)`
+### `sso.getLoginUrl(returnUrl?, options?)`
 
-Build the login URL string without redirecting. Returns `Promise<string>`.
+Build the login URL string without redirecting. Returns `Promise<string>`. Accepts the same `options.prompt` as `login()`.
 
 > ⚠️ Do NOT mix `getLoginUrl()` with `login()` for the same login attempt: both regenerate and overwrite the `state` / PKCE verifier in sessionStorage, so the flow started first will fail with a state mismatch. Use only one entry point per login.
 
+#### Silent session probe (`prompt: "none"`)
+
+Passing `prompt: "none"` starts a **silent probe**: if the user still has a session on the SSO center, the authorize endpoint redirects straight back with a code and login completes without UI; if not, the IdP redirects back with `error=login_required` (or `consent_required` / `interaction_required`). When you start the probe via `login()` / `getLoginUrl()`, the SDK records a probe marker alongside `state`; `handleCallback()` then recognizes the matching error callback, cleans up the transient data and returns `null` instead of throwing — treat `null` as "no SSO session". The default `<CallbackPage>` redirects back to your `returnUrl` with `sso_probe=no_session` appended.
+
+```typescript
+// Triggered by an explicit user action (e.g. clicking "继续 NIHPLOD 账户"):
+await sso.login("/dashboard", { prompt: "none" });
+
+// On the page returnUrl points to:
+const params = new URLSearchParams(location.search);
+if (params.get("sso_probe") === "no_session") {
+  // No SSO session — fall back to the normal interactive login button
+}
+```
+
+> ⚠️ Do NOT auto-probe on page load: it round-trips every visitor through the SSO center and adds latency for users without a session. Always trigger it from a deliberate user action (click).
+
 ### `sso.handleCallback(callbackUrl)`
 
-Handle the OAuth callback. Parses `code` and `state` from the URL, validates state, and exchanges the code for tokens.
+Handle the OAuth callback. Parses `code` and `state` from the URL, validates state, and exchanges the code for tokens. When an `id_token` is present, the SDK verifies its signature, issuer, audience, expiry and `at_hash`, and — when the login was initiated via `login()` / `getLoginUrl()` / `loginPopup()` — also validates the OIDC `nonce` claim against the value generated at login time (constant-time comparison, fail-closed, protecting against ID Token replay).
 
 | Parameter | Type | Description |
 |------|------|------|
 | `callbackUrl` | `string` | Full callback URL (`window.location.href`) |
 
-Returns `Promise<TokenData>`.
+Returns `Promise<TokenData | null>` — `null` only when a silent probe (`prompt: "none"`) finds no SSO session (see above).
 
 ### `sso.refreshToken()`
 
@@ -361,15 +379,39 @@ const handler = createLogoutRouteHandler({
   ssoBaseUrl: "https://nihplod.cn",
   redirectUri: "https://yourapp.com/api/auth/callback",
   postLogoutRedirectUri: "https://yourapp.com/",
-  redirectToSso: true,
+  // Logout scope: "local" (default) only signs out of THIS site (revoke
+  // refresh_token + clear cookies, redirect to the site home page);
+  // "global" additionally redirects to the SSO end-session endpoint to
+  // sign out of all NIHPLOD platforms (RP-Initiated Logout).
+  defaultScope: "local",
 });
 
 // Prefer POST to trigger logout (prevents logout CSRF via cross-site GET);
-// GET is kept for compatibility with plain <a> navigations.
+// a GET without a valid logout state does NOT log out — it returns a
+// confirmation page (HTML) whose form POSTs to the same endpoint.
 export const GET = handler;
 export const POST = handler;
 ```
 
+**Logout scopes (default changed):** the GET confirmation page now includes a "同时退出所有 NIHPLOD 平台" checkbox; when checked, the form POSTs `global=1` and the handler performs a global logout (end-session redirect) regardless of `defaultScope`. A POST without a `global` field uses `defaultScope`. If you trigger logout from your own fetch call, add `global=1` to the form body to opt into a global logout.
+
+> **Migration:** `redirectToSso` is deprecated and logs a one-time warning. `redirectToSso: true` → `defaultScope: "global"`; `redirectToSso: false` → `defaultScope: "local"`. Note the default changed from "redirect to SSO" to **local logout** — pass `defaultScope: "global"` to keep the old behavior.
+
+```typescript
+// src/app/api/auth/backchannel-logout/route.ts
+import { createBackchannelLogoutRouteHandler } from "@nihplod/sso-sdk/next";
+
+export const POST = createBackchannelLogoutRouteHandler({
+  clientId: "...",
+  ssoBaseUrl: "https://nihplod.cn",
+  onLogout: async ({ sub, sid }) => {
+    // Clear your own server-side session for this user/session
+  },
+});
+```
+
+The backchannel handler receives `logout_token` pushes from the SSO center (OIDC Back-Channel Logout) when the user signs out globally or revokes consent, verifies the token (RS256 signature via JWKS, issuer/audience/expiry, `events` claim, `jti` replay protection), clears the SSO cookies, and calls your `onLogout` hook. If the hook throws, it responds 500 so the IdP retries delivery. **Remember to register this route's public URL as `backchannelLogoutUri` in the SSO admin console for your client.**
+
 Trigger the logout endpoint with a POST request (recommended):
 
 ```tsx
@@ -378,7 +420,7 @@ Trigger the logout endpoint with a POST request (recommended):
 </button>
 ```
 
-A plain `<a href="/api/auth/logout">` still works via GET, but note it can be triggered cross-site (logout CSRF).
+A plain `<a href="/api/auth/logout">` navigation (GET) renders the built-in confirmation page instead of logging out directly, so cross-site image/prefetch requests can no longer trigger a logout (logout CSRF protection). Only a POST — or a GET carrying a valid RP-Initiated Logout `state` — performs the logout.
 
 ### Cookie Configuration
 
@@ -389,6 +431,7 @@ Default cookie names:
 | access_token | `__Host-nihplod_sso_at` | Requires Secure + Path=/ + no Domain |
 | refresh_token | `__Host-nihplod_sso_rt` | Requires Secure + Path=/ + no Domain |
 | state | `__Host-nihplod_sso_state` | Requires Secure + Path=/ + no Domain |
+| nonce | `__Host-nihplod_sso_nonce` | OIDC nonce for ID Token replay protection (validated fail-closed in the callback); Requires Secure + Path=/ + no Domain |
 | return_url | `__Host-nihplod_sso_return` | Requires Secure + Path=/ + no Domain |
 | verifier | `__Secure-nihplod_sso_verifier` | Requires Secure + no Domain; Path is the callback path, therefore uses `__Secure-` prefix |
 
@@ -402,7 +445,7 @@ By default, the SDK stores tokens in **sessionStorage** (tab-scoped persistence)
 
 > ⚠️ XSS note: any token readable by JavaScript can be stolen by XSS. sessionStorage narrows the exposure compared with `localStorage` (tab-scoped, auto-cleared), but a `refresh_token` readable by JS is still exfiltratable while the tab is open. If you need stronger guarantees, use the Next.js BFF pattern below (tokens in `httpOnly` cookies) or keep the refresh token inside a Service Worker.
 
-Transient OAuth data (PKCE `code_verifier`, `state`, `returnUrl`, popup nonce) is stored separately in **sessionStorage**, because it must survive the full-page redirect to the SSO center and back; it is cleared automatically when the tab closes. In SSR environments without `sessionStorage`, it falls back to an in-memory map.
+Transient OAuth data (PKCE `code_verifier`, `state`, OIDC `nonce`, `returnUrl`, popup nonce) is stored separately in **sessionStorage**, because it must survive the full-page redirect to the SSO center and back; it is cleared automatically when the tab closes. In SSR environments without `sessionStorage`, it falls back to an in-memory map.
 
 If the sub-project is a **Next.js BFF / Confidential Client**, you can store tokens in `localStorage` for multi-tab sharing:
 

package/dist/index.d.mts

@@ -7,7 +7,7 @@
  *   整页跳转与刷新后登录态保留，关闭标签页自动清除；SSR / 隐私模式写入失败时
  *   降级为内存 Map。对需要多 Tab 共享 token 或 BFF/Confidential Client 场景，
  *   可通过 setTokenStorage() 注入 localStorage 实现（如 createSecureStorage({ persist: true })）。
- * - 临时数据（PKCE verifier / state / returnUrl / popup nonce）：必须跨整页重定向存活
+ * - 临时数据（PKCE verifier / state / OIDC nonce / returnUrl / popup nonce）：必须跨整页重定向存活
  *   （login() 会 302 跳转到 SSO 中心再回来），因此默认写入 sessionStorage；
  *   SSR 等无 sessionStorage 环境自动降级为内存 Map。
  *
@@ -134,6 +134,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";
+}
 /** Token 响应 */
 interface TokenResponse {
     access_token: string;
@@ -195,12 +210,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 字符串）
      *
@@ -210,7 +228,7 @@ declare class SsoClient {
      * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
      * 同一次登录只使用其中一个入口。
      */
-    getLoginUrl(returnUrl?: string): Promise<string>;
+    getLoginUrl(returnUrl?: string, options?: LoginOptions): Promise<string>;
     /**
      * 弹窗模式 SSO 登录
      *
@@ -256,9 +274,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
      *
@@ -359,7 +379,7 @@ declare function generateState(): string;
  * 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";
+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";
 /**
  * 将 OAuth 2.0 服务端 error 字段映射到 SsoErrorCode
  *

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  *   整页跳转与刷新后登录态保留，关闭标签页自动清除；SSR / 隐私模式写入失败时
  *   降级为内存 Map。对需要多 Tab 共享 token 或 BFF/Confidential Client 场景，
  *   可通过 setTokenStorage() 注入 localStorage 实现（如 createSecureStorage({ persist: true })）。
- * - 临时数据（PKCE verifier / state / returnUrl / popup nonce）：必须跨整页重定向存活
+ * - 临时数据（PKCE verifier / state / OIDC nonce / returnUrl / popup nonce）：必须跨整页重定向存活
  *   （login() 会 302 跳转到 SSO 中心再回来），因此默认写入 sessionStorage；
  *   SSR 等无 sessionStorage 环境自动降级为内存 Map。
  *
@@ -134,6 +134,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";
+}
 /** Token 响应 */
 interface TokenResponse {
     access_token: string;
@@ -195,12 +210,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 字符串）
      *
@@ -210,7 +228,7 @@ declare class SsoClient {
      * state / PKCE verifier，先调用的那次授权流程将因 state 不匹配而失败。
      * 同一次登录只使用其中一个入口。
      */
-    getLoginUrl(returnUrl?: string): Promise<string>;
+    getLoginUrl(returnUrl?: string, options?: LoginOptions): Promise<string>;
     /**
      * 弹窗模式 SSO 登录
      *
@@ -256,9 +274,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
      *
@@ -359,7 +379,7 @@ declare function generateState(): string;
  * 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";
+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";
 /**
  * 将 OAuth 2.0 服务端 error 字段映射到 SsoErrorCode
  *

package/dist/index.js

@@ -136,8 +136,10 @@ var STORAGE_PREFIX = "nihplod_sso_";
 var TOKEN_KEY = "token";
 var VERIFIER_KEY_PREFIX = "pkce_verifier_";
 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;
 }
@@ -247,6 +249,15 @@ function getOAuthState(clientId) {
 function removeOAuthState(clientId) {
   _transient.remove(buildKey(STATE_KEY, clientId));
 }
+function saveOAuthNonce(nonce, clientId) {
+  _transient.set(buildKey(NONCE_KEY, clientId), nonce);
+}
+function getOAuthNonce(clientId) {
+  return _transient.get(buildKey(NONCE_KEY, clientId));
+}
+function removeOAuthNonce(clientId) {
+  _transient.remove(buildKey(NONCE_KEY, clientId));
+}
 function saveLogoutState(state, clientId) {
   _transient.set(buildKey(LOGOUT_STATE_KEY, clientId), state);
 }
@@ -265,20 +276,33 @@ 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);
     removeOAuthState(clientId);
+    removeOAuthNonce(clientId);
     removeReturnUrl(clientId);
     removeLogoutState(clientId);
+    removeSilentProbe(clientId);
     removePkceVerifier(clientId);
     removePkceVerifier(`${clientId}_popup_nonce`);
     return;
   }
   removeTokenData();
   removeOAuthState();
+  removeOAuthNonce();
   removeReturnUrl();
   removeLogoutState();
+  removeSilentProbe();
   const prefix = STORAGE_PREFIX + VERIFIER_KEY_PREFIX;
   const stores = [
     typeof sessionStorage !== "undefined" ? sessionStorage : null,
@@ -367,18 +391,21 @@ function normalizeIssuer(url) {
 var cachedJwks = null;
 var cachedDiscovery = null;
 var JWKS_CACHE_TTL_MS = 5 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 1e4;
 async function fetchDiscoveryDoc(baseUrl) {
   const now = Date.now();
   if (cachedDiscovery && cachedDiscovery.baseUrl === baseUrl && now - cachedDiscovery.fetchedAt < JWKS_CACHE_TTL_MS) {
     return cachedDiscovery.doc;
   }
   try {
-    const res = await fetch(`${baseUrl}/api/oauth/.well-known/openid-configuration`);
-    const doc = res.ok ? await res.json() : null;
+    const res = await fetch(`${baseUrl}/api/oauth/.well-known/openid-configuration`, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+    });
+    if (!res.ok) return null;
+    const doc = await res.json();
     cachedDiscovery = { baseUrl, doc, fetchedAt: now };
     return doc;
   } catch {
-    cachedDiscovery = { baseUrl, doc: null, fetchedAt: now };
     return null;
   }
 }
@@ -390,7 +417,10 @@ async function fetchJwks(baseUrl, options = {}) {
   const discovery = await fetchDiscoveryDoc(baseUrl);
   const jwksUri = discovery?.jwks_uri || `${baseUrl}/api/oauth/jwks`;
   try {
-    const res = await fetch(jwksUri, options.forceRefresh ? { cache: "no-cache" } : void 0);
+    const res = await fetch(jwksUri, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      ...options.forceRefresh ? { cache: "no-cache" } : {}
+    });
     if (!res.ok) return null;
     const jwks = await res.json();
     cachedJwks = { baseUrl, jwks, fetchedAt: now };
@@ -437,7 +467,7 @@ async function computeAtHash(accessToken) {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 async function validateIdToken(idToken, accessToken, expectedIssuer, expectedClientId, options = {}) {
-  const { rejectHs256WhenRs256Available = true } = options;
+  const { rejectHs256WhenRs256Available = true, expectedNonce } = options;
   const header = decodeJwtHeader(idToken);
   if (!header) {
     throw new SsoError("id_token_invalid", "ID Token \u683C\u5F0F\u9519\u8BEF");
@@ -527,10 +557,21 @@ async function validateIdToken(idToken, accessToken, expectedIssuer, expectedCli
       throw new SsoError("id_token_at_hash_mismatch", "ID Token at_hash \u4E0D\u5339\u914D");
     }
   }
+  if (expectedNonce !== void 0) {
+    const tokenNonce = typeof payload.nonce === "string" ? payload.nonce : "";
+    if (!tokenNonce || !timingSafeEqualString(expectedNonce, tokenNonce)) {
+      throw new SsoError("id_token_nonce_mismatch", "ID Token nonce \u4E0D\u5339\u914D");
+    }
+  }
   return { sub: payload.sub };
 }
 
 // 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;
@@ -624,17 +665,27 @@ 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();
+    const nonce = generateState();
     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);
     }
@@ -645,8 +696,12 @@ var _SsoClient = class _SsoClient {
     params.set("redirect_uri", this.config.redirectUri);
     params.set("scope", this.config.scopes || "openid profile");
     params.set("state", state);
+    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()}`;
   }
   /**
@@ -658,12 +713,19 @@ 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();
+    const nonce = generateState();
     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();
@@ -672,8 +734,12 @@ var _SsoClient = class _SsoClient {
     params.set("redirect_uri", this.config.redirectUri);
     params.set("scope", this.config.scopes || "openid profile");
     params.set("state", state);
+    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()}`;
   }
   /**
@@ -713,9 +779,11 @@ var _SsoClient = class _SsoClient {
     const verifier = generateCodeVerifier();
     const challenge = await generateCodeChallenge(verifier);
     const state = generateState();
+    const nonce = generateState();
     const popupNonce = generateState();
     savePkceVerifier(this.config.clientId, verifier);
     saveOAuthState(state, this.config.clientId);
+    saveOAuthNonce(nonce, this.config.clientId);
     savePkceVerifier(`${this.config.clientId}_popup_nonce`, popupNonce);
     if (options.returnUrl) {
       this._saveReturnUrlIfTrusted(options.returnUrl);
@@ -727,6 +795,7 @@ var _SsoClient = class _SsoClient {
     params.set("redirect_uri", this.config.redirectUri);
     params.set("scope", this.config.scopes || "openid profile");
     params.set("state", state);
+    params.set("nonce", nonce);
     params.set("code_challenge", challenge);
     params.set("code_challenge_method", "S256");
     params.set("popup_nonce", popupNonce);
@@ -751,6 +820,7 @@ var _SsoClient = class _SsoClient {
     if (!popup) {
       removePkceVerifier(this.config.clientId);
       removeOAuthState(this.config.clientId);
+      removeOAuthNonce(this.config.clientId);
       removePkceVerifier(`${this.config.clientId}_popup_nonce`);
       throw new SsoError(
         "popup_blocked",
@@ -770,12 +840,27 @@ var _SsoClient = class _SsoClient {
           const savedNonce = getPkceVerifier(`${this.config.clientId}_popup_nonce`);
           if (!savedNonce || !timingSafeEqualString(event.data.nonce ?? "", savedNonce)) return;
           removePkceVerifier(`${this.config.clientId}_popup_nonce`);
+          try {
+            event.source?.postMessage(
+              { type: "nihplod_sso_popup_ack", nonce: savedNonce },
+              event.origin
+            );
+          } catch {
+          }
           completed = true;
           cleanup();
           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,6 +886,7 @@ var _SsoClient = class _SsoClient {
     } catch (err) {
       removePkceVerifier(this.config.clientId);
       removeOAuthState(this.config.clientId);
+      removeOAuthNonce(this.config.clientId);
       removePkceVerifier(`${this.config.clientId}_popup_nonce`);
       throw err;
     }
@@ -812,15 +898,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}`);
     }
@@ -828,18 +928,23 @@ var _SsoClient = class _SsoClient {
     const returnedState = params.get("state");
     if (!code) {
       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);
     if (!savedState || !timingSafeEqualString(savedState, returnedState ?? "")) {
       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"
       );
     }
+    const expectedNonce = getOAuthNonce(this.config.clientId) ?? void 0;
     const verifier = getPkceVerifier(this.config.clientId);
     if (!verifier) {
       throw new SsoError(
@@ -886,7 +991,8 @@ var _SsoClient = class _SsoClient {
           data.id_token,
           data.access_token,
           this.config.ssoBaseUrl,
-          this.config.clientId
+          this.config.clientId,
+          { expectedNonce }
         );
       } catch (err) {
         removeTokenData(this.config.clientId);
@@ -894,7 +1000,9 @@ 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,