Synchronize both language guides, API references and examples with the implemented authorization, storage and delivery behavior. Document migration requirements and accepted operational limits.
3.6 KiB
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": "你好!"}'