Arcrun/mcp/OAUTH.md

arcrun-mcp OAuth 2.1 Server（claude.ai 遠端 connector 安全登入）

Design 文件。對應 PR feat/mcp-oauth-server。實作全在 mcp/（改既有 arcrun-mcp 這一顆 worker 的框架碼，非新 worker、非應用工作流、無 service binding）。

1. 為什麼（安全定調）

MCP 打進 arcrun = 觸及該租戶 KBDB 全量讀寫，是個資外泄面，必須有真認證。

修掉的漏洞：partner-auth.ts 舊行為在 MULTI_TENANT=false（self-hosted）時，把 Authorization: Bearer <x> 的 <x> 直接當成 org_namespace 明碼放行。於是任何知道 URL 的人送 Bearer leo 就能讀寫 leo 的全部資料。這正是本次要關掉的洞。

鐵律：只知道「網址 + 明碼 namespace」的人，必須讀不到任何資料。

2. 安全模型（owner secret 怎麼把關）

claude.ai remote connector 走 OAuth 2.1 + PKCE（S256）。整條鏈唯一的「人類祕密閘」在 /authorize 同意頁：要求輸入 owner secret（MCP_OWNER_SECRET，存 CF Secrets，非 KV、非明碼 var）。

• 祕密正確 → 才發 authorization code → claude.ai 用 PKCE code_verifier 換 access_token。
• 祕密錯誤 / 未帶 → 不發碼，重顯同意頁（401）。
• MCP_OWNER_SECRET 未設 → /authorize 直接回 503（拒絕在無把關下發碼，不留不安全預設）。

為何「只知 URL 的人」進不來：他能打開 /authorize 頁、能自己跑 DCR 拿 client_id、能發起 PKCE，但走到發碼那步需要 owner secret，而 secret 只在 CF Secrets、只有 owner 知道。拿不到 code → 換不到 token → 打 /mcp 一律 401。access_token 是唯一被 /mcp 接受的 bearer（見 §5 相容決策）。

縱深防禦：

• PKCE S256 強制：/authorize 與 /token 都要求 code_challenge_method=S256；plain／缺省一律拒。
• authorization code 一次性 + 極短 TTL（600s）：讀到即從 KV 刪，防重放。
• redirect_uri 白名單（DCR 無狀態，見 §5）：預設只允許 claude.ai／claude.com／anthropic.com （含子網域）＋ localhost；http 僅限本機。擋 open-redirect／釣魚把 code 送去攻擊者。可用 MCP_ALLOWED_REDIRECT_HOSTS 調整。
• token audience 綁定 + 簽發端驗證（RFC 8707）：
  • /authorize、/token 收到 client 的 resource 參數時，正規化後（scheme/host 小寫、去預設 port、 path 去尾斜線；與 metadata.ts resourceUri 產出的 canonical 一致）必須 == 本 server canonical resourceUri(origin)。不符則簽發端 fail fast：/authorize redirect 帶 error=invalid_target （redirect_uri 已驗過才 redirect，否則 400）、/token 回 400 invalid_target。
  • 存進 aud 的一律是 canonical resourceUri(origin)（不存 client 原樣值）→ 與 partner-auth 的嚴格比對 at.aud === resourceUri(origin) 恆一致。
  • 為何要正規化而非純字串拒：claude.ai 送 …/mcp/（尾斜線）或大小寫變體是等價 canonical → 正規化後接受、 存 canonical aud → /mcp 必過。若對等價形也拒，claude.ai 真送變體會永久授權失敗連不上（把「OAuth 成功 但 /mcp 401」的問題換位重現）。只有正規化後真正不同的 resource（別的 host/path）才 fail-fast 拒。
• KV key 用 SHA-256 hash：code／token 不以明碼當 key，KV list 也拿不到可用憑證（比照 wasi-shim.ts 只寫短效 oauth2 cache 的精神）。
• owner secret／static token 用常數時間比對：防 timing attack。

3. Endpoint 清單（全掛在 worker origin 根，非 /mcp basePath）

Method	Path	規範	作用
GET	/.well-known/oauth-protected-resource（+/mcp 後綴變體）	RFC 9728	Protected Resource Metadata：resource + authorization_servers
GET	/.well-known/oauth-authorization-server（+/mcp 後綴變體）	RFC 8414	AS Metadata：authorize/token/registration endpoint、S256、code、none
POST	/register	RFC 7591	Dynamic Client Registration → 回 client_id（public client，無 secret）
GET	/authorize	OAuth 2.1	呈現 owner-secret 同意頁（要求 response_type=code + PKCE S256 + 合法 redirect_uri）
POST	/authorize	OAuth 2.1	驗 owner secret → 發 code → 302 redirect 回 redirect_uri?code=&state=
POST	/token	OAuth 2.1	authorization_code + code_verifier(PKCE) → access_token

未帶有效 token 的 /mcp（及 GUI REST 端點）：回 401 + WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource"（RFC 9728 §5.1），claude.ai 靠這個 發現 OAuth。

metadata 以「當前請求 origin」動態生成 → 同一份碼在 mcp.arcrun.dev 與 arcrun-mcp.<sub>.workers.dev 都正確。

4. 各資料存哪（儲存鐵律逐項）

資料	存哪	理由
authorization code	短效 KV OAUTH_KV，key=oauth:code:<sha256>，TTL 600s，一次性	「取得的暫時性認證」，允許進短效 KV
access token	短效 KV OAUTH_KV，key=oauth:tok:<sha256>，TTL=MCP_TOKEN_TTL（預設 30 天）	同上；過期自動消失
owner secret	CF Secrets MCP_OWNER_SECRET（wrangler secret put）	長效機密，非 KV、非明碼 var
static token（相容用）	CF Secrets MCP_STATIC_TOKEN（選配）	長效機密，同上
DCR client 註冊	不落地（無狀態）	public client 無 secret，非機密；不需持久 → 不塞 KV（守鐵律）
refresh token	不實作（見 §5）	避免長效機密落地；改短效 access_token + 到期重新授權
owner namespace / token TTL / redirect 白名單	[vars]（非機密設定）	純設定值

5. 相容決策（明碼-namespace-bearer 舊路徑怎麼處理）

預設安全優先，遠端一律走 OAuth。 partner-auth.ts 新認證順序：

1. OAuth access_token（OAUTH_KV 查得到）→ 解出綁定 namespace。遠端 claude.ai 的正規路徑。
2. MCP_STATIC_TOKEN（真祕密，CF Secret） → 解成 MCP_OWNER_NAMESPACE。本機 CLI / GUI / 本機 Claude Code 的相容路徑——用「真祕密 token」取代舊「明碼 namespace」，owner 可掌控（CF Secrets）。
3. 官方 SaaS（MULTI_TENANT 未設/true） → KBDB partner-key 驗證，行為完全不變。
4. 【預設關，SUNSET】ALLOW_PLAINTEXT_NAMESPACE="true" → 恢復舊明碼路徑。僅遷移期，設了等於重開漏洞，正式勿用。
5. 皆不符 → 401 + WWW-Authenticate。

明碼 namespace 當 bearer 的舊路徑已從預設移除（步驟 5 直接 401）。之所以保留步驟 2/4：

• 本機 Claude Code MCP 目前經 acr mcp-setup 把 namespace 寫進 .mcp.json 的 Authorization header。若硬砍會斷本機整合。正解＝改用 MCP_STATIC_TOKEN（真祕密）；mcp-setup 寫入真祕密而非 明碼 namespace 屬 CLI 側後續（本 PR 未動 CLI，於報告標為待辦）。
• ALLOW_PLAINTEXT_NAMESPACE 只是遷移期的明確 opt-in 逃生門，預設關 = 預設安全。

逃生門有退場（SUNSET）：ALLOW_PLAINTEXT_NAMESPACE 只是遷移期暫時相容，驗收完即刪整段 code path ＋ Env 欄位。移除追蹤：Gitea issue #18（#18）。code 中該分支已標 SUNSET 註記。

access_token TTL 是有意取捨（無 refresh token）

為何不做 refresh token：refresh token 需長效持久化，依鐵律得進 CF Secrets/KBDB 而非 KV，成本與 面積都大。有意取捨＝改採「較長 TTL 的 access_token + 到期重走 OAuth（owner 重輸一次 owner secret）」， 兼顧安全（週期性重認證）與簡潔（無長效機密落地）。

• 預設 MCP_TOKEN_TTL = 2592000 秒（30 天）——本 PR 維持此預設（leo 拍板不改）。
• 可調：[vars] 改 MCP_TOKEN_TTL 即可；7 天（604800）為更保守選項（縮短 = 更頻繁重認證 = 更安全但 UX 略煩）。
• 到期行為：KV TTL 到 → token 自動失效 → /mcp 回 401 + WWW-Authenticate → claude.ai 重走 OAuth （再輸一次 owner secret）。無 refresh token 故無長效機密落地。
• 後續（per-owner 可調，非本 PR）：TTL 風險偏好交用戶決定——console 設定頁 → 存 KBDB → /token 發 token 時讀 per-owner 覆蓋、回退 30 天。追蹤：Gitea issue #19（#19）。

6. 測試涵蓋

mcp/tests/unit/oauth.test.ts：

• PKCE S256 驗證（正確 / 拒 plain / 拒缺省 method / verifier 長度邊界 / 竄改）；已知 SHA-256 向量、RFC 7636 附錄範例。
• 短效 KV store：authorization code 一次性（consume 後失效，防重放）、access token 存取 + exp 過期、key 為 hash。
• metadata：origin 推導、Protected Resource / AS Metadata 必要欄位、WWW-Authenticate 格式。
• RFC 8707 resource 正規化/簽發端驗證：normalizeResource/resourceMatches（尾斜線/大小寫/預設 port 等價、別 host/path 不等價）；/authorize 尾斜線變體→正常發碼且 token aud 為 canonical、 別 host 的 resource → GET/POST /authorize redirect error=invalid_target 不發碼、/token 帶別 host resource → 400 invalid_target。
• consent XSS escape（惡意 state 不注入）。
• 完整流程整合（Hono app.request）：well-known 動態 origin、DCR 回 client_id 無 secret、redirect_uri 白名單擋非法 host、GET /authorize 要 PKCE、MCP_OWNER_SECRET 未設→503、正確祕密+正確 verifier→ access_token、錯誤祕密→401 不發 code、錯誤 verifier→invalid_grant、重用 code→invalid_grant、 OAUTH_KV 未設→503。
• 防 drift：spy KV 攔所有 put，斷言對 OAUTH_KV 的每一次 put 都帶 expirationTtl（> 0）—— 防未來有人往這顆 KV 塞長效資料（守儲存鐵律）。

mcp/tests/unit/partner-auth.test.ts（改測真實 middleware）：

• 無/壞 Authorization → 401 + WWW-Authenticate（RFC 9728）。
• OAuth token → 解出 namespace；未知 token（明碼）在 self-hosted → 401（洞已補）。
• RFC 8707 aud 驗證：token aud 不等於本次請求 origin 算出的 canonical resource URI → 401 invalid_token。
• MCP_STATIC_TOKEN 相容路徑通過 / 明碼被擋。
• 官方 SaaS partner-key（mock KBDB）行為不變。
• ALLOW_PLAINTEXT_NAMESPACE 逃生門開/關。

全部測試綠；tsc --noEmit exit 0；wrangler deploy --dry-run 打包過、OAUTH_KV binding 正確識別。

7. leo 部署前要做什麼（不在本 PR 內，本 PR 不部署）

1. 建 KV namespace + 填 id（依部署路徑）：
   • CLI 路徑（acr init / acr update）→ 已自動化：本 PR 把 OAUTH_KV 納入 deploy.ts REQUIRED_KV_NAMESPACES → init/update 自動建 namespace（冪等）＋ injectWranglerConfig 把 REPLACE_WITH_REAL_KV_ID 換成用戶帳號真 id。零手動。
   • 手動直推（leo21c wrangler deploy，mistakes #23 codeload 陷阱下走的路徑）→ 需手動： wrangler kv namespace create OAUTH_MCP → 把 id 貼進 mcp/wrangler.toml 的 [[kv_namespaces]] OAUTH_KV。
2. 設 owner secret（CF Secrets）：wrangler secret put MCP_OWNER_SECRET（輸入只有你知道的強祕密）。 3.（選配）設本機相容 static token：wrangler secret put MCP_STATIC_TOKEN，並把本機 .mcp.json 的 Authorization: Bearer <此值>（取代舊明碼 namespace）。 4.（選配）[vars] 調 MCP_OWNER_NAMESPACE（預設 leo）/MCP_TOKEN_TTL（預設 2592000）/ MCP_ALLOWED_REDIRECT_HOSTS。
3. 重部署 arcrun-mcp（走 leo21c wrangler 直推，勿 acr update——codeload 陷阱 mistakes #23）。
4. 驗收：curl <origin>/.well-known/oauth-protected-resource → 200；未帶 token 打 /mcp → 401 帶 WWW-Authenticate；claude.ai 加 remote connector 走完 OAuth（輸 owner secret）能連上。

⚠️ 若 KV/secret 未就緒：OAuth 端點誠實回 503、/mcp 回 401（不假綠）；既有官方 SaaS partner-key 路徑不受影響。