角色与能力语义（权威定义）

返回 README

---

本文是全站五角色及其能力语义的唯一权威来源（Tier A）。 角色由 OAuth IdP 统一定义、统一通过 JWT 下发；下游 kungal（论坛）、moyu（补丁站）、wiki 等所有 RP 必须遵守本文的语义,不得自行发明与此冲突的解释。 任何站点的鉴权(后端为准)在把 roles claim 映射成内部权限时,都必须满足本文 §3 的能力序与 §4 的强制规则。

---

1. 五个角色

角色集是固定的 5 个,种子定义在 IdP 代码 cmd/migrate。除此之外的任何字符串(含历史别名 super_admin)不是有效角色,下游不得依赖。

站点域角色(加法扩展):除本文的全局五角色外,还有一层只在单个站点生效的 站点域角色(site_roles claim,如「letmoe 的 moderator」)。它是本契约的加法扩展,不改动这里 的任何语义;全局 roles claim 与授予矩阵一切照旧。详见 12-site-roles.md。

---

2. 角色如何下发（claim 格式 —— 权威)

• access_token 的 roles claim 是一个角色名字符串数组(见 04 JWT Claims)。
• roles 是一个无序集合,不是有序列表,也不是数值等级。 下游不得假设元素顺序,不得假设某个角色一定在/不在数组里(除非按集合成员判断)。
• 普通用户的 roles 为空数组 []。 字符串 "user" 不会出现在 claim 里——它是隐式默认。下游不得用"数组里有没有 user"来判断是否登录(用是否持有有效 token 判断登录;用"数组是否含某个提权角色"判断提权)。
• 角色是可叠加的:一个账号可同时持有多个角色(例如所有 ren 账号都同时持有 admin,见 §3.2 不变量)。
• 角色变更在下一次 token 刷新后生效。下游必须每次从最新 claim / userinfo 重新解析角色,不得把角色长期缓存到失去时效(提权/降权要能在会话中途生效)。

---

3. 能力语义与层级（权威）

3.1 两条独立的轴

能力分两条互相正交的轴,下游必须分别理解:

1. 管理/审核轴(有序,逐级包含):

   普通用户  <  moderator  <  admin  <  ren

   高一级必须被视为拥有低一级在本站的全部能力。即:
   • 任何持有 admin 的账号,必须被授予 moderator 的全部能力;
   • 任何持有 ren 的账号,必须被授予 admin(以及因此 moderator)的全部能力。
2. 发布轴(正交): creator 是"可信发布者"标记,只赋予 galgame 直接发布能力(跳过审核 + 跳过提交配额),不赋予任何审核或管理能力。它独立于管理轴——一个 creator 不是 moderator,一个 moderator 不自动是 creator。

注意:管理轴的"逐级包含"是契约层的强制语义(§4 规则 2),下游必须在自己的鉴权里实现它,不能因为内部用数值等级或角色名白名单就把某个高角色漏掉。

3.2 运行不变量:ren 必与 admin 同授

IdP 保证(并由运维约定):任何 ren 账号都同时持有 admin。但下游不得把这条当作可省略 ren 处理的借口——按 §4 规则 2,下游仍必须把 ren 当作 ≥ admin 来对待,使系统在该不变量被打破时依然正确。

3.3 能力语义速查

galgame/wiki 相关能力的具体接口与门禁以 galgame_wiki 契约 为准(该契约也属 Tier A);本文只定义角色与能力的语义映射。各下游站点自身内容(帖子/补丁/评分等)的具体接口在各自仓库,但其角色判定必须符合本文 §3、§4。

---

4. 下游必须遵守的规则（MUST）

1. 以集合语义解析 roles。 按"是否包含某角色名"判断,不依赖顺序;不靠 "user" 是否在数组里判断登录(§2)。
2. 实现管理轴的逐级包含。 任何把 roles 映射到内部权限的逻辑,必须让 ren ⊇ admin ⊇ moderator:
   • 不得把 ren 当作普通用户或忽略;
   • 不得把 admin 排除在 moderator 能做的事之外。
   • 若内部用数值等级,必须:ren、admin → 最高管理级;moderator → 审核级;映射表必须覆盖所有提权角色,不得静默丢弃。
3. creator 仅作发布能力,不授予审核/管理权。 不得用 creator 放行任何审核或后台操作。
4. 后端为唯一鉴权点;前端门禁仅 UX。 前端可隐藏 UI,但不得作为唯一防线;真正的权限判断必须在后端按 claim 做。前端"更严于后端"(例如把某操作藏在 admin 之后而后端只要 moderator)允许,但属 UX 不一致,应尽量对齐。
5. 不得在下游实现角色授予/撤销。 角色变更只在 OAuth 后台进行(矩阵见 §5);下游只读 claim。creator 申请走 08 的中央队列,授予仍归 OAuth。
6. 角色时效。 每次刷新重新解析角色,使提权/降权能在会话中途生效(§2)。

---

5. 角色授予矩阵（仅 OAuth 后台）

• ren 永不可经 API 授予/撤销(只能直接配置 DB)。
• 不能修改自己的角色。
• 成为 creator 另有自助申请通道(任意登录用户申请 → admin 审核 → 授予),见 08-creator-applications.md。

---

6. 下游合规状态（已整改 · 存档）

本节最初记录的是本文落地时下游对 ren 处理的合规差距;两站均已整改完毕,以下为存档与现状锚点:

• kungal（论坛):✅ 已整改(commit 58d3f68c "unify roles to OAuth's named-role model; drop numeric tier")。数值等级已废弃;apps/api/pkg/role/role.go 以角色名集合 + 能力函数(CanModerate = moderator∪admin∪ren、CanAdminister = admin∪ren、IsCreator)实现 §3 语义,super_admin 已按本文 §1 移除。
• moyu（补丁站):✅ 已整改(commit 58b9710e "align role labels site-wide with the OAuth 5-role contract")。apps/api/internal/middleware/auth.go 的 SuperAdminRoles = {admin, ren} / ModeratorRoles = {admin, ren, moderator} 完整识别 ren 为最高管理级;前端标签已对齐契约命名。
• 两站对 creator 的"不授予审核权"处理始终符合本契约(§3.1)。
• 历史别名 super_admin:IdP 从不签发;两下游均已不依赖该字符串。

整改后,只持 ren(无 admin)的账号在各站均获得完整管理权,系统不再依赖 §3.2 的"ren 必同时持 admin"运维约定,该不变量退回为纵深防御。新接入的 RP 直接按 §3、§4 实现即可,不需要参考任何历史数值等级。

---

7. 关联文档

• 04-tokens-and-errors.md —— roles claim 的 JWT 位置。
• 08-creator-applications.md —— creator 申请/审批流程。
• galgame_wiki 契约 —— galgame 编辑/审核/发布的具体接口与角色门禁。