@nihplod/sso-sdk 1.0.0

package/README.md

@@ -0,0 +1,360 @@
+# @nihplod/sso-sdk
+
+NIHPLOD SSO 子项目接入 SDK — OAuth 2.0 授权码 + PKCE 客户端封装。
+
+## 安装
+
+```bash
+npm install @nihplod/sso-sdk
+```
+
+## 快速开始
+
+```typescript
+import { SsoClient } from "@nihplod/sso-sdk";
+
+const sso = new SsoClient({
+  clientId: "your-client-id",
+  redirectUri: "https://yourapp.com/callback",
+  ssoBaseUrl: "https://nihplod.cn",
+});
+
+// 1. 发起登录
+await sso.login();
+
+// 2. 处理回调（在回调页面中）
+const token = await sso.handleCallback(window.location.href);
+
+// 3. 获取用户信息
+const user = await sso.getUserInfo();
+
+// 4. 登出
+await sso.logout();
+```
+
+---
+
+## API 参考
+
+### `new SsoClient(config)`
+
+创建 SSO 客户端实例。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `clientId` | `string` | ✅ | OAuth Client ID |
+| `redirectUri` | `string` | ✅ | 回调 URL，须与注册时一致 |
+| `ssoBaseUrl` | `string` | ✅ | SSO 中心地址，如 `https://nihplod.cn` |
+| `scopes` | `string` | ❌ | 空格分隔的 scope，默认 `"openid profile"` |
+| `clientSecret` | `string` | ❌ | **仅 Confidential Client 需要**。浏览器端 SPA（Public Client）请勿传入，避免密钥泄露。BFF / Next.js Route Handler 可传入 |
+
+### `sso.login(returnUrl?)`
+
+发起 SSO 登录。生成 PKCE 参数后 302 跳转到 SSO 登录页。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `returnUrl` | `string` | 登录成功后的返回地址（可选） |
+
+### `sso.getLoginUrl(returnUrl?)`
+
+构建登录 URL 字符串，不执行跳转。返回 `Promise<string>`。
+
+### `sso.handleCallback(callbackUrl)`
+
+处理 OAuth 回调。解析 URL 中的 `code` 和 `state`，校验 state 后用 code 换取 token。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `callbackUrl` | `string` | 完整的回调 URL（`window.location.href`） |
+
+返回 `Promise<TokenData>`。
+
+### `sso.refreshToken()`
+
+使用 refresh_token 刷新 access_token。采用互斥锁防止并发刷新。
+
+返回 `Promise<TokenData>`。
+
+### `sso.getUserInfo()`
+
+获取当前用户信息。若 access_token 已过期则自动刷新。
+
+返回 `Promise<SsoUser>`。
+
+```typescript
+interface SsoUser {
+  sub: string;
+  nickname?: string;
+  avatar?: string;
+  phone?: string;          // 脱敏手机号
+  membership_level?: string;
+  total_points?: number;
+}
+```
+
+### `sso.getAccessToken()`
+
+获取当前有效的 access_token。若已过期则自动刷新。
+
+返回 `Promise<string | null>`。
+
+### `sso.isAuthenticated()`
+
+检查是否已认证（仅本地检查，不发起网络请求）。
+
+返回 `boolean`。
+
+### `sso.logout(redirectToSso?)`
+
+清除本地 token 数据，并尝试撤销服务端 refresh_token。
+
+| 参数 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `redirectToSso` | `boolean` | `false` | 是否重定向到 SSO 登出页（OIDC RP-Initiated Logout） |
+
+当 `redirectToSso=true` 时，会跳转到 `/logout?client_id=...&post_logout_redirect_uri=...`，
+由主站完成会话清除后回到子项目回调地址。
+
+### `sso.getDiscovery()`
+
+获取 OIDC Discovery 文档。
+
+返回 `Promise<OidcDiscovery>`。
+
+---
+
+## TypeScript 类型
+
+```typescript
+// SsoClient 配置
+interface SsoClientConfig {
+  clientId: string;
+  redirectUri: string;
+  ssoBaseUrl: string;
+  scopes?: string;
+  clientSecret?: string; // 仅 Confidential Client 需要
+}
+
+// Token 数据
+interface TokenData {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token: string;
+  id_token?: string;
+  issued_at: number;
+  expires_at: number;
+}
+
+// 用户信息
+interface SsoUser {
+  sub: string;
+  nickname?: string;
+  avatar?: string;
+  phone?: string;
+  membership_level?: string;
+  total_points?: number;
+}
+
+// OIDC Discovery
+interface OidcDiscovery {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint: string;
+  jwks_uri: string;
+  introspection_endpoint: string;
+  revocation_endpoint?: string;
+  end_session_endpoint?: string;
+  scopes_supported: string[];
+  response_types_supported: string[];
+  grant_types_supported: string[];
+  code_challenge_methods_supported: string[];
+}
+```
+
+---
+
+## React 绑定
+
+### `<SsoProvider>`
+
+```tsx
+import { SsoProvider } from "@nihplod/sso-sdk/react";
+
+<SsoProvider
+  config={{
+    clientId: "...",
+    redirectUri: "...",
+    ssoBaseUrl: "...",
+    scopes: "openid profile",
+  }}
+  refreshThreshold={60}  // 过期前 60s 自动刷新
+>
+  <App />
+</SsoProvider>
+```
+
+### `useSso()`
+
+```tsx
+import { useSso } from "@nihplod/sso-sdk/react";
+
+const {
+  user,              // SsoUser | null
+  isAuthenticated,   // boolean
+  isLoading,         // boolean
+  login,             // (returnUrl?: string) => Promise<void>
+  logout,            // (redirectToSso?: boolean) => Promise<void>
+  refreshUser,       // () => Promise<void>
+  getAccessToken,    // () => Promise<string | null>
+  client,            // SsoClient 实例
+} = useSso();
+```
+
+### `<RequireAuth>`
+
+```tsx
+import { RequireAuth } from "@nihplod/sso-sdk/react";
+
+<RequireAuth>
+  <ProtectedContent />
+</RequireAuth>
+```
+
+### `withAuth(Component)`
+
+```tsx
+import { withAuth } from "@nihplod/sso-sdk/react";
+
+function DashboardPage() { return <div>Dashboard</div>; }
+export default withAuth(DashboardPage);
+```
+
+### `<CallbackPage>`
+
+```tsx
+import { CallbackPage } from "@nihplod/sso-sdk/react";
+
+// 在回调路由中渲染此组件即可
+export default function AuthCallback() {
+  return <CallbackPage />;
+}
+```
+
+---
+
+## Next.js 绑定
+
+Next.js 推荐采用 **Middleware + Route Handler** 的 BFF 模式，token 存放在
+`httpOnly` Cookie 中，JavaScript 无法读取，安全性最高。
+
+```typescript
+// src/middleware.ts
+import { createSsoMiddleware } from "@nihplod/sso-sdk/next";
+
+export const middleware = createSsoMiddleware({
+  clientId: "...",
+  ssoBaseUrl: "https://nihplod.cn",
+  redirectUri: "https://yourapp.com/api/auth/callback",
+  scopes: "openid profile",
+  publicPaths: ["/", "/public"],
+  // Confidential Client（BFF）可传入 clientSecret
+  // clientSecret: process.env.SSO_CLIENT_SECRET,
+});
+
+export const config = {
+  matcher: ["/((?!_next|favicon.ico).*)"],
+};
+```
+
+```typescript
+// src/app/api/auth/callback/route.ts
+import { createCallbackRouteHandler } from "@nihplod/sso-sdk/next";
+
+export const GET = createCallbackRouteHandler({
+  clientId: "...",
+  ssoBaseUrl: "https://nihplod.cn",
+  redirectUri: "https://yourapp.com/api/auth/callback",
+  defaultReturnPath: "/dashboard",
+  // 与 middleware 一致，Confidential Client 可传入 clientSecret
+});
+```
+
+```typescript
+// src/app/api/auth/logout/route.ts
+import { createLogoutRouteHandler } from "@nihplod/sso-sdk/next";
+
+export const GET = createLogoutRouteHandler({
+  clientId: "...",
+  ssoBaseUrl: "https://nihplod.cn",
+  redirectUri: "https://yourapp.com/api/auth/callback",
+  postLogoutRedirectUri: "https://yourapp.com/",
+  redirectToSso: true,
+});
+```
+
+页面中使用标准 `<a>` 跳转登出端点即可：
+
+```tsx
+<a href="/api/auth/logout">退出登录</a>
+```
+
+### Cookie 配置
+
+默认 Cookie 名称：
+
+| Cookie | 默认名称 | 说明 |
+|--------|----------|------|
+| access_token | `__Host-nihplod_sso_at` | 要求 Secure + Path=/ + 无 Domain |
+| refresh_token | `__Host-nihplod_sso_rt` | 要求 Secure + Path=/ + 无 Domain |
+| state | `__Host-nihplod_sso_state` | 要求 Secure + Path=/ + 无 Domain |
+| return_url | `__Host-nihplod_sso_return` | 要求 Secure + Path=/ + 无 Domain |
+| verifier | `__Secure-nihplod_sso_verifier` | 要求 Secure + 无 Domain；Path 为回调路径，因此使用 `__Secure-` 前缀 |
+
+> 本地开发若使用 `http://localhost`，浏览器会拒绝 `Secure` Cookie。此时可仅在本地关闭 `secure`，生产环境必须启用 HTTPS。
+
+---
+
+## 安全建议与 Token 存储
+
+SDK 默认将 token 保存在**内存**中，Public Client（SPA/移动端/桌面端）在浏览器中不应把 `refresh_token` 写入 `localStorage`，以防止 XSS 窃取长期凭证。
+
+如果子项目是 **Next.js BFF / Confidential Client**，可以将 token 保存在 `localStorage` 以便多 Tab 共享：
+
+```typescript
+import { setTokenStorage, createSecureStorage } from "@nihplod/sso-sdk";
+
+setTokenStorage(createSecureStorage({ persist: true }));
+```
+
+生产环境更推荐通过 Service Worker 或 HTTP-only Cookie 封装 refresh token，前端只持有 access token 短期凭证。
+
+---
+
+## 工具函数
+
+```typescript
+import {
+  generateCodeVerifier,
+  generateCodeChallenge,
+  generateState,
+  setTokenStorage,
+  createSecureStorage,
+  getTokenData,
+  saveTokenData,
+  removeTokenData,
+  clearAllSsoData,
+} from "@nihplod/sso-sdk";
+
+// PKCE
+const verifier = generateCodeVerifier(64);
+const challenge = await generateCodeChallenge(verifier);
+
+// State
+const state = generateState();
+
+// 自定义 Token 存储（默认内存存储）
+setTokenStorage(createSecureStorage({ persist: false }));
+```

