0023 OAuth 2.0 提供方、个人访问令牌与 Blessing Skin 兼容资源 API
- 状态:已接受(2026-10-30)
- 相关:设计文档 02 §1.2(F18)、§1.5(F60、F61)、§2.6、§3;03(S02、C09、C13、C15、§7.4–7.5);04 §3(D4)、§4;ADR 0022
背景
M3 第二部分。Blessing Skin 用 Laravel Passport 做 OAuth 2.0 提供方:用户在 /user/oauth/manage 自建应用,第三方网站(论坛、服务器面板)用授权码流程拿到令牌,调用 /api/user、/api/players、/api/closet 等资源接口。问题:
- 应用密钥明文存储并一直显示在页面上;访问令牌默认一年有效。
- 衣柜写权限的 scope 注册成了拼错的
Closet.ReadWrtie,路由却要求Closet.ReadWrite,第三方永远拿不到衣柜写权限(C13)。 - 改密码、找回密码不吊销 OAuth 令牌(S02);删除用户不删令牌(C09)。
- 读一条不存在的通知直接 500(C15);衣柜分页的
perPage没有上限。 - 没有个人访问令牌:脚本只能自己实现一遍授权流程。
决策
- 自己实现授权服务器(
internal/oauth),不用设计文档 04 选的 zitadel/oidc:- 需要的只是授权码 + PKCE、刷新令牌、吊销和元数据,几百行,状态全在我们自己的表里,与会话一起在事务里吊销。
- zitadel/oidc 以 OIDC 为中心,要实现一整套 Storage 接口,还会带进 go-jose、securecookie、otel 等依赖。
- 以后做 Yggdrasil Connect(F58,OIDC)时再评估:在这套表上加 ID Token,或者那时再引入库。
- 数据(迁移
20261029155749_oauth):oauth_clients:数字 id 就是client_id(与 Passport 一致,迁移时保留),名称、回调地址列表、密钥哈希(公开客户端为空)。oauth_grants:用户允许过某个应用的 scope;再次请求不超出这些 scope 时直接通过,不再询问(同 Passport)。oauth_codes:授权码(哈希、10 分钟、一次性)与 PKCE 质询。oauth_tokens:应用的访问令牌和刷新令牌,以及个人访问令牌(kind区分),只存 SHA-256。- 令牌带前缀:
slo_(访问)、slr_(刷新)、slp_(个人访问令牌),一眼能分辨,也方便密钥扫描工具识别泄露。
- 授权流程:
GET /oauth/authorize302 到前端页面/user/oauth/authorize(同样的查询参数),未登录先去登录再回来。页面调GET /api/v1/oauth/authorize检查请求,用户点"授权"或"拒绝"时调POST /api/v1/oauth/authorize,拿到要跳转的地址。client_id不存在、回调地址没有登记(必须完全一致;只登记了一个时可以省略)时,错误显示在页面上,不跳转,免得伪造的请求把用户带到任意地址。其它错误(response_type不是code、未知 scope、PKCE 参数不对)按 RFC 6749 跳回应用,带上error和state。- 公开客户端(没有密钥:浏览器、桌面、手机应用)必须用 PKCE;服务端应用可选(Passport 兼容)。支持
S256和plain。 - 普通用户的授权里会去掉管理类 scope;全部被去掉时返回
invalid_scope。 - 应用主人被封禁或注销后,应用不再能用,它已经签发给其他用户的令牌也立即失效(M3 收尾时补上)。
- 授权写审计
oauth.authorize。
- 令牌端点
POST /oauth/token:- 接受表单(RFC 6749)或 JSON(Laravel 也接受);客户端凭据放 HTTP Basic 或表单都行。
- 支持
authorization_code和refresh_token。不支持password和client_credentials:BS 的资源接口都需要具体的用户,这两种拿到的令牌在 BS 上本来也用不了。 - 授权码只能用一次:在事务里删除授权码,删到的那个请求才拿到令牌,同时兑换只有一个成功。授权码没通过检查(客户端不对、回调地址不对、PKCE 校验失败)也会作废,防止被偷的授权码被反复尝试。
- 刷新令牌每次使用都换新的,旧的一对立即失效;刷新时可以缩小 scope,不能扩大。
- 错误是 RFC 6749 §5.2 的格式,另加 Laravel 的
message字段(Passport 客户端读这个)。 - 访问令牌默认 1 天(
oauth.access_token_ttl_seconds),刷新令牌 30 天未用即失效(oauth.refresh_token_ttl_seconds)。BS 默认一年;需要的站点可以把访问令牌调到最长一年。
- 其它端点:
POST /oauth/revoke(RFC 7009)、GET /.well-known/oauth-authorization-server(RFC 8414 元数据)。/oauth/token、/oauth/revoke和资源 API 允许任意来源的 CORS:它们不读 Cookie,浏览器应用(PKCE)可以直接调用。跨域预检只回应这些路径:/api/v1的 CSRF 防护靠的是别的网站永远得不到预检许可(M3 收尾时修正:原来/api/*的通配预检也会回应/api/v1)。 - Scope 沿用 BS 的名字。
X.ReadWrite包含X.Read;Closet.ReadWrtie当作Closet.ReadWrite(修 C13)。管理类 scope(*Management.*、Notification.ReadWrite)只有管理员能授予,使用时还要求令牌主人仍是管理员。没有请求 scope 时默认User.Read(同 BS)。 - 个人访问令牌:用户在"应用与令牌"页面创建,选 scope 和有效期(7、30、90、365 天或永不过期),令牌只显示一次;列表显示最近使用时间(最多每分钟写一次)。每人最多 50 个,每人最多 25 个应用。创建写审计
token.create。 - 吊销:改密码、找回密码、封禁、注销、"退出其它所有设备"时,应用的令牌、未兑换的授权码和个人访问令牌与网页会话、启动器令牌一起失效(S02)。授权记录保留,用户下次使用应用时不必重新确认。用户在"已授权的应用"里撤销某个应用,就删除授权记录、令牌和授权码。删除应用会删掉与它有关的一切。
- 兼容 BS 的资源 API(
internal/httpapi/bsapi.go,L-B):- 本部分:
/api(根)、GET /api/user、GET /api/user/notifications、POST /api/user/notifications/{id}、GET|POST /api/players、DELETE /api/players/{pid}、PUT /api/players/{pid}/name、PUT|DELETE /api/players/{pid}/textures、GET|POST /api/closet、PUT|DELETE /api/closet/{tid}。管理类/api/admin/*放到 M3 第三部分。 - 响应保持 BS 的形状:模型对象用 snake_case 字段(
uid、pid、tid_skin、last_modified……);操作结果是{"code", "message", "data"},失败时 code 不为 0 但 HTTP 仍是 200(BS 的客户端靠 code 判断);输入错误是 Laravel 的 422{"message", "errors"};401、403、404、429 是{"message"}。通知正文是渲染好的 HTML。 - 修正:读不存在或别人的通知 404(BS 500,C15);衣柜每页最多 100 条;改别人的角色 403、不存在 404。
- 根
/api的blessing_skin字段写6.0.2,表示与这个版本的 API 兼容,另有skinloom字段是真实版本。 - 限流同 BS:每个用户每分钟 60 次。
- 这组接口直接挂在 chi 上,不进 OpenAPI,理由同 Yggdrasil(ADR 0022)。
- 本部分:
- 前端:
/user/oauth/authorize(授权确认页)、/user/oauth/manage(BS 的同名页面,现在包含"我的应用""已授权的应用""个人访问令牌"三部分),用户中心增加入口。
备选方案
- zitadel/oidc 或 ory/fosite:见上,暂不需要 OIDC,依赖与适配成本都偏高。
- 授权码失败不作废:RFC 只要求成功使用后作废;作废失败的授权码让偷到授权码的人只能试一次。
- 资源 API 失败时返回 4xx:更规范,但 BS 的客户端会把 4xx 当异常,读不到
code和message。 - 个人访问令牌也用于
/api/v1:需要给每个操作定义 scope,等 API 稳定后再做;脚本目前用兼容接口和skinloom admin token。
影响
- 迁移
20261029155749_oauth:oauth_clients、oauth_grants、oauth_codes、oauth_tokens四张新表(只建表)。 - 新设置
oauth.access_token_ttl_seconds、oauth.refresh_token_ttl_seconds。 - 新包
internal/oauth;texture.ClosetPage;account吊销会话时一并吊销 OAuth 与个人访问令牌(revokeTokens)。 csrfGuard只检查/api/v1/:其它/api/*(Yggdrasil、兼容资源 API)和/oauth/*只认令牌。- 从 BS 迁移(M5 迁移工具):应用的
client_id、名称、回调地址原样导入,明文密钥导入时哈希;已签发的令牌不迁移,用户重新授权。