Files
WebHooker/docs/zh/api/oauth.md
T
翅膀 5fcb129170 docs(worker): align guides with runtime behavior
Synchronize both language guides, API references and examples with
the implemented authorization, storage and delivery behavior.
Document migration requirements and accepted operational limits.
2026-10-23 23:24:05 +08:00

3.6 KiB
Raw Blame History

OAuth

WebHooker 实现 GitHub OAuth2 以支持用户发起的操作(评论、合并、反应)。

流程

用户 → GET /auth/github → 重定向到 GitHub → 授权 →
  → GET /auth/github/callback → 交换 code 获取 Token → 存储到 KV

端点

启动 OAuth

GET /auth/github

将用户重定向到 GitHub 的授权页面。

查询参数:

参数 说明
redirect 可选,登录后返回的相对路径(如 /admin)。必须以 / 开头但不能以 // 开头;任何不安全的值回退为 /。

响应: 302 重定向到 GitHub OAuth 授权 URL。

OAuth 回调

GET /auth/github/callback

GitHub 授权后重定向到此地址。将 code 交换为访问令牌并存储到 KV。

查询参数(来自 GitHub):

参数 说明
code 授权码
state CSRF 保护的状态参数

在浏览器中发起(GET /auth/github)的登录,回调时必须带回发起时设置的 wh_oauth_state Cookie,否则返回 400 Invalid or expired state。

响应:

  • 浏览器流程(Accept: text/html):设置管理员会话 Cookie,然后重定向到 redirect 目标;无管理权限的用户被重定向到 /admin?error=forbidden。
  • JSON 流程:返回 { "userId": "...", "login": "...", "redirectTo": "..." }。
  • 机器人账号绑定(由 Discord、Telegram 或飞书的 /gh login 发起):此时还不会绑定。回调返回一个同时列出 GitHub 账号与聊天账号的 HTML 确认页;只有 GitHub 用户在该页确认后才写入绑定。

确认机器人账号绑定

POST /auth/github/link

由确认页提交(表单字段 nonce,10 分钟内有效、只能使用一次)。把聊天账号绑定到 GitHub 账号并返回 HTML 结果页;未知、过期或已使用的 nonce 返回 400("链接已失效")。

撤销 Token

DELETE /auth/token/:userId

删除用户存储的 OAuth Token(本人的,或超级管理员删除任意用户的)。撤销会记录在 D1 中,即使 KV 尚未同步,Token 也会在所有节点立即失效。

响应:

{
  "ok": true
}

Token 存储

Token 以键模式 token:{userId} 存储在 KV 中:

{
  "userId": "12345",
  "accessToken": "gho_...",
  "expiresAt": 1735689600000,
  "live": true
}

expiresAt 是毫秒级 Unix 时间戳。保存的 Token 可使用 10 小时,KV 条目在 9 小时(90%)后过期。Token 不会自动刷新——过期后需要重新登录(或重新执行 /gh login)。live 表示该 Token 在 D1 中有"当前令牌"记录:重新登录或退出登录会让之前的 Token 在所有节点立即失效。反向索引 token-reverse:{sha256 of token} 将访问令牌映射回用户 id,使 Bearer 鉴权的端点能解析调用者。与 GitHub 账号绑定的 Discord 用户存储在 D1 的 discord_links 表中;Telegram 用户存储在 D1 的 telegram_links 表中。

使用 Token

OAuth 完成后,在操作 API 调用的 Authorization 头中包含访问令牌:

curl -X POST https://your-worker/api/comment \
  -H "Authorization: Bearer gho_..." \
  -H "Content-Type: application/json" \
  -d '{"owner": "org", "repo": "repo", "issueNumber": 1, "body": "你好!"}'