第三方 OAuth 接入参考
端点总表
所有对外端点、认证方式、缓存约束与用途。
约定：{issuer} 形如 https://id.example.com/v1/oauth，{origin} 是它的源，{consentUi} 是同意页前端地址（从元数据的 authorization_endpoint 读取）。
第三方会用到的端点
| 方法 | 地址 | 认证 | 缓存 | 用途 |
|---|---|---|---|---|
GET | {consentUi}/authorize | 无（依赖用户登录态） | 不缓存 | 授权入口，浏览器跳转目标 |
POST | {issuer}/token | 客户端认证 | no-store | 换令牌 / 刷新 / 客户端凭据 |
POST | {issuer}/revoke | 客户端认证 | no-store | 撤销令牌 |
POST | {issuer}/introspect | 仅机密客户端 | no-store | 查询令牌是否有效 |
GET | {issuer}/jwks | 无 | 5 分钟 | 令牌签名公钥 |
GET | {origin}/v1/auth/userinfo | 用户访问令牌（auth 受众） | 不缓存 | 读取用户信息 |
introspect 不对公开客户端开放：它等于「拿任意一枚令牌问服务器它还有效吗」，开放给公开客户端，任何拿到泄露令牌的一方都能免费确认令牌是否可用。
服务内部端点（第三方不要调用）
| 方法 | 地址 | 说明 |
|---|---|---|
POST | {issuer}/preauthorize | 同意页前置校验：校验客户端与回调地址，返回展示素材与 consent_ticket（有效期 30 分钟） |
POST | {issuer}/authorize | 同意页提交授权决策：同时消费票据与身份断言，返回 JSON 格式的重定向地址（不是 302） |
这两个端点只接受 POST + JSON，是给 MuoCeon 自己的同意页用的。标准客户端按 RFC 6749 发起 GET 会拿到 405——这也是为什么元数据里的 authorization_endpoint 指向同意页而不是这里。
账号自管理端点（第一方）
| 方法 | 地址 | 认证与 scope | 备注 |
|---|---|---|---|
GET | {issuer}/grants | oauth 受众 + oauth:grants:read | 分页列出已授权应用，可按 kind=first_party|third_party 分段 |
DELETE | {issuer}/grants/:clientId | oauth 受众 + oauth:grants:revoke | 带 did 只撤该设备，不带则撤该客户端全部会话；要求近期认证（max_age=300） |
发现端点
| 地址 | 规范 |
|---|---|
{origin}/.well-known/oauth-authorization-server/v1/oauth | RFC 8414 |
{origin}/.well-known/openid-configuration/v1/oauth | RFC 8414 路径形式 |
{issuer}/.well-known/openid-configuration | OIDC Discovery |
{origin}/.well-known/oauth-protected-resource/v1/auth | RFC 9728 |
{origin}/.well-known/oauth-protected-resource/v1/oauth | RFC 9728 |
{origin}/.well-known/oauth-protected-resource/v1/account | RFC 9728 |
通用约束
- 所有端点独立限流；触发时返回
429，带Retry-After头。 - 令牌相关端点（
token/revoke/introspect）的错误遵循 RFC 6749 §5.2，见 错误码。 - 撤销端点对不存在的令牌同样返回
200，避免被当成令牌探测接口。