Skip to content

feat(worker): bespoke OAuth with device authorization grant (RFC 8628) #203

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
liplus-lin-lay merged 1 commit into from
Apr 20, 2026
Merged

feat(worker): bespoke OAuth with device authorization grant (RFC 8628) #203

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 26 additions & 2 deletions docs/0-requirements.ja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,26 @@ WebhookMcpAgent DO が以下のツールセットを提供する。ローカル
| 3 | フルペイロードが必要なイベントのみ `get_event(event_id)` で取得 |
| 4 | 処理完了後 `mark_processed(event_id)` でマーク |

### F7. OAuth 認証（Device Authorization Grant, RFC 8628）

Worker は OAuth 2.1 Device Authorization Grant を自前実装する（`@cloudflare/workers-oauth-provider` は v0.11.0 で撤去）。GitHub App の device flow を upstream として利用し、localhost callback に依存しない。

| ID | 要件 |
|----|------|
| F7.1 | `GET /.well-known/oauth-authorization-server` で RFC 8414 メタデータを返す |
| F7.2 | `POST /oauth/register` で RFC 7591 dynamic client registration を行う（public client、secret 発行なし） |
| F7.3 | `POST /oauth/device_authorization` で GitHub に device code を要求し、RFC 8628 §3.2 形式の JSON（device_code / user_code / verification_uri / verification_uri_complete / expires_in / interval）を返す |
| F7.4 | `POST /oauth/token` で `grant_type=urn:ietf:params:oauth:grant-type:device_code` を処理し、GitHub への polling 結果に応じて `authorization_pending` / `slow_down` / `access_denied` / `expired_token` を RFC 8628 §3.5 準拠で返す |
| F7.5 | `POST /oauth/token` で `grant_type=refresh_token` を処理し、access token と refresh token を rotate する |
| F7.6 | 旧 `GET /oauth/authorize` および `GET /oauth/callback` は **HTTP 410 Gone** を返す（localhost callback flow は v0.11.0 で廃止） |
| F7.7 | 保護対象 API ルート（`/mcp`, `/events`）は `Authorization: Bearer <access_token>` ヘッダによる独自 token 検証 middleware で認可する |
| F7.8 | KV schema は自前設計: `client:{client_id}` / `device:{device_code}` / `user_code:{user_code}` / `token:{access_token}` / `refresh:{refresh_token}` / `grant:{grant_id}` |

**GitHub App 前提条件:**

- GitHub App の設定で **"Enable Device Flow"** を有効化する必要がある（未有効時は `device_flow_disabled` が返る）
- 使用する upstream endpoint: `POST https://github.com/login/device/code`, `POST https://github.com/login/oauth/access_token`

## 非機能要件

### N1. セキュリティ
Expand All @@ -167,7 +187,7 @@ WebhookMcpAgent DO が以下のツールセットを提供する。ローカル
| N2.2 | シークレット | Cloudflare Secret `GITHUB_WEBHOOK_SECRET` | なし（検証スキップ） |
| N2.3 | チャンネル通知の有効/無効 | `WEBHOOK_CHANNEL` | 有効（`0` で無効） |
| N2.4 | カスタムドメイン | `github-webhook.smgjp.com` | Cloudflare Worker のカスタムドメインとして設定済み |
| N2.5 | 認証方式 | Worker 自前認証 | Cloudflare Access は使用しない。Worker が webhook secret + OAuth で認証を処理する |
| N2.5 | 認証方式 | Worker 自前認証 | Cloudflare Access は使用しない。Worker が webhook secret + OAuth Device Authorization Grant (RFC 8628) で認証を処理する |
| N2.6 | プレビューインスタンス | `preview` 環境 | 本番と同一構成の検証用インスタンス |

### N3. 制約
Expand All @@ -177,7 +197,7 @@ WebhookMcpAgent DO が以下のツールセットを提供する。ローカル
| N3.1 | WebhookStore / McpAgent DO はテナント別インスタンス（`idFromName("store-{accountId}")` / `getAgentByName("tenant-{accountId}")`）で動作する。TenantRegistry DO は単一インスタンスで全テナントの installation-account マッピングを管理する |
| N3.2 | SSE 接続は DO のメモリ内で管理される（DO eviction 時に切断） |
| N3.3 | ローカルブリッジはツール呼び出しごとに Worker セッションを再利用する（セッション失効時は自動リトライ） |
| N3.4 | OAuth コールバック時に `GET /user/installations` で取得した accessible_account_ids（ユーザー + org）を GitHubUserProps に保存し、McpAgent が複数 store を並列クエリして結果をマージする。これにより org インストールのイベントもメンバーの MCP セッションから参照できる |
| N3.4 | Device flow 完了時に `GET /user/installations` で取得した accessible_account_ids（ユーザー + org）を GitHubUserProps に保存し、McpAgent が複数 store を並列クエリして結果をマージする。これにより org インストールのイベントもメンバーの MCP セッションから参照できる |

