mirror of
https://github.com/Elysola/WebHooker.git
synced 2026-11-20 17:13:49 +00:00
Synchronize both language guides, API references and examples with the implemented authorization, storage and delivery behavior. Document migration requirements and accepted operational limits.
102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
# OAuth
|
|
|
|
WebHooker implements GitHub OAuth2 to enable user-initiated actions (comment, merge, react).
|
|
|
|
## Flow
|
|
|
|
```text
|
|
User → GET /auth/github → Redirect to GitHub → Authorize →
|
|
→ GET /auth/github/callback → Exchange code for token → Store in KV
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
### Start OAuth
|
|
|
|
```
|
|
GET /auth/github
|
|
```
|
|
|
|
Redirects the user to GitHub's authorization page.
|
|
|
|
**Query Parameters:**
|
|
|
|
| Parameter | Description |
|
|
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `redirect` | Optional relative path to return to after sign-in (e.g. `/admin`). Must start with `/` but not `//`; any unsafe value falls back to `/`. |
|
|
|
|
**Response:** `302` redirect to GitHub OAuth authorize URL.
|
|
|
|
### OAuth Callback
|
|
|
|
```
|
|
GET /auth/github/callback
|
|
```
|
|
|
|
GitHub redirects here after authorization. Exchanges the code for an access token and stores it in KV.
|
|
|
|
**Query Parameters (from GitHub):**
|
|
|
|
| Parameter | Description |
|
|
| --------- | ----------------------------------- |
|
|
| `code` | Authorization code |
|
|
| `state` | State parameter for CSRF protection |
|
|
|
|
A sign-in started in the browser (`GET /auth/github`) must come back with the `wh_oauth_state` cookie that start set; otherwise the callback answers `400 Invalid or expired state`.
|
|
|
|
**Response:**
|
|
|
|
- **Browser flow** (`Accept: text/html`): sets an admin session cookie, then redirects to the `redirect` target. Users without admin access are redirected to `/admin?error=forbidden`.
|
|
- **JSON flow**: returns `{ "userId": "...", "login": "...", "redirectTo": "..." }`.
|
|
- **Bot account link** (started by `/gh login` on Discord, Telegram or Feishu): nothing is linked yet. The callback answers with an HTML confirmation page that names both the GitHub account and the chat account; the link is written only when the GitHub user confirms it there.
|
|
|
|
### Confirm Bot Account Link
|
|
|
|
```
|
|
POST /auth/github/link
|
|
```
|
|
|
|
Submitted by the confirmation page (form field `nonce`, valid for 10 minutes and usable once). Links the chat account to the GitHub account and answers with an HTML result page; an unknown, expired or already used `nonce` gets `400` ("link expired").
|
|
|
|
### Revoke Token
|
|
|
|
```
|
|
DELETE /auth/token/:userId
|
|
```
|
|
|
|
Removes the stored OAuth token for a user (your own, or any user's for a super admin). The revocation is recorded in D1, so the token stops working everywhere at once, even where KV has not caught up yet.
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"ok": true
|
|
}
|
|
```
|
|
|
|
## Token Storage
|
|
|
|
Tokens are stored in KV with key pattern `token:{userId}`:
|
|
|
|
```json
|
|
{
|
|
"userId": "12345",
|
|
"accessToken": "gho_...",
|
|
"expiresAt": 1735689600000,
|
|
"live": true
|
|
}
|
|
```
|
|
|
|
`expiresAt` is a Unix timestamp in milliseconds. A stored token is used for 10 hours; the KV entry expires after 9 hours (90%). Tokens are not refreshed — after that, sign in (or run `/gh login`) again. `live` marks a token whose "current token" record is kept in D1: signing in again or signing out invalidates the previous token everywhere at once. A reverse index `token-reverse:{sha256 of token}` maps the access token back to its user id so Bearer-authenticated endpoints can resolve the caller. Discord users linked to a GitHub account are stored in the D1 `discord_links` table; Telegram users in the D1 `telegram_links` table.
|
|
|
|
## Using Tokens
|
|
|
|
After OAuth, include the access token in the `Authorization` header for action API calls:
|
|
|
|
```bash
|
|
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": "Hello!"}'
|
|
```
|