@nihplod/sso-sdk 1.4.1 → 1.6.0

package/README.md

@@ -84,7 +84,7 @@ if (params.get("sso_probe") === "no_session") {
 
 ### `sso.handleCallback(callbackUrl)`
 
-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).
+Handle the OAuth callback. Parses `code` and `state` from the URL, validates state, and exchanges the code for tokens. When the requested scope includes `openid`, the token response **must** contain an `id_token` (fail-closed: a missing `id_token` is rejected instead of silently skipping validation). The SDK verifies the ID Token's 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, protecting against ID Token replay). The check is fail-closed both ways: a stored nonce requires a matching token nonce, and (since 1.6.0) a token carrying a `nonce` claim while no expected nonce is stored locally (e.g. the nonce cookie/sessionStorage entry was evicted) is rejected as well.
 
 | Parameter | Type | Description |
 |------|------|------|
@@ -225,8 +225,11 @@ import { SsoProvider } from "@nihplod/sso-sdk/react";
     redirectUri: "...",
     ssoBaseUrl: "...",
     scopes: "openid profile",
+    debug: false,            // Optional: verbose SDK logs ([SSO SDK] prefix)
   }}
-  refreshThreshold={60}  // Auto-refresh 60s before expiry
+  refreshThreshold={60}      // Auto-refresh 60s before expiry
+  onTokenRefreshed={(token) => { /* sync token elsewhere */ }}
+  onSessionExpired={(err) => { /* show "session expired, please sign in again" */ }}
 >
   <App />
 </SsoProvider>
@@ -242,7 +245,9 @@ const {
   isAuthenticated,   // boolean
   isLoading,         // boolean
   error,             // SsoError | null — set when loading user info fails (e.g. session revoked)
+  sessionExpired,    // boolean — refresh_token revoked/expired; survives "no local token" reloads
   login,             // (returnUrl?: string) => Promise<void>
+  loginPopup,        // (options?: { returnUrl?; width?; height? }) => Promise<TokenData>
   logout,            // (redirectToSso?: boolean) => Promise<void>
   refreshUser,       // () => Promise<void>
   getAccessToken,    // () => Promise<string | null>
@@ -252,6 +257,12 @@ const {
 
 Authentication state is three-valued: `isLoading` (initializing/refreshing) → `error` (load failed, e.g. session expired) → `user` (authenticated). Render your UI accordingly.
 
+`sessionExpired` turns `true` when refresh fails because the token was revoked/expired; unlike `error` it is **not** cleared when the local token has already been removed, so you can reliably show a "登录已过期，请重新登录" banner. It resets on successful login or explicit `logout()`.
+
+`loginPopup` keeps the current page state (no full-page redirect) and returns the exchanged token data; the callback tab notifies the opener via `postMessage` with a one-time nonce. If the browser blocks the popup, catch the `popup_blocked` error and fall back to `login()`.
+
+Cross-tab sync: `logout()` and silent token rotation broadcast over `BroadcastChannel`, so other tabs update immediately even though the default token storage is `sessionStorage` (a raw `storage` event does not fire for `sessionStorage`; the listener only helps when you opt into `createSecureStorage({ persist: true })`).
+
 ### `<RequireAuth>`
 
 ```tsx
@@ -332,11 +343,15 @@ export const middleware = createSsoMiddleware({
   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.
+  // ⚠️ The middleware is only a UX gate — always re-verify tokens in
+  // Route Handlers / Server Components (e.g. with @nihplod/sso-verify)
+  // before serving sensitive data.
+  // failClosedOnIntrospectionError: false by default. When introspection is
+  // *unreachable* (network error / timeout / 5xx — as opposed to a
+  // confirmed-invalid token), requests carrying an SSO access_token cookie are
+  // let through (fail-open), because redirecting to an SSO center that is down
+  // helps no one. Set to true to return 502 instead (fail-closed) if your app
+  // prefers rejecting over passing during an SSO outage.
   // 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
@@ -364,7 +379,15 @@ export const config = {
 > of redirecting to an SSO center that is likely down. This is safe because the middleware
 > is only a UX gate — Route Handlers / Server Components must still re-verify the token.
 > Confirmed-invalid tokens (401/403 or `active:false`) still trigger the redirect, and
-> requests without any SSO cookie still redirect as before.
+> requests without any SSO cookie still redirect as before. Set
+> `failClosedOnIntrospectionError: true` to return **502** instead of failing open.
+>
+> **Removed fast path:** the former "main-site session cookie" (`__Host-user_token` /
+> `ssoCookieName` / `validateSsoCookie`) shortcut has been removed — it was dead code
+> (`__Host-user_token` holds the main site's *internal* token, which introspection
+> always rejects, and `__Host-` cookies are never sent to subdomains), yet cost every
+> request a wasted introspection round-trip. Both options are now deprecated no-ops
+> (kept for config compatibility; setting either logs a warning).
 
 ```typescript
 // src/app/api/auth/callback/route.ts
@@ -375,6 +398,12 @@ export const GET = createCallbackRouteHandler({
   ssoBaseUrl: "https://nihplod.cn",
   redirectUri: "https://yourapp.com/api/auth/callback",
   defaultReturnPath: "/dashboard",
+  // Optional but recommended: keep in sync with createSsoMiddleware's `scopes`.
+  // Only when explicitly set AND it includes `openid` does the callback require an
+  // id_token (fail-closed). If omitted, legacy-compatible behavior applies: the ID
+  // token is validated when present but its absence is not rejected, so upgrading
+  // apps that didn't configure scopes keep working.
+  scopes: "openid profile",
   // Same as middleware; Confidential Client can pass clientSecret
 });
 ```
@@ -421,6 +450,8 @@ export const POST = createBackchannelLogoutRouteHandler({
 
 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.**
 
+> **jti replay storage (since 1.6.0):** the default replay cache is an in-memory per-instance Map. Multi-instance / serverless deployments MUST inject shared storage via the `jtiStore` option (e.g. Redis: `addIfAbsent` = `SET key 1 NX EX ttl`, `remove` = `DEL key` — `remove` lets the SDK release the jti so the IdP can redeliver after an `onLogout` failure; without it, redeliveries are rejected as replays).
+
 Trigger the logout endpoint with a POST request (recommended):
 
 ```tsx
@@ -440,16 +471,50 @@ 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 |
+| nonce | `__Host-nihplod_sso_nonce` | OIDC nonce for ID Token replay protection. Validated fail-closed when the nonce cookie is present (cookie TTL 10 minutes); since 1.6.0, an id_token that carries a `nonce` while the cookie has expired is also rejected (restart the login flow). Requires Secure + Path=/ + no Domain |
+| id_token | `__Host-nihplod_sso_id` | ID token cookie used as `id_token_hint` for RP-Initiated Logout. Requires Secure + Path=/ + no Domain |
+| logout_state | `__Host-nihplod_sso_logout_state` | One-time logout state for CSRF protection on the RP-Initiated Logout 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 |
 
+> In the Next.js BFF flow, the transient cookies above (`state`, `nonce`, `return_url`, `verifier`) are written with the per-login `state` as a name suffix (e.g. `__Host-nihplod_sso_state_<state>`) and looked up by the `state` returned from the IdP. This keeps concurrent tabs from overwriting each other's login attempt. The legacy unsuffixed names are still accepted as a fallback during rolling upgrades.
+
 > 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.
 
 ---
 
+## Changelog
+
+### 1.6.0
+
+Security and correctness hardening. Migration notes:
+
+- **ID Token must carry `iat`.** `validateIdToken` now rejects tokens without an `iat` claim (`id_token_invalid`). Any spec-compliant IdP already includes it.
+- **Nonce check fails closed.** An `id_token` that carries a `nonce` claim while no expected nonce is stored locally (e.g. the nonce cookie/sessionStorage entry was evicted) is now rejected with `id_token_nonce_mismatch` (OIDC Core §12.2), instead of silently skipping the check. Refresh-issued ID tokens must not carry `nonce` per spec, so the refresh flow is unaffected. If login fails with this error after upgrading, restart the login flow — do not downgrade the check.
+- **New `jtiStore` option** for `createBackchannelLogoutRouteHandler` / `verifyLogoutToken(Detailed)`. The default jti replay cache is an in-memory per-instance Map; multi-instance / serverless deployments MUST inject shared storage (e.g. Redis `SET NX EX` for `addIfAbsent`, `DEL` for `remove` — `remove` lets the SDK release the jti so the IdP can redeliver after your `onLogout` hook fails). Replay keys are now prefixed with the token issuer to prevent cross-issuer jti collisions.
+- **New `allowCrossOriginDiscoveryEndpoints` option** on `SsoClientConfig` (default `false`). Discovery documents whose `authorization_endpoint` is not same-origin with `ssoBaseUrl`, or whose `token_endpoint` / `userinfo_endpoint` is not same-origin with `ssoBaseUrl` (or `serverBaseUrl` when configured), are rejected with a warning and the SDK falls back to the default endpoints. Set this flag only if your SSO center genuinely hosts endpoints on another origin.
+- **Multi-tab token sync**: after a silent refresh, the new token data is broadcast to other tabs via `BroadcastChannel` and persisted directly (light shape check), so other tabs no longer attempt their own refresh with an already-rotated refresh_token. Older SDK tabs (no payload) fall back to the previous `loadUser()`-only behavior.
+- `handleCallback` now clears the one-time transient data (state/nonce/PKCE verifier/silent-probe marker) when the token endpoint returns an error (e.g. `invalid_grant`) or when the required `id_token` is missing — the authorization code is already consumed and retrying cannot succeed. Network failures and JWKS validation failures still retain the data for retry.
+- `getAccessToken()` / `getUserInfo()` refresh when the token has less than 10s of validity left (expiry skew), instead of returning a token that may expire in flight. `isAuthenticated()` intentionally keeps the exact check (it's a synchronous UI hint).
+- Next.js callback: the token exchange request now has a 10s timeout (previously unbounded) and still gets one retry before the 502 error page. RP-Initiated Logout state comparison is now constant-time. The middleware never asset-bypasses paths under `/api/` (e.g. `/api/app.js` no longer skips authentication; list public API paths in `publicPaths` explicitly).
+
+---
+
 ## Security Recommendations and Token Storage
 
+> ⚠️ **The Next.js middleware is only a UX gate.** It decides whether to redirect
+> unauthenticated visitors to the SSO login page; it is NOT a security boundary.
+> Any route serving sensitive data MUST re-verify the token in the Route Handler /
+> Server Component itself (e.g. with `@nihplod/sso-verify`, or the `getSessionUser`
+> pattern in `examples/nextjs-app`). This applies regardless of
+> `failClosedOnIntrospectionError` — that option only changes how the middleware
+> behaves when the SSO introspection endpoint is unreachable.
+
+> ℹ️ HS256 ID Tokens are **always rejected** (symmetric secrets cannot be safely
+> distributed to public clients). The `rejectHs256WhenRs256Available` option of
+> `validateIdToken` is deprecated and has no effect — it only chooses which error
+> code is thrown. The SSO center must be configured with an RS256 key pair.
+
 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.
@@ -468,6 +533,33 @@ In production, it is more secure to keep the refresh token in a Service Worker o
 
 ---
 
+## Error Codes
+
+All SDK failures are thrown as `SsoError` (`error.code` / `error.description`; `error.message` is `[SSO SDK] <code>: <description>`).
+
+| Code | Meaning | Typical handling |
+| --- | --- | --- |
+| `invalid_config` | Missing/invalid config (clientId, redirectUri, ssoBaseUrl), or middleware/callback config mismatch | Fix configuration; check `insecureLocalDev` and cookie names are identical everywhere |
+| `state_mismatch` | OAuth `state` mismatch (CSRF protection) | Restart login; never ignore |
+| `pkce_required` | PKCE verifier missing (expired tab / different tab) | Restart login |
+| `authorization_code_expired` / `authorization_code_used` | Code expired or already redeemed | Restart login |
+| `user_denied_authorization` | User cancelled on the SSO page | Show a neutral "login cancelled" message |
+| `client_disabled` | Client disabled in admin console | Contact administrator |
+| `account_disabled` | User account disabled | Show reason, contact support |
+| `session_expired` / `no_refresh_token` | Refresh token revoked/expired | Clear local state and ask the user to sign in again (`sessionExpired` is set on `SsoProvider`) |
+| `network_error` | Network failure or request timeout (10s; revoke 3s) | Show retry; keep local tokens for retryable cases |
+| `rate_limited` | Server rate limit | Back off and retry later |
+| `sso_server_error` | SSO server error | Retry later |
+| `popup_blocked` | `window.open` blocked | Fall back to full-page `login()` |
+| `popup_closed` | User closed the login popup | Offer retry |
+| `id_token_*` (`id_token_invalid`, `..._signature`, `..._nonce_mismatch`, `..._at_hash_mismatch`, …) | ID token missing or failed validation (fail-closed) | Restart login; if persistent, check `scopes` parity between middleware and callback |
+| `logout_token_*` | Back-channel logout token validation failed | Return 400/500 so the IdP retries; check clock skew/JWKS |
+| `not_authenticated` | No local token when calling user APIs | Trigger login |
+
+Next.js callback errors are rendered as a branded HTML page for browser navigations (with a "重新登录" action). Programmatic callers can force JSON with `?format=json` or an `Accept` header that excludes `text/html`. Customize the page with the `renderErrorPage` option; enable `debug: true` for server-side error logs.
+
+---
+
 ## Utility Functions
 
 ```typescript

package/dist/index.d.mts

@@ -32,6 +32,12 @@ interface TokenStorage {
     get(key: string): string | null;
     set(key: string, value: string): void;
     remove(key: string): void;
+    /**
+     * 可选：枚举当前存储中的 key（不含 SDK 内部前缀）。
+     * 供 clearAllSsoData() 清理 client 级残留（`token:<clientId>` 等）。
+     * 自定义存储若不实现，clearAllSsoData() 仅能按已知 key 清理。
+     */
+    keys?(): string[];
 }
 /**
  * 创建存储实现
@@ -106,10 +112,26 @@ interface SsoClientConfig {
     redirectUri: string;
     /** SSO 中心地址，如 "https://nihplod.cn" */
     ssoBaseUrl: string;
+    /**
+     * 允许 Discovery 文档声明跨源端点（默认 false）。
+     *
+     * ⚠️ 安全警告：Discovery 文档若被篡改（如中间人/反向代理劫持），攻击者可把
+     * token_endpoint 指向自己的服务器窃取 authorization code / refresh_token。
+     * SDK 默认校验 authorization_endpoint 必须与 ssoBaseUrl 同源、
+     * token_endpoint / userinfo_endpoint 必须与 ssoBaseUrl（或 serverBaseUrl）同源，
+     * 不匹配时告警并回退到默认端点。仅当 SSO 中心确实把端点托管在其他域名时
+     * 才设置此开关，并自行确保 Discovery 通道可信。
+     */
+    allowCrossOriginDiscoveryEndpoints?: boolean;
     /** 请求的 scope（空格分隔），如 "openid profile phone" */
     scopes?: string;
     /** RP-Initiated Logout 返回地址（可选）。不传时回退到 redirectUri */
     postLogoutRedirectUri?: string;
+    /**
+     * 调试日志开关（默认 false）。开启后输出登录/回调/刷新/登出等关键流程日志，
+     * 便于接入方定位问题（生产默认关闭，避免日志噪音）。
+     */
+    debug?: boolean;
     /**
      * 服务端到服务端调用的内网地址（可选，如 http://127.0.0.1:3000）。
      * 仅用于 discovery / token / userinfo / revocation 等服务器间请求；
@@ -154,6 +176,11 @@ interface TokenResponse {
     access_token: string;
     token_type: string;
     expires_in: number;
+    /**
+     * authorization_code 交换主站必然返回（缺失时 handleCallback 抛
+     * token_request_failed）；refresh 响应按 RFC 6749 §6 可省略，
+     * 此时 SDK 沿用旧 refresh_token。
+     */
     refresh_token: string;
     id_token?: string;
 }
@@ -179,11 +206,28 @@ declare class SsoClient {
     private _discovery;
     private _discoveryFetchedAt;
     private _refreshLock;
+    /** Discovery 端点 origin 校验失败只告警一次（拒绝的文档不缓存，避免每次调用刷屏） */
+    private _discoveryOriginWarned;
     /** Discovery 文档缓存 TTL（5 分钟） */
     private static readonly DISCOVERY_TTL_MS;
     /** Discovery fetch 超时（10 秒） */
     private static readonly DISCOVERY_TIMEOUT_MS;
     constructor(config: SsoClientConfig);
+    /**
+     * 调试日志（config.debug=true 时输出，前缀 [SSO SDK]）：
+     * 覆盖登录发起 / 回调结果 / 刷新失败 / 登出等关键节点，便于接入方定位问题。
+     * 不会输出 token/授权码等敏感值。
+     */
+    debugLog(...args: unknown[]): void;
+    /**
+     * 校验 Discovery 文档端点 origin（防文档被篡改后 token/code 被导向攻击者服务器）：
+     * - authorization_endpoint 必须与 ssoBaseUrl 同源（浏览器跳转目标）；
+     * - token_endpoint / userinfo_endpoint 必须与 ssoBaseUrl 同源，
+     *   或（配置了 serverBaseUrl 时）与内网地址同源。
+     * 任一不匹配：告警并返回 null（上层回退到默认端点，fail-safe）。
+     * 可通过 config.allowCrossOriginDiscoveryEndpoints 关闭（见配置项警告）。
+     */
+    private _sanitizeDiscovery;
     /**
      * 获取 OIDC Discovery 文档（带缓存 + 超时）
      *
@@ -305,6 +349,9 @@ declare class SsoClient {
      * 检查是否已认证（不发起网络请求）
      *
      * 仅检查本地是否存在未过期的 access_token。
+     * 故意不做 EXPIRY_SKEW_MS 提前量：这是同步的 UI 提示判定（是否显示"已登录"），
+     * 提前 10s 翻转 false 会让调用方在 token 仍有效时误显示未登录；真正发请求的
+     * getAccessToken/getUserInfo 已带提前量。
      */
     isAuthenticated(): boolean;
     /**
@@ -417,9 +464,11 @@ declare class OAuthError extends Error {
  */
 /**
  * 校验 returnUrl 是否可信（防开放重定向）。
- * 仅允许：相对路径（且不以 // 开头）或与 currentOrigin 完全同源的绝对 URL。
- * 拒绝一切含反斜杠 \ 的值：浏览器会把 "/\evil.com" 归一化为 "//evil.com"，
- * 形成协议相对 URL 开放重定向。
+ * 仅允许：
+ * - 站内相对路径（以单个 "/" 开头且不以 "//" 开头）
+ * - 与 currentOrigin 完全同源的 http(s) 绝对 URL
+ * 拒绝一切含反斜杠/控制字符的值（浏览器会将 "/\evil.com" 解析为跨站 URL），
+ * 拒绝 userinfo 与危险 scheme。
  */
 declare function isTrustedReturnUrl(url: string, currentOrigin: string): boolean;
 /**

package/dist/index.d.ts

@@ -32,6 +32,12 @@ interface TokenStorage {
     get(key: string): string | null;
     set(key: string, value: string): void;
     remove(key: string): void;
+    /**
+     * 可选：枚举当前存储中的 key（不含 SDK 内部前缀）。
+     * 供 clearAllSsoData() 清理 client 级残留（`token:<clientId>` 等）。
+     * 自定义存储若不实现，clearAllSsoData() 仅能按已知 key 清理。
+     */
+    keys?(): string[];
 }
 /**
  * 创建存储实现
@@ -106,10 +112,26 @@ interface SsoClientConfig {
     redirectUri: string;
     /** SSO 中心地址，如 "https://nihplod.cn" */
     ssoBaseUrl: string;
+    /**
+     * 允许 Discovery 文档声明跨源端点（默认 false）。
+     *
+     * ⚠️ 安全警告：Discovery 文档若被篡改（如中间人/反向代理劫持），攻击者可把
+     * token_endpoint 指向自己的服务器窃取 authorization code / refresh_token。
+     * SDK 默认校验 authorization_endpoint 必须与 ssoBaseUrl 同源、
+     * token_endpoint / userinfo_endpoint 必须与 ssoBaseUrl（或 serverBaseUrl）同源，
+     * 不匹配时告警并回退到默认端点。仅当 SSO 中心确实把端点托管在其他域名时
+     * 才设置此开关，并自行确保 Discovery 通道可信。
+     */
+    allowCrossOriginDiscoveryEndpoints?: boolean;
     /** 请求的 scope（空格分隔），如 "openid profile phone" */
     scopes?: string;
     /** RP-Initiated Logout 返回地址（可选）。不传时回退到 redirectUri */
     postLogoutRedirectUri?: string;
+    /**
+     * 调试日志开关（默认 false）。开启后输出登录/回调/刷新/登出等关键流程日志，
+     * 便于接入方定位问题（生产默认关闭，避免日志噪音）。
+     */
+    debug?: boolean;
     /**
      * 服务端到服务端调用的内网地址（可选，如 http://127.0.0.1:3000）。
      * 仅用于 discovery / token / userinfo / revocation 等服务器间请求；
@@ -154,6 +176,11 @@ interface TokenResponse {
     access_token: string;
     token_type: string;
     expires_in: number;
+    /**
+     * authorization_code 交换主站必然返回（缺失时 handleCallback 抛
+     * token_request_failed）；refresh 响应按 RFC 6749 §6 可省略，
+     * 此时 SDK 沿用旧 refresh_token。
+     */
     refresh_token: string;
     id_token?: string;
 }
@@ -179,11 +206,28 @@ declare class SsoClient {
     private _discovery;
     private _discoveryFetchedAt;
     private _refreshLock;
+    /** Discovery 端点 origin 校验失败只告警一次（拒绝的文档不缓存，避免每次调用刷屏） */
+    private _discoveryOriginWarned;
     /** Discovery 文档缓存 TTL（5 分钟） */
     private static readonly DISCOVERY_TTL_MS;
     /** Discovery fetch 超时（10 秒） */
     private static readonly DISCOVERY_TIMEOUT_MS;
     constructor(config: SsoClientConfig);
+    /**
+     * 调试日志（config.debug=true 时输出，前缀 [SSO SDK]）：
+     * 覆盖登录发起 / 回调结果 / 刷新失败 / 登出等关键节点，便于接入方定位问题。
+     * 不会输出 token/授权码等敏感值。
+     */
+    debugLog(...args: unknown[]): void;
+    /**
+     * 校验 Discovery 文档端点 origin（防文档被篡改后 token/code 被导向攻击者服务器）：
+     * - authorization_endpoint 必须与 ssoBaseUrl 同源（浏览器跳转目标）；
+     * - token_endpoint / userinfo_endpoint 必须与 ssoBaseUrl 同源，
+     *   或（配置了 serverBaseUrl 时）与内网地址同源。
+     * 任一不匹配：告警并返回 null（上层回退到默认端点，fail-safe）。
+     * 可通过 config.allowCrossOriginDiscoveryEndpoints 关闭（见配置项警告）。
+     */
+    private _sanitizeDiscovery;
     /**
      * 获取 OIDC Discovery 文档（带缓存 + 超时）
      *
@@ -305,6 +349,9 @@ declare class SsoClient {
      * 检查是否已认证（不发起网络请求）
      *
      * 仅检查本地是否存在未过期的 access_token。
+     * 故意不做 EXPIRY_SKEW_MS 提前量：这是同步的 UI 提示判定（是否显示"已登录"），
+     * 提前 10s 翻转 false 会让调用方在 token 仍有效时误显示未登录；真正发请求的
+     * getAccessToken/getUserInfo 已带提前量。
      */
     isAuthenticated(): boolean;
     /**
@@ -417,9 +464,11 @@ declare class OAuthError extends Error {
  */
 /**
  * 校验 returnUrl 是否可信（防开放重定向）。
- * 仅允许：相对路径（且不以 // 开头）或与 currentOrigin 完全同源的绝对 URL。
- * 拒绝一切含反斜杠 \ 的值：浏览器会把 "/\evil.com" 归一化为 "//evil.com"，
- * 形成协议相对 URL 开放重定向。
+ * 仅允许：
+ * - 站内相对路径（以单个 "/" 开头且不以 "//" 开头）
+ * - 与 currentOrigin 完全同源的 http(s) 绝对 URL
+ * 拒绝一切含反斜杠/控制字符的值（浏览器会将 "/\evil.com" 解析为跨站 URL），
+ * 拒绝 userinfo 与危险 scheme。
  */
 declare function isTrustedReturnUrl(url: string, currentOrigin: string): boolean;
 /**