@zhijiewang/openharness 2.11.0 → 2.12.0

package/README.md

@@ -378,6 +378,7 @@ mcpServers:
 ```
 
 See [docs/mcp-servers.md](docs/mcp-servers.md) for the full reference.
+See [docs/mcp-servers.md](docs/mcp-servers.md#authentication) for OAuth 2.1 setup (auto-triggered on 401; `/mcp-login` and `/mcp-logout` commands available).
 
 **MCP Server Registry** — browse and install from a curated catalog:
 

package/dist/commands/index.d.ts

@@ -17,7 +17,7 @@ import type { CommandContext, CommandResult } from "./types.js";
 /**
  * Check if input is a slash command. If so, execute it.
  */
-export declare function processSlashCommand(input: string, context: CommandContext): CommandResult | null;
+export declare function processSlashCommand(input: string, context: CommandContext): Promise<CommandResult | null>;
 /**
  * Get all registered command names (for autocomplete/display).
  */

package/dist/commands/index.js

@@ -34,7 +34,7 @@ registerSkillCommands(register);
 /**
  * Check if input is a slash command. If so, execute it.
  */
-export function processSlashCommand(input, context) {
+export async function processSlashCommand(input, context) {
     const trimmed = input.trim();
     if (!trimmed.startsWith("/"))
         return null;

package/dist/commands/info.js

@@ -8,7 +8,10 @@ import { gitBranch, isGitRepo, isInMergeOrRebase } from "../git/index.js";
 import { readOhConfig } from "../harness/config.js";
 import { estimateMessageTokens } from "../harness/context-warning.js";
 import { getContextWindow } from "../harness/cost.js";
+import { normalizeMcpConfig } from "../mcp/config-normalize.js";
 import { connectedMcpServers } from "../mcp/loader.js";
+import { getAuthStatus } from "../mcp/oauth.js";
+import { mcpLoginHandler, mcpLogoutHandler } from "./mcp-auth.js";
 export function registerInfoCommands(register, getCommandMap) {
     register("help", "Show available commands", () => {
         const categories = {
@@ -39,6 +42,8 @@ export function registerInfoCommands(register, getCommandMap) {
                 "doctor",
                 "context",
                 "mcp",
+                "mcp-login",
+                "mcp-logout",
                 "mcp-registry",
                 "init",
                 "bug",
@@ -387,19 +392,50 @@ export function registerInfoCommands(register, getCommandMap) {
         ];
         return { output: lines.join("\n"), handled: true };
     });
-    register("mcp", "Show MCP server status", () => {
-        const mcp = connectedMcpServers();
-        if (mcp.length === 0) {
+    register("mcp", "Show MCP server status", async () => {
+        const connected = connectedMcpServers();
+        if (connected.length === 0) {
             return {
                 output: "No MCP servers connected.\nConfigure in .oh/config.yaml under mcpServers.\nRun /mcp-registry to browse available servers.",
                 handled: true,
             };
         }
-        const lines = [`MCP Servers (${mcp.length} connected):\n`];
-        for (const name of mcp) {
-            lines.push(`  ✓ ${name}`);
+        const cfg = readOhConfig();
+        const servers = cfg?.mcpServers ?? [];
+        const storageDir = join(homedir(), ".oh", "credentials", "mcp");
+        const lines = [`MCP Servers (${connected.length} connected):`, ""];
+        for (const name of connected) {
+            const entry = servers.find((s) => s.name === name);
+            if (!entry) {
+                lines.push(`  ${name.padEnd(20)}  unknown  —`);
+                continue;
+            }
+            const normalized = normalizeMcpConfig(entry, process.env);
+            if (normalized.kind === "error") {
+                lines.push(`  ${name.padEnd(20)}  error    ${normalized.message}`);
+                continue;
+            }
+            const kind = normalized.cfg.type;
+            const status = await getAuthStatus(normalized.cfg, storageDir);
+            let statusText;
+            switch (status) {
+                case "n/a":
+                    statusText = "—";
+                    break;
+                case "none":
+                    statusText = "not authenticated";
+                    break;
+                case "authenticated":
+                    statusText = "authenticated";
+                    break;
+                case "expired":
+                    statusText = "expired (re-authenticate with /mcp-login)";
+                    break;
+            }
+            lines.push(`  ${name.padEnd(20)}  ${kind.padEnd(6)}  ${statusText}`);
         }
-        lines.push("\nRun /mcp-registry to browse and add more servers.");
+        lines.push("");
+        lines.push("Run /mcp-registry to browse and add more servers.");
         return { output: lines.join("\n"), handled: true };
     });
     register("mcp-registry", "Browse and add MCP servers from the curated registry", (args) => {
@@ -426,6 +462,12 @@ export function registerInfoCommands(register, getCommandMap) {
         }
         return { output: `Found ${results.length} servers:\n\n${formatRegistry(results)}`, handled: true };
     });
+    register("mcp-login", "Authenticate to a remote MCP server via OAuth", async (args) => {
+        return mcpLoginHandler(args);
+    });
+    register("mcp-logout", "Wipe local OAuth tokens for an MCP server", async (args) => {
+        return mcpLogoutHandler(args);
+    });
     register("init", "Initialize project with .oh/ config", () => {
         const ohDir = join(process.cwd(), ".oh");
         if (existsSync(ohDir)) {

package/dist/commands/mcp-auth.d.ts

@@ -0,0 +1,11 @@
+export type CommandResult = {
+    output: string;
+    handled: true;
+};
+export declare function mcpLogoutHandler(name: string, opts?: {
+    storageDir?: string;
+}): Promise<CommandResult>;
+export declare function mcpLoginHandler(name: string, opts?: {
+    storageDir?: string;
+}): Promise<CommandResult>;
+//# sourceMappingURL=mcp-auth.d.ts.map

package/dist/commands/mcp-auth.js

@@ -0,0 +1,57 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readOhConfig } from "../harness/config.js";
+import { McpClient } from "../mcp/client.js";
+import { normalizeMcpConfig } from "../mcp/config-normalize.js";
+import { clearTokens } from "../mcp/oauth.js";
+import { loadCredentials } from "../mcp/oauth-storage.js";
+function defaultStorageDir() {
+    return join(homedir(), ".oh", "credentials", "mcp");
+}
+export async function mcpLogoutHandler(name, opts = {}) {
+    const storageDir = opts.storageDir ?? defaultStorageDir();
+    const trimmed = name.trim();
+    if (!trimmed) {
+        return { output: "Usage: /mcp-logout <server-name>", handled: true };
+    }
+    const existing = await loadCredentials(storageDir, trimmed);
+    if (!existing) {
+        return { output: `No credentials stored for '${trimmed}'.`, handled: true };
+    }
+    await clearTokens(storageDir, trimmed);
+    return {
+        output: `Local token for '${trimmed}' wiped. Server-side session may remain valid until expiry.`,
+        handled: true,
+    };
+}
+export async function mcpLoginHandler(name, opts = {}) {
+    const storageDir = opts.storageDir ?? defaultStorageDir();
+    const trimmed = name.trim();
+    if (!trimmed) {
+        return { output: "Usage: /mcp-login <server-name>", handled: true };
+    }
+    const cfg = readOhConfig();
+    const servers = cfg?.mcpServers ?? [];
+    const entry = servers.find((s) => s.name === trimmed);
+    if (!entry) {
+        return { output: `No MCP server named '${trimmed}' in .oh/config.yaml.`, handled: true };
+    }
+    const normalized = normalizeMcpConfig(entry, process.env);
+    if (normalized.kind === "error") {
+        return { output: `Invalid config for '${trimmed}': ${normalized.message}`, handled: true };
+    }
+    if (normalized.cfg.type === "stdio") {
+        return { output: `Server '${trimmed}' is stdio; OAuth is not applicable.`, handled: true };
+    }
+    await clearTokens(storageDir, trimmed);
+    try {
+        const client = await McpClient.connect(entry, { storageDir });
+        client.disconnect();
+        return { output: `\u2713 Authenticated to '${trimmed}'.`, handled: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { output: `Authentication failed for '${trimmed}': ${msg}`, handled: true };
+    }
+}
+//# sourceMappingURL=mcp-auth.js.map

package/dist/commands/types.d.ts

@@ -22,7 +22,7 @@ export type CommandResult = {
     /** If set, toggle fast mode */
     toggleFastMode?: boolean;
 };
-export type CommandHandler = (args: string, context: CommandContext) => CommandResult;
+export type CommandHandler = (args: string, context: CommandContext) => CommandResult | Promise<CommandResult>;
 export type CommandContext = {
     messages: Message[];
     model: string;

package/dist/components/REPL.js

@@ -405,8 +405,14 @@ export default function REPL({ provider, tools, permissionMode, systemPrompt, mo
                 totalOutputTokens: costRef.current.totalOutputTokens,
                 sessionId,
             };
-            const result = processSlashCommand(trimmed, ctx);
-            if (result) {
+            void processSlashCommand(trimmed, ctx).then((result) => {
+                if (!result) {
+                    const userMsg = createUserMessage(input);
+                    setMessages((prev) => [...prev, userMsg]);
+                    pendingPromptRef.current = input;
+                    setSubmitCount((c) => c + 1);
+                    return;
+                }
                 if (result.openCybergotchiSetup) {
                     setShowCybergotchiSetup(true);
                     return;
@@ -446,7 +452,8 @@ export default function REPL({ provider, tools, permissionMode, systemPrompt, mo
                     setSubmitCount((c) => c + 1);
                     return;
                 }
-            }
+            });
+            return;
         }
         const userMsg = createUserMessage(input);
         setMessages((prev) => [...prev, userMsg]);

package/dist/harness/config.d.ts

@@ -17,11 +17,13 @@ export type McpHttpConfig = McpCommonConfig & {
     type: "http";
     url: string;
     headers?: Record<string, string>;
+    auth?: "oauth" | "none";
 };
 export type McpSseConfig = McpCommonConfig & {
     type: "sse";
     url: string;
     headers?: Record<string, string>;
+    auth?: "oauth" | "none";
 };
 export type McpServerConfig = McpStdioConfig | McpHttpConfig | McpSseConfig;
 export type HookDef = {

package/dist/harness/submit-handler.js

@@ -58,7 +58,7 @@ export async function handleUserInput(input, ctx) {
             totalOutputTokens: ctx.cost.totalOutputTokens,
             sessionId: ctx.sessionId,
         };
-        const result = processSlashCommand(trimmed, cmdCtx);
+        const result = await processSlashCommand(trimmed, cmdCtx);
         if (result) {
             if (result.clearMessages)
                 messages = [];

package/dist/mcp/client.d.ts

@@ -16,7 +16,11 @@ export declare class McpClient {
     private timeoutMs;
     private reconnectImpl;
     private constructor();
-    static connect(cfg: McpServerConfig, timeoutMs?: number): Promise<McpClient>;
+    static connect(cfg: McpServerConfig, timeoutMsOrOpts?: number | {
+        timeoutMs?: number;
+        openFn?: (url: string) => Promise<void>;
+        storageDir?: string;
+    } | undefined): Promise<McpClient>;
     /** Test-only constructor. Not exported from the package's public API. */
     static _forTesting(opts: ForTestingOptions): McpClient;
     private defaultReconnect;

package/dist/mcp/client.js

@@ -1,5 +1,12 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import open from "open";
 import { normalizeMcpConfig } from "./config-normalize.js";
+import { buildAuthProvider } from "./oauth.js";
 import { buildClient, connectWithFallback } from "./transport.js";
+function credentialsDir() {
+    return join(homedir(), ".oh", "credentials", "mcp");
+}
 const DEFAULT_TIMEOUT_MS = 5_000;
 export class McpClient {
     name;
@@ -19,13 +26,29 @@ export class McpClient {
             this.instructions = instr;
         }
     }
-    static async connect(cfg, timeoutMs = cfg.timeout ?? DEFAULT_TIMEOUT_MS) {
+    static async connect(cfg, timeoutMsOrOpts = undefined) {
+        // Backward-compatible: accept number for timeout OR options object
+        const opts = typeof timeoutMsOrOpts === "number" ? { timeoutMs: timeoutMsOrOpts } : (timeoutMsOrOpts ?? {});
+        const timeoutMs = opts.timeoutMs ?? cfg.timeout ?? DEFAULT_TIMEOUT_MS;
+        const openFn = opts.openFn ??
+            (async (url) => {
+                await open(url);
+            });
+        const storageDirResolved = opts.storageDir ?? credentialsDir();
         const normalized = normalizeMcpConfig(cfg, process.env);
         if (normalized.kind === "error") {
             throw new Error(normalized.message);
         }
-        const sdk = await connectWithFallback(normalized.cfg, (c) => buildClient(c));
-        return new McpClient(cfg.name, cfg, sdk, timeoutMs);
+        const authProvider = buildAuthProvider(normalized.cfg, storageDirResolved, openFn);
+        if (authProvider)
+            await authProvider.ready();
+        try {
+            const sdk = await connectWithFallback(normalized.cfg, (c) => buildClient(c, { authProvider }));
+            return new McpClient(cfg.name, cfg, sdk, timeoutMs);
+        }
+        finally {
+            authProvider?.close();
+        }
     }
     /** Test-only constructor. Not exported from the package's public API. */
     static _forTesting(opts) {
@@ -35,7 +58,17 @@ export class McpClient {
         const normalized = normalizeMcpConfig(this.cfg, process.env);
         if (normalized.kind === "error")
             throw new Error(normalized.message);
-        return connectWithFallback(normalized.cfg, (c) => buildClient(c));
+        const authProvider = buildAuthProvider(normalized.cfg, credentialsDir(), async (url) => {
+            await open(url);
+        });
+        if (authProvider)
+            await authProvider.ready();
+        try {
+            return await connectWithFallback(normalized.cfg, (c) => buildClient(c, { authProvider }));
+        }
+        finally {
+            authProvider?.close();
+        }
     }
     async listTools() {
         const res = await this.sdk.listTools();

package/dist/mcp/oauth-storage.d.ts

@@ -0,0 +1,23 @@
+export type OhCredentials = {
+    issuerUrl: string;
+    clientInformation: {
+        client_id: string;
+        client_secret?: string;
+    } & Record<string, unknown>;
+    tokens: {
+        access_token: string;
+        refresh_token?: string;
+        expires_at?: number;
+        token_type?: string;
+        scope?: string;
+    };
+    codeVerifier?: string;
+    updatedAt: string;
+};
+/** Atomically write credentials for one server. Creates the directory with 0o700 on first use. */
+export declare function saveCredentials(storageDir: string, name: string, creds: OhCredentials): Promise<void>;
+/** Load credentials. Returns undefined on missing file OR corrupt JSON. Warns on world/group-readable mode. */
+export declare function loadCredentials(storageDir: string, name: string): Promise<OhCredentials | undefined>;
+/** Idempotent delete — ENOENT is swallowed. */
+export declare function deleteCredentials(storageDir: string, name: string): Promise<void>;
+//# sourceMappingURL=oauth-storage.d.ts.map

package/dist/mcp/oauth-storage.js

@@ -0,0 +1,58 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+function pathFor(storageDir, name) {
+    return join(storageDir, `${name}.json`);
+}
+/** Atomically write credentials for one server. Creates the directory with 0o700 on first use. */
+export async function saveCredentials(storageDir, name, creds) {
+    const filePath = pathFor(storageDir, name);
+    const tmpPath = `${filePath}.tmp`;
+    await fs.mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
+    const body = JSON.stringify(creds, null, 2);
+    await fs.writeFile(tmpPath, body, { mode: 0o600 });
+    await fs.rename(tmpPath, filePath);
+}
+/** Load credentials. Returns undefined on missing file OR corrupt JSON. Warns on world/group-readable mode. */
+export async function loadCredentials(storageDir, name) {
+    const filePath = pathFor(storageDir, name);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    try {
+        if (process.platform !== "win32") {
+            const s = await fs.stat(filePath);
+            if ((s.mode & 0o077) !== 0) {
+                console.warn(`[mcp] credentials file for '${name}' is world/group-readable; run 'chmod 600 ${filePath}'`);
+            }
+        }
+    }
+    catch {
+        // stat failure is non-fatal for load
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        console.warn(`[mcp] credentials file for '${name}' is corrupt; ignoring`);
+        return undefined;
+    }
+}
+/** Idempotent delete — ENOENT is swallowed. */
+export async function deleteCredentials(storageDir, name) {
+    const filePath = pathFor(storageDir, name);
+    try {
+        await fs.unlink(filePath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
+//# sourceMappingURL=oauth-storage.js.map

package/dist/mcp/oauth.d.ts

@@ -0,0 +1,79 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { NormalizedConfig } from "./config-normalize.js";
+/** Thrown when the OAuth callback flow fails — user cancelled, timeout, state mismatch, etc. */
+export declare class OAuthFlowError extends Error {
+    readonly serverName: string;
+    constructor(serverName: string, reason: string);
+}
+export type OAuthCallbackResult = {
+    code: string;
+    state: string;
+};
+export type PendingCallback = {
+    /** The full redirect URI clients should be sent to. */
+    readonly redirectUri: string;
+    /** Resolves with the captured code+state; rejects on timeout or close. */
+    readonly done: Promise<OAuthCallbackResult>;
+    /** Close the listener immediately. Idempotent. */
+    close: () => void;
+};
+/**
+ * Bind a single-shot HTTP listener on 127.0.0.1 to receive the OAuth redirect.
+ * Returns after the server has bound (so redirectUri is available synchronously on the result).
+ * The `done` promise resolves when a valid /oauth/callback arrives, or rejects on timeout/close.
+ */
+export declare function awaitOAuthCallback(opts: {
+    timeoutMs: number;
+}): Promise<PendingCallback>;
+/** Strip access_token=, refresh_token=, and "Bearer <x>" from a log message. */
+export declare function redactToken(msg: string): string;
+export type OhOAuthProviderOptions = {
+    name: string;
+    storageDir: string;
+    /** Browser launch hook — injected for tests; production wires to `open` from the npm package. */
+    openFn: (url: string) => Promise<void>;
+};
+/**
+ * Implements the SDK's OAuthClientProvider backed by OhCredentials on disk.
+ * Lazily binds the callback listener on ready() (called before the SDK reads redirectUrl).
+ */
+export declare class OhOAuthProvider implements OAuthClientProvider {
+    private readonly name;
+    private readonly storageDir;
+    private readonly openFn;
+    private pending;
+    private _redirectUri;
+    private inMemoryCodeVerifier;
+    constructor(opts: OhOAuthProviderOptions);
+    /** Bind the callback listener and prepare redirectUri. Call before first SDK access. */
+    ready(): Promise<void>;
+    /** Release the callback listener (no-op if already resolved/closed). */
+    close(): void;
+    get redirectUrl(): string | URL | undefined;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(info: OAuthClientInformationMixed): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    redirectToAuthorization(url: URL): Promise<void>;
+    saveCodeVerifier(verifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    /** Await a resolved callback from the listener bound in ready(). */
+    awaitCallback(): Promise<OAuthCallbackResult>;
+    private emptyCreds;
+}
+export type AuthStatus = "n/a" | "none" | "authenticated" | "expired";
+/**
+ * Construct an OAuth provider for a normalized config, iff:
+ * - type is http or sse
+ * - no static headers.Authorization
+ * - auth !== "none"
+ * Otherwise return undefined — the transport proceeds without OAuth.
+ */
+export declare function buildAuthProvider(cfg: NormalizedConfig, storageDir: string, openFn: (url: string) => Promise<void>): OhOAuthProvider | undefined;
+/** Delete stored credentials for a server. Safe to call when none exist. */
+export declare function clearTokens(storageDir: string, name: string): Promise<void>;
+/** Compute auth state for a server for /mcp display. */
+export declare function getAuthStatus(cfg: NormalizedConfig, storageDir: string): Promise<AuthStatus>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/mcp/oauth.js

@@ -0,0 +1,257 @@
+import { createServer } from "node:http";
+import { deleteCredentials, loadCredentials, saveCredentials } from "./oauth-storage.js";
+/** Thrown when the OAuth callback flow fails — user cancelled, timeout, state mismatch, etc. */
+export class OAuthFlowError extends Error {
+    serverName;
+    constructor(serverName, reason) {
+        super(`OAuth flow for '${serverName}' failed: ${reason}`);
+        this.name = "OAuthFlowError";
+        this.serverName = serverName;
+    }
+}
+const SUCCESS_HTML = `<!doctype html><html><body style="font-family: system-ui; padding: 2rem">
+<h2>Authorization complete</h2>
+<p>You can close this tab and return to openHarness.</p>
+</body></html>`;
+/**
+ * Bind a single-shot HTTP listener on 127.0.0.1 to receive the OAuth redirect.
+ * Returns after the server has bound (so redirectUri is available synchronously on the result).
+ * The `done` promise resolves when a valid /oauth/callback arrives, or rejects on timeout/close.
+ */
+export async function awaitOAuthCallback(opts) {
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once("listening", () => resolve());
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1");
+    });
+    const addr = server.address();
+    const redirectUri = `http://127.0.0.1:${addr.port}/oauth/callback`;
+    let closed = false;
+    let timer = null;
+    let resolveResult;
+    let rejectResult;
+    const done = new Promise((res, rej) => {
+        resolveResult = res;
+        rejectResult = rej;
+    });
+    function cleanup() {
+        if (closed)
+            return;
+        closed = true;
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        server.close();
+    }
+    server.on("request", (req, res) => {
+        const host = req.headers.host ?? "";
+        if (!host.startsWith("127.0.0.1:")) {
+            res.statusCode = 403;
+            res.end("forbidden");
+            return;
+        }
+        const url = new URL(req.url ?? "/", `http://${host}`);
+        if (req.method !== "GET" || url.pathname !== "/oauth/callback") {
+            res.statusCode = 404;
+            res.end("not found");
+            return;
+        }
+        const code = url.searchParams.get("code") ?? "";
+        const state = url.searchParams.get("state") ?? "";
+        res.statusCode = 200;
+        res.setHeader("content-type", "text/html; charset=utf-8");
+        res.end(SUCCESS_HTML, () => {
+            cleanup();
+            resolveResult({ code, state });
+        });
+    });
+    timer = setTimeout(() => {
+        cleanup();
+        rejectResult(new Error(`OAuth callback timeout after ${opts.timeoutMs}ms`));
+    }, opts.timeoutMs);
+    return {
+        redirectUri,
+        done,
+        close: () => {
+            if (closed)
+                return;
+            cleanup();
+            rejectResult(new Error("OAuth callback closed before completion"));
+        },
+    };
+}
+/** Strip access_token=, refresh_token=, and "Bearer <x>" from a log message. */
+export function redactToken(msg) {
+    return msg
+        .replace(/(access_token|refresh_token|code)=[^&\s"']+/gi, "$1=<redacted>")
+        .replace(/Bearer\s+[^\s"']+/gi, "Bearer <redacted>");
+}
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1_000;
+/**
+ * Implements the SDK's OAuthClientProvider backed by OhCredentials on disk.
+ * Lazily binds the callback listener on ready() (called before the SDK reads redirectUrl).
+ */
+export class OhOAuthProvider {
+    name;
+    storageDir;
+    openFn;
+    pending = null;
+    _redirectUri = null;
+    inMemoryCodeVerifier = null;
+    constructor(opts) {
+        this.name = opts.name;
+        this.storageDir = opts.storageDir;
+        this.openFn = opts.openFn;
+    }
+    /** Bind the callback listener and prepare redirectUri. Call before first SDK access. */
+    async ready() {
+        if (this.pending)
+            return;
+        this.pending = await awaitOAuthCallback({ timeoutMs: CALLBACK_TIMEOUT_MS });
+        this._redirectUri = this.pending.redirectUri;
+    }
+    /** Release the callback listener (no-op if already resolved/closed). */
+    close() {
+        if (this.pending) {
+            // Attach a no-op catch so the rejected `done` promise doesn't become an unhandled rejection.
+            this.pending.done.catch(() => { });
+            this.pending.close();
+        }
+        this.pending = null;
+        this._redirectUri = null;
+    }
+    get redirectUrl() {
+        return this._redirectUri ?? undefined;
+    }
+    get clientMetadata() {
+        return {
+            client_name: "openharness",
+            redirect_uris: this._redirectUri ? [this._redirectUri] : [],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        };
+    }
+    async clientInformation() {
+        const creds = await loadCredentials(this.storageDir, this.name);
+        return creds?.clientInformation;
+    }
+    async saveClientInformation(info) {
+        const creds = (await loadCredentials(this.storageDir, this.name)) ?? this.emptyCreds();
+        creds.clientInformation = info;
+        creds.updatedAt = new Date().toISOString();
+        await saveCredentials(this.storageDir, this.name, creds);
+    }
+    async tokens() {
+        const creds = await loadCredentials(this.storageDir, this.name);
+        if (!creds?.tokens?.access_token)
+            return undefined;
+        return {
+            access_token: creds.tokens.access_token,
+            refresh_token: creds.tokens.refresh_token,
+            token_type: creds.tokens.token_type ?? "Bearer",
+            scope: creds.tokens.scope,
+            expires_in: creds.tokens.expires_at && creds.tokens.expires_at > Date.now()
+                ? Math.floor((creds.tokens.expires_at - Date.now()) / 1000)
+                : 0,
+        };
+    }
+    async saveTokens(tokens) {
+        const creds = (await loadCredentials(this.storageDir, this.name)) ?? this.emptyCreds();
+        creds.tokens = {
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            token_type: tokens.token_type ?? "Bearer",
+            scope: tokens.scope,
+            expires_at: tokens.expires_in ? Date.now() + Number(tokens.expires_in) * 1000 : undefined,
+        };
+        creds.codeVerifier = undefined;
+        this.inMemoryCodeVerifier = null;
+        creds.updatedAt = new Date().toISOString();
+        await saveCredentials(this.storageDir, this.name, creds);
+    }
+    async redirectToAuthorization(url) {
+        const urlStr = url.toString();
+        try {
+            await this.openFn(urlStr);
+            console.warn(`[mcp] ${this.name}: opened browser for OAuth authorization. Waiting for callback...`);
+        }
+        catch (_err) {
+            console.warn(`[mcp] ${this.name}: could not open browser automatically. Please open this URL manually:\n  ${urlStr}`);
+            // Don't re-throw — the listener may still receive the callback if the user opens the URL by hand.
+        }
+    }
+    async saveCodeVerifier(verifier) {
+        this.inMemoryCodeVerifier = verifier;
+        const creds = (await loadCredentials(this.storageDir, this.name)) ?? this.emptyCreds();
+        creds.codeVerifier = verifier;
+        creds.updatedAt = new Date().toISOString();
+        await saveCredentials(this.storageDir, this.name, creds);
+    }
+    async codeVerifier() {
+        if (this.inMemoryCodeVerifier)
+            return this.inMemoryCodeVerifier;
+        const creds = await loadCredentials(this.storageDir, this.name);
+        if (!creds?.codeVerifier) {
+            throw new Error(`no code verifier saved for '${this.name}'`);
+        }
+        return creds.codeVerifier;
+    }
+    /** Await a resolved callback from the listener bound in ready(). */
+    async awaitCallback() {
+        if (!this.pending)
+            throw new Error("awaitCallback called before ready()");
+        try {
+            return await this.pending.done;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new OAuthFlowError(this.name, msg);
+        }
+    }
+    emptyCreds() {
+        return {
+            issuerUrl: "",
+            clientInformation: { client_id: "" },
+            tokens: { access_token: "" },
+            updatedAt: new Date().toISOString(),
+        };
+    }
+}
+/**
+ * Construct an OAuth provider for a normalized config, iff:
+ * - type is http or sse
+ * - no static headers.Authorization
+ * - auth !== "none"
+ * Otherwise return undefined — the transport proceeds without OAuth.
+ */
+export function buildAuthProvider(cfg, storageDir, openFn) {
+    if (cfg.type === "stdio")
+        return undefined;
+    const headers = cfg.headers;
+    if (headers?.Authorization)
+        return undefined;
+    if (cfg.auth === "none")
+        return undefined;
+    return new OhOAuthProvider({ name: cfg.name, storageDir, openFn });
+}
+/** Delete stored credentials for a server. Safe to call when none exist. */
+export async function clearTokens(storageDir, name) {
+    await deleteCredentials(storageDir, name);
+}
+/** Compute auth state for a server for /mcp display. */
+export async function getAuthStatus(cfg, storageDir) {
+    if (cfg.type === "stdio")
+        return "n/a";
+    const headers = cfg.headers;
+    if (headers?.Authorization)
+        return "n/a";
+    const creds = await loadCredentials(storageDir, cfg.name);
+    if (!creds?.tokens?.access_token)
+        return "none";
+    if (creds.tokens.expires_at && creds.tokens.expires_at <= Date.now())
+        return "expired";
+    return "authenticated";
+}
+//# sourceMappingURL=oauth.js.map

package/dist/mcp/transport.d.ts

@@ -1,3 +1,4 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { NormalizedConfig } from "./config-normalize.js";
@@ -16,11 +17,14 @@ export declare class ProtocolError extends Error {
     readonly cause: unknown;
     constructor(serverName: string, cause: unknown);
 }
+export type BuildTransportOptions = {
+    authProvider?: OAuthClientProvider;
+};
 /**
  * Construct an SDK Transport for a normalized config.
  * Does NOT call .start() — caller (Client.connect) handles that.
  */
-export declare function buildTransport(cfg: NormalizedConfig): Promise<Transport>;
+export declare function buildTransport(cfg: NormalizedConfig, opts?: BuildTransportOptions): Promise<Transport>;
 /**
  * Connect to an MCP server, with auto-fallback from Streamable HTTP to
  * legacy SSE when the config's type was INFERRED from url (not explicit).
@@ -30,9 +34,16 @@ export declare function buildTransport(cfg: NormalizedConfig): Promise<Transport
  * wires it to `buildClient` (Task 7).
  */
 export declare function connectWithFallback<T>(cfg: NormalizedConfig, doConnect: (cfg: NormalizedConfig) => Promise<T>): Promise<T>;
+export type BuildClientOptions = {
+    authProvider?: OAuthClientProvider;
+};
 /**
  * Build a connected SDK Client for a normalized config.
  * Maps connect-time errors into OH's typed error taxonomy.
+ *
+ * When the auth provider exposes `awaitCallback()` (i.e. OhOAuthProvider), this
+ * function handles the full OAuth callback → finishAuth → reconnect loop so callers
+ * don't need to orchestrate it manually.
  */
-export declare function buildClient(cfg: NormalizedConfig): Promise<Client>;
+export declare function buildClient(cfg: NormalizedConfig, opts?: BuildClientOptions): Promise<Client>;
 //# sourceMappingURL=transport.d.ts.map

package/dist/mcp/transport.js

@@ -1,4 +1,5 @@
 import { createRequire } from "node:module";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -9,7 +10,7 @@ export class RemoteAuthRequiredError extends Error {
     wwwAuthenticate;
     constructor(serverName, wwwAuthenticate) {
         super(`MCP server '${serverName}' requires authentication. ` +
-            `Add headers.Authorization to your config (OAuth flow is not yet supported).`);
+            `Add 'auth: oauth' to enable the OAuth 2.1 flow, or set headers.Authorization for a static bearer token.`);
         this.name = "RemoteAuthRequiredError";
         this.serverName = serverName;
         this.wwwAuthenticate = wwwAuthenticate;
@@ -41,7 +42,7 @@ export class ProtocolError extends Error {
  * Construct an SDK Transport for a normalized config.
  * Does NOT call .start() — caller (Client.connect) handles that.
  */
-export async function buildTransport(cfg) {
+export async function buildTransport(cfg, opts = {}) {
     if (cfg.type === "stdio") {
         return new StdioClientTransport({
             command: cfg.command,
@@ -52,11 +53,13 @@ export async function buildTransport(cfg) {
     if (cfg.type === "http") {
         return new StreamableHTTPClientTransport(new URL(cfg.url), {
             requestInit: cfg.headers ? { headers: cfg.headers } : undefined,
+            authProvider: opts.authProvider,
         });
     }
     if (cfg.type === "sse") {
         return new SSEClientTransport(new URL(cfg.url), {
             requestInit: cfg.headers ? { headers: cfg.headers } : undefined,
+            authProvider: opts.authProvider,
         });
     }
     throw new Error(`unknown transport type: ${cfg.type}`);
@@ -112,7 +115,6 @@ export async function connectWithFallback(cfg, doConnect) {
         if (!isFallbackCandidate(err))
             throw err;
         // Log + retry
-        // biome-ignore lint/suspicious/noConsole: user-facing diagnostic
         console.warn(`[mcp] ${cfg.name}: Streamable HTTP failed (${err.message}); trying legacy SSE`);
         const sseCfg = { ...cfg, type: "sse" };
         return await doConnect(sseCfg);
@@ -120,25 +122,87 @@ export async function connectWithFallback(cfg, doConnect) {
 }
 const DEFAULT_TIMEOUT_MS = 5_000;
 const CLIENT_INFO = { name: "openharness", version: pkg.version };
+/** Duck-type check: does this provider expose awaitCallback (our OhOAuthProvider)? */
+function hasAwaitCallback(p) {
+    return typeof p.awaitCallback === "function";
+}
 /**
  * Build a connected SDK Client for a normalized config.
  * Maps connect-time errors into OH's typed error taxonomy.
+ *
+ * When the auth provider exposes `awaitCallback()` (i.e. OhOAuthProvider), this
+ * function handles the full OAuth callback → finishAuth → reconnect loop so callers
+ * don't need to orchestrate it manually.
  */
-export async function buildClient(cfg) {
-    const transport = await buildTransport(cfg);
+export async function buildClient(cfg, opts = {}) {
+    const transport = await buildTransport(cfg, opts);
     const client = new Client(CLIENT_INFO, { capabilities: {} });
     const timeoutMs = cfg.timeout ?? DEFAULT_TIMEOUT_MS;
-    let timer = null;
+    async function tryConnect() {
+        let timer = null;
+        try {
+            await Promise.race([
+                client.connect(transport),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`init timeout after ${timeoutMs}ms`)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== null)
+                clearTimeout(timer);
+        }
+    }
     try {
-        await Promise.race([
-            client.connect(transport),
-            new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`init timeout after ${timeoutMs}ms`)), timeoutMs);
-            }),
-        ]);
+        await tryConnect();
         return client;
     }
     catch (err) {
+        // If the SDK requires a browser-based OAuth flow (UnauthorizedError after REDIRECT),
+        // and our provider knows how to await the callback, complete the loop here.
+        // Per the SDK design, after finishAuth we must create a fresh transport + client
+        // because the original transport is already in a "started" state.
+        if (err instanceof UnauthorizedError && opts.authProvider && hasAwaitCallback(opts.authProvider)) {
+            try {
+                const { code } = await opts.authProvider.awaitCallback();
+                await transport.finishAuth(code);
+                // Close the old transport before constructing a fresh one — the SDK's
+                // Transport is one-shot after an UnauthorizedError; leaving it open leaks
+                // the underlying TCP socket / event stream.
+                try {
+                    await transport.close?.();
+                }
+                catch {
+                    // best-effort
+                }
+                // Build a fresh transport + client for the authenticated retry
+                const freshTransport = await buildTransport(cfg, opts);
+                const freshClient = new Client(CLIENT_INFO, { capabilities: {} });
+                let freshTimer = null;
+                try {
+                    await Promise.race([
+                        freshClient.connect(freshTransport),
+                        new Promise((_, reject) => {
+                            freshTimer = setTimeout(() => reject(new Error(`init timeout after ${timeoutMs}ms`)), timeoutMs);
+                        }),
+                    ]);
+                }
+                finally {
+                    if (freshTimer !== null)
+                        clearTimeout(freshTimer);
+                }
+                return freshClient;
+            }
+            catch (oauthErr) {
+                // Classify the retry error the same way as the primary path
+                if (oauthErr instanceof RemoteAuthRequiredError ||
+                    oauthErr instanceof UnreachableError ||
+                    oauthErr instanceof ProtocolError) {
+                    throw oauthErr;
+                }
+                throw new ProtocolError(cfg.name, oauthErr);
+            }
+        }
         // Leave RemoteAuthRequiredError / UnreachableError / ProtocolError as-is
         if (err instanceof RemoteAuthRequiredError || err instanceof UnreachableError || err instanceof ProtocolError) {
             throw err;
@@ -151,9 +215,5 @@ export async function buildClient(cfg) {
         // Otherwise protocol-shaped
         throw new ProtocolError(cfg.name, err);
     }
-    finally {
-        if (timer !== null)
-            clearTimeout(timer);
-    }
 }
 //# sourceMappingURL=transport.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {
@@ -44,6 +44,7 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "marked": "^17.0.5",
+    "open": "^11.0.0",
     "react": "^18.3.1",
     "yaml": "^2.7.0",
     "zod": "^3.24.0"