02 三级权限作用域

02 三级权限作用域

本节摘要:第 01 节的四档管「能不能进」,这一节管「进来能干啥」。OpenWork 的令牌带三级权限作用域(scope):所有者(owner)、协作者(collaborator)、查看者(viewer)。本节讲清这三级如何分级、各自的权力范围、为什么需要「协作者」这个中间态。

一、令牌的 scope:权力范围

一个令牌除了标识「你是谁」,还带一个 scope(作用域),表示「你能干什么」。OpenWork 的令牌有三级 scope:

令牌 = { id, scope: owner|collaborator|viewer, ... }
​

scope 在令牌签发时确定,之后每次请求带这个令牌,服务端按 scope 决定允许什么操作。

二、owner:全部权限

owner 是最高 scope,拥有全部权限:

• 读写工作区、会话、能力
• 管理操作(签发/撤销令牌、改配置、删工作区)
• 所有 Agent 操作

owner 通常是工作区的「主人」——他创建了工作区,自然有全部权限。

三、collaborator:读写但不能管理

collaborator 是中间 scope:

• 读写工作区、会话、能力(和 owner 一样能干活)
• 但不能管理(不能签发令牌、改配置、删工作区)

为什么需要这个中间态?考虑团队协作场景:

• 你想让队友能一起改代码、用 Agent(需要读写)。
• 但不想让队友能改工作区配置、签发令牌(管理操作太敏感)。
• 如果只有 owner/viewer 二选,你要么给 owner(权限太大),要么给 viewer(只能看不能改)——都不合适。

collaborator 正好——「能干活但不能管」。这是团队协作的合理权限。

四、viewer:强制只读

viewer 是最低 scope,强制只读:

• 只能读(GET/HEAD)
• 任何写操作都被拒绝(下一节详讲如何强制)

viewer 适合「给别人看但不让改」的场景:

• 给 reviewer 看你的工作进展
• 给客户 demo
• 公开分享一个可读的工作区

五、scope 的分级逻辑

把三级放一起,分级逻辑很清晰:

权限范围:owner > collaborator > viewer
   │
   ├─ owner: 读写 + 管理
   ├─ collaborator: 读写(无管理)
   └─ viewer: 只读(强制)
​

这种分级覆盖了常见的协作角色:主人(owner)、队友(collaborator)、观众(viewer)。

六、令牌的签发

scope 在令牌签发时确定。令牌的形态大致是:

令牌字符串: owt_<随机ID>(明文,只返回一次)
落盘存储: { id, hash(哈希后的), scope, createdAt, label? }
​

注意几点:

• 明文只返回一次:签发时返回明文令牌给用户,之后只存哈希(安全,防泄露)。
• scope 固定:签发时定 scope,之后不变(要变就重新签发)。
• 可带 label:给令牌起个名(如「队友小张的令牌」),方便管理。

七、scope 与鉴权模式的协作

scope(本节)和鉴权模式(第 01 节)协作决定「能不能做某操作」:

请求带令牌(某 scope)
   │
   ▼ 1. 鉴权模式检查(第 01 节):这个路由要哪种 auth?
   │    ├─ 不符 ──► 401/403
   │
   ▼ 2. scope 检查(本节):这个操作要哪个 scope?
   │    ├─ 管理操作 ──► 要 owner
   │    ├─ 写操作 ──► owner 或 collaborator(viewer 拒)
   │    └─ 读操作 ──► 任意 scope
   │
   ▼ 都过 ──► 执行
​

鉴权模式管「能不能进这个路由」,scope 管「进来后能不能做这个操作」。两层叠加,精细控制。

八、本节要点回顾

1. 三级 scope:owner / collaborator / viewer,管「进来能干啥」。
2. owner:全部权限,含管理(签发令牌/改配置)。
3. collaborator:读写无管理——团队协作的合理权限(中间态)。
4. viewer:强制只读,适合「看但不改」场景。
5. 分级覆盖协作角色:主人/队友/观众。
6. 令牌签发:明文只返回一次,存哈希;scope 签发时定。
7. 与鉴权模式协作:auth 管进路由,scope 管做操作,两层叠加。

scope 讲清了,下一节讲最硬核的——viewer 的「强制只读」如何在反代层把关。