鲲 Galgame OAuth 文档

基础路径：/api/v1

重要约定：身份操作必须在 OAuth 完成

下游 kungal / moyu / wiki 不要在自己前端实现下列操作：

• 新用户注册（跳转到 oauth.kungal.com/auth/register?redirect=<oauth-authorize-url>，注册成功后自动 SSO 回跳）—— 详见 05-registration.md
• 改邮箱（POST /auth/email/send-code + PUT /auth/email）
• 改密码（PUT /auth/password）
• 重设密码 / 启用 2FA / 管理登录设备 / 注销账号 / 撤销已授权 OAuth Client（未来）

跳转目标：注册去 /auth/register?redirect=...，账号管理去 https://oauth.kungal.com/profile。

技术上这些端点都能通过 end-user JWT 代理，但身份层操作必须集中在一个前端：安全审计单点、未来加 2FA / 异地通知时只改一处、避免邮箱劫持攻击面跨多个站点放大。

展示层操作（name / avatar / bio）可以站内提供 UI 或跳转，任选。

详细分类表 + 跳转按钮代码示例见 02-user-profile.md §身份操作 vs 展示操作。

---

文档索引

API 参考（按主题）

完整接入指南

---

响应格式

{
  "code": 0,        // 0 = 成功，非零 = 错误码
  "message": "成功",
  "data": { ... }   // 成功时有数据；失败时一般为 null 或缺省
}

认证失败返回 HTTP 401 / 403：/auth/me / /auth/* 等受保护端点（protected 组，挂 middleware.Auth，见 cmd/oauth/main.go）在 token 缺失 / 失效 / 过期时返回 HTTP 401 + { code: 10001 | 10002 | 10003, message }；权限不足返回 HTTP 403。下游客户端应同时检查 HTTP status 与 code。完整列表见 04-tokens-and-errors.md §认证错误。

认证

OAuth 一共有三种鉴权方式，按场景区分：

终端用户 JWT 通过完整的 OAuth Authorization Code + PKCE 流程拿到（详见 oauth-integration-guide.md）。Client Basic Auth 的 client_id / client_secret 在 OAuth 后台创建 Client 时生成。

---

变更摘要

2026-06-27 角色语义定权威（重要）：新增 11-roles.md——把全站五角色 user/creator/moderator/admin/ren 及其能力语义定为 Tier A 权威，下游必须遵守。要点：① roles claim 是角色名集合，普通用户为空数组（user 隐式，下游不得用「数组含 user」判断登录）；② 管理轴逐级包含 moderator ⊂ admin ⊂ ren，任何把 claim 映射成内部权限的逻辑必须让 ren ⊇ admin ⊇ moderator；③ creator 是正交的「直接发布 galgame」能力，不含审核/管理权。下游 kungal / moyu 必须整改对 ren 的处理：kungal 数值等级把 ren 塌成普通用户、moyu 完全不识别 ren——目前仅因「ren 账号必同时持 admin」未出事，违反健壮性要求，须修复（见 11 §6）。

2026-06-14 登出修复（RP-Initiated Logout）：新增 07-logout.md。修复「在 wiki / 补丁站登出后，再点登录/注册会静默登回刚才的账号」——根因是 RP 登出没清掉 OP（oauth.kungal.com）的会话（OP 的 localStorage 跨 origin 清不掉 + 跨站 cookie 带不过去）。方案：RP 登出时顶层跳转到 OP 登出入口 GET https://oauth.kungal.com/auth/logout?client_id=&redirect=，由 OP 清会话再回跳。新增后端 GET /oauth/post-logout-redirect 白名单校验 + GET /oauth/authorize 的 prompt=login 参数。下游 kungal / moyu 必须改登出实现（见 07）。

2026-05-23 注册流程统一（L1，重要）：新增 05-registration.md 文档；引入邮箱验证码两步注册——POST /auth/register/send-code 寄码 + POST /auth/register 带 code 创建账号并发 token（注册即登录，返回 access_token + 写 refresh cookie）；新增 GET /oauth/client-info 公开元数据端点；oauth_clients 加 auto_consent 列，5 个第一方 client 默认开启——同意页对第一方静默跳过，用户感知是"注册完一闪回到原站点已登录"。下游 kungal / moyu 的 legacy 注册端点全部删除，"注册"按钮改为复用登录的 PKCE 跳转模式（目标 URL 换成 /auth/register?redirect=<authorize_url>）。

2026-05-23 政策：明确"身份层 vs 展示层"分类。下游禁止在自己前端做改邮箱 / 改密码 / 注销账号等身份操作，必须跳转 OAuth profile。详见上方"重要约定"小节和 02-user-profile.md。

2026-05-23：新增 POST /auth/me/avatar 端点。一次性的"上传头像图片 → 写库" multipart 端点，避免下游 kungal / moyu 自己维护 image_service client。配额从 OAuth 一侧扣；老的两步法（PATCH /auth/me { avatar_image_hash }）继续保留。

2026-05-23：正式收录 POST /auth/email/send-code / PUT /auth/email / PUT /auth/password 端点文档（以前只有口头提及）。同时把对应的错误码 10004 / 10006 / 10010-10013 补全到 04-tokens-and-errors.md。

文档拆分（2026-05-23）：原 api-reference.md 拆为 4 个主题文件（01-04）。所有内容保留，按"OAuth 协议 / 用户自助 / 跨服务 / Token 与错误"四块组织。完整 OAuth 接入指南仍是单独的 oauth-integration-guide.md。