## CI/CD

Expand Down Expand Up @@ -211,6 +231,8 @@ WebhookMcpAgent DO が以下のツールセットを提供する。ローカル
| @modelcontextprotocol/sdk | MCP SDK |
| zod | スキーマバリデーション |

OAuth 実装は自前（`worker/src/oauth.ts` + `worker/src/oauth-store.ts`）。`@cloudflare/workers-oauth-provider` は v0.11.0 で撤去済み（device flow 非対応のため）。

### ローカルブリッジ (mcp-server/)

| パッケージ | 用途 |
Expand All @@ -228,6 +250,8 @@ Node.js >= 18.0.0 が必要。
| `worker/src/agent.ts` | WebhookMcpAgent DO（MCP ツール定義、テナント別インスタンス） |
| `worker/src/store.ts` | WebhookStore DO（SQLite + SSE、テナント別インスタンス） |
| `worker/src/tenant.ts` | TenantRegistry DO（installation-account マッピング、クォータ管理） |
| `worker/src/oauth.ts` | OAuth Device Authorization Grant (RFC 8628) 自前実装（metadata / register / device_authorization / token / 独自 token 検証 middleware） |
| `worker/src/oauth-store.ts` | OAuth KV schema helper（client / device / user_code / token / refresh / grant レコード操作） |
| `worker/wrangler.toml` | Worker デプロイ設定 |
| `shared/src/types.ts` | 共有型定義 |
| `shared/src/summarize.ts` | イベントサマリー生成 |
Expand Down
28 changes: 26 additions & 2 deletions docs/0-requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,26 @@ WebhookMcpAgent DO が以下のツールセットを提供する。ローカル
| 3 | フルペイロードが必要なイベントのみ `get_event(event_id)` で取得 |
| 4 | 処理完了後 `mark_processed(event_id)` でマーク |

### F7. OAuth 認証（Device Authorization Grant, RFC 8628）

Worker は OAuth 2.1 Device Authorization Grant を自前実装する（`@cloudflare/workers-oauth-provider` は v0.11.0 で撤去）。GitHub App の device flow を upstream として利用し、localhost callback に依存しない。

| ID | 要件 |
|----|------|
| F7.1 | `GET /.well-known/oauth-authorization-server` で RFC 8414 メタデータを返す |
| F7.2 | `POST /oauth/register` で RFC 7591 dynamic client registration を行う（public client、secret 発行なし） |
| F7.3 | `POST /oauth/device_authorization` で GitHub に device code を要求し、RFC 8628 §3.2 形式の JSON（device_code / user_code / verification_uri / verification_uri_complete / expires_in / interval）を返す |
| F7.4 | `POST /oauth/token` で `grant_type=urn:ietf:params:oauth:grant-type:device_code` を処理し、GitHub への polling 結果に応じて `authorization_pending` / `slow_down` / `access_denied` / `expired_token` を RFC 8628 §3.5 準拠で返す |
| F7.5 | `POST /oauth/token` で `grant_type=refresh_token` を処理し、access token と refresh token を rotate する |
| F7.6 | 旧 `GET /oauth/authorize` および `GET /oauth/callback` は **HTTP 410 Gone** を返す（localhost callback flow は v0.11.0 で廃止） |
| F7.7 | 保護対象 API ルート（`/mcp`, `/events`）は `Authorization: Bearer <access_token>` ヘッダによる独自 token 検証 middleware で認可する |
| F7.8 | KV schema は自前設計: `client:{client_id}` / `device:{device_code}` / `user_code:{user_code}` / `token:{access_token}` / `refresh:{refresh_token}` / `grant:{grant_id}` |

**GitHub App 前提条件:**

- GitHub App の設定で **"Enable Device Flow"** を有効化する必要がある（未有効時は `device_flow_disabled` が返る）
- 使用する upstream endpoint: `POST https://github.com/login/device/code`, `POST https://github.com/login/oauth/access_token`