package/dist/index.d.mts

@@ -0,0 +1,272 @@
+/**
+ * Token 存储抽象层
+ *
+ * 默认使用 localStorage，以支持多 Tab 间自动同步 token 并避免并发刷新。
+ * 对 XSS 敏感的子项目可通过 setTokenStorage() 注入更安全的自定义实现
+ *（如内存存储、Service Worker 封装、或带加密的 storage）。
+ *
+ * 多 client 隔离：
+ * - token / state / return_url 均支持按 clientId 隔离 key
+ * - 不传 clientId 时使用全局 key，保持向后兼容
+ */
+/** Token 数据 */
+interface TokenData {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token: string;
+    id_token?: string;
+    /** Token 签发时间（epoch ms），用于计算过期 */
+    issued_at: number;
+    /** 访问令牌实际过期时间（epoch ms）= issued_at + expires_in * 1000 */
+    expires_at: number;
+}
+/** 存储接口 */
+interface TokenStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/**
+ * 设置自定义存储实现
+ */
+declare function setTokenStorage(storage: TokenStorage): void;
+/**
+ * 获取当前存储实现
+ */
+declare function getTokenStorage(): TokenStorage;
+declare function saveTokenData(data: TokenData, clientId?: string): void;
+declare function getTokenData(clientId?: string): TokenData | null;
+declare function removeTokenData(clientId?: string): void;
+declare function savePkceVerifier(clientId: string, verifier: string): void;
+declare function getPkceVerifier(clientId: string): string | null;
+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 saveReturnUrl(url: string, clientId?: string): void;
+declare function getReturnUrl(clientId?: string): string | null;
+declare function removeReturnUrl(clientId?: string): void;
+declare function clearAllSsoData(clientId?: string): void;
+/**
+ * 清理指定 clientId 列表的 PKCE verifier
+ *
+ * 适用于非浏览器环境或已知 clientId 场景。
+ */
+declare function clearVerifiersForClients(clientIds: string[]): void;
+
+/**
+ * SSO Client 核心类
+ *
+ * 封装完整的 OAuth 2.0 授权码 + PKCE S256 流程：
+ * - login(): 发起授权请求
+ * - handleCallback(): 处理回调，交换 token
+ * - refreshToken(): 刷新 access token（原子轮换）
+ * - getUserInfo(): 获取用户信息
+ * - logout(): 登出
+ * - isAuthenticated(): 检查认证状态
+ */
+
+/** SSO 客户端配置 */
+interface SsoClientConfig {
+    /** OAuth Client ID（从管理后台获取） */
+    clientId: string;
+    /** OAuth Client Secret（从管理后台获取）
+     *
+     * ⚠️ 安全提醒：client_secret 不应暴露在前端代码中。
+     * 对于浏览器端 SPA（Public Client），应省略此字段；SDK 会使用 PKCE 完成授权，
+     * 且 token 端点不会发送 client_secret。
+     * 对于 BFF/Next.js 等 Confidential Client，可传入 client_secret。
+     */
+    clientSecret?: string;
+    /** 回调 URL（必须与注册的 redirect_uri 完全一致） */
+    redirectUri: string;
+    /** SSO 中心地址，如 "https://nihplod.cn" */
+    ssoBaseUrl: string;
+    /** 请求的 scope（空格分隔），如 "openid profile phone" */
+    scopes?: string;
+}
+/** 用户信息 */
+interface SsoUser {
+    sub: string;
+    nickname?: string;
+    avatar?: string;
+    phone?: string;
+    membership_level?: string;
+    total_points?: number;
+}
+/** Token 响应 */
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token: string;
+    id_token?: string;
+}
+/** OIDC Discovery 文档 */
+interface OidcDiscovery {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    jwks_uri: string;
+    introspection_endpoint: string;
+    revocation_endpoint?: string;
+    end_session_endpoint?: string;
+    scopes_supported: string[];
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+}
+declare class SsoClient {
+    readonly config: SsoClientConfig;
+    private _discovery;
+    private _discoveryFetchedAt;
+    private _refreshLock;
+    /** Discovery 文档缓存 TTL（5 分钟） */
+    private static readonly DISCOVERY_TTL_MS;
+    /** Discovery fetch 超时（10 秒） */
+    private static readonly DISCOVERY_TIMEOUT_MS;
+    constructor(config: SsoClientConfig);
+    /**
+     * 获取 OIDC Discovery 文档（带缓存 + 超时）
+     *
+     * 缓存 5 分钟，超时 10 秒。
+     * 失败时返回 null（上层调用方回退到硬编码默认端点）。
+     */
+    private _getDiscovery;
+    /** 获取 authorize 端点 URL（优先 Discovery，回退默认） */
+    private _getAuthorizeEndpoint;
+    /** 获取 token 端点 URL（优先 Discovery，回退默认） */
+    private _getTokenEndpoint;
+    /** 获取 userinfo 端点 URL（优先 Discovery，回退默认） */
+    private _getUserinfoEndpoint;
+    /**
+     * 发起 SSO 登录
+     *
+     * 生成 PKCE code_verifier/code_challenge 和 state 参数，
+     * 构建 authorize URL，通过 302 跳转到 SSO 登录页。
+     *
+     * @param returnUrl - 登录成功后的返回地址（可选，保存到 sessionStorage）
+     */
+    login(returnUrl?: string): Promise<void>;
+    /**
+     * 构建登录 URL（不跳转，返回 URL 字符串）
+     *
+     * 适用于需要手动处理跳转的场景。
+     */
+    getLoginUrl(returnUrl?: string): Promise<string>;
+    /**
+     * 处理 OAuth 回调
+     *
+     * 解析回调 URL，校验 state 参数，用授权码交换 token。
+     * 成功后 token 自动保存到 sessionStorage。
+     *
+     * @param callbackUrl - 完整的回调 URL（window.location.href）
+     * @returns TokenData 或 null
+     */
+    handleCallback(callbackUrl: string): Promise<TokenData>;
+    /**
+     * 刷新 Access Token
+     *
+     * 使用 refresh_token 换取新的 access_token。
+     * 采用互斥锁防止并发刷新。
+     * 支持 Refresh Token 原子轮换。
+     */
+    refreshToken(): Promise<TokenData>;
+    private _doRefreshToken;
+    /**
+     * 获取用户信息
+     *
+     * 若 access_token 已过期则自动刷新后再请求。
+     */
+    getUserInfo(): Promise<SsoUser>;
+    /**
+     * 获取当前 access_token
+     *
+     * 若已过期则自动刷新。用于子项目自行发起 API 请求时获取 Bearer token。
+     * 若无 token 返回 null；若刷新失败则抛出错误（与 getUserInfo 行为一致）。
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * 检查是否已认证（不发起网络请求）
+     *
+     * 仅检查本地是否存在未过期的 access_token。
+     */
+    isAuthenticated(): boolean;
+    /**
+     * 登出
+     *
+     * 清除本地所有 token 和临时数据，并尝试撤销服务端 refresh_token。
+     * @param redirectToSso - 是否重定向到 SSO 登出页（默认 false）
+     */
+    logout(redirectToSso?: boolean): Promise<void>;
+    /**
+     * 获取 OIDC Discovery 文档
+     *
+     * 用于调试和获取 SSO 中心完整配置。
+     * 可能返回 null（当 Discovery 端点不可达且无缓存时）。
+     */
+    getDiscovery(): Promise<OidcDiscovery | null>;
+}
+
+/**
+ * PKCE (Proof Key for Code Exchange) 工具函数
+ *
+ * 实现 RFC 7636 规范：
+ * - code_verifier: 43-128 字符的随机字符串
+ * - code_challenge: SHA-256(code_verifier) 的 base64url 编码
+ *
+ * 仅支持 S256 模式，不提供 plain 模式。
+ */
+/**
+ * 生成 code_verifier
+ *
+ * 生成 43-128 字符之间的安全随机字符串，
+ * 使用 `crypto.getRandomValues` 保证密码学安全性。
+ *
+ * @param length - 长度（默认 64），范围 43-128
+ */
+declare function generateCodeVerifier(length?: number): string;
+/**
+ * 计算 code_challenge (S256)
+ *
+ * 对 code_verifier 进行 SHA-256 哈希，然后进行 base64url 编码。
+ *
+ * @param codeVerifier - PKCE code_verifier
+ */
+declare function generateCodeChallenge(codeVerifier: string): Promise<string>;
+/**
+ * 生成 state 参数
+ *
+ * 32 字节 hex 随机字符串，用于 CSRF 防护。
+ */
+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";
+/**
+ * SSO SDK 自定义错误
+ */
+declare class SsoError extends Error {
+    readonly code: SsoErrorCode;
+    readonly description: string;
+    readonly cause?: unknown;
+    constructor(code: SsoErrorCode, description: string, cause?: unknown);
+}
+/**
+ * OAuth 2.0 服务端返回的错误
+ */
+declare class OAuthError extends Error {
+    readonly code: OAuthErrorCode;
+    readonly description: string;
+    readonly uri?: string;
+    constructor(code: OAuthErrorCode, 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 };