aid-npm-test987-sso-sdk 0.1.1

package/README.md

@@ -0,0 +1,725 @@
+# aid-sso-sdk
+
+AidLux OIDC SSO 前端接入 SDK，面向浏览器环境，和具体前端技术栈无关。
+
+SDK 只封装各子系统接入 SSO 时稳定、公共的前端逻辑：
+
+- 判断 session cookie 是否存在
+- 构造 `/api/oidc/*` 登录、注册、绑定跳转地址
+- 使用原生 `fetch` 调用 OIDC 原始接口
+- 登出、401 清理、AidLux 个人中心地址构造
+- 账号绑定流程参数拼装
+- 未授权状态码和业务 code 的公共判断
+
+SDK 不依赖 Vue、React、Next.js、Umi、Pinia、Redux、Axios，也不使用任何子系统自己的 request 封装。
+
+## 适用范围
+
+适合这些子系统：
+
+- 使用 cookie session 接入 AidLux OIDC SSO
+- 后端已提供统一 `/api/oidc/*` 接口
+- 前端需要兼容 hash 路由、history 路由、有本地登录页或无本地登录页
+- 需要统一处理登出、401、个人中心、旧账号绑定
+
+SDK 不负责这些业务逻辑：
+
+- 子系统自己的用户信息接口，例如 `/api/user/info`
+- 菜单权限、角色权限、账号激活状态
+- Pinia、Redux、Umi initialState 等状态管理细节
+- 本地登录页的 UI 和路由跳转策略
+- 离线私有化 token 模式
+- 子系统业务 request 的完整封装
+
+## 接入总览
+
+一个新子系统建议按下面顺序接入：
+
+1. 后端提供固定 `/api/oidc/*` 接口。
+2. 后端设置前端可读的 session cookie。
+3. 前端安装 `aid-sso-sdk`。
+4. 创建子系统自己的 `ssoSdk` 单例。
+5. 配置业务请求携带 cookie。
+6. 在路由守卫或应用初始化里判断登录态。
+7. 根据产品形态选择“直接跳 SSO”或“先进入本地登录页”。
+8. 登录页或登录按钮调用 SDK 跳转 SSO。
+9. 注册入口调用 SDK 跳转 SSO 注册。
+10. 旧账号迁移场景调用 SDK 绑定流程。
+11. 业务请求拦截器使用 SDK 判断 401 并清理状态。
+12. 用户菜单接入登出和 AidLux 个人中心。
+13. 按验收清单验证完整流程。
+
+## 1. 后端接口准备
+
+所有子系统后端必须提供固定 OIDC 接口：
+
+```text
+GET  /api/oidc/login
+GET  /api/oidc/register
+GET  /api/oidc/callback
+POST /api/oidc/logout
+GET  /api/oidc/aidauth
+```
+
+接口职责：
+
+- `/api/oidc/login`：接收 `return_path` 和可选 `extra_param`，然后 302 到 SSO 登录。
+- `/api/oidc/register`：接收 `return_path` 和可选 `extra_param`，然后进入 SSO 注册流程。
+- `/api/oidc/callback`：由 OIDC Provider 回调，后端完成 code 换 token、创建 session、写 cookie，然后 302 回 `return_path`。
+- `/api/oidc/logout`：清理服务端 session，并通过 `Set-Cookie: Max-Age=0` 清理 cookie。
+- `/api/oidc/aidauth`：返回 AidLux 登录中心地址，用于前端构造个人中心 URL。
+
+前端 SDK 不处理 OIDC 的 client id、client secret、authorize、token 交换等后端细节。
+
+## 2. Cookie 约定
+
+每个子系统都需要确定自己的 session cookie 名称：
+
+```ts
+const COOKIE_NAME = 'your_system_session';
+```
+
+要求：
+
+- cookie 由子系统后端设置。
+- cookie 名称不要和其他子系统冲突。
+- cookie 必须允许前端读取，不能设置 `HttpOnly`。
+- 前端只判断 cookie 是否存在，不解析 cookie 值。
+- 业务请求通过浏览器自动携带 cookie 完成鉴权。
+
+已有示例：
+
+```text
+aimo            -> aimo_session
+license-manger -> ls_session
+```
+
+## 3. 安装 SDK
+
+开发阶段通过本地目录依赖安装：
+
+```bash
+pnpm add file:../aid-sso-sdk
+```
+
+发布到 npm 源后：
+
+```bash
+npm install aid-sso-sdk
+```
+
+如果项目使用 pnpm，建议保持锁文件只使用 `pnpm-lock.yaml`，不要同时维护多种 lockfile。
+
+## 4. 创建 SSO SDK
+
+建议在子系统里新建一个独立文件：
+
+```text
+src/utils/sso.ts
+```
+
+示例：
+
+```ts
+import { createSsoSdk } from 'aid-sso-sdk';
+
+export const ssoSdk = createSsoSdk({
+  cookieName: 'your_system_session',
+  from: 'aimo',
+  clearLocalAuth() {
+    localStorage.removeItem('access_token');
+    localStorage.removeItem('refresh_token');
+    localStorage.removeItem('user');
+  },
+});
+```
+
+配置说明：
+
+```ts
+type SsoSdkOptions = {
+  cookieName: string;
+  oidcBasePath?: '/api/oidc';
+  from?: 'aimo' | 'aic';
+  oidcServerAddress?: string | (() => string);
+  navigate?: (url: string) => void;
+  clearLocalAuth?: () => void;
+};
+```
+
+字段说明：
+
+- `cookieName`：必填，必须和后端写入的 session cookie 名一致。
+- `oidcBasePath`：默认 `/api/oidc`，当前规范固定为该值。
+- `from`：来源子系统标识。当前 SDK 已固定为 `'aimo' | 'aic'`，新增来源前需要先确认 SSO 是否支持。
+- `oidcServerAddress`：子系统前端访问地址，默认 `window.location.origin`。
+- `navigate`：自定义跳转函数，默认 `window.location.assign(url)`。
+- `clearLocalAuth`：清理子系统自己的本地登录状态，SDK 会在登出和 401 处理中调用。
+
+`from` 和 `oidcServerAddress` 是配套参数。只要配置了 `from`，SDK 就会在 `extra_param` 中配套传递 `oidc_server_address`；如果调用方没有显式传 `oidcServerAddress`，SDK 默认使用 `window.location.origin`。
+
+这两个参数主要用于注册流程：SSO 可以根据来源子系统和子系统访问地址，拉取或填写对应子系统的申请试用表单信息。
+
+## 5. 业务代码直接使用 ssoSdk
+
+SDK 创建的 `ssoSdk` 实例本身就是一个语义清晰的封装。业务代码直接导入使用，不需要再给每个方法包一层空函数：
+
+```ts
+import { ssoSdk } from '@/utils/sso';
+
+// 判断登录态
+if (!ssoSdk.hasSession()) {
+  ssoSdk.redirectToLogin();
+}
+
+// 登出
+await ssoSdk.logout();
+```
+
+`ssoSdk.hasSession()` 一眼就能看出它来自 SDK；包一层 `hasOidcSession()` 反而多了一层间接，需要跳转到包装文件才能定位实现。
+
+### 什么时候才值得包装
+
+只有一种情况：你需要**改变 SDK 的默认行为**——比如追加子系统特有的默认参数，或者在 SDK 方法前后执行额外的逻辑。
+
+```ts
+// 场景 1：带上项目特有的 extraParam
+export const redirectToLogin = (returnPath?: string) =>
+  ssoSdk.redirectToLogin({
+    returnPath,
+    extraParam: { source: 'license_page' },
+  });
+
+// 场景 2：退出时额外清理子系统缓存
+export const logout = async () => {
+  clearLocalCache();
+  await ssoSdk.logout();
+};
+```
+
+空包装——函数体只有一个 SDK 方法调用、不加任何额外逻辑——不需要写。让业务代码直接用 `ssoSdk` 即可。
+
+## 6. 配置业务请求携带 Cookie
+
+在线 OIDC 模式下，业务请求必须允许携带 cookie。
+
+Axios 示例：
+
+```ts
+axios.create({
+  baseURL: '/api',
+  withCredentials: true,
+});
+```
+
+Umi request 示例：
+
+```ts
+const request = extend({
+  prefix: '/api',
+  credentials: 'include',
+});
+```
+
+注意事项：
+
+- 在线 OIDC 模式下，不要再给业务请求手动注入 `Authorization`。
+- 鉴权凭证由浏览器自动携带 session cookie。
+- 如果项目同时存在离线 token 模式，离线逻辑保留在子系统内部，不放进 SDK。
+
+## 7. 选择登录入口模式
+
+子系统通常有两种登录入口形态。
+
+### 7.1 无本地登录页：直接跳 SSO
+
+适合没有自己登录页的系统，例如 `license-manger`。
+
+路由守卫、页面切换或应用初始化时：
+
+```ts
+if (!ssoSdk.hasSession()) {
+  ssoSdk.redirectToLogin({
+    returnPath: window.location.href,
+  });
+}
+```
+
+如果不传 `returnPath`，SDK 默认使用 `window.location.href`：
+
+```ts
+ssoSdk.redirectToLogin();
+```
+
+### 7.2 有本地登录页：先进入本地 `/login`
+
+适合需要保留本地登录壳、账号密码登录、注册入口、绑定提示的系统，例如 `aimo`。
+
+路由守卫仍由子系统自己控制：
+
+```ts
+router.push(`/login?redirect=${encodeURIComponent(to.fullPath)}`);
+```
+
+登录页读取 `redirect`，计算最终 SSO 回跳地址：
+
+```ts
+const redirect = route.query.redirect as string | undefined;
+const returnPath = `${window.location.origin}/#${redirect || '/'}`;
+
+ssoSdk.redirectToLogin({ returnPath });
+```
+
+注意：
+
+- SDK 不决定是否先进入子系统 `/login`。
+- SDK 只负责最后跳 `/api/oidc/login`。
+- hash 路由、history 路由、本地登录页 redirect 参数由子系统自己计算。
+
+## 8. return_path 规则
+
+SDK 的 `return_path` 规则只有两条，由 `getLoginUrl()`、`redirectToLogin()`、`getRegisterUrl()`、`redirectToRegister()` 等方法内部处理：
+
+- 传了 `returnPath`：原样使用。
+- 没传：使用 `window.location.href`。
+
+常见写法：
+
+history 路由当前页直接跳：
+
+```ts
+ssoSdk.redirectToLogin();
+```
+
+hash 路由在本地登录页里跳：
+
+```ts
+const returnPath = `${window.location.origin}/#${redirect || '/'}`;
+ssoSdk.redirectToLogin({ returnPath });
+```
+
+不要让 SDK 猜测路由模式。子系统最清楚自己的路由结构，应主动传入准确的 `returnPath`。
+
+## 9. 登录和注册
+
+构造登录地址但不跳转：
+
+```ts
+const loginUrl = ssoSdk.getLoginUrl({ returnPath });
+```
+
+直接跳转登录：
+
+```ts
+ssoSdk.redirectToLogin({ returnPath });
+```
+
+构造注册地址但不跳转：
+
+```ts
+const registerUrl = ssoSdk.getRegisterUrl({ returnPath });
+```
+
+直接跳转注册：
+
+```ts
+ssoSdk.redirectToRegister({ returnPath });
+```
+
+登录和注册使用相同的 `return_path` 和 `extra_param` 规则。
+
+## 10. 旧账号绑定流程
+
+绑定流程分为两段：
+
+1. 跳转 SSO 前：子系统调用 `redirectToBind()`，把绑定所需参数带到 SSO。
+2. SSO 登录并回到子系统后：子系统在路由守卫中判断 URL query 里的 `hash`，调用自己的绑定接口完成绑定。
+
+SDK 只负责第一段“跳转并携带参数”。第二段“回来后调用子系统绑定接口”必须由子系统实现，因为绑定接口属于各子系统后端。
+
+当子系统旧账号登录后，后端返回需要绑定 AidLux 账号时，跳转前调用：
+
+```ts
+ssoSdk.redirectToBind({
+  hash,
+  username,
+  returnPath,
+});
+```
+
+SDK 会自动处理：
+
+- `extra_param.hash`
+- `extra_param.username`
+- `extra_param.bind_hash`
+- `extra_param.from`
+- `extra_param.oidc_server_address`
+- 顶层 query `bind_hash`
+
+如果后端返回了独立的 `bindHash`：
+
+```ts
+ssoSdk.redirectToBind({
+  hash,
+  bindHash,
+  username,
+  returnPath,
+});
+```
+
+如果还有额外绑定参数：
+
+```ts
+ssoSdk.redirectToBind({
+  hash,
+  username,
+  returnPath,
+  extraParam: {
+    source: 'migration',
+  },
+});
+```
+
+`redirectToBind()` 最终会跳转到：
+
+```text
+/api/oidc/login?return_path=...&bind_hash=...&extra_param=...
+```
+
+SSO 登录完成后，子系统后端 callback 会把 `extra_param` 里的 `hash` 带回子系统前端路由。子系统需要在路由守卫中处理：
+
+```ts
+router.beforeEach(async (to, _, next) => {
+  const query = to.query;
+
+  if (query?.hash) {
+    try {
+      await userBind({ hash: query.hash as string });
+      // 绑定成功后移除 hash，避免刷新或再次进入路由时重复绑定
+      to.query = omit(to.query, ['hash']);
+      next(to);
+      return;
+    } catch (error) {
+      // 绑定失败时应清理 hash，避免登录/绑定循环
+      to.query = omit(to.query, ['hash', 'redirect']);
+      next('/login');
+      return;
+    }
+  }
+
+  next();
+});
+```
+
+`aimo` 当前就是这种处理方式：在 `src/router/index.ts` 中判断 `query.hash`，然后调用 `userBind({ hash })`。离线 token 回调场景下，也是在处理 `access_token` 后继续判断 `query.hash` 并调用同一个绑定接口。
+
+注意事项：
+
+- `redirectToBind()` 不会调用子系统绑定接口。
+- 绑定接口由子系统后端提供，例如 `userBind({ hash })`。
+- 绑定成功后要从 URL 中移除 `hash`，避免重复绑定。
+- 绑定失败后要清理 `hash` 或重新进入登录流程，避免死循环。
+
+## 11. extra_param
+
+`extraParam` 会被序列化为一个 `extra_param` 字符串，用于把来源系统、绑定信息或其他后端需要的上下文透传给 OIDC 流程：
+
+```ts
+ssoSdk.redirectToLogin({
+  returnPath,
+  extraParam: {
+    source: 'invite',
+  },
+});
+```
+
+生成结构类似：
+
+```text
+/api/oidc/login?return_path=...&extra_param=from=aimo&oidc_server_address=...&source=invite
+```
+
+接入方通常只需要关心 `extraParam`。绑定流程历史上还需要顶层 query `bind_hash`，这个参数由 SDK 在 `redirectToBind()` 内部自动生成，不需要业务方手动传。
+
+## 12. 401 和 Session 过期处理
+
+SDK 不封装业务请求客户端，但提供公共常量和判断函数。
+
+```ts
+import { isUnauthorizedBusinessCode, isUnauthorizedStatus } from 'aid-sso-sdk';
+
+if (isUnauthorizedStatus(response.status) || isUnauthorizedBusinessCode(data.code)) {
+  ssoSdk.handleUnauthorized({
+    returnPath: window.location.href,
+  });
+}
+```
+
+SDK 当前默认识别：
+
+```ts
+const HTTP_UNAUTHORIZED_STATUS = 401;
+const BUSINESS_UNAUTHORIZED_CODE = 401;
+const BUSINESS_SESSION_EXPIRED_CODE = 4011;
+const DEFAULT_UNAUTHORIZED_BUSINESS_CODES = [401, 4011] as const;
+```
+
+`handleUnauthorized()` 会执行：
+
+```text
+clearLocalAuth()
+clearSession()
+redirectToLogin()
+```
+
+如果只想清理，不想立即跳转：
+
+```ts
+ssoSdk.handleUnauthorized({
+  redirect: false,
+});
+```
+
+## 13. 登出
+
+推荐用户点击登出时调用：
+
+```ts
+try {
+  await ssoSdk.logout();
+} catch (error) {
+  console.error(error);
+}
+
+ssoSdk.redirectToLogin();
+```
+
+也可以让 SDK 在登出成功后直接跳登录：
+
+```ts
+await ssoSdk.logout({
+  redirectToLogin: true,
+  returnPath: window.location.href,
+});
+```
+
+`logout()` 行为：
+
+- 调用 `POST /api/oidc/logout`
+- 执行 `clearLocalAuth()`
+- 清理当前 session cookie
+- 如果后端登出失败，清理仍会执行，然后先抛出错误，不会继续自动跳转登录
+- `redirectToLogin: true` 只在登出接口成功时生效
+
+## 14. AidLux 个人中心
+
+用户菜单中跳转个人中心：
+
+```ts
+const profileUrl = await ssoSdk.getAidProfileUrl({
+  targetUserId: user.aid_user_id,
+  targetUsername: user.aid_username,
+  type: 'account',
+});
+
+window.open(profileUrl, '_blank');
+```
+
+SDK 会调用 `GET /api/oidc/aidauth` 获取登录中心地址，并生成 AidLux `/user/profile` 个人中心地址。
+
+`type` 只能使用 SSO 当前已有页面：
+
+```ts
+type AidProfilePageType = 'profile' | 'account' | 'password' | 'bind_phone' | 'bind_email';
+```
+
+`/api/oidc/aidauth` 固定返回：
+
+```json
+{ "login_page_url": "https://auth.aidlux.com" }
+```
+
+## 15. 开发代理和部署注意事项
+
+开发环境代理必须确保 `/api/oidc/*` 能到达子系统后端，并且必须设置 `changeOrigin: false`。
+
+`changeOrigin: false` 很重要：它可以保留浏览器访问前端时的 Host/来源上下文，避免代理把请求来源改成后端地址，导致后端解析不到真实使用者 IP 或写入错误域名下的 cookie。
+
+如果业务 API 前缀就是 `/api`，通常一条 `/api` 代理即可覆盖：
+
+```ts
+proxy: {
+  '/api': {
+    target: 'http://your-backend',
+    changeOrigin: false, // 必须设置，避免后端解析不到真实使用者 IP
+  },
+}
+```
+
+如果业务 API 前缀不是 `/api`，例如 `/api/v1`，需要额外配置 `/api/oidc`：
+
+```ts
+proxy: {
+  '/api/oidc': {
+    target: 'http://your-backend',
+    changeOrigin: false, // 必须设置，避免后端解析不到真实使用者 IP
+  },
+  '/api/v1': {
+    target: 'http://your-backend',
+    changeOrigin: false, // 必须设置，避免后端解析不到真实使用者 IP
+  },
+}
+```
+
+注意：
+
+- cookie 方案下，开发代理必须设置 `changeOrigin: false`，避免后端解析不到真实使用者 IP，也避免 cookie 域和前端访问域不一致。
+- 生产 Nginx 也要确保 `/api/oidc/*` 代理到子系统后端。
+- OIDC callback 地址应使用前端访问域下的 `/api/oidc/callback`，让 cookie 写在前端访问域。
+
+## 16. 框架接入示例
+
+### Vue 3 + Vue Router
+
+```ts
+// src/utils/sso.ts
+export const ssoSdk = createSsoSdk({
+  cookieName: 'your_session',
+  from: 'aimo',
+  clearLocalAuth() {
+    localStorage.removeItem('user');
+  },
+});
+```
+
+```ts
+// router.beforeEach
+if (!ssoSdk.hasSession()) {
+  next(`/login?redirect=${encodeURIComponent(to.fullPath)}`);
+  return;
+}
+```
+
+```ts
+// Login.vue
+const returnPath = `${window.location.origin}/#${redirect || '/'}`;
+ssoSdk.redirectToLogin({ returnPath });
+```
+
+### React / Umi
+
+```ts
+// src/services/oidc.ts
+export const ssoSdk = createSsoSdk({
+  cookieName: 'ls_session',
+  clearLocalAuth() {
+    persist.clear();
+  },
+});
+```
+
+```ts
+// app.tsx onPageChange
+if (!currentUser?.username && !ssoSdk.hasSession()) {
+  ssoSdk.redirectToLogin({
+    returnPath: window.location.href,
+  });
+}
+```
+
+```ts
+// request interceptor
+if (isUnauthorizedBusinessCode(data.code) || isUnauthorizedStatus(response.status)) {
+  ssoSdk.handleUnauthorized({
+    returnPath: window.location.href,
+  });
+}
+```
+
+## 17. 验收清单
+
+接入完成后至少验证这些场景：
+
+- 未登录访问受保护页面，会进入 SSO 或本地登录页。
+- 登录成功后能回到原页面。
+- hash 路由系统登录后能回到正确 hash 页面。
+- history 路由系统刷新深层路径不丢失。
+- 业务接口能自动携带 session cookie。
+- session 过期时，业务接口 401 能清理本地状态并重新登录。
+- 点击登出后，服务端 session 和前端 cookie 都被清理。
+- 登出后访问受保护页面会重新进入登录流程。
+- 个人中心能打开正确 AidLux `/user/profile` 页面。
+- 绑定流程能携带 `hash`、`username`、`bind_hash` 并完成回跳。
+- 本地登录页模式下，`returnPath` 不会错误指回 `/login`。
+- `/api/oidc/*` 没有经过业务 request 的 `{ code: 200 }` 拦截器。
+
+## 18. 常见问题
+
+### 登录后还是判断未登录
+
+检查：
+
+- 后端是否写入了正确 cookie 名称。
+- cookie 是否设置了 `HttpOnly`。
+- cookie domain/path 是否能被当前前端页面读取。
+- 业务请求是否设置 `withCredentials: true` 或 `credentials: 'include'`。
+
+### 登录后回到了 `/login`
+
+通常是本地登录页传错了 `returnPath`。
+
+有本地登录页时，不要直接使用当前登录页的 `window.location.href`，应读取 `redirect` 后计算最终业务地址。
+
+### `/api/oidc/logout` 或 `/api/oidc/aidauth` 被业务拦截器报错
+
+说明 OIDC 接口可能走了子系统业务 request 封装。
+
+SDK 内部会用原生 `fetch` 调用 OIDC 原始接口，业务代码不要再用 axios/umi-request 包一层调用这些接口。
+
+### 新子系统的 `from` 类型不允许
+
+当前 SDK 已按 SSO 现有值固定为：
+
+```ts
+type SsoSubsystemFrom = 'aimo' | 'aic';
+```
+
+新增来源前，需要先确认 SSO 侧是否支持，再扩展 SDK 类型。
+
+## 19. API 摘要
+
+```ts
+type OidcBasePath = '/api/oidc';
+type SsoSubsystemFrom = 'aimo' | 'aic';
+type AidProfilePageType = 'profile' | 'account' | 'password' | 'bind_phone' | 'bind_email';
+
+type SsoSdkOptions = {
+  cookieName: string;
+  oidcBasePath?: OidcBasePath;
+  from?: SsoSubsystemFrom;
+  oidcServerAddress?: string | (() => string);
+  navigate?: (url: string) => void;
+  clearLocalAuth?: () => void;
+};
+
+type SsoSdk = {
+  hasSession(): boolean;
+  clearSession(): void;
+  getLoginUrl(input?: { returnPath?: string; extraParam?: ExtraParamMap }): string;
+  redirectToLogin(input?: { returnPath?: string; extraParam?: ExtraParamMap }): void;
+  getRegisterUrl(input?: { returnPath?: string; extraParam?: ExtraParamMap }): string;
+  redirectToRegister(input?: { returnPath?: string; extraParam?: ExtraParamMap }): void;
+  redirectToBind(input: BindInput): void;
+  logout(input?: { redirectToLogin?: boolean; returnPath?: string }): Promise<void>;
+  getAidProfileUrl(input?: AidProfileUrlInput): Promise<string>;
+  handleUnauthorized(input?: { redirect?: boolean; returnPath?: string }): void;
+};
+
+const HTTP_UNAUTHORIZED_STATUS = 401;
+const BUSINESS_UNAUTHORIZED_CODE = 401;
+const BUSINESS_SESSION_EXPIRED_CODE = 4011;
+const DEFAULT_UNAUTHORIZED_BUSINESS_CODES = [401, 4011] as const;
+
+function isUnauthorizedStatus(status?: number | null): boolean;
+function isUnauthorizedBusinessCode(code?: number | string | null): boolean;
+```