baa-conductor

T-012-auth-model.md

 1---
 2task_id: T-012
 3title: 鉴权与 Token 模型
 4status: done
 5branch: feat/T-012-auth-model
 6repo: /Users/george/code/baa-conductor
 7base_ref: main
 8depends_on:
 9  - T-001
10write_scope:
11  - packages/auth/**
12  - docs/auth/**
13updated_at: 2026-03-21T19:41:56+0800
14---
15
16# T-012 鉴权与 Token 模型
17
18## 目标
19
20把设计中的角色、token、权限边界落实成清晰的鉴权模型和代码挂载点。
21
22## 本任务包含
23
24- 角色定义
25- token 形式说明
26- middleware 或校验器骨架
27- `controller`、`worker`、`browser_admin`、`ops_admin`、`readonly` 的权限矩阵
28
29## 本任务不包含
30
31- 完整生产级 secrets 管理
32- 外部身份供应商接入
33
34## 建议起始文件
35
36- `packages/auth/src/index.ts`
37- `docs/auth/README.md`
38- `DESIGN.md` 第 11.3、11.4、28 节
39
40## 交付物
41
42- 鉴权设计文档
43- 代码侧鉴权挂载点
44
45## 验收
46
47- 角色边界清晰
48- 写接口与读接口权限可区分
49- 浏览器控制与 controller 调度权限可区分
50
51## files_changed
52
53- `coordination/tasks/T-012-auth-model.md`
54- `docs/auth/README.md`
55- `packages/auth/package.json`
56- `packages/auth/src/index.ts`
57- `packages/auth/src/actions.ts`
58- `packages/auth/src/model.ts`
59- `packages/auth/src/policy.ts`
60- `packages/auth/src/control-api.ts`
61
62## commands_run
63
64- `git switch -c feat/T-012-auth-model main`
65- `pnpm --filter @baa-conductor/auth typecheck` (`pnpm` 不在当前环境 PATH 中，未执行成功)
66- `./node_modules/.bin/tsc --noEmit -p /Users/george/code/baa-conductor/packages/auth/tsconfig.json`
67
68## result
69
70- 明确了 `controller`、`worker`、`browser_admin`、`ops_admin`、`readonly` 的角色边界与允许动作
71- 定义了 `service_hmac`、`service_signed`、`browser_session`、`ops_session` 四类 token 模型与 principal 形状
72- 在 `packages/auth` 下建立了 action、token/principal、授权策略、Control API route 授权映射四层骨架
73- 在 `docs/auth/README.md` 中整理了权限矩阵、资源归属规则和 `T-003` 接入方式
74
75## risks
76
77- 还没有真实 token 签发、签名校验与密钥轮换实现
78- 资源归属目前只约束到 `controllerId` / `workerId`，后续可能需要细化到 `run_id` / `step_id`
79- `control-api-worker` 还未接入本包，`T-003` 仍需补 verifier 注入和 DB 归属校验
80
81## next_handoff
82
83- `T-003` 先把 `@baa-conductor/auth` 作为 workspace 依赖接入，并复用 `CONTROL_API_AUTH_RULES` 与 `authorizeControlApiRoute(...)`
84- step 写接口在鉴权通过后继续结合数据库中的 `assigned_worker_id` 做最终归属校验
85- controller 写接口在鉴权通过后继续结合 leader term、owner 字段做冲突与幂等检查
86
87## notes
88
89- `2026-03-21`: 创建任务卡