## Non-Functional Requirements

### N1. セキュリティ
Expand All @@ -167,7 +187,7 @@ WebhookMcpAgent DO が以下のツールセットを提供する。ローカル
| N2.2 | シークレット | Cloudflare Secret `GITHUB_WEBHOOK_SECRET` | なし（検証スキップ） |
| N2.3 | チャンネル通知の有効/無効 | `WEBHOOK_CHANNEL` | 有効（`0` で無効） |
| N2.4 | カスタムドメイン | `github-webhook.smgjp.com` | Cloudflare Worker のカスタムドメインとして設定済み |
| N2.5 | 認証方式 | Worker 自前認証 | Cloudflare Access は使用しない。Worker が webhook secret + OAuth で認証を処理する |
| N2.5 | 認証方式 | Worker 自前認証 | Cloudflare Access は使用しない。Worker が webhook secret + OAuth Device Authorization Grant (RFC 8628) で認証を処理する |
| N2.6 | プレビューインスタンス | `preview` 環境 | 本番と同一構成の検証用インスタンス |

**GitHub Webhook 購読イベント:**
Expand All @@ -190,7 +210,7 @@ WebhookMcpAgent DO が以下のツールセットを提供する。ローカル
| ID | 制約 |
|----|------|
| N3.1 | WebhookStore / McpAgent DO はテナント別インスタンス（`idFromName("store-{accountId}")` / `getAgentByName("tenant-{accountId}")`）で動作する。TenantRegistry DO は単一インスタンスで全テナントの installation-account マッピングを管理する |
| N3.4 | OAuth コールバック時に `GET /user/installations` で取得した accessible_account_ids（ユーザー + org）を GitHubUserProps に保存し、McpAgent が複数 store を並列クエリして結果をマージする。これにより org インストールのイベントもメンバーの MCP セッションから参照できる |
| N3.4 | Device flow 完了時に `GET /user/installations` で取得した accessible_account_ids（ユーザー + org）を GitHubUserProps に保存し、McpAgent が複数 store を並列クエリして結果をマージする。これにより org インストールのイベントもメンバーの MCP セッションから参照できる |
| N3.2 | WebSocket / SSE 接続は DO のメモリ内で管理される（DO eviction 時に切断） |
| N3.3 | ローカルブリッジはツール呼び出しごとに Worker セッションを再利用する（セッション失効時は自動リトライ） |

Expand All @@ -204,6 +224,8 @@ WebhookMcpAgent DO が以下のツールセットを提供する。ローカル
| @modelcontextprotocol/sdk | MCP SDK |
| zod | スキーマバリデーション |

OAuth 実装は自前（`worker/src/oauth.ts` + `worker/src/oauth-store.ts`）。`@cloudflare/workers-oauth-provider` は v0.11.0 で撤去済み（device flow 非対応のため）。

### ローカルブリッジ (mcp-server/)

| パッケージ | 用途 |
Expand Down Expand Up @@ -272,6 +294,8 @@ manifest.json のバージョンも一致させる。
| `worker/src/agent.ts` | WebhookMcpAgent DO（MCP ツール定義、テナント別インスタンス） |
| `worker/src/store.ts` | WebhookStore DO（SQLite + SSE、テナント別インスタンス） |
| `worker/src/tenant.ts` | TenantRegistry DO（installation-account マッピング、クォータ管理） |
| `worker/src/oauth.ts` | OAuth Device Authorization Grant (RFC 8628) 自前実装（metadata / register / device_authorization / token / 独自 token 検証 middleware） |
| `worker/src/oauth-store.ts` | OAuth KV schema helper（client / device / user_code / token / refresh / grant レコード操作） |
| `worker/wrangler.toml` | Worker デプロイ設定 |
| `shared/src/types.ts` | 共有型定義 |
| `shared/src/summarize.ts` | イベントサマリー生成 |
Expand Down
7 changes: 0 additions & 7 deletions worker/package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 0 additions & 1 deletion worker/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@
"deploy": "wrangler deploy"
},
"dependencies": {
"@cloudflare/workers-oauth-provider": "^0.3.1",
"@modelcontextprotocol/sdk": "^1.0.0",
"agents": "^0.8.0",
"zod": "^4.0.0"
Expand Down
Loading
Loading