统一登录与静默续期接入指南
更新时间：2026-10-24。本文是新建子应用的认证接入基准。目录内较早的示例正在逐步更新；如有冲突，以本文和当前 API 行为为准。
子应用只处理 JWT
子应用不实现邮箱、密码、验证码、Google/GitHub OAuth 或 refresh token。把用户送到：
https://accounts.aryuki.com/login?app_id=<APP_ID>&redirect=<URL_ENCODED_CALLBACK>
根路径 / 带同样的 app_id/redirect 参数也会转到登录流程；旧参数 client_id 仍可用。默认回调必须与该 app 配置的 HTTPS .com callback_url 完全一致；管理员开启 允许 .cn 回调 后，也可使用对应 aryuki.cn 主机、完全相同的路径。开关可在注册或详情页随时调整，/dash 列表显示状态。关闭后，从 .cn 发起的请求会回退至原 .com 回调，不会因此报错。Auth Center 校验应用启用状态及用户权限后，在回调查询参数中附加 token；不要把含 JWT 的 URL 记录到日志。
子应用应根据经验证的公开请求来源选择登录入口和回调：.com 请求使用 accounts.aryuki.com 与原回调，.cn 请求使用 accounts.aryuki.cn 与对应 .cn 回调。通过 ESA 代理时，Worker 必须先校验 HMAC 来源证明（v1、公开主机、方法、路径加查询、五分钟内时间戳）；不可仅信任 Host、Origin 或 X-Forwarded-Host。Auth Center 会再次校验 app ID、回调主机及路径和开关。若客户端限制可打开的服务域名，开关关闭后的 .com 回退可能无法打开；发布前请核对允许的域名列表。
通行密钥受浏览器 WebAuthn 域名限制：在 .com 注册的凭据不能直接用于 .cn；如需在 .cn 登录，请在 .cn 页面另外注册凭据。
子应用接收 token 后调用 GET https://accounts.aryuki.com/api/verify?app_id=<APP_ID>，请求头 Authorization: Bearer <token>。成功响应沿用 { "valid": true, "user": ... }。后端每次敏感请求应核对本地 JWT 有效期，并按需要调用该验证接口确认账号、应用权限和会话未被撤销。不要仅因为本地 Cookie 尚在就接受过期 JWT。
JWT 含 sub/uuid、role、email、email_verified、avatar_url、auth_provider 和 session_id。用户资产和记录必须以 sub/uuid 关联，不能以邮箱、用户名或 OAuth provider ID 关联。新应用只用 role 判定 admin/user。旧应用若仍以用户名 admin 判断管理员，应在维护时改为 role。
到期后的路径
Access JWT 最长 1 小时；Auth Center 的 HttpOnly refresh Cookie 按用户的 cookie_expiry_days 与全局上限取较短值，管理员使用管理员有效期。刷新不会延长原会话的绝对到期时间。子应用的 Cookie 与 Auth Center Cookie 分属不同站点，Auth Center 无法直接更新子应用保存的 JWT。
当子应用 JWT 到期或 /api/verify 返回未授权时，清理自己的本地会话，并按原登录协议将浏览器重定向到上方 /login?...。只要 Auth Center refresh Cookie 和 D1 会话仍有效，它会无提示签发新 JWT、检查最新 app 权限并回跳；失效时正常展示登录页。已经按此路径处理过期 token 的旧应用不需要修改登录代码。若旧应用只显示错误、不重定向，或自行设了更短的本地 Cookie，需要在该应用中补上回跳处理；单改 Auth Center 不能替它延长本地 Cookie。
退出登录或强制退出设备会撤销 D1 会话；新 JWT 在 /api/verify 立即失效。用户中心的设备记录会显示该会话访问过的 app ID。不要在子应用中直接调用 Auth Center 的 /api/auth/session/continue；它是仅供同域页面使用的 Cookie 续期接口。
OAuth 与绑定
登录页始终展示 Google 和 GitHub 渠道。已绑定身份直接登录；新身份进入 Auth Center 的外部注册流程。已有账户应从用户详情的 Bind other account 弹窗选择渠道，管理员可从用户详情为目标用户发起绑定。不要构造、保存或转发旧的 /:uuid/ssoconnect、/sso-binding 或复制绑定链接。
2026-09-30 更新：登录页会在输入邮箱/用户名后展开密码操作；这只改变 Auth Center 的界面，不改变子应用的 redirect_uri 回调、JWT 校验或静默续期接入方式。账号解绑仅移除 Google/GitHub 身份关联，不移除 Auth Center 邮箱；子应用始终以 UUID 关联数据，不能以渠道 ID 或邮箱关联。
2026-09-30 部署时清除了旧 GitHub/Google 绑定（包括旧 github_id 对应关系）。受影响用户需要重新绑定；账号 UUID、权限和已有资产不会因此改变。旧的 OAuth 迁移文件含 GitHub 绑定回填 SQL，生产环境不可在清理后重新执行。
Google 回调 URI 为 https://accounts.aryuki.com/api/google/callback。OAuth 客户端密钥只存在 Auth Center 的 Worker secret 中；子应用不配置这些密钥。Google/GitHub 注册仍服从 External registration 开关，已绑定账号登录不受该开关影响。