@nihplod/sso-sdk 1.1.0 → 1.2.1

package/README.md

@@ -23,6 +23,8 @@ const sso = new SsoClient({
 await sso.login();
 
 // 2. Handle callback (inside the callback page)
+//    Token is persisted to sessionStorage by default, so it survives
+//    the full-page redirect back from the SSO center.
 const token = await sso.handleCallback(window.location.href);
 
 // 3. Get user info
@@ -60,6 +62,8 @@ Initiate SSO login. Generates PKCE parameters and redirects to the SSO login pag
 
 Build the login URL string without redirecting. Returns `Promise<string>`.
 
+> ⚠️ 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.
+
 ### `sso.handleCallback(callbackUrl)`
 
 Handle the OAuth callback. Parses `code` and `state` from the URL, validates state, and exchanges the code for tokens.
@@ -113,13 +117,26 @@ Clear local token data and attempt to revoke the server-side refresh_token.
 |------|------|------|------|
 | `redirectToSso` | `boolean` | `false` | Whether to redirect to the SSO logout page (OIDC RP-Initiated Logout) |
 
-When `redirectToSso=true`, the user is redirected to `/logout?client_id=...&post_logout_redirect_uri=...`. The main site clears the session and then returns to the sub-project callback address.
+When `redirectToSso=true`, the user is redirected to the `end_session_endpoint` from OIDC Discovery (fallback: `/api/oauth/end-session`) with `client_id`, `post_logout_redirect_uri`, `id_token_hint` and `state` parameters. The generated `state` is saved to sessionStorage; the main site clears the session and then returns to the sub-project callback address. Validate the `state` on the return page with `sso.validateLogoutState()` to prevent logout CSRF.
+
+### `sso.validateLogoutState(url)`
+
+Validate the `state` parameter of an RP-Initiated Logout redirect-back (logout CSRF protection). Call this on the page that `post_logout_redirect_uri` points to. Returns `true` only when the URL carries a `state` matching the one saved by `sso.logout(true)`; on success the saved state is cleared (one-time).
+
+```typescript
+// On the post_logout_redirect_uri page:
+if (sso.validateLogoutState(window.location.href)) {
+  // Trusted redirect-back from the SSO logout page
+}
+```
+
+Returns `boolean`.
 
 ### `sso.getDiscovery()`
 
 Fetch the OIDC Discovery document.
 
-Returns `Promise<OidcDiscovery>`.
+Returns `Promise<OidcDiscovery | null>` — may be `null` when the discovery endpoint is unreachable and no cached document exists.
 
 ---
 
@@ -204,6 +221,7 @@ const {
   user,              // SsoUser | null
   isAuthenticated,   // boolean
   isLoading,         // boolean
+  error,             // SsoError | null — set when loading user info fails (e.g. session revoked)
   login,             // (returnUrl?: string) => Promise<void>
   logout,            // (redirectToSso?: boolean) => Promise<void>
   refreshUser,       // () => Promise<void>
@@ -212,6 +230,8 @@ const {
 } = useSso();
 ```
 
+Authentication state is three-valued: `isLoading` (initializing/refreshing) → `error` (load failed, e.g. session expired) → `user` (authenticated). Render your UI accordingly.
+
 ### `<RequireAuth>`
 
 ```tsx
@@ -222,6 +242,21 @@ import { RequireAuth } from "@nihplod/sso-sdk/react";
 </RequireAuth>
 ```
 
+If starting the login flow fails (e.g. the user closes the popup, `popup_closed`), the component resets its internal trigger flag and shows a retry entry point instead of getting stuck on "please log in". Use `onError` to observe the failure and `renderLoginError(error, retry)` to customize the UI.
+
+```tsx
+<RequireAuth
+  autoLogin
+  usePopup
+  onError={(err) => console.warn("login failed", err)}
+  renderLoginError={(err, retry) => (
+    <button onClick={retry}>登录未完成，点击重试</button>
+  )}
+>
+  <ProtectedContent />
+</RequireAuth>
+```
+
 ### `withAuth(Component)`
 
 ```tsx
@@ -242,6 +277,23 @@ export default function AuthCallback() {
 }
 ```
 
+By default the component performs a full-page redirect (`window.location.href`) to the saved `returnUrl` (or `/`) after the token exchange — safe because tokens are persisted to sessionStorage by default. For SPAs that prefer router navigation (no page reload, app state preserved), pass `onSuccess` to take over the redirect; `onError` / `renderError` customize failure handling:
+
+```tsx
+function CallbackRoute() {
+  const navigate = useNavigate();
+  return (
+    <CallbackPage
+      onSuccess={(tokenData) => navigate("/dashboard", { replace: true })}
+      onError={(err) => console.warn("sso callback failed", err)}
+      renderError={(message) => <MyErrorPage message={message} />}
+    />
+  );
+}
+```
+
+The default error UI is also exported as `DefaultCallbackError` if you want to reuse it.
+
 ---
 
 ## Next.js Bindings
@@ -257,7 +309,7 @@ export const middleware = createSsoMiddleware({
   ssoBaseUrl: "https://nihplod.cn",
   redirectUri: "https://yourapp.com/api/auth/callback",
   scopes: "openid profile",
-  publicPaths: ["/", "/public"],
+  publicPaths: ["/", "/public", "/api/auth/logout"],
   // Confidential Client (BFF) can pass clientSecret
   // clientSecret: process.env.SSO_CLIENT_SECRET,
   // validateSsoCookie defaults to true: the middleware calls the introspection
@@ -265,6 +317,12 @@ export const middleware = createSsoMiddleware({
   // "cookie exists = logged in" semantics (lowest latency, but may pass revoked
   // sessions). Either way, the middleware is only a UX gate — always re-verify
   // tokens in Route Handlers / Server Components before serving sensitive data.
+  // insecureLocalDev: false by default; set true ONLY for http://localhost
+  // development (disables the Secure cookie attribute and strips __Host-/__Secure-
+  // prefixes, which browsers refuse to write over HTTP). Must be set consistently
+  // on the middleware, callback and logout handlers. Never enable in production —
+  // as a safety guard, the option is force-ignored (with a warning) when
+  // NODE_ENV=production and ssoBaseUrl uses https, keeping cookies secure.
 });
 
 export const config = {
@@ -272,6 +330,13 @@ export const config = {
 };
 ```
 
+> **Token expiry behavior (expected):** the middleware does NOT refresh tokens. When the
+> `access_token` cookie expires or fails introspection, the middleware clears it and
+> redirects to `/api/oauth/authorize`. Because the user still holds an SSO session on the
+> main site, the authorize endpoint immediately redirects back with a fresh authorization
+> code (silent re-auth), and the callback handler issues new cookies — the user typically
+> only sees a quick redirect loop through the SSO center. No client-side action is needed.
+
 ```typescript
 // src/app/api/auth/callback/route.ts
 import { createCallbackRouteHandler } from "@nihplod/sso-sdk/next";
@@ -325,13 +390,15 @@ Default cookie names:
 | 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 |
 
-> For local development with `http://localhost`, the browser will reject `Secure` cookies. You may disable `secure` locally, but HTTPS is mandatory in production.
+> For local development with `http://localhost`, browsers reject `Secure` cookies — and cookies named with `__Host-`/`__Secure-` prefixes are refused outright when `Secure` is missing (Chrome, Edge and Firefox all enforce this; behavior on `localhost` varies by browser, some treat it as a secure context for `Secure` cookies, none accept prefixed names without `Secure`). The visible symptom: the login callback appears to succeed but the cookies are never written, so the middleware keeps judging you as logged out and redirects to the SSO authorize page in an infinite loop. Fix: set `insecureLocalDev: true` on `createSsoMiddleware`, `createCallbackRouteHandler` and `createLogoutRouteHandler` (it disables `Secure` and strips the prefixes, with a startup warning), or serve local dev over HTTPS. HTTPS is mandatory in production — and as a production guard, all three helpers force-ignore `insecureLocalDev` (keeping `Secure` and the `__Host-`/`__Secure-` prefixes, with a warning) when `NODE_ENV=production` and `ssoBaseUrl` uses HTTPS.
 
 ---
 
 ## Security Recommendations and Token Storage
 
-By default, the SDK stores tokens in **memory**. Public Clients (SPA / mobile / desktop) should **never** write the `refresh_token` to `localStorage` to prevent XSS from stealing long-lived credentials.
+By default, the SDK stores tokens in **sessionStorage** (tab-scoped persistence). This keeps the login state across page reloads and the full-page redirect that `CallbackPage` performs after the token exchange, while the data is cleared automatically when the tab closes and is never shared with other tabs. In SSR environments or privacy modes where `sessionStorage` is unavailable/unwritable, it falls back to an in-memory map (login state is lost on reload in that case).
+
+> ⚠️ 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.
 
@@ -369,6 +436,6 @@ const challenge = await generateCodeChallenge(verifier);
 // State
 const state = generateState();
 
-// Custom token storage (default is memory storage)
+// Custom token storage (default is sessionStorage; persist: true → localStorage)
 setTokenStorage(createSecureStorage({ persist: false }));
 ```

package/dist/index.d.mts

@@ -2,8 +2,10 @@
  * 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；
@@ -34,12 +36,13 @@ interface TokenStorage {
 /**
  * 创建存储实现
  *
- * @param options.persist 是否持久化到 localStorage。默认 false（内存存储）。
+ * @param options.persist 是否持久化到 localStorage。默认 false（sessionStorage）。
+ *   - false（默认）：sessionStorage，标签页级持久化（刷新/整页跳转后登录态保留，
+ *     关闭标签页即清除），多 Tab 间不共享；隐私模式等写入失败时降级为内存。
+ *   - true：localStorage，多 Tab 共享、关闭浏览器后仍保留。
  *   ⚠️ 安全警告：persist=true 会将 refresh_token 明文写入 localStorage，
  *   任何 XSS 均可在不被检测的情况下读取。仅在 BFF/Confidential Client
  *   且 refresh_token 不直接暴露给浏览器的场景下使用。
- *   - Confidential/BFF 子项目可设为 true。
- *   - Public Client 在浏览器中应保持 false（默认）。
  */
 declare function createSecureStorage(options?: {
     persist?: boolean;
@@ -61,6 +64,9 @@ declare function removePkceVerifier(clientId: string): void;
 declare function saveOAuthState(state: string, clientId?: string): void;
 declare function getOAuthState(clientId?: string): string | null;
 declare function removeOAuthState(clientId?: string): void;
+declare function saveLogoutState(state: string, clientId?: string): void;
+declare function getLogoutState(clientId?: string): string | null;
+declare function removeLogoutState(clientId?: string): void;
 declare function saveReturnUrl(url: string, clientId?: string): void;
 declare function getReturnUrl(clientId?: string): string | null;
 declare function removeReturnUrl(clientId?: string): void;
@@ -110,7 +116,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;
 }
@@ -173,12 +184,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>;
     /**
@@ -223,7 +242,7 @@ declare class SsoClient {
      * 处理 OAuth 回调
      *
      * 解析回调 URL，校验 state 参数，用授权码交换 token。
-     * 成功后 token 自动保存到 token 存储（默认内存，可通过 setTokenStorage 定制）。
+     * 成功后 token 自动保存到 token 存储（默认 sessionStorage，可通过 setTokenStorage 定制）。
      *
      * @param callbackUrl - 完整的回调 URL（window.location.href）
      * @returns TokenData 或 null
@@ -261,9 +280,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 文档
      *
@@ -332,8 +370,9 @@ declare class SsoError extends Error {
 /**
  * OAuth 2.0 协议层错误（RFC 6749 §5.2）
  *
- * 用于表示服务端原样返回的 OAuth 错误（error / error_description / error_uri），
- * 与 SDK 语义的 SsoError 区分。
+ * 保留用于表示服务端原样返回的 OAuth 错误（error / error_description / error_uri），
+ * 与 SDK 语义的 SsoError 区分。当前 SDK 内部不抛出此类型（统一使用 SsoError +
+ * mapOAuthErrorToSsoCode 映射），作为公共类型导出供子项目自行解析 OAuth 响应时使用。
  */
 declare class OAuthError extends Error {
     readonly code: string;
@@ -348,6 +387,8 @@ declare class OAuthError extends Error {
 /**
  * 校验 returnUrl 是否可信（防开放重定向）。
  * 仅允许：相对路径（且不以 // 开头）或与 currentOrigin 完全同源的绝对 URL。
+ * 拒绝一切含反斜杠 \ 的值：浏览器会把 "/\evil.com" 归一化为 "//evil.com"，
+ * 形成协议相对 URL 开放重定向。
  */
 declare function isTrustedReturnUrl(url: string, currentOrigin: string): boolean;
 /**
@@ -356,4 +397,4 @@ declare function isTrustedReturnUrl(url: string, currentOrigin: string): boolean
  */
 declare function timingSafeEqualString(a: string, b: string): boolean;
 
-export { OAuthError, type OidcDiscovery, SsoClient, type SsoClientConfig, SsoError, type SsoErrorCode, type SsoUser, type TokenData, type TokenResponse, type TokenStorage, clearAllSsoData, clearVerifiersForClients, createSecureStorage, generateCodeChallenge, generateCodeVerifier, generateState, getOAuthState, getPkceVerifier, getReturnUrl, getTokenData, getTokenStorage, isTrustedReturnUrl, mapOAuthErrorToSsoCode, removeOAuthState, removePkceVerifier, removeReturnUrl, removeTokenData, saveOAuthState, savePkceVerifier, saveReturnUrl, saveTokenData, setTokenStorage, timingSafeEqualString };
+export { OAuthError, type OidcDiscovery, SsoClient, type SsoClientConfig, SsoError, type SsoErrorCode, type SsoUser, type TokenData, type TokenResponse, type TokenStorage, clearAllSsoData, clearVerifiersForClients, createSecureStorage, generateCodeChallenge, generateCodeVerifier, generateState, getLogoutState, getOAuthState, getPkceVerifier, getReturnUrl, getTokenData, getTokenStorage, isTrustedReturnUrl, mapOAuthErrorToSsoCode, removeLogoutState, removeOAuthState, removePkceVerifier, removeReturnUrl, removeTokenData, saveLogoutState, saveOAuthState, savePkceVerifier, saveReturnUrl, saveTokenData, setTokenStorage, timingSafeEqualString };

package/dist/index.d.ts

@@ -2,8 +2,10 @@
  * 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；
@@ -34,12 +36,13 @@ interface TokenStorage {
 /**
  * 创建存储实现
  *
- * @param options.persist 是否持久化到 localStorage。默认 false（内存存储）。
+ * @param options.persist 是否持久化到 localStorage。默认 false（sessionStorage）。
+ *   - false（默认）：sessionStorage，标签页级持久化（刷新/整页跳转后登录态保留，
+ *     关闭标签页即清除），多 Tab 间不共享；隐私模式等写入失败时降级为内存。
+ *   - true：localStorage，多 Tab 共享、关闭浏览器后仍保留。
  *   ⚠️ 安全警告：persist=true 会将 refresh_token 明文写入 localStorage，
  *   任何 XSS 均可在不被检测的情况下读取。仅在 BFF/Confidential Client
  *   且 refresh_token 不直接暴露给浏览器的场景下使用。
- *   - Confidential/BFF 子项目可设为 true。
- *   - Public Client 在浏览器中应保持 false（默认）。
  */
 declare function createSecureStorage(options?: {
     persist?: boolean;
@@ -61,6 +64,9 @@ declare function removePkceVerifier(clientId: string): void;
 declare function saveOAuthState(state: string, clientId?: string): void;
 declare function getOAuthState(clientId?: string): string | null;
 declare function removeOAuthState(clientId?: string): void;
+declare function saveLogoutState(state: string, clientId?: string): void;
+declare function getLogoutState(clientId?: string): string | null;
+declare function removeLogoutState(clientId?: string): void;
 declare function saveReturnUrl(url: string, clientId?: string): void;
 declare function getReturnUrl(clientId?: string): string | null;
 declare function removeReturnUrl(clientId?: string): void;
@@ -110,7 +116,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;
 }
@@ -173,12 +184,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>;
     /**
@@ -223,7 +242,7 @@ declare class SsoClient {
      * 处理 OAuth 回调
      *
      * 解析回调 URL，校验 state 参数，用授权码交换 token。
-     * 成功后 token 自动保存到 token 存储（默认内存，可通过 setTokenStorage 定制）。
+     * 成功后 token 自动保存到 token 存储（默认 sessionStorage，可通过 setTokenStorage 定制）。
      *
      * @param callbackUrl - 完整的回调 URL（window.location.href）
      * @returns TokenData 或 null
@@ -261,9 +280,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 文档
      *
@@ -332,8 +370,9 @@ declare class SsoError extends Error {
 /**
  * OAuth 2.0 协议层错误（RFC 6749 §5.2）
  *
- * 用于表示服务端原样返回的 OAuth 错误（error / error_description / error_uri），
- * 与 SDK 语义的 SsoError 区分。
+ * 保留用于表示服务端原样返回的 OAuth 错误（error / error_description / error_uri），
+ * 与 SDK 语义的 SsoError 区分。当前 SDK 内部不抛出此类型（统一使用 SsoError +
+ * mapOAuthErrorToSsoCode 映射），作为公共类型导出供子项目自行解析 OAuth 响应时使用。
  */
 declare class OAuthError extends Error {
     readonly code: string;
@@ -348,6 +387,8 @@ declare class OAuthError extends Error {
 /**
  * 校验 returnUrl 是否可信（防开放重定向）。
  * 仅允许：相对路径（且不以 // 开头）或与 currentOrigin 完全同源的绝对 URL。
+ * 拒绝一切含反斜杠 \ 的值：浏览器会把 "/\evil.com" 归一化为 "//evil.com"，
+ * 形成协议相对 URL 开放重定向。
  */
 declare function isTrustedReturnUrl(url: string, currentOrigin: string): boolean;
 /**
@@ -356,4 +397,4 @@ declare function isTrustedReturnUrl(url: string, currentOrigin: string): boolean
  */
 declare function timingSafeEqualString(a: string, b: string): boolean;
 
-export { OAuthError, type OidcDiscovery, SsoClient, type SsoClientConfig, SsoError, type SsoErrorCode, type SsoUser, type TokenData, type TokenResponse, type TokenStorage, clearAllSsoData, clearVerifiersForClients, createSecureStorage, generateCodeChallenge, generateCodeVerifier, generateState, getOAuthState, getPkceVerifier, getReturnUrl, getTokenData, getTokenStorage, isTrustedReturnUrl, mapOAuthErrorToSsoCode, removeOAuthState, removePkceVerifier, removeReturnUrl, removeTokenData, saveOAuthState, savePkceVerifier, saveReturnUrl, saveTokenData, setTokenStorage, timingSafeEqualString };
+export { OAuthError, type OidcDiscovery, SsoClient, type SsoClientConfig, SsoError, type SsoErrorCode, type SsoUser, type TokenData, type TokenResponse, type TokenStorage, clearAllSsoData, clearVerifiersForClients, createSecureStorage, generateCodeChallenge, generateCodeVerifier, generateState, getLogoutState, getOAuthState, getPkceVerifier, getReturnUrl, getTokenData, getTokenStorage, isTrustedReturnUrl, mapOAuthErrorToSsoCode, removeLogoutState, removeOAuthState, removePkceVerifier, removeReturnUrl, removeTokenData, saveLogoutState, saveOAuthState, savePkceVerifier, saveReturnUrl, saveTokenData, setTokenStorage, timingSafeEqualString };