@tsingroc/tsingroc-components 3.14.0 → 4.0.0

package/src/components/Auth.tsx

@@ -0,0 +1,608 @@
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { jwtDecode, type JwtPayload } from "jwt-decode";
+import Sdk from "casdoor-js-sdk";
+import type { SdkConfig } from "casdoor-js-sdk/lib/esm/sdk";
+
+export type AccessTokenPayload =
+  | CasdoorAccessTokenPayload
+  | LocalAccessTokenPayload;
+
+interface CasdoorAccessTokenPayload extends JwtPayload {
+  /**
+   * Token 的发布者。见 [JWT 标准][1]。
+   *
+   * [1]: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+   */
+  iss: string;
+  /**
+   * Token 的主题。见 [JWT 标准][1]。
+   *
+   * [1]: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+   */
+  sub: string;
+  /**
+   * Token 的目标应用 ID。见 [JWT 标准][1]。
+   *
+   * [1]: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+   */
+  aud: string[];
+  /**
+   * 使用 Token 的应用 ID。见 [JWT 标准][1]。
+   *
+   * [1]: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+   */
+  azp: string;
+  /**
+   * Token 的唯一标识符。见 [JWT 标准][1]。
+   *
+   * [1]: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+   */
+  jti: string;
+  /** Token 的过期时间（Unix 时间戳）。*/
+  exp: number;
+  /** Token 的生效时间（Unix 时间戳）。*/
+  nbf: number;
+  /** Token 的签发时间（Unix 时间戳）。*/
+  iat: number;
+
+  /** 用户的登录名。*/
+  name: string;
+  /** 用户的 UUID。*/
+  id: string;
+  /** 用户的显示名。*/
+  displayName: string;
+  /** 用户的头像 URL。*/
+  avatar: string;
+  /** 用户的邮件地址。*/
+  email: string;
+  /** 用户的手机号。*/
+  phone: string;
+
+  owner: "tsingroc";
+  tokenType: "access-token";
+  scope: "profile";
+}
+
+interface LocalAccessTokenPayload extends JwtPayload {
+  /** Token 的过期时间（Unix 时间戳）。*/
+  exp: number;
+  /** Token 的生效时间（Unix 时间戳）。*/
+  nbf: number;
+  /** Token 的签发时间（Unix 时间戳）。*/
+  iat: number;
+  /** 用户信息 */
+  User: {
+    /** 注册时间。*/
+    createTime: string;
+    /** 用户的 UUID。*/
+    id?: string;
+    /** 用户名。*/
+    username?: string;
+    /** 是否已删除。*/
+    deleted?: boolean;
+    /** 用户的角色。*/
+    role: {
+      /** 角色的 UUID。*/
+      id: string;
+      /** 角色名。*/
+      name: string;
+      /** 角色的显示名。*/
+      display_name: string;
+      /** 角色拥有的权限。*/
+      functions: string[];
+      /** 角色的优先级。*/
+      priority: number;
+    };
+    /** 用户的角色的 UUID。*/
+    roleId: string;
+  };
+}
+
+export type UserInfo = CasdoorUserInfo | LocalUserInfo;
+
+interface CasdoorUserInfo {
+  /**
+   * Token 的发布者。见 [JWT 标准][1]。
+   *
+   * [1]: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+   */
+  iss: string;
+  /**
+   * Token 的主题。见 [JWT 标准][1]。
+   *
+   * [1]: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+   */
+  sub: string;
+  /**
+   * Token 的目标应用 ID。见 [JWT 标准][1]。
+   *
+   * [1]: https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+   */
+  aud: string;
+  /** 用户的全名（显示名）。*/
+  name: string;
+  /** 短用户名（登录名）。*/
+  prefered_username?: string;
+  /** 用户的邮件地址。*/
+  email?: string;
+  /** 用户的邮件地址是否已确认。*/
+  email_verified?: boolean;
+  /** 用户的手机号。*/
+  phone?: string;
+  /** 用户的头像 URL。*/
+  picture: string;
+  /** 用户的地址。*/
+  address?: string;
+  /** 用户所属的用户组。*/
+  groups: string[];
+  /** 用户的角色。*/
+  roles: string[];
+}
+
+interface LocalUserInfo {
+  /** 注册时间。*/
+  createTime?: string;
+  /** 用户的 UUID。*/
+  id?: string;
+  /** 用户名。*/
+  username?: string;
+  /** 用户的角色。*/
+  roles: string[];
+}
+
+export type Auth = CasdoorAuth | LocalAuth;
+
+interface CommonAuth {
+  /**
+   * 当前使用的登录机制。
+   *
+   * - `"casdoor"`：基于 Casdoor 的登录系统。
+   * - `"local"`：场站端使用的内网登录系统。
+   */
+  mode: "casdoor" | "local";
+  /**
+   * 跳转到登录页面。
+   *
+   * 参数 `redirect` 可以填入登录完成后要跳转到的地址。如果省略，那么跳转目标将由
+   * {@linkcode AuthCallback} 的 {@linkcode AuthCallbackProps.onRedirect | onRedirect}
+   * 属性决定，默认为跳转到主页。
+   */
+  login(redirect?: string): void;
+  /**
+   * 从登录页面返回时应该调用的回调。当登录状态无效时会**抛出异常**。
+   *
+   * 当 {@linkcode mode | mode === "local"} 时，该函数无效。
+   */
+  callback(): Promise<void>;
+  /** 在线检查用户是否登录。用户未登录时会**抛出异常**。*/
+  validate(): Promise<void>;
+  /**
+   * 登出。
+   *
+   * 参数 `redirect` 可以填入登出后跳转到的地址。如果省略，默认为**不做任何跳转**。
+   * 你也可以在登出后手动加一行跳转操作，比如使用 React Router 的 `navigate`。
+   */
+  logout(redirect?: string): void;
+  /**
+   * 以当前用户的 access token 作为 bearer token 发起请求。
+   * 用法与正常的 {@linkcode fetch} 完全一致。未登录时，返回的 Promise 会立即失败。
+   */
+  fetchWithAuth(
+    resource: RequestInfo | URL,
+    options?: RequestInit,
+  ): Promise<Response>;
+  /** 用户的个人信息，未经过 {@linkcode AuthCheck} 验证时为空。*/
+  userInfo?: UserInfo;
+  /** Access Token，未登录时为空。*/
+  accessToken?: string;
+  /** 解码后的 Access Token，未登录时为空。这里也会有一些用户的个人信息。*/
+  decodedAccessToken?: AccessTokenPayload;
+}
+
+export interface CasdoorAuth extends CommonAuth {
+  mode: "casdoor";
+  /** 全局的 Casdoor SDK 对象。*/
+  sdk: Sdk;
+  userInfo?: CasdoorUserInfo;
+  decodedAccessToken?: CasdoorAccessTokenPayload;
+}
+
+export interface LocalAuth extends CommonAuth {
+  mode: "local";
+  /**
+   * 在登录页面需要通过该函数调用登录 API。
+   *
+   * 账号或密码错误时会**抛出异常**。
+   */
+  localLogin(username: string, password: string): Promise<void>;
+  userInfo?: LocalUserInfo;
+  decodedAccessToken?: LocalAccessTokenPayload;
+}
+
+type User = Pick<CommonAuth, "userInfo" | "accessToken" | "decodedAccessToken">;
+type CasdoorUser = Pick<
+  CasdoorAuth,
+  "userInfo" | "accessToken" | "decodedAccessToken"
+>;
+type LocalUser = Pick<
+  LocalAuth,
+  "userInfo" | "accessToken" | "decodedAccessToken"
+>;
+
+const commonAuth = (
+  user: User,
+  setUser: (user: User) => void,
+): Pick<CommonAuth, "logout" | "fetchWithAuth"> => ({
+  async logout(redirect) {
+    localStorage.removeItem("access_token");
+    setUser({});
+    if (redirect) {
+      location.href = redirect;
+    }
+  },
+  async fetchWithAuth(resource, options) {
+    const token = user.accessToken;
+    if (!token) {
+      throw new Error("未登录时无法使用 fetchWithAuth");
+    }
+    return await fetch(resource, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...options?.headers,
+      },
+    });
+  },
+});
+
+function casdoorAuth(
+  user: User,
+  setUser: (user: User) => void,
+  sdkConfig: SdkConfig,
+  signinOrigin?: string,
+  signinPath?: string,
+): CasdoorAuth {
+  const sdk = new Sdk(sdkConfig);
+  return {
+    mode: "casdoor",
+    sdk,
+    login(redirect?: string) {
+      location.href = sdk.getSigninUrl();
+      if (redirect) {
+        sessionStorage.setItem("login_redirect", redirect);
+      }
+    },
+    async callback() {
+      // sdk 的类型声明有误
+      const resp = (await sdk.signin(
+        signinOrigin ?? location.origin,
+        signinPath,
+      )) as unknown as { token?: string };
+      const token = resp.token;
+      if (!token) {
+        throw new Error("登录 API 返回了异常的结果：" + JSON.stringify(resp));
+      }
+      localStorage.setItem("access_token", token);
+      setUser({
+        accessToken: token,
+        get decodedAccessToken() {
+          return jwtDecode<AccessTokenPayload>(token);
+        },
+      });
+    },
+    async validate() {
+      const token = user.accessToken;
+      if (!token) {
+        throw new Error("未登录！");
+      }
+      // sdk 的类型声明有误
+      const resp = (await sdk.getUserInfo(token)) as unknown as
+        | UserInfo
+        | { status: "error" };
+      if ("status" in resp) {
+        localStorage.removeItem("access_token");
+        setUser({});
+        throw new Error("登陆状态无效！");
+      } else {
+        setUser({ ...user, userInfo: resp });
+      }
+    },
+    ...commonAuth(user, setUser),
+    ...(user as CasdoorUser),
+  };
+}
+
+const localAuth = (
+  user: User,
+  setUser: (user: User) => void,
+  loginPage: string,
+  signinOrigin?: string,
+  signinPath?: string,
+): LocalAuth => ({
+  mode: "local",
+  login(redirect) {
+    location.href = loginPage;
+    if (redirect) {
+      sessionStorage.setItem("login_redirect", redirect);
+    }
+  },
+  async localLogin(username, password) {
+    const resp = await fetch(
+      new URL(signinPath ?? "/api/signin", signinOrigin ?? location.origin),
+      {
+        method: "post",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ username, password }),
+      },
+    );
+    if (resp.status !== 200) {
+      throw new Error("账号或密码错误！");
+    }
+    const json = await resp.json();
+    const token = json.token;
+    if (typeof token !== "string") {
+      throw new Error("登录 API 返回了异常的结果：" + JSON.stringify(json));
+    }
+    localStorage.setItem("access_token", token);
+    setUser({
+      accessToken: token,
+      get decodedAccessToken() {
+        return jwtDecode<AccessTokenPayload>(token);
+      },
+    });
+    const redirect = sessionStorage.getItem("login_redirect");
+    sessionStorage.removeItem("login_redirect");
+    location.href = redirect ?? "/";
+  },
+  async callback() {},
+  async validate() {
+    const token = user.accessToken;
+    if (!token) {
+      throw new Error("未登录！");
+    }
+    const resp = await fetch(
+      new URL("/api/userInfo", signinOrigin ?? location.origin),
+      { headers: { Authorization: `Bearer ${token}` } },
+    );
+    try {
+      if (resp.status !== 200) {
+        throw new Error("登陆状态无效！");
+      }
+      const json = await resp.json();
+      if (!json.data) {
+        throw new Error("登陆状态无效！");
+      }
+      setUser({ ...user, userInfo: json.data });
+    } catch (err) {
+      localStorage.removeItem("access_token");
+      setUser({});
+      throw err;
+    }
+  },
+  ...commonAuth(user, setUser),
+  ...(user as LocalUser),
+});
+
+const AuthContext = createContext<Auth | undefined>(undefined);
+
+/**
+ * 获取登录鉴权相关的工具函数和全局状态。必须在 {@linkcode AuthProvider} 内部才能使用。
+ *
+ * 参数 `user` 仅供组件库内部使用，编写项目代码时可以忽略。
+ */
+export function useAuth(user: string = "useAuth") {
+  const auth = useContext(AuthContext);
+  if (auth === undefined) {
+    throw new Error(user + " 必须在 AuthProvider 内部使用！");
+  }
+  return auth;
+}
+
+export interface AuthProviderProps {
+  /**
+   * 要使用的登录机制。
+   *
+   * - `"casdoor"`：基于 Casdoor 的登录系统。
+   * - `"local"`：场站端使用的内网登录系统。
+   *
+   * @default "casdoor"
+   */
+  mode?: "casdoor" | "local";
+  /**
+   * 用于初始化 Casdoor SDK 的配置对象。
+   * {@linkcode SdkConfig.redirectPath | sdkConfig.redirectPath} 应该指向一个包含
+   * {@linkcode AuthCallback} 组件的路径。
+   */
+  sdkConfig?: SdkConfig;
+  /** {@linkcode mode | mode: "local"} 时，登录页面的路径。*/
+  loginPage?: string;
+  /**
+   * 登录 API 的源点，末尾不带 `/`。
+   * @default location.origin
+   */
+  signinOrigin?: string;
+  /**
+   * 登陆 API 的路径。
+   * @default "/api/signin"
+   */
+  signinPath?: string;
+  /** 需要管理登录状态的内容。*/
+  children: ReactNode;
+}
+
+/**
+ * 为包裹的内容提供登陆状态管理服务，通常应该包裹在整个 App 组件外部。
+ *
+ * 使用时至少需要提供 {@linkcode AuthProviderProps.sdkConfig | sdkConfig} 和
+ * {@linkcode AuthProviderProps.signinOrigin | signinOrigin} 两个属性。
+ * 其中，{@linkcode SdkConfig.redirectPath | sdkConfig.redirectPath} 应该指向一个包含
+ * {@linkcode AuthCallback} 组件的路径。
+ *
+ * 在 {@linkcode AuthProvider} 的内部，
+ * 可以使用 {@linkcode useAuth} 来获取登录鉴权相关的工具函数和全局状态，
+ * 也可以使用 {@linkcode AuthCheck} 来确保某个页面或内容只有已登录用户可以访问。
+ */
+export function AuthProvider(props: AuthProviderProps): ReactNode {
+  const [user, setUser] = useState<User>(() => {
+    const token = localStorage.getItem("access_token");
+    if (!token) {
+      return {};
+    } else {
+      return {
+        accessToken: token,
+        get decodedAccessToken() {
+          return jwtDecode<AccessTokenPayload>(token);
+        },
+      };
+    }
+  });
+  const auth = useMemo<Auth>(() => {
+    if ((props.mode ?? "casdoor") === "casdoor") {
+      if (!props.sdkConfig) {
+        throw new Error(`设置了 mode === "casdoor"，却没有设置 sdkConfig！`);
+      }
+      return casdoorAuth(
+        user,
+        setUser,
+        props.sdkConfig,
+        props.signinOrigin,
+        props.signinPath,
+      );
+    } else {
+      if (!props.loginPage) {
+        throw new Error(`设置了 mode === "local"，却没有设置 loginPage！`);
+      }
+      return localAuth(
+        user,
+        setUser,
+        props.loginPage,
+        props.signinOrigin,
+        props.signinPath,
+      );
+    }
+  }, [
+    props.mode,
+    props.sdkConfig,
+    props.loginPage,
+    props.signinOrigin,
+    props.signinPath,
+    user,
+  ]);
+  return (
+    <AuthContext.Provider value={auth}>{props.children}</AuthContext.Provider>
+  );
+}
+
+export interface AuthCheckProps {
+  /**
+   * 用户必须拥有的角色。用户必须拥有这里列出的所有角色才能访问被保护的内容。
+   * 如果省略，则只需要登录即可访问。
+   */
+  roles?: string[];
+  /**
+   * 在检查过程中时向用户显示的加载界面。
+   * @default "正在登录……"
+   */
+  loading?: ReactNode;
+  /**
+   * 当用户未登录或登录状态验证失败时的回调。默认会跳转到登录。
+   * @default () => auth.login(location.href) // auth = useAuth()
+   */
+  onFail?: (err: unknown) => void;
+  /**
+   * 用户已登录，但不满足权限要求时显示的内容。
+   * @default "您无权访问此页面！"
+   */
+  forbidden?: ReactNode;
+  /** 用户登录后显示的内容。*/
+  children: ReactNode;
+}
+
+/**
+ * 在线检查用户是否登录、是否满足权限要求。
+ * 未登录的用户会被跳转到登录，不满足权限要求的用户会见到警告信息，只有检验通过的用户才能访问内部的内容。
+ *
+ * 该组件必须在 {@linkcode AuthProvider} 内部才能使用。
+ */
+export function AuthCheck(props: AuthCheckProps): ReactNode {
+  const auth = useAuth("AuthCheck");
+  const userInfo = auth.userInfo;
+  // 用于确保在 Strict Mode 下副作用也只执行一次
+  const effectDone = useRef(false);
+  useEffect(() => {
+    if (effectDone.current) return;
+    effectDone.current = true;
+    if (!auth.userInfo) {
+      auth.validate().catch(props.onFail ?? (() => auth.login(location.href)));
+    }
+    // 这个副作用只在首次渲染时执行
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  if (userInfo) {
+    if ((props.roles ?? []).every((role) => userInfo.roles.includes(role))) {
+      return props.children;
+    } else {
+      return props.forbidden ?? "您无权访问此页面！";
+    }
+  } else {
+    return props.loading ?? "正在登录……";
+  }
+}
+
+export interface AuthCallbackProps {
+  /**
+   * 跳转时的回调。传入的 `redirect` 参数就是 {@linkcode Auth.login | login} 函数的参数。
+   * @default (redirect) => { location.href = redirect ?? "/"; }
+   */
+  onRedirect?: (redirect?: string) => void;
+  /**
+   * 发生错误时显示的内容。
+   * @default (err) => err.toString()
+   */
+  error?: (err: unknown) => ReactNode;
+  /**
+   * 跳转前显示的内容。
+   * @default "正在跳转……"
+   */
+  children?: ReactNode;
+}
+
+/**
+ * 从登录页面返回到的回调页面。
+ *
+ * 该组件必须在 {@linkcode AuthProvider} 内部才能使用。
+ */
+export function AuthCallback(props: AuthCallbackProps): ReactNode {
+  const auth = useAuth("AuthCallback");
+  const [error, setError] = useState<unknown>();
+  // 用于确保在 Strict Mode 下副作用也只执行一次
+  const effectDone = useRef(false);
+  useEffect(() => {
+    if (effectDone.current) return;
+    effectDone.current = true;
+    const redirect = sessionStorage.getItem("login_redirect");
+    sessionStorage.removeItem("login_redirect");
+    auth.callback().then(() => {
+      if (props.onRedirect) {
+        props.onRedirect(redirect ?? undefined);
+      } else {
+        location.href = redirect ?? "/";
+      }
+    }, setError);
+    // 这个副作用只在首次渲染时执行
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  if (error) {
+    return props.error ? props.error(error) : (error as object).toString();
+  } else {
+    return props.children ?? "正在跳转……";
+  }
+}