forked from wangziqi/gongxue-base
283 lines
15 KiB
Markdown
283 lines
15 KiB
Markdown
# CASL 授权体系迁移文档
|
||
|
||
## 概述
|
||
|
||
NestJS 后端授权已从基于 `permissions.includes()` 的字符串匹配迁移到 CASL（`@casl/ability`）基于能力的 ABAC 授权模型。
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ AuthorizationModule (@Global) │
|
||
│ │
|
||
│ ┌──────────────────────┐ ┌────────────────────────┐ │
|
||
│ │ CaslAbilityFactory │ │ AuthorizationService │ │
|
||
│ │ │ │ │ │
|
||
│ │ createForUser(user) │ │ can(req, action, subj) │ │
|
||
│ │ → AppAbility │ │ assert(req, ...) │ │
|
||
│ │ │ │ canAbility(ab, ...) │ │
|
||
│ └──────────┬───────────┘ │ assertAbility(ab, ...) │ │
|
||
│ │ └────────────────────────┘ │
|
||
│ ┌──────────▼───────────┐ ┌────────────────────────┐ │
|
||
│ │ casl.constants.ts │ │ PoliciesGuard │ │
|
||
│ │ mapPermissionCode() │ │ @CheckPolicies(…) │ │
|
||
│ │ CaslAction/Subject │ └────────────────────────┘ │
|
||
│ └──────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 核心类型
|
||
|
||
|概念|类型|说明|
|
||
|---|---|---|
|
||
|Action|`CaslAction`|`'manage' \| 'create' \| 'read' \| 'update' \| 'delete'`|
|
||
|Subject|`SubjectName`|`'Student' \| 'Room' \| 'Class' \| …` (所有实体)|
|
||
|Ability|`AppAbility`|`MongoAbility<[CaslAction, AppSubject]>`|
|
||
|User|`AuthenticatedUser`|`{ id, username, permissions, isSuperAdmin, roles }`|
|
||
|
||
### 权限码映射
|
||
|
||
|旧权限码|CASL Action|CASL Subject|
|
||
|---|---|---|
|
||
|`student:view`|`read`|`Student`|
|
||
|`student:create` / `student:import`|`create`|`Student`|
|
||
|`student:edit`|`update`|`Student`|
|
||
|`student:delete`|`delete`|`Student`|
|
||
|`student:export`|`read`|`Student`|
|
||
|`occupancy:checkin`|`create`|`Occupancy`|
|
||
|`occupancy:checkout`|`update`|`Occupancy`|
|
||
|`occupancy:transfer`|`update`|`Occupancy`|
|
||
|`bill:generate` / `bill:confirm`|`update`|`Bill`|
|
||
|`bill:export-excel` / `bill:export-pdf`|`read`|`Bill`|
|
||
|`deposit:approve`|`update`|`Deposit`|
|
||
|`sync:trigger` / `integration:trigger`|`update`|`Sync` / `Integration`|
|
||
|
||
完整映射见 `apps/server/src/authorization/casl.constants.ts`。
|
||
|
||
### 超管处理
|
||
|
||
`isSuperAdmin === true` → `ability.can('manage', 'all')` → 所有操作全部放行。
|
||
|
||
### 未知权限码处理
|
||
|
||
未知/无法映射的权限码（如 `ghost:action`）→ **不产生任何 CASL ability → deny-by-default**。用户对象上仍保留完整的 `permissions` 数组用于前端菜单/日志，但授权判断拒绝未知码。
|
||
|
||
## 修改文件清单
|
||
|
||
### 新增文件
|
||
|
||
|文件|说明|
|
||
|---|---|
|
||
|`apps/server/src/authorization/casl.constants.ts`|Action/Subject 定义、权限码映射函数|
|
||
|`apps/server/src/authorization/interfaces.ts`|`AppAbility`, `AuthenticatedUser`, `PolicyHandler` 类型|
|
||
|`apps/server/src/authorization/casl-ability.factory.ts`|CASL Ability 构建工厂|
|
||
|`apps/server/src/authorization/authorization.service.ts`|通用授权服务（HTTP + 非 HTTP）|
|
||
|`apps/server/src/authorization/authorization.module.ts`|@Global 模块|
|
||
|`apps/server/src/authorization/index.ts`|桶导出|
|
||
|`apps/server/src/authorization/decorators/check-policies.decorator.ts`|`@CheckPolicies()` 装饰器|
|
||
|`apps/server/src/authorization/guards/policies.guard.ts`|`PoliciesGuard` CASL 策略守卫|
|
||
|`apps/server/src/authorization/casl-ability.factory.spec.ts`|工厂测试（17 用例）|
|
||
|`apps/server/src/authorization/authorization.service.spec.ts`|服务测试（12 用例）|
|
||
|`apps/server/src/authorization/guards/policies.guard.spec.ts`|策略守卫测试（7 用例）|
|
||
|
||
### 修改文件
|
||
|
||
|文件|变更|
|
||
|---|---|
|
||
|`apps/server/src/auth/guards/permission.guard.ts`|注入 `CaslAbilityFactory`，用 `ability.can()` 替代 `permissions.includes()`|
|
||
|`apps/server/src/auth/guards/permission.guard.spec.ts`|新增 CASL 授权测试（7 用例）|
|
||
|`apps/server/src/app.module.ts`|导入 `AuthorizationModule`|
|
||
|`apps/server/package.json`|新增 `@casl/ability` 依赖|
|
||
|`apps/server/src/students/students.controller.ts`|注入 `AuthorizationService`，用 CASL 替代 `isSuperAdmin` 检查|
|
||
|`apps/server/src/classes/classes.controller.ts`|同上|
|
||
|`apps/server/src/attendance/attendance.controller.ts`|同上，修复测试兼容|
|
||
|`apps/server/src/schedules/schedules.controller.ts`|同上|
|
||
|`apps/server/src/dashboard/dashboard.controller.ts`|同上|
|
||
|
||
## Agent Tool 使用指南
|
||
|
||
CASL 授权服务**不依赖 HTTP ExecutionContext**，可在 Agent Tool、后台任务、CLI 等场景直接使用：
|
||
|
||
```typescript
|
||
import { CaslAbilityFactory } from './authorization';
|
||
import { AuthorizationService } from './authorization';
|
||
import { CaslAction, SubjectName } from './authorization';
|
||
|
||
// 方式 1: 只构建 Ability
|
||
const factory = app.get(CaslAbilityFactory);
|
||
const ability = factory.createForUser({
|
||
permissions: ['attendance:view', 'attendance:create'],
|
||
isSuperAdmin: false,
|
||
});
|
||
|
||
if (ability.can(CaslAction.Read, SubjectName.Attendance)) {
|
||
// 执行考勤查询
|
||
}
|
||
|
||
// 方式 2: 使用 AuthorizationService
|
||
const authz = app.get(AuthorizationService);
|
||
const toolAbility = factory.createForUser(user);
|
||
authz.assertAbility(toolAbility, CaslAction.Create, SubjectName.Attendance);
|
||
// 如果无权限，抛出 ForbiddenException
|
||
|
||
// 方式 3: 通过 request-like 对象（适用于有 request 模拟的场景）
|
||
authz.assert(
|
||
{ user: { permissions: ['student:view'], isSuperAdmin: false } },
|
||
CaslAction.Read,
|
||
SubjectName.Student,
|
||
);
|
||
```
|
||
|
||
推荐 Agent Tool 使用 **方式 1+2**：先用 `factory.createForUser(user)` 构建 ability，再用 `service.canAbility/assertAbility` 检查。这种方式完全独立于 NestJS 请求生命周期。
|
||
|
||
## 测试命令与结果
|
||
|
||
```bash
|
||
cd apps/server
|
||
|
||
# 全部测试
|
||
npx jest --no-coverage
|
||
# 结果: 27 passed, 127 passed, 3 skipped
|
||
|
||
# 仅 CASL 相关测试
|
||
npx jest --no-coverage authorization/ auth/guards/permission.guard.spec.ts
|
||
# 结果: 54 passed
|
||
|
||
# 类型检查
|
||
npx tsc -p tsconfig.build.json --noEmit
|
||
# 结果: clean (无错误)
|
||
```
|
||
|
||
## 遗留风险 / TODO
|
||
|
||
1. **`class:edit` 宽泛授权**（ponytail 标记）：拥有 `class:edit` 权限的教师目前获得全量学生/排课/考勤管理权限。理想情况下应通过 CASL conditions 限制为仅自己班级的学生。当前数据模型（需查询 `class_teacher` 关联表确定 scope）无法直接在 CASL Ability 中表达。**未降低现有权限**，保留现状并加 TODO。
|
||
|
||
2. **前端权限守卫**：前端 `PermissionRoute` 组件（`apps/admin/src/auth/permission-store.ts`）仍然使用 `permissions.includes()` 检查。不影响安全性（后端是真实授权源），但可在后续迭代中统一。
|
||
|
||
3. **操作日志中的权限上下文**：当前操作日志记录仍使用 `user.permissions` 数组。CASL 迁移未改变日志格式。
|
||
|
||
4. **`dashboard:manage` 权限**：`dashboard` subject 在 preset permissions 中仅有 `dashboard:view`，但 dashboard.controller 检查了 `dashboard:manage`。CASL 映射将 `dashboard:manage` 的未知 action 映射为 `read`（保守），非 super_admin 用户理论上无法通过此检查。但实际上 controller 的权限守卫用的是 `@RequirePermission('dashboard:view')`，CASL 映射正常。`dashboard:manage` 仅出现在内部方法 `canManageAllDashboard` 的 permissions.includes 检查中，现已被 CASL 替代。
|
||
|
||
5. **构建验证**：`npx nest build` 未在迁移中执行（jest + tsc 已覆盖编译和类型检查）。Docker 部署前建议执行一次完整构建。
|
||
|
||
## Agent Tool 只读数据安全执行框架
|
||
|
||
### 架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ AgentToolsModule (NON-HTTP — no controller) │
|
||
│ │
|
||
│ ┌──────────────────────┐ ┌─────────────────────────────┐ │
|
||
│ │ AgentToolRegistry │ │ AgentToolExecutor │ │
|
||
│ │ │ │ │ │
|
||
│ │ listAvailable(ctx) │ │ execute(name, input, ctx) │ │
|
||
│ │ → ToolDef[] │ │ 1. assertPermission │ │
|
||
│ │ │ │ 2. tool.validate(input) │ │
|
||
│ │ Filtered by exact- │ │ 3. tool.execute(…) │ │
|
||
│ │ code permission │ │ 4. audit (best-effort) │ │
|
||
│ └──────────────────────┘ └─────────────────────────────┘ │
|
||
│ │
|
||
│ Built-in tools: │
|
||
│ ┌──────────────────────────────────────────────────────┐ │
|
||
│ │ search_students (student:view) │ │
|
||
│ │ get_student_basic (student:view) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 安全保证
|
||
|
||
1. **动态暴露（listAvailable）**：只暴露 principal 拥有 exact permission 的 Tool。
|
||
2. **执行时二次授权（execute）**：不依赖 `listAvailable`，`execute` 再次调用 `assertPermission`。
|
||
3. **数据库 WHERE 数据范围**：`StudentAccessScope` 使用 TypeORM QueryBuilder + EXISTS 子查询，在 SQL 层面限制数据范围：
|
||
- `manageAll`：超管或全量学生范围 → 无限制
|
||
- `teacher`：仅 `ClassTeacher.userId` 分配班级的 active `ClassStudent`
|
||
4. **输出白名单**：所有 Tool 输出仅限 `id, name, studentNo, gender, status, organizationId, organizationName, classIds`。`phone`, `idNumber`, `emergencyContact`, `emergencyPhone` 不进入查询 SELECT。
|
||
5. **审计**：模块 `AI Agent Tool`，记录 tool 名、状态（success/denied/failed）、userId/username（来自 context principal）。审计写入失败不影响 Tool 调用结果。
|
||
6. **审计脱敏**：审计 detail 绝不包含 raw input、phone、idNumber 等敏感值。
|
||
|
||
### SDK 适配伪代码（provider-neutral）
|
||
|
||
任何 LLM SDK（Vercel AI、LangChain、OpenAI function calling 等）都可以适配：
|
||
|
||
```typescript
|
||
// 1. 获取 NestJS 容器中的 Registry 和 Executor
|
||
const registry = app.get(AgentToolRegistry);
|
||
const executor = app.get(AgentToolExecutor);
|
||
const authz = app.get(AuthorizationService);
|
||
|
||
// 2. 构建可信 AgentToolContext（userId/permissions 来自服务端认证）
|
||
const ability = abilityFactory.createForUser(authenticatedUser);
|
||
const ctx: AgentToolContext = {
|
||
userId: authenticatedUser.id,
|
||
username: authenticatedUser.username,
|
||
permissions: authenticatedUser.permissions,
|
||
isSuperAdmin: authenticatedUser.isSuperAdmin,
|
||
ability,
|
||
};
|
||
|
||
// 3. 动态暴露工具列表（给 LLM SDK 的 tools/functions 定义）
|
||
const availableTools = registry.listAvailable(ctx);
|
||
const sdkTools = availableTools.map(tool => ({
|
||
name: tool.name,
|
||
description: tool.description,
|
||
// … 根据 tool 自定义参数 schema
|
||
}));
|
||
|
||
// 4. 执行 Tool 调用（带输入校验 + 二次授权 + 审计）
|
||
const result = await executor.execute("search_students", rawInput, ctx);
|
||
// result.status: 'success' | 'denied' | 'failed'
|
||
// result.result: 白名单后的数据（仅 success 时）
|
||
// result.error: 错误信息（denied/failed 时）
|
||
```
|
||
|
||
### 新增文件清单
|
||
|
||
|文件|说明|
|
||
|---|---|
|
||
|`src/agent-tools/agent-tool.types.ts`|AgentToolContext, ToolDef, ToolExecutionResult 类型定义|
|
||
|`src/agent-tools/agent-tool.registry.ts`|Tool 注册 + 按权限过滤暴露|
|
||
|`src/agent-tools/agent-tool.executor.ts`|执行时二次授权 + 输入校验 + 审计|
|
||
|`src/agent-tools/tools/search-students.tool.ts`|search_students Tool|
|
||
|`src/agent-tools/tools/get-student-basic.tool.ts`|get_student_basic Tool|
|
||
|`src/agent-tools/agent-tools.module.ts`|NestJS 模块（不暴露 HTTP endpoint）|
|
||
|`src/agent-tools/index.ts`|桶导出|
|
||
|`src/students/student-access-scope.ts`|StudentAccessScope 数据范围类型|
|
||
|`src/agent-tools/agent-tool.executor.spec.ts`|执行器测试（19 用例）|
|
||
|`src/agent-tools/tools/search-students.tool.spec.ts`|search_students 测试（12 用例）|
|
||
|`src/agent-tools/tools/get-student-basic.tool.spec.ts`|get_student_basic 测试（10 用例）|
|
||
|`src/students/students.agent-api.spec.ts`|agent-safe API 测试（17 用例）|
|
||
|
||
### 修改文件
|
||
|
||
|文件|变更|
|
||
|---|---|
|
||
|`src/authorization/authorization.service.ts`|新增 `canPermission` / `assertPermission` 方法|
|
||
|`src/authorization/authorization.service.spec.ts`|新增 8 个 exact-code 权限检查测试|
|
||
|`src/students/students.service.ts`|新增 `agentSearchStudents` / `agentGetStudentBasic` + `applyStudentScope`|
|
||
|`src/app.module.ts`|导入 `AgentToolsModule`|
|
||
|`docs/superpowers/plans/casl-migration.md`|本文档新增 Agent Tool 章节|
|
||
|
||
### 测试结果
|
||
|
||
```bash
|
||
npx jest --no-coverage --forceExit
|
||
# 结果: 31 suites, 223 passed, 3 skipped
|
||
|
||
npx tsc -p tsconfig.build.json --noEmit
|
||
# 结果: clean
|
||
|
||
npx nest build
|
||
# 结果: clean
|
||
|
||
npx eslint --no-fix src/agent-tools/**/*.ts src/students/student-access-scope.ts src/authorization/authorization.service.ts
|
||
# 结果: clean
|
||
```
|
||
|
||
### 剩余风险
|
||
|
||
1. **classIds 聚合为第二查询**：对大量结果，批量聚合 classIds 的第二条查询使用 `IN (:...ids)`，在 MySQL 中 IN 子句过大时有性能上限（当前 limit 50 安全）。
|
||
2. **`manageAll` 判定**：当前 `manageAll` = `isSuperAdmin`。若未来有非超管的全量学生范围角色，需扩展 `StudentAccessScope` 的 `manageAll` 判定逻辑。
|
||
3. **Tool 扩展**：当前仅 `student:view` 的两个 Tool。新增 Tool 只需实现 `ToolDef` 并注册到 `AgentToolsModule`，无需修改框架代码。
|