@lark-apaas/auth-sdk 0.1.0-alpha.6 → 0.1.0-alpha.8

package/README.md

@@ -1,8 +1,8 @@
-## @lark-apaas/auth-sdk
+# @lark-apaas/auth-sdk
 
 基于 CASL 的前端鉴权 SDK，封装了权限数据获取、Ability 初始化与 React 集成，帮助你在应用中便捷地做「功能级/按钮级/菜单级/页面级」的权限控制。
 
-### 安装
+## 安装
 
 ```bash
 npm i @lark-apaas/auth-sdk
@@ -10,7 +10,9 @@ npm i @lark-apaas/auth-sdk
 yarn add @lark-apaas/auth-sdk
 ```
 
-### 快速开始
+## 快速开始
+
+### 模版接入
 
 ```tsx
 import React from 'react';
@@ -31,37 +33,114 @@ export default function App() {
     </AuthProvider>
   );
 }
+```
+
+### 开发组件 - 使用 Can 组件
+
+```tsx
+import { CanRole } from '@lark-apaas/auth-sdk';
 
 function Home() {
-  const ability = useAuthAbility();
   return (
     <div>
-      <Can I="admin" a="@role">
+      <CanRole roles={['role_admin']}>
+        <div>管理员按钮</div>
+      </CanRole>
+      <CanRole roles={['role_admin', 'role_editor']}>
+        <div>编辑按钮</div>
+      </CanRole>
+    </div>
+  );
+}
+```
+
+### 开发组件 - 使用 AbilityContext 处理复杂场景
+
+```tsx
+import { useContext } from 'react';
+import { AbilityContext, ROLE_SUBJECT } from '@lark-apaas/auth-sdk';
+
+function Home() {
+  const ability = useContext(AbilityContext);
+  return (
+    <div>
+      {ability.can('role_admin', ROLE_SUBJECT) || ability.can('role_editor', ROLE_SUBJECT) ? (
         <div>可见的仪表盘</div>
-      </Can>
-      <button disabled={ability.cannot('reader', '@role')}>创建任务</button>
+      ) : null}
     </div>
   );
 }
 ```
 
+### 开发组件 - 进阶示例
+
+### 菜单按权限过滤
+
+```tsx
+import { useContext } from 'react';
+import { AbilityContext } from '@lark-apaas/auth-sdk';
+
+const menus = [
+  { name: 'Dashboard', path: '/dashboard', p: { action: 'role_admin', subject: '@role' } },
+  { name: 'Users', path: '/users', p: { action: 'role_editor', subject: '@role' } },
+  { name: 'Settings', path: '/settings', p: { action: 'role_admin', subject: '@role' } },
+];
+
+function Nav() {
+  const ability = useContext(AbilityContext);
+  return (
+    <nav>
+      {menus.map(m => ability.can(m.p.action, m.p.subject) && (
+        <a key={m.path} href={m.path}>{m.name}</a>
+      ))}
+    </nav>
+  );
+} 
+```
+
 ---
 
-## 核心 API
+## 核心 API - 面向 Agent
+
+### CanRole 组件 (推荐)
+
+- **作用**: 条件渲染，只有当角色 id 包含在 `roles` 中时才渲染子内容。
+
+```tsx
+<CanRole roles={['role_admin', 'role_editor']}>
+  <button>删除任务</button>
+</CanRole>
+```
+
+### AbilityContext 提供原子化的权限判断能力
+
+- **作用**: 从 React 上下文获取 CASL `Ability` 实例，使用 `ability.can(action, subject)` 做权限判断。
+
+```tsx
+import { useContext } from 'react';
+import { AbilityContext } from '@lark-apaas/auth-sdk';
+
+const ability = useContext(AbilityContext);
+const canCreate = ability.can('role_editor', '@role');
+```
+
+## 核心 API - 面向接入方
 
 ### AuthProvider
+
 - **作用**: 提供 `Ability` 与权限状态上下文，自动/手动拉取权限。
 - **Props**:
   - `config?: AuthSdkConfig`
+    - `enable?: boolean` 是否启用权限 SDK，默认 false
     - `permissionApi?: PermissionApiConfig` 拉取权限接口配置
       - `timeout?: number`，默认 5000ms
       - `headers?: Record<string,string>` 自定义请求头
-    - `enable?: boolean` 是否启用权限 SDK，默认 false
     - `onError?: (error: Error) => void`
     - `onSuccess?: (data: PermissionApiResponse) => void`
   - `children: React.ReactNode`
 
 示例：
+
 ```tsx
 <AuthProvider config={{
   enable: true,
@@ -71,36 +150,10 @@ function Home() {
 </AuthProvider>
 ```
 
-### useAuth
-- **作用**: 访问权限状态与方法。
-- **返回**:
-  - `ability: Ability` CASL `Ability` 实例
-  - `isLoading: boolean` 是否正在加载权限数据
-  - `error: Error | null` 最近一次加载错误（如果有）
-  - `fetchPermissions(userId?: string): Promise<void>` 手动拉取权限数据
-
-```tsx
-const { ability, isLoading, error, fetchPermissions } = useAuth();
-```
-
-### useAuthAbility
-- **作用**: 获取 CASL `Ability` 实例，使用 `ability.can(action, subject)` 做任意判断。
-
-```tsx
-const ability = useAuthAbility();
-const canCreate = ability.can('Editor', '@role');
-```
-
-### Can 组件（来自 @casl/react 的 Contextual Can）
-- **作用**: 条件渲染，只有当 `I` 对 `a` 可操作时才渲染子内容；也支持 render prop。
-
-```tsx
-<Can I="Editor" a="@role">
-  <button>删除任务</button>
-</Can>
-```
+## 核心 API - 面向 SDK 开发者
 
 ### PermissionClient
+
 - **作用**: 独立的权限数据获取客户端，供非 React 场景（或自定义状态管理）使用。
 - **方法**:
   - `constructor(config?: PermissionApiConfig)`
@@ -116,6 +169,7 @@ const data = await client.fetchPermissions('user-123');
 ```
 
 ### 能力工厂（与 CASL 交互）
+
 - `createAbility({ permissions?: Permission[], roles?: string[] }): Ability`
 - `updateAbility(ability: Ability, { permissions?: Permission[], roles?: string[] }): void`
 - `convertPermissionsToRules(permissions: Permission[], roles: string[]): CaslRule[]`
@@ -133,50 +187,20 @@ updateAbility(ability, { permissions: [{ id: 'p1', name: 'Task Read', sub: 'Task
 ---
 
 ## 类型与再导出
-- 从本包导出的类型：`PermissionApiResponse`、`PermissionApiConfig`、`AuthSdkConfig`、`CaslRule`。
-- 便捷再导出：`MongoAbility`, `AbilityBuilder`, `AbilityClass`（来自 `@casl/ability`）。
 
----
+- 从本包导出的类型：`PermissionApiResponse`、`PermissionApiConfig`、`AuthSdkConfig`、`CaslRule`。
+- 最终用户代码中仅需要使用到的 API 有：
+  - `CanRole` 组件: 条件渲染，只有当角色 id 包含在 `roles` 中时才渲染子内容。
+  - `AbilityContext`: 从 React 上下文获取 CASL `Ability` 实例，用于权限判断。
+  - `ROLE_SUBJECT`: 特殊 subject `@role` 常量，用于角色判断。
 
 ## 集成建议与最佳实践
-- **权限接口返回**：`{ role_ids: string[] }`。
-- **错误处理**：实现 `onError` 上报或提示；`onSuccess` 可做埋点。
-- **渲染时机**：根据 `useAuth()` 的 `isLoading`/`error` 渲染 Loading/Error 页，避免闪烁。
-- **与路由结合**：页面级的访问控制需要结合路由库（如 `react-router-dom`）和 `useAuthAbility` hook 来自行实现。
 
----
-
-## 进阶示例
-
-### 菜单按权限过滤
-```tsx
-import { useAuthAbility } from '@lark-apaas/auth-sdk';
-
-const menus = [
-  { name: 'Dashboard', path: '/dashboard', p: { action: 'Editor', subject: '@role' } },
-  { name: 'Users', path: '/users', p: { action: 'Admin', subject: '@role' } },
-  { name: 'Settings', path: '/settings', p: { action: 'Admin', subject: '@role' } },
-];
-
-function Nav() {
-  const ability = useAuthAbility();
-  return (
-    <nav>
-      {menus.map(m => ability.can(m.p.action, m.p.subject) && (
-        <a key={m.path} href={m.path}>{m.name}</a>
-      ))}
-    </nav>
-  );
-}
-```
-
----
-
-## 常见问题（FAQ）
-- **如何做角色判断？** 角色被映射为对特殊 subject `@role` 的 action。你可以使用 `ability.can('admin_role', '@role')` 来判断当前用户是否拥有 `admin_role` 角色。
-- **如何实现路由守卫？** 由于 `CanRoute` 组件已移除，您需要结合您使用的路由库（如 `react-router-dom`）和 `useAuthAbility` hook 来手动实现路由守卫。通过在路由渲染前检查权限，然后决定是否渲染组件或重定向。
+- **直接使用组件**：`CanRole` 组件是直接使用的主要入口，可以使用 `AbilityContext` 获取 `Ability` 实例，在特殊场景下手动判断权限。
+- **与路由结合**：页面级的访问控制需要结合路由库（如 `react-router-dom`）和 `AbilityContext` 来自行实现。
 
 ---
 
 ## 许可
+
 MIT

package/lib/AuthProvider.d.ts

@@ -46,6 +46,13 @@ export interface AuthProviderProps {
  * ```
  */
 export declare function AuthProvider({ children, config }: AuthProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * 获取 Ability 实例
+ *
+ * @param permissionApiConfig - 权限 API 配置
+ * @returns Ability 实例或错误
+ */
+export declare function getAbility(permissionApiConfig: AuthSdkConfig['permissionApi']): Promise<Error | MongoAbility<import("@casl/ability").AbilityTuple, import("@casl/ability").MongoQuery>>;
 /**
  * useAuth Hook - 获取权限数据和加载状态
  *
@@ -104,6 +111,9 @@ export declare function useAuthAbility(): MongoAbility;
  * ```
  */
 export declare const Can: React.FunctionComponent<import("@casl/react").BoundCanProps<MongoAbility<import("@casl/ability").AbilityTuple, import("@casl/ability").MongoQuery>>>;
+export declare const useCanRole: ({ roles }: {
+    roles: string[];
+}) => boolean;
 /**
  * CanRole Component - 基于 Ability 实例的角色条件渲染组件
  *
@@ -113,16 +123,16 @@ export declare const Can: React.FunctionComponent<import("@casl/react").BoundCan
  *
  * function MyComponent() {
  *   return (
- *     <CanRole I="Admin">
+ *     <CanRole role="Admin">
  *       <TaskList />
  *     </CanRole>
  *   );
  * }
  * ```
  */
-export declare const CanRole: ({ children, I, }: {
+export declare function CanRole({ children, roles, }: {
     children: React.ReactNode;
-    I: string;
-}) => import("react/jsx-runtime").JSX.Element;
+    roles: string[];
+}): import("react/jsx-runtime").JSX.Element | null;
 export {};
 //# sourceMappingURL=AuthProvider.d.ts.map

package/lib/AuthProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthProvider.d.ts","sourceRoot":"","sources":["../src/AuthProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAMN,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C;;GAEG;AACH,eAAO,MAAM,cAAc,uGAE1B,CAAC;AAEF;;;GAGG;AACH,UAAU,qBAAqB;IAC7B,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,gBAAgB,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAOD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,iBAAiB,2CA2DnE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,IAAI,qBAAqB,CAQ/C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAE7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,GAAG,sJAA+C,CAAC;AAEhE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,GAAI,kBAGrB;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,CAAC,EAAE,MAAM,CAAC;CACX,4CAIA,CAAC"}
+{"version":3,"file":"AuthProvider.d.ts","sourceRoot":"","sources":["../src/AuthProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAMN,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAK7C;;GAEG;AACH,eAAO,MAAM,cAAc,uGAE1B,CAAC;AAEF;;;GAGG;AACH,UAAU,qBAAqB;IAC7B,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,gBAAgB,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAOD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,iBAAiB,2CA2DnE;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,mBAAmB,EAAE,aAAa,CAAC,eAAe,CAAC,2GAiBpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,IAAI,qBAAqB,CAQ/C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,IAAI,YAAY,CAE7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,GAAG,sJAA+C,CAAC;AAEhE,eAAO,MAAM,UAAU,GAAa,WAAW;IAAE,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,KAAG,OAepE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,kDAIA"}

package/lib/AuthProvider.js

@@ -1,4 +1,4 @@
-import { jsx } from "react/jsx-runtime";
+import { Fragment, jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useState } from "react";
 import { ROLE_SUBJECT, createAbility, updateAbility } from "./ability-factory.js";
 import { PermissionClient } from "./permission-client.js";
@@ -54,6 +54,20 @@ function AuthProvider({ children, config }) {
         })
     });
 }
+async function getAbility(permissionApiConfig) {
+    const ability = createAbility({});
+    const client = new PermissionClient(permissionApiConfig);
+    try {
+        const data = await client.fetchPermissions();
+        updateAbility(ability, {
+            roles: data.roles
+        });
+    } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        return error;
+    }
+    return ability;
+}
 function useAuth() {
     const context = useContext(AuthStateContext);
     if (!context) throw new Error('useAuth must be used within an AuthProvider');
@@ -63,9 +77,19 @@ function useAuthAbility() {
     return useContext(AbilityContext);
 }
 const Can = createContextualCan(AbilityContext.Consumer);
-const CanRole = ({ children, I })=>/*#__PURE__*/ jsx(Can, {
-        I: I,
-        a: ROLE_SUBJECT,
-        children: children
+const useCanRole = function({ roles }) {
+    const context = useContext(AuthStateContext);
+    if (!context) return false;
+    const { ability } = context;
+    const allowed = !roles || 0 === roles.length || roles.length > 0 && roles.some((role)=>ability.can(role, ROLE_SUBJECT));
+    return !!allowed;
+};
+function CanRole({ children, roles }) {
+    const allowed = useCanRole({
+        roles
     });
-export { AbilityContext, AuthProvider, Can, CanRole, useAuth, useAuthAbility };
+    return allowed ? /*#__PURE__*/ jsx(Fragment, {
+        children: children
+    }) : null;
+}
+export { AbilityContext, AuthProvider, Can, CanRole, getAbility, useAuth, useAuthAbility, useCanRole };

package/lib/index.d.ts

@@ -4,10 +4,9 @@
  * 基于 CASL 的前端鉴权 SDK
  * 封装了权限数据获取和 Ability 初始化逻辑
  */
-export type { Action, Subject, Permission, UserRole, PermissionApiResponse, PermissionApiConfig, AuthSdkConfig, CaslRule, } from './types';
-export { createAbility, updateAbility, convertPermissionsToRules, ROLE_SUBJECT, } from './ability-factory';
+export type { PermissionApiResponse, PermissionApiConfig, AuthSdkConfig, } from './types';
+export { ROLE_SUBJECT } from './ability-factory';
 export { PermissionClient } from './permission-client';
-export { AuthProvider, useAuth, useAuthAbility, Can, AbilityContext, } from './AuthProvider';
+export { AuthProvider, useAuth, CanRole, AbilityContext } from './AuthProvider';
 export type { AuthProviderProps } from './AuthProvider';
-export { MongoAbility, AbilityBuilder, type AbilityClass } from '@casl/ability';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,MAAM,EACN,OAAO,EACP,UAAU,EACV,QAAQ,EACR,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,EACb,QAAQ,GACT,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,aAAa,EACb,aAAa,EACb,yBAAyB,EACzB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EACL,YAAY,EACZ,OAAO,EACP,cAAc,EACd,GAAG,EACH,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,GACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhF,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/lib/index.js

@@ -1,5 +1,4 @@
-import { ROLE_SUBJECT, convertPermissionsToRules, createAbility, updateAbility } from "./ability-factory.js";
+import { ROLE_SUBJECT } from "./ability-factory.js";
 import { PermissionClient } from "./permission-client.js";
-import { AbilityContext, AuthProvider, Can, useAuth, useAuthAbility } from "./AuthProvider.js";
-import { AbilityBuilder, MongoAbility } from "@casl/ability";
-export { AbilityBuilder, AbilityContext, AuthProvider, Can, MongoAbility, PermissionClient, ROLE_SUBJECT, convertPermissionsToRules, createAbility, updateAbility, useAuth, useAuthAbility };
+import { AbilityContext, AuthProvider, CanRole, useAuth } from "./AuthProvider.js";
+export { AbilityContext, AuthProvider, CanRole, PermissionClient, ROLE_SUBJECT, useAuth };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/auth-sdk",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "基于 CASL 的前端鉴权 SDK",
   "types": "./lib/index.d.ts",
   "main": "./lib/index.js",