@nihplod/sso-sdk 1.0.1 → 1.2.0

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,9 +309,20 @@ 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
+  // endpoint to verify the SSO session cookie. Set to false only if you accept
+  // "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 = {
@@ -267,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";
@@ -284,21 +354,30 @@ export const GET = createCallbackRouteHandler({
 // src/app/api/auth/logout/route.ts
 import { createLogoutRouteHandler } from "@nihplod/sso-sdk/next";
 
-export const GET = createLogoutRouteHandler({
+const handler = createLogoutRouteHandler({
   clientId: "...",
   ssoBaseUrl: "https://nihplod.cn",
   redirectUri: "https://yourapp.com/api/auth/callback",
   postLogoutRedirectUri: "https://yourapp.com/",
   redirectToSso: true,
 });
+
+// Prefer POST to trigger logout (prevents logout CSRF via cross-site GET);
+// GET is kept for compatibility with plain <a> navigations.
+export const GET = handler;
+export const POST = handler;
 ```
 
-Use a standard `<a>` tag to trigger the logout endpoint:
+Trigger the logout endpoint with a POST request (recommended):
 
 ```tsx
-<a href="/api/auth/logout">Logout</a>
+<button onClick={() => fetch("/api/auth/logout", { method: "POST" }).then(() => location.assign("/"))}>
+  Logout
+</button>
 ```
 
+A plain `<a href="/api/auth/logout">` still works via GET, but note it can be triggered cross-site (logout CSRF).
+
 ### Cookie Configuration
 
 Default cookie names:
@@ -311,13 +390,17 @@ 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.
 
 If the sub-project is a **Next.js BFF / Confidential Client**, you can store tokens in `localStorage` for multi-tab sharing:
 
@@ -353,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

@@ -1,9 +1,15 @@
 /**
  * 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
@@ -27,6 +33,20 @@ interface TokenStorage {
     set(key: string, value: string): void;
     remove(key: string): void;
 }
+/**
+ * 创建存储实现
+ *
+ * @param options.persist 是否持久化到 localStorage。默认 false（sessionStorage）。
+ *   - false（默认）：sessionStorage，标签页级持久化（刷新/整页跳转后登录态保留，
+ *     关闭标签页即清除），多 Tab 间不共享；隐私模式等写入失败时降级为内存。
+ *   - true：localStorage，多 Tab 共享、关闭浏览器后仍保留。
+ *   ⚠️ 安全警告：persist=true 会将 refresh_token 明文写入 localStorage，
+ *   任何 XSS 均可在不被检测的情况下读取。仅在 BFF/Confidential Client
+ *   且 refresh_token 不直接暴露给浏览器的场景下使用。
+ */
+declare function createSecureStorage(options?: {
+    persist?: boolean;
+}): TokenStorage;
 /**
  * 设置自定义存储实现
  */
@@ -44,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;
@@ -85,6 +108,8 @@ interface SsoClientConfig {
     ssoBaseUrl: string;
     /** 请求的 scope（空格分隔），如 "openid profile phone" */
     scopes?: string;
+    /** RP-Initiated Logout 返回地址（可选）。不传时回退到 redirectUri */
+    postLogoutRedirectUri?: string;
 }
 /** 用户信息 */
 interface SsoUser {
@@ -141,26 +166,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
@@ -198,9 +275,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 文档
      *
@@ -247,9 +343,16 @@ 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" | "sso_server_error" | "network_error" | "id_token_invalid" | "id_token_unsupported_alg" | "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";
-/** OAuth 2.0 标准错误码 */
-type OAuthErrorCode = "invalid_request" | "invalid_client" | "invalid_grant" | "unauthorized_client" | "unsupported_grant_type" | "invalid_scope" | "access_denied" | "server_error" | "rate_limited";
+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";
+/**
+ * 将 OAuth 2.0 服务端 error 字段映射到 SsoErrorCode
+ *
+ * @param oauthError 服务端返回的 error 字段
+ * @param context 调用上下文："token_exchange"（授权码换 token）或 "refresh"（刷新）。
+ *   invalid_grant 在换 token 场景多为授权码过期/已用，在刷新场景多为会话失效，
+ *   需按上下文细化映射。
+ */
+declare function mapOAuthErrorToSsoCode(oauthError: string, context?: "token_exchange" | "refresh"): SsoErrorCode;
 /**
  * SSO SDK 自定义错误
  */
@@ -260,13 +363,33 @@ declare class SsoError extends Error {
     constructor(code: SsoErrorCode, description: string, cause?: unknown);
 }
 /**
- * OAuth 2.0 服务端返回的错误
+ * OAuth 2.0 协议层错误（RFC 6749 §5.2）
+ *
+ * 保留用于表示服务端原样返回的 OAuth 错误（error / error_description / error_uri），
+ * 与 SDK 语义的 SsoError 区分。当前 SDK 内部不抛出此类型（统一使用 SsoError +
+ * mapOAuthErrorToSsoCode 映射），作为公共类型导出供子项目自行解析 OAuth 响应时使用。
  */
 declare class OAuthError extends Error {
-    readonly code: OAuthErrorCode;
+    readonly code: string;
     readonly description: string;
     readonly uri?: string;
-    constructor(code: OAuthErrorCode, description: string, uri?: string);
+    constructor(code: string, description: string, uri?: string);
 }
 
-export { OAuthError, type OAuthErrorCode, type OidcDiscovery, SsoClient, type SsoClientConfig, SsoError, type SsoErrorCode, type SsoUser, type TokenData, type TokenResponse, type TokenStorage, clearAllSsoData, clearVerifiersForClients, generateCodeChallenge, generateCodeVerifier, generateState, getOAuthState, getPkceVerifier, getReturnUrl, getTokenData, getTokenStorage, removeOAuthState, removePkceVerifier, removeReturnUrl, removeTokenData, saveOAuthState, savePkceVerifier, saveReturnUrl, saveTokenData, setTokenStorage };
+/**
+ * 安全相关小工具：returnUrl 开放重定向校验、常量时间字符串比较
+ */
+/**
+ * 校验 returnUrl 是否可信（防开放重定向）。
+ * 仅允许：相对路径（且不以 // 开头）或与 currentOrigin 完全同源的绝对 URL。
+ * 拒绝一切含反斜杠 \ 的值：浏览器会把 "/\evil.com" 归一化为 "//evil.com"，
+ * 形成协议相对 URL 开放重定向。
+ */
+declare function isTrustedReturnUrl(url: string, currentOrigin: string): boolean;
+/**
+ * 常量时间字符串比较（避免 state / at_hash / nonce 等机密值的时序侧信道）。
+ * 长度不同也执行完整循环，不提前返回。
+ */
+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, 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

@@ -1,9 +1,15 @@
 /**
  * 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
@@ -27,6 +33,20 @@ interface TokenStorage {
     set(key: string, value: string): void;
     remove(key: string): void;
 }
+/**
+ * 创建存储实现
+ *
+ * @param options.persist 是否持久化到 localStorage。默认 false（sessionStorage）。
+ *   - false（默认）：sessionStorage，标签页级持久化（刷新/整页跳转后登录态保留，
+ *     关闭标签页即清除），多 Tab 间不共享；隐私模式等写入失败时降级为内存。
+ *   - true：localStorage，多 Tab 共享、关闭浏览器后仍保留。
+ *   ⚠️ 安全警告：persist=true 会将 refresh_token 明文写入 localStorage，
+ *   任何 XSS 均可在不被检测的情况下读取。仅在 BFF/Confidential Client
+ *   且 refresh_token 不直接暴露给浏览器的场景下使用。
+ */
+declare function createSecureStorage(options?: {
+    persist?: boolean;
+}): TokenStorage;
 /**
  * 设置自定义存储实现
  */
@@ -44,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;
@@ -85,6 +108,8 @@ interface SsoClientConfig {
     ssoBaseUrl: string;
     /** 请求的 scope（空格分隔），如 "openid profile phone" */
     scopes?: string;
+    /** RP-Initiated Logout 返回地址（可选）。不传时回退到 redirectUri */
+    postLogoutRedirectUri?: string;
 }
 /** 用户信息 */
 interface SsoUser {
@@ -141,26 +166,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
@@ -198,9 +275,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 文档
      *
@@ -247,9 +343,16 @@ 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" | "sso_server_error" | "network_error" | "id_token_invalid" | "id_token_unsupported_alg" | "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";
-/** OAuth 2.0 标准错误码 */
-type OAuthErrorCode = "invalid_request" | "invalid_client" | "invalid_grant" | "unauthorized_client" | "unsupported_grant_type" | "invalid_scope" | "access_denied" | "server_error" | "rate_limited";
+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";
+/**
+ * 将 OAuth 2.0 服务端 error 字段映射到 SsoErrorCode
+ *
+ * @param oauthError 服务端返回的 error 字段
+ * @param context 调用上下文："token_exchange"（授权码换 token）或 "refresh"（刷新）。
+ *   invalid_grant 在换 token 场景多为授权码过期/已用，在刷新场景多为会话失效，
+ *   需按上下文细化映射。
+ */
+declare function mapOAuthErrorToSsoCode(oauthError: string, context?: "token_exchange" | "refresh"): SsoErrorCode;
 /**
  * SSO SDK 自定义错误
  */
@@ -260,13 +363,33 @@ declare class SsoError extends Error {
     constructor(code: SsoErrorCode, description: string, cause?: unknown);
 }
 /**
- * OAuth 2.0 服务端返回的错误
+ * OAuth 2.0 协议层错误（RFC 6749 §5.2）
+ *
+ * 保留用于表示服务端原样返回的 OAuth 错误（error / error_description / error_uri），
+ * 与 SDK 语义的 SsoError 区分。当前 SDK 内部不抛出此类型（统一使用 SsoError +
+ * mapOAuthErrorToSsoCode 映射），作为公共类型导出供子项目自行解析 OAuth 响应时使用。
  */
 declare class OAuthError extends Error {
-    readonly code: OAuthErrorCode;
+    readonly code: string;
     readonly description: string;
     readonly uri?: string;
-    constructor(code: OAuthErrorCode, description: string, uri?: string);
+    constructor(code: string, description: string, uri?: string);
 }
 
-export { OAuthError, type OAuthErrorCode, type OidcDiscovery, SsoClient, type SsoClientConfig, SsoError, type SsoErrorCode, type SsoUser, type TokenData, type TokenResponse, type TokenStorage, clearAllSsoData, clearVerifiersForClients, generateCodeChallenge, generateCodeVerifier, generateState, getOAuthState, getPkceVerifier, getReturnUrl, getTokenData, getTokenStorage, removeOAuthState, removePkceVerifier, removeReturnUrl, removeTokenData, saveOAuthState, savePkceVerifier, saveReturnUrl, saveTokenData, setTokenStorage };
+/**
+ * 安全相关小工具：returnUrl 开放重定向校验、常量时间字符串比较
+ */
+/**
+ * 校验 returnUrl 是否可信（防开放重定向）。
+ * 仅允许：相对路径（且不以 // 开头）或与 currentOrigin 完全同源的绝对 URL。
+ * 拒绝一切含反斜杠 \ 的值：浏览器会把 "/\evil.com" 归一化为 "//evil.com"，
+ * 形成协议相对 URL 开放重定向。
+ */
+declare function isTrustedReturnUrl(url: string, currentOrigin: string): boolean;
+/**
+ * 常量时间字符串比较（避免 state / at_hash / nonce 等机密值的时序侧信道）。
+ * 长度不同也执行完整循环，不提前返回。
+ */
+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, getLogoutState, getOAuthState, getPkceVerifier, getReturnUrl, getTokenData, getTokenStorage, isTrustedReturnUrl, mapOAuthErrorToSsoCode, removeLogoutState, removeOAuthState, removePkceVerifier, removeReturnUrl, removeTokenData, saveLogoutState, saveOAuthState, savePkceVerifier, saveReturnUrl, saveTokenData, setTokenStorage, timingSafeEqualString };