@octo-dock/mcp-bridge 0.1.0 → 0.2.0

package/README.md

@@ -4,13 +4,31 @@ Stdio ↔ HTTP bridge for [OctoDock](https://octo-dock.com) MCP.
 
 OctoDock serves Model Context Protocol over HTTP at `https://octo-dock.com/mcp/{apiKey}`. Some MCP clients (e.g. **Claude Desktop free tier**) only support stdio transport and cannot connect to HTTP remotes directly. This package is a thin bridge: it reads/writes stdio on one side and forwards JSON-RPC messages to the OctoDock HTTP endpoint on the other.
 
+## What's new in 0.2.0
+
+**OAuth 2.0 + PKCE S256 is now the default login flow.** The bridge no longer stores your MCP URL with embedded API key — instead it holds short-lived access tokens + refresh tokens that are auto-rotated. Credential leakage risk drops dramatically (sharing your URL no longer equals sharing your Gmail control).
+
+- Default `login` opens a browser to OctoDock's authorization page, you click Allow, bridge stores `access_token` + `refresh_token` + `client_credentials` locally (`~/.octodock/config.json` with `chmod 0o600`).
+- `login --legacy-api-key` flag keeps the old URL-paste flow for backward compatibility (0.1.x config migrates automatically — no re-login required if you don't want).
+- Existing 0.1.x users upgrading to 0.2.0: bridge detects legacy config and keeps working. Run `login` (without flag) whenever you want to migrate to OAuth.
+
 ## Quick start
 
+### New user (OAuth — recommended)
+
 ```bash
 npx -y @octo-dock/mcp-bridge login
 ```
 
-This opens [octo-dock.com/dashboard](https://octo-dock.com/dashboard), you copy your MCP URL from the top of the page, paste it back into the terminal, and the bridge saves it to `~/.octodock/config.json`.
+This opens your browser to OctoDock's authorization page. Sign in, click **Allow**, bridge saves OAuth credentials to `~/.octodock/config.json`.
+
+### Existing 0.1.x user or OAuth not available (legacy)
+
+```bash
+npx -y @octo-dock/mcp-bridge login --legacy-api-key
+```
+
+This opens [octo-dock.com/dashboard](https://octo-dock.com/dashboard), you copy your legacy MCP URL (the one containing `ak_xxxxxx`) from the collapsed section on the dashboard, paste it back into the terminal.
 
 Then add the bridge to your MCP client config.
 
@@ -40,15 +58,18 @@ Run `npx -y @octo-dock/mcp-bridge` with no args. It reads `~/.octodock/config.js
 
 ## Environment variables
 
-- `OCTODOCK_MCP_URL` — override the stored URL at runtime (useful in CI / Docker).
-- `OCTODOCK_DASHBOARD_URL` — override the dashboard URL opened by `login` (default `https://octo-dock.com/dashboard`).
+- `OCTODOCK_MCP_URL` — override the stored URL at runtime, legacy mode only (useful in CI / Docker).
+- `OCTODOCK_DASHBOARD_URL` — override the dashboard URL opened by legacy `login --legacy-api-key` (default `https://octo-dock.com/dashboard`).
+- `OCTODOCK_ISSUER_URL` — override OAuth issuer base URL used by default `login` (default `https://octo-dock.com`).
 
 ## How it works
 
 The bridge opens two MCP SDK transports and wires their `onmessage` / `send` hooks together:
 
 - `StdioServerTransport` — reads the MCP client's JSON-RPC messages on stdin, writes responses to stdout.
-- `StreamableHTTPClientTransport` — POSTs JSON-RPC messages to `https://octo-dock.com/mcp/{apiKey}`, subscribes to SSE for server-initiated messages.
+- `StreamableHTTPClientTransport` — sends JSON-RPC to OctoDock remote, subscribes to SSE for server-initiated messages.
+  - **OAuth mode (0.2.0+ default):** connects to `https://octo-dock.com/mcp` with `Authorization: Bearer <access_token>`. Access tokens auto-refresh before expiry (60-second window); if refresh fails, bridge shuts down and asks you to re-login.
+  - **Legacy mode:** connects to `https://octo-dock.com/mcp/{apiKey}` directly (API key in URL).
 
 No message parsing or state machine — pure forwarding. Whatever your MCP client says, OctoDock hears; whatever OctoDock says, your MCP client hears.
 

package/dist/bridge.js

@@ -1,25 +1,123 @@
-// stdio ↔ HTTP transparent proxy
+// stdio ↔ HTTP transparent proxy for @octo-dock/mcp-bridge
+//
+// Phase C4 雙軌 runtime：
+// - OAuth 模式：從 config 拿 accessToken 當 Authorization: Bearer header、
+//   啟動前預判 tokenExpiresAt < now + 60s 主動 refresh、refresh 結果寫回
+//   config（chmod 0o600）。issuerUrl 用於 fetch metadata + endpoint 路由。
+// - Legacy 模式：保留 C2 之前路徑、URL 夾 API key 直接 StreamableHTTP 連
+//
 // 架構：本地跑一個 StdioServerTransport 吃 stdin/stdout，另一邊開一個
 // StreamableHTTPClientTransport 連到 OctoDock，收到的訊息直接互相轉發。
 // 不做 method 解析、不做 JSON-RPC 狀態機，純 forward。
+//
+// 401 處理策略（bot-2 pre-flight #4）：bridge 啟動前主動 refresh 解 90%
+// 情境。運作中若 transport error 含 401/invalid_token 內容、shutdown +
+// 提示「下次啟動會自動 refresh、如 refresh 仍失敗請 re-login」— 不做 hot
+// token swap（MCP SDK transport 中途換 token 複雜度高、refresh 失敗無限
+// retry 會違反 pre-flight #4 防循環）
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { readConfig } from "./config.js";
+import { readConfig, writeConfig, getConfigMode } from "./config.js";
+import { fetchAuthorizationServerMetadata, refreshAccessToken, redactSecrets, } from "./oauth-client.js";
+/** Token refresh pre-check：少於 60 秒才 refresh、避免每次 bridge 啟動都打 token endpoint */
+const REFRESH_THRESHOLD_MS = 60_000;
 function logStderr(msg) {
     // Claude Desktop 會把 stderr 收到 log file；stdout 不能寫非 JSON-RPC 訊息否則會污染 protocol
     process.stderr.write(`[octodock-mcp-bridge] ${msg}\n`);
 }
+/**
+ * OAuth 模式：確保 accessToken 可用（快過期則 refresh）。
+ * Refresh 成功回新 config、失敗 throw 明確錯讓上層提示 re-login。
+ */
+async function ensureFreshAccessToken(config) {
+    if (!config.accessToken ||
+        !config.refreshToken ||
+        !config.clientId ||
+        !config.clientSecret ||
+        !config.issuerUrl ||
+        !config.tokenExpiresAt) {
+        throw new Error("OAuth config incomplete — 請執行 `npx @octo-dock/mcp-bridge login`");
+    }
+    const needsRefresh = config.tokenExpiresAt < Date.now() + REFRESH_THRESHOLD_MS;
+    if (!needsRefresh)
+        return config;
+    logStderr("Access token 快過期、正在 refresh...");
+    const metadata = await fetchAuthorizationServerMetadata(config.issuerUrl);
+    const newTokens = await refreshAccessToken({
+        tokenEndpoint: metadata.token_endpoint,
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        refreshToken: config.refreshToken,
+    });
+    const updated = {
+        ...config,
+        accessToken: newTokens.accessToken,
+        refreshToken: newTokens.refreshToken,
+        tokenExpiresAt: newTokens.expiresAt,
+    };
+    await writeConfig(updated);
+    logStderr("✓ Token 已刷新");
+    return updated;
+}
+/**
+ * 組 StreamableHTTPClientTransport、根據 mode 決定是否帶 Bearer header
+ */
+function createHttpTransport(config) {
+    const mode = getConfigMode(config);
+    if (mode === "oauth") {
+        // OAuth 模式：endpoint 是 issuerUrl + /mcp、Bearer header 帶 accessToken
+        const remoteUrl = new URL("/mcp", config.issuerUrl);
+        const transport = new StreamableHTTPClientTransport(remoteUrl, {
+            requestInit: {
+                headers: {
+                    Authorization: `Bearer ${config.accessToken}`,
+                },
+            },
+        });
+        return { transport, remoteUrl };
+    }
+    // Legacy 模式：URL path 含 ak_xxx API key、無 Authorization header
+    const remoteUrl = new URL(config.mcpUrl);
+    const transport = new StreamableHTTPClientTransport(remoteUrl);
+    return { transport, remoteUrl };
+}
 export async function runBridge() {
-    const config = await readConfig();
+    let config = await readConfig();
     if (!config) {
         logStderr("找不到設定檔 ~/.octodock/config.json。請先執行：npx -y @octo-dock/mcp-bridge login");
         process.exitCode = 2;
         return;
     }
-    const remoteUrl = new URL(config.mcpUrl);
-    logStderr(`啟動 bridge → ${remoteUrl.origin}${remoteUrl.pathname}`);
+    const initialMode = getConfigMode(config);
+    if (initialMode === "uninitialized") {
+        logStderr("Config 不完整（沒有 OAuth tokens 也沒有 legacy mcpUrl）。請重新執行 `npx @octo-dock/mcp-bridge login`");
+        process.exitCode = 2;
+        return;
+    }
+    // OAuth 模式：啟動前預先刷新快過期的 access token
+    if (initialMode === "oauth") {
+        try {
+            config = await ensureFreshAccessToken(config);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            logStderr(`✗ OAuth token refresh 失敗：${errMsg}`);
+            logStderr("提示：若 refresh token 已過期或被撤銷、請執行 `npx @octo-dock/mcp-bridge login` 重新授權");
+            // redact 再 log 完整錯誤給 debug 用
+            try {
+                logStderr(`debug: ${JSON.stringify(redactSecrets(err))}`);
+            }
+            catch {
+                /* JSON fail 吞 */
+            }
+            process.exitCode = 3;
+            return;
+        }
+    }
+    const { transport: http, remoteUrl } = createHttpTransport(config);
+    const modeLabel = initialMode === "oauth" ? "OAuth" : "legacy API key";
+    logStderr(`啟動 bridge → ${remoteUrl.origin}${remoteUrl.pathname} (${modeLabel} mode)`);
     const stdio = new StdioServerTransport();
-    const http = new StreamableHTTPClientTransport(remoteUrl);
     // stdin → HTTP
     stdio.onmessage = (msg) => {
         http.send(msg).catch((err) => {
@@ -47,8 +145,19 @@ export async function runBridge() {
     stdio.onclose = () => { void shutdown("stdio closed"); };
     http.onclose = () => { void shutdown("remote closed"); };
     stdio.onerror = (err) => { logStderr(`stdio error: ${err.message}`); };
-    http.onerror = (err) => { logStderr(`remote error: ${err.message}`); };
-    // 先起 HTTP client，確認連線 OK 再吃 stdin，避免 race
+    http.onerror = (err) => {
+        // OAuth 模式下遇到 401 / unauthorized 類錯誤、提示用戶下次啟動會自動 refresh
+        // 若啟動前 ensureFreshAccessToken 已通但運作中仍 401、代表 server 撤銷或 token
+        // 被無效化、不 hot swap 避免 bot-2 pre-flight #4 無限 retry 風險
+        const errMsg = err.message.toLowerCase();
+        if (initialMode === "oauth" && (errMsg.includes("401") || errMsg.includes("unauthorized") || errMsg.includes("invalid_token"))) {
+            logStderr(`remote error: ${err.message} — 可能 access token 已被撤銷、請執行 \`npx @octo-dock/mcp-bridge login\` 重新授權`);
+        }
+        else {
+            logStderr(`remote error: ${err.message}`);
+        }
+    };
+    // 先起 HTTP client、確認連線 OK 再吃 stdin、避免 race
     try {
         await http.start();
     }

package/dist/cli.js

@@ -57,7 +57,9 @@ async function main() {
         return;
     }
     if (cmd === "login") {
-        await runLogin();
+        // Phase C3：預設走 OAuth、--legacy-api-key flag fallback 到舊貼 URL 模式
+        const legacy = args.includes("--legacy-api-key");
+        await runLogin({ legacy });
         return;
     }
     if (cmd && cmd.startsWith("-")) {

package/dist/config.js

@@ -1,5 +1,12 @@
 // 讀寫 ~/.octodock/config.json
-// 這個檔案存的是使用者的 MCP URL（包含 API key），所以要 chmod 600 避免同機器其他使用者讀到。
+//
+// Phase C2 雙軌 schema：
+// - legacy 模式（bridge 0.1.x 舊用戶）：只有 mcpUrl 欄位、URL path 含 ak_xxx API key
+// - OAuth 模式（bridge 0.2.0+）：加 issuerUrl + clientId/clientSecret + accessToken/refreshToken/tokenExpiresAt
+//
+// readConfig 會自動識別 config 形態、不 break 舊用戶升級（跟 C3 login `--legacy-api-key` flag 搭配）
+// writeConfig chmod 0o600 保護 accessToken / refreshToken / clientSecret 不讓同機器其他用戶讀到
+// （對應 bot-2 D2 pre-flight #1 Token 本地儲存安全性）
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { promises as fs } from "node:fs";
@@ -8,6 +15,18 @@ const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 export function getConfigPath() {
     return CONFIG_PATH;
 }
+/** 判斷 config 是 oauth / legacy / uninitialized 哪種模式 */
+export function getConfigMode(config) {
+    if (!config)
+        return "uninitialized";
+    // OAuth 模式優先檢查：有 accessToken + clientId + issuerUrl 才算 OAuth ready
+    if (config.accessToken && config.clientId && config.issuerUrl)
+        return "oauth";
+    // Legacy 模式：只有 mcpUrl
+    if (config.mcpUrl)
+        return "legacy";
+    return "uninitialized";
+}
 export async function readConfig() {
     // ENV override 優先：CI / Docker 情境 user 可能直接設環境變數而不寫檔
     const envUrl = process.env.OCTODOCK_MCP_URL?.trim();
@@ -17,10 +36,24 @@ export async function readConfig() {
     try {
         const raw = await fs.readFile(CONFIG_PATH, "utf-8");
         const parsed = JSON.parse(raw);
-        if (!parsed.mcpUrl || typeof parsed.mcpUrl !== "string") {
+        // Migration：舊 config 只有 mcpUrl、新 config 可能同時有 mcpUrl + OAuth 欄位
+        // 兩種都當 valid config 讀取、runtime 靠 getConfigMode 判斷走哪條路
+        const hasLegacyUrl = typeof parsed.mcpUrl === "string" && parsed.mcpUrl.length > 0;
+        const hasOAuthSet = typeof parsed.accessToken === "string" &&
+            typeof parsed.clientId === "string" &&
+            typeof parsed.issuerUrl === "string";
+        if (!hasLegacyUrl && !hasOAuthSet) {
             return null;
         }
-        return { mcpUrl: parsed.mcpUrl };
+        return {
+            mcpUrl: typeof parsed.mcpUrl === "string" ? parsed.mcpUrl : undefined,
+            issuerUrl: typeof parsed.issuerUrl === "string" ? parsed.issuerUrl : undefined,
+            clientId: typeof parsed.clientId === "string" ? parsed.clientId : undefined,
+            clientSecret: typeof parsed.clientSecret === "string" ? parsed.clientSecret : undefined,
+            accessToken: typeof parsed.accessToken === "string" ? parsed.accessToken : undefined,
+            refreshToken: typeof parsed.refreshToken === "string" ? parsed.refreshToken : undefined,
+            tokenExpiresAt: typeof parsed.tokenExpiresAt === "number" ? parsed.tokenExpiresAt : undefined,
+        };
     }
     catch (err) {
         if (err.code === "ENOENT")
@@ -28,10 +61,24 @@ export async function readConfig() {
         throw err;
     }
 }
+/**
+ * 寫入 config。chmod 0o600 是 bot-2 D2 pre-flight #1 token 本地儲存安全性的落實
+ * （同機器其他 user 讀不到 accessToken / refreshToken / clientSecret）
+ */
 export async function writeConfig(config) {
     await fs.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    await fs.writeFile(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+    // 過濾 undefined 欄位再 stringify、避免 JSON 含 explicit null/undefined
+    const filtered = {};
+    for (const [k, v] of Object.entries(config)) {
+        if (v !== undefined && v !== null)
+            filtered[k] = v;
+    }
+    await fs.writeFile(CONFIG_PATH, JSON.stringify(filtered, null, 2), { mode: 0o600 });
 }
+/**
+ * 驗 legacy mcpUrl 格式：protocol http/https + path 含 /mcp/{apiKey}
+ * 這個驗證只適用 legacy 模式，OAuth 模式用 issuerUrl 走 /.well-known/ 發現
+ */
 export function validateMcpUrl(url) {
     let parsed;
     try {
@@ -49,3 +96,24 @@ export function validateMcpUrl(url) {
     }
     return { ok: true };
 }
+/**
+ * 驗 OAuth issuerUrl 格式：protocol http/https + 無 path（或僅 /）
+ * bridge login OAuth flow 接收 issuerUrl 時用
+ */
+export function validateIssuerUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, reason: "不是合法的 URL 格式" };
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        return { ok: false, reason: "protocol 必須是 http 或 https" };
+    }
+    // issuerUrl 應該是 base URL 不含 path（例如 https://octo-dock.com）
+    if (parsed.pathname !== "/" && parsed.pathname !== "") {
+        return { ok: false, reason: "issuerUrl 應該是 base URL 不含 path（例如 https://octo-dock.com）" };
+    }
+    return { ok: true };
+}

package/dist/login.js

@@ -1,10 +1,24 @@
-// 互動式 login：開瀏覽器到 dashboard，請使用者貼 MCP URL 回終端機
-// 這是 MVP 版本的 device flow：手動複製貼上，不走 OAuth device code（等後端加 endpoint 再升級）
+// Interactive login for @octo-dock/mcp-bridge
+//
+// Phase C3：預設走 OAuth 2.0 authorization code flow + PKCE S256、拿 access/
+// refresh tokens 存進 ~/.octodock/config.json。
+//
+// `--legacy-api-key` flag fallback 到 Phase C2 之前的舊流程（用戶手動貼含
+// `ak_xxx` 的 MCP URL 回 terminal）、給雙軌期舊用戶 or 暫時無法走 OAuth 的
+// 情境用（例如公司 proxy 擋瀏覽器 callback、或 CI 環境無互動）。
+//
+// 流程選擇原則：
+// - 預設 OAuth：安全、URL 分享不等於 credential 洩漏、token 自動 refresh
+// - legacy：URL 夾 API key 易用但 URL 洩漏等同 Gmail 控制權給人；未來
+//   Phase C 後期 bridge 升到 1.0 時考慮下架 legacy flag
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { spawn } from "node:child_process";
 import { writeConfig, validateMcpUrl, getConfigPath } from "./config.js";
+import { startOAuthFlow, redactSecrets } from "./oauth-client.js";
 const DASHBOARD_URL = process.env.OCTODOCK_DASHBOARD_URL || "https://octo-dock.com/dashboard";
+const DEFAULT_ISSUER_URL = process.env.OCTODOCK_ISSUER_URL || "https://octo-dock.com";
+/** 開 default browser 給 OAuth / dashboard flow 用、延用跟 oauth-client 同 pattern */
 function openBrowser(url) {
     const platform = process.platform;
     let cmd;
@@ -27,26 +41,31 @@ function openBrowser(url) {
         child.unref();
     }
     catch {
-        // 忽略：user 會看到 URL 自己開
+        /* ignore */
     }
 }
-export async function runLogin() {
-    console.log("=== OctoDock MCP Bridge ─ Login ===");
+// ============================================================
+// Legacy login flow（保留 C2 之前的貼 URL 模式、給 --legacy-api-key flag 或
+// OAuth fail fallback 用）
+// ============================================================
+async function runLegacyLogin() {
+    console.log("=== OctoDock MCP Bridge ─ Legacy API Key Login ===");
     console.log("");
-    console.log("這個流程會把你的 OctoDock MCP URL 存到本機 config，讓 Claude Desktop、Cursor 等 stdio-only 客戶端可以使用你的帳號。");
+    console.log("注意：legacy 模式 URL 含 API key、分享 URL 等同分享 Gmail 控制權。");
+    console.log("建議改走 OAuth 流程（不加 --legacy-api-key flag、重新執行 login）。");
     console.log("");
     console.log(`步驟 1：打開瀏覽器前往 ${DASHBOARD_URL}`);
-    console.log("步驟 2：在 dashboard 上方複製你的 MCP URL（長得像 https://octo-dock.com/mcp/ak_xxxxxx）");
-    console.log("步驟 3：把 URL 貼回下面這個輸入框，按 Enter");
+    console.log("步驟 2：在 dashboard 展開「舊版 URL」折疊、複製含 ak_xxxxxx 的 URL");
+    console.log("步驟 3：把 URL 貼回下面這個輸入框、按 Enter");
     console.log("");
     openBrowser(DASHBOARD_URL);
     const rl = createInterface({ input, output });
     try {
-        // 最多給 3 次輸入機會，無效就結束
+        // 最多給 3 次輸入機會、無效就結束
         for (let attempt = 0; attempt < 3; attempt++) {
             const url = (await rl.question("MCP URL > ")).trim();
             if (!url) {
-                console.log("（空白輸入，請重新貼上 URL）");
+                console.log("（空白輸入、請重新貼上 URL）");
                 continue;
             }
             const check = validateMcpUrl(url);
@@ -56,9 +75,9 @@ export async function runLogin() {
             }
             await writeConfig({ mcpUrl: url });
             console.log("");
-            console.log(`✓ 設定已存到 ${getConfigPath()}`);
+            console.log(`✓ 設定已存到 ${getConfigPath()}（legacy 模式、含 API key）`);
             console.log("");
-            console.log("接下來：把這段 JSON 貼到 Claude Desktop 的 claude_desktop_config.json（位置見 README），然後重啟 Claude Desktop。");
+            console.log("接下來：把這段 JSON 貼到 Claude Desktop 的 claude_desktop_config.json、重啟 Claude Desktop：");
             console.log("");
             console.log(JSON.stringify({
                 mcpServers: {
@@ -70,10 +89,87 @@ export async function runLogin() {
             }, null, 2));
             return;
         }
-        console.log("✗ 嘗試 3 次都無效，請重新執行 `npx @octo-dock/mcp-bridge login`");
+        console.log("✗ 嘗試 3 次都無效、請重新執行 `npx @octo-dock/mcp-bridge login`");
         process.exitCode = 1;
     }
     finally {
         rl.close();
     }
 }
+// ============================================================
+// OAuth login flow（Phase C3 預設）
+// ============================================================
+async function runOAuthLogin() {
+    console.log("=== OctoDock MCP Bridge ─ OAuth Login ===");
+    console.log("");
+    console.log("這個流程會走 OAuth 2.0 授權、拿到短效 access token 跟可續期的");
+    console.log("refresh token、存到本機 config（chmod 0o600、其他 user 讀不到）。");
+    console.log("");
+    console.log("你會看到瀏覽器打開 OctoDock 的授權頁、登入後點「允許」就完成。");
+    console.log("如果瀏覽器沒自動開、下面會印出授權 URL 讓你手動開。");
+    console.log("");
+    try {
+        const result = await startOAuthFlow({
+            issuerUrl: DEFAULT_ISSUER_URL,
+            clientName: "@octo-dock/mcp-bridge",
+        });
+        // 存進 config（chmod 0o600 由 writeConfig 負責）
+        const config = {
+            issuerUrl: result.issuerUrl,
+            clientId: result.clientId,
+            clientSecret: result.clientSecret,
+            accessToken: result.accessToken,
+            refreshToken: result.refreshToken,
+            tokenExpiresAt: result.tokenExpiresAt,
+        };
+        await writeConfig(config);
+        console.log("");
+        console.log(`✓ OAuth 授權完成、已存到 ${getConfigPath()}`);
+        console.log(`  Client: ${result.clientId}`);
+        console.log(`  Access token 過期時間：${new Date(result.tokenExpiresAt).toLocaleString("zh-TW")}`);
+        console.log(`  Refresh token：${result.refreshToken.slice(0, 8)}... (自動續期)`);
+        console.log("");
+        console.log("接下來：把這段 JSON 貼到 Claude Desktop 的 claude_desktop_config.json、重啟 Claude Desktop：");
+        console.log("");
+        console.log(JSON.stringify({
+            mcpServers: {
+                octodock: {
+                    command: "npx",
+                    args: ["-y", "@octo-dock/mcp-bridge@latest"],
+                },
+            },
+        }, null, 2));
+    }
+    catch (err) {
+        // 錯誤訊息經 redactSecrets 再 log、防意外洩漏 token 到 stderr
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error("");
+        console.error(`✗ OAuth login 失敗：${errMsg}`);
+        console.error("");
+        if (errMsg.includes("Another bridge instance is registering")) {
+            console.error("提示：你可能在跑多個 login、等幾秒重試、或手動刪 ~/.octodock/.register.lock");
+        }
+        else if (errMsg.includes("Timed out waiting for OAuth callback")) {
+            console.error("提示：OAuth 超時（5 分鐘）、可能瀏覽器沒打開或沒點同意、重新執行 login");
+        }
+        else {
+            console.error("如果問題反覆出現、可以試 `--legacy-api-key` flag 走舊 API key 模式。");
+        }
+        // 不重試 OAuth（refresh token 失敗等也會進來）、用戶自己下次再跑 login
+        process.exitCode = 1;
+        // 再印一次 redacted 完整 error 物件給 debug 用（沒 token 殘留）
+        try {
+            console.error("debug:", JSON.stringify(redactSecrets(err), null, 2));
+        }
+        catch {
+            /* JSON.stringify fail、吞 */
+        }
+    }
+}
+export async function runLogin(options = {}) {
+    if (options.legacy) {
+        await runLegacyLogin();
+        return;
+    }
+    await runOAuthLogin();
+}

package/dist/oauth-client.js

@@ -0,0 +1,357 @@
+/**
+ * OAuth client for @octo-dock/mcp-bridge (Phase C Commit C1)
+ *
+ * 提供 bridge 走 OAuth 2.0 authorization code flow + PKCE S256 連接 OctoDock
+ * server 的所有 primitive。取代舊版「URL 夾 API key `ak_xxx`」單軌模式。
+ *
+ * 對齊 server-side（Phase A + A.5）實作：
+ * - /oauth/register：動態註冊 client（RFC 7591、open registration）
+ * - /oauth/authorize：PKCE S256 enforcement（code_challenge 驗 43-128 chars + S256 method）
+ * - /oauth/token：code_verifier 驗 SHA-256 比對（A.5 新增）
+ * - /oauth/revoke：logout 用（C3 login 會用到）
+ *
+ * Security 設計對齊 bot-2 D2 pre-flight 10 條 + bot-1 主動延伸 2 條：
+ * - PKCE S256（#3）：code_verifier 32 random bytes base64url → challenge = SHA-256 base64url
+ * - Local callback server bind 127.0.0.1 不 0.0.0.0（#2、防 LAN 暴露）
+ * - state CSRF 防護（#2 延伸）：隨機 state、callback 比對才 accept
+ * - Dynamic client registration race（#5）：lock file `~/.octodock/.register.lock` 獨占
+ * - Log redact helper（#7）：secret 欄位不進 stderr / crash stack
+ * - Token refresh 防循環（#4）：refresh 失敗 → 明確提示 re-login、不無限 retry
+ * - Zero new npm deps（#8）：Node 20 原生 fetch + crypto + http 模組
+ *
+ * Plan reference: docs/plan-oauth-upgrade.md @ 4d667e8 (v2e) 第三章 C1
+ */
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { openSync, closeSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const CONFIG_DIR = join(homedir(), ".octodock");
+const REGISTER_LOCK_PATH = join(CONFIG_DIR, ".register.lock");
+// ============================================================
+// Secret keys 清單：log redact helper 過濾這些欄位
+// ============================================================
+const SECRET_KEYS = new Set([
+    "accessToken",
+    "refreshToken",
+    "clientSecret",
+    "mcpApiKey",
+    "code_verifier",
+    "code_challenge",
+    "access_token",
+    "refresh_token",
+    "client_secret",
+    "secret_hash",
+]);
+/**
+ * 遞迴過濾 object 裡的 secret 欄位、替換成 "[REDACTED]"
+ * 給 console.log / console.error / crash stack 用、防 token 洩漏到用戶 paste 的 log
+ */
+export function redactSecrets(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => redactSecrets(v));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (SECRET_KEYS.has(k)) {
+            out[k] = "[REDACTED]";
+        }
+        else {
+            out[k] = redactSecrets(v);
+        }
+    }
+    return out;
+}
+// ============================================================
+// PKCE helpers (RFC 7636)
+// ============================================================
+/** 產生 code_verifier：32 random bytes base64url（輸出長度 43 chars） */
+function generateCodeVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+/** 產生 code_challenge：SHA-256(code_verifier) base64url 無 padding */
+function generateCodeChallenge(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+/** 產生 random state 防 CSRF（16 bytes base64url） */
+function generateState() {
+    return randomBytes(16).toString("base64url");
+}
+// ============================================================
+// Lock file：防 parallel registerClient race
+// ============================================================
+function acquireRegisterLock() {
+    try {
+        // `wx` = O_CREAT | O_EXCL、存在則 throw EEXIST
+        return openSync(REGISTER_LOCK_PATH, "wx");
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return null;
+        throw err;
+    }
+}
+function releaseRegisterLock(fd) {
+    try {
+        closeSync(fd);
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        unlinkSync(REGISTER_LOCK_PATH);
+    }
+    catch {
+        /* ignore */
+    }
+}
+// ============================================================
+// Open browser（延用 login.ts 既有 pattern）
+// ============================================================
+function openBrowser(url) {
+    const platform = process.platform;
+    let cmd;
+    let args;
+    if (platform === "darwin") {
+        cmd = "open";
+        args = [url];
+    }
+    else if (platform === "win32") {
+        cmd = "cmd";
+        args = ["/c", "start", "", url];
+    }
+    else {
+        cmd = "xdg-open";
+        args = [url];
+    }
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => {
+            /* 打不開沒關係、上層會印 URL 讓 user 手動開 */
+        });
+        child.unref();
+    }
+    catch {
+        /* 同上 */
+    }
+}
+export async function fetchAuthorizationServerMetadata(issuerUrl) {
+    const url = new URL("/.well-known/oauth-authorization-server", issuerUrl).toString();
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch authorization server metadata: HTTP ${res.status} ${res.statusText}`);
+    }
+    return (await res.json());
+}
+export async function registerClient(issuerUrl, clientName) {
+    const metadata = await fetchAuthorizationServerMetadata(issuerUrl);
+    // bridge register 時用 `http://localhost` 當 redirect_uri prefix、
+    // 對應 server-side Phase A Commit 2 f8990e7 的 RFC 8252 localhost:* port-agnostic 豁免
+    const registrationEndpoint = metadata.registration_endpoint ?? new URL("/oauth/register", issuerUrl).toString();
+    // Race protection：獨占 lock file、fail 就等用戶重試
+    const lockFd = acquireRegisterLock();
+    if (lockFd === null) {
+        throw new Error("Another bridge instance is registering. Please wait a few seconds and retry `npx @octo-dock/mcp-bridge login`.");
+    }
+    try {
+        const res = await fetch(registrationEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                client_name: clientName,
+                redirect_uris: ["http://localhost", "http://127.0.0.1"],
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`Dynamic client registration failed: HTTP ${res.status} ${res.statusText}. ${body.slice(0, 200)}`);
+        }
+        const data = (await res.json());
+        return { clientId: data.client_id, clientSecret: data.client_secret };
+    }
+    finally {
+        releaseRegisterLock(lockFd);
+    }
+}
+function startCallbackServer() {
+    return new Promise((resolve, reject) => {
+        let resolveCallback;
+        let rejectCallback;
+        const server = createServer((req, res) => {
+            try {
+                const url = new URL(req.url ?? "/", "http://localhost");
+                if (url.pathname !== "/callback") {
+                    res.writeHead(404);
+                    res.end("Not found");
+                    return;
+                }
+                const code = url.searchParams.get("code");
+                const state = url.searchParams.get("state");
+                const error = url.searchParams.get("error");
+                const errorDescription = url.searchParams.get("error_description");
+                if (error) {
+                    res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+                    res.end(`<html><body style="font-family:sans-serif;padding:2rem"><h1>授權失敗</h1><p>${error}${errorDescription ? `: ${errorDescription}` : ""}</p></body></html>`);
+                    rejectCallback?.(new Error(`OAuth authorization failed: ${error}`));
+                    return;
+                }
+                if (!code || !state) {
+                    res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+                    res.end(`<html><body style="font-family:sans-serif;padding:2rem"><h1>授權失敗</h1><p>缺少 code 或 state 參數</p></body></html>`);
+                    rejectCallback?.(new Error("Missing code or state in callback"));
+                    return;
+                }
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                res.end(`<html><body style="font-family:sans-serif;padding:2rem"><h1>✓ 授權成功</h1><p>你可以關掉這個視窗、回到 terminal 完成設定。</p></body></html>`);
+                resolveCallback?.({ code, state });
+            }
+            catch (err) {
+                rejectCallback?.(err);
+            }
+        });
+        server.on("error", reject);
+        // 明確 bind 127.0.0.1（不 0.0.0.0、不 ::1）
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            resolve({
+                port: addr.port,
+                waitForCallback: (expectedState, timeoutMs) => new Promise((res, rej) => {
+                    const timer = setTimeout(() => {
+                        rej(new Error("Timed out waiting for OAuth callback"));
+                        server.close();
+                    }, timeoutMs);
+                    resolveCallback = (result) => {
+                        clearTimeout(timer);
+                        if (result.state !== expectedState) {
+                            rej(new Error("state mismatch (possible CSRF attack) — aborting"));
+                            server.close();
+                            return;
+                        }
+                        res(result);
+                    };
+                    rejectCallback = (err) => {
+                        clearTimeout(timer);
+                        rej(err);
+                    };
+                }),
+                close: () => server.close(),
+            });
+        });
+    });
+}
+async function exchangeCodeForTokens(params) {
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: params.clientId,
+        client_secret: params.clientSecret,
+        code: params.code,
+        redirect_uri: params.redirectUri,
+        code_verifier: params.codeVerifier,
+    });
+    const res = await fetch(params.tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        const errBody = await res.json().catch(() => ({ error: "unknown" }));
+        throw new Error(`Token exchange failed: ${JSON.stringify(redactSecrets(errBody))}`);
+    }
+    const data = (await res.json());
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: Date.now() + data.expires_in * 1000,
+        scope: data.scope,
+    };
+}
+// ============================================================
+// Refresh access token
+// ============================================================
+export async function refreshAccessToken(params) {
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: params.clientId,
+        client_secret: params.clientSecret,
+        refresh_token: params.refreshToken,
+    });
+    const res = await fetch(params.tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        // 區分 refresh_token 過期 / 撤銷 vs 暫時 server error
+        const errBody = (await res.json().catch(() => ({})));
+        if (res.status === 400 && errBody.error === "invalid_grant") {
+            // refresh_token 無效（過期或被撤銷）— 不 retry、請用戶 re-login
+            throw new Error("Refresh token is invalid or revoked. Please run `npx @octo-dock/mcp-bridge login` to re-authorize.");
+        }
+        throw new Error(`Token refresh failed: HTTP ${res.status} ${JSON.stringify(redactSecrets(errBody))}`);
+    }
+    const data = (await res.json());
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: Date.now() + data.expires_in * 1000,
+        scope: data.scope,
+    };
+}
+export async function startOAuthFlow(options) {
+    const clientName = options.clientName ?? "@octo-dock/mcp-bridge";
+    const timeoutMs = options.callbackTimeoutMs ?? 5 * 60 * 1000; // 5 分鐘
+    // 1. Fetch authorization server metadata
+    const metadata = await fetchAuthorizationServerMetadata(options.issuerUrl);
+    // 2. Register client if no existing credentials
+    const client = options.existingClient
+        ? options.existingClient
+        : await registerClient(options.issuerUrl, clientName);
+    // 3. Generate PKCE + state
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    const state = generateState();
+    // 4. Start local callback server bind 127.0.0.1 隨機 port
+    const server = await startCallbackServer();
+    const redirectUri = `http://127.0.0.1:${server.port}/callback`;
+    try {
+        // 5. Build authorize URL + open browser
+        const authUrl = new URL(metadata.authorization_endpoint);
+        authUrl.searchParams.set("response_type", "code");
+        authUrl.searchParams.set("client_id", client.clientId);
+        authUrl.searchParams.set("redirect_uri", redirectUri);
+        authUrl.searchParams.set("scope", "mcp");
+        authUrl.searchParams.set("state", state);
+        authUrl.searchParams.set("code_challenge", codeChallenge);
+        authUrl.searchParams.set("code_challenge_method", "S256");
+        console.log("\n打開瀏覽器完成授權（5 分鐘內完成）：");
+        console.log(authUrl.toString());
+        console.log("");
+        openBrowser(authUrl.toString());
+        // 6. Wait for callback
+        const { code } = await server.waitForCallback(state, timeoutMs);
+        // 7. Exchange code for tokens
+        const tokens = await exchangeCodeForTokens({
+            tokenEndpoint: metadata.token_endpoint,
+            clientId: client.clientId,
+            clientSecret: client.clientSecret,
+            code,
+            redirectUri,
+            codeVerifier,
+        });
+        return {
+            clientId: client.clientId,
+            clientSecret: client.clientSecret,
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            tokenExpiresAt: tokens.expiresAt,
+            issuerUrl: options.issuerUrl,
+        };
+    }
+    finally {
+        server.close();
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@octo-dock/mcp-bridge",
-  "version": "0.1.0",
-  "description": "Stdio ↔ HTTP bridge for OctoDock MCP. Lets Claude Desktop free tier (and any stdio-only MCP client) connect to your OctoDock remote MCP.",
+  "version": "0.2.0",
+  "description": "Stdio ↔ HTTP bridge for OctoDock MCP with OAuth 2.0 + PKCE S256 support. Lets Claude Desktop free tier (and any stdio-only MCP client) connect to your OctoDock remote MCP via OAuth (no more URL-embedded API keys).",
   "license": "BSL-1.1",
   "author": "OctoDock Contributors",
   "homepage": "https://octo-dock.com",