initial commit

docs/api/oauth.md

@@ -0,0 +1,85 @@
+# 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                        |
+| --------- | ---------------------------------- |
+| `userId`  | Your application's user identifier |
+
+**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 |
+
+**Response:** Redirects to your `BASE_URL` with a success/error indicator.
+
+### Revoke Token
+
+```
+DELETE /auth/token/:userId
+```
+
+Removes the stored OAuth token for a user.
+
+**Response:**
+
+```json
+{
+  "ok": true
+}
+```
+
+## Token Storage
+
+Tokens are stored in KV with key pattern `token:{userId}`:
+
+```json
+{
+  "accessToken": "gho_...",
+  "expiresAt": "2025-01-01T00:00:00.000Z"
+}
+```
+
+Tokens are automatically expired based on the `expiresAt` timestamp.
+
+## 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!"}'
+```