pi-mcp-extension 1.7.3 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-extension",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "description": "MCP (Model Context Protocol) client extension for the Pi coding agent — connect Pi to any MCP server",
   "type": "module",
   "keywords": [

package/src/callback-server.ts

@@ -8,6 +8,7 @@
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http";
 import type { Socket } from "net";
 import { URL } from "url";
+import { CallbackUrlValidationError, isLocalCallbackHost, parseCallbackUrl } from "./callback-url.js";
 
 interface PendingAuth {
   resolve: (code: string) => void;
@@ -73,72 +74,52 @@ function escapeHtml(text: string): string {
  * Handle incoming HTTP requests to the callback server.
  */
 function handleRequest(req: IncomingMessage, res: ServerResponse): void {
-  const url = new URL(req.url || "/", "http://localhost");
-
-  // Only handle the callback path
-  if (url.pathname !== CALLBACK_PATH) {
-    res.writeHead(404, { "Content-Type": "text/plain", "Connection": "close" });
-    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");
-
-  // Enforce state parameter presence for CSRF protection
-  if (!state) {
-    const errorMsg = "Missing required state parameter - potential CSRF attack";
+  let parsed: ReturnType<typeof parseCallbackUrl>;
+  try {
+    const requestUrl = new URL(req.url || "/", "http://localhost").toString();
+    parsed = parseCallbackUrl(requestUrl, {
+      expectedState: (state) => pendingAuths.has(state),
+    });
+  } catch (err) {
+    if (err instanceof CallbackUrlValidationError) {
+      if (err.reason === "wrong_path") {
+        res.writeHead(404, { "Content-Type": "text/plain", "Connection": "close" });
+        res.end("Not found");
+        return;
+      }
+      res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
+      res.end(HTML_ERROR(err.message));
+      return;
+    }
     res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
-    res.end(HTML_ERROR(errorMsg));
+    res.end(HTML_ERROR("Invalid callback request"));
     return;
   }
 
   // Handle OAuth errors
-  if (error) {
-    const errorMsg = errorDescription || error;
+  if ("error" in parsed) {
     res.writeHead(200, { "Content-Type": "text/html", "Connection": "close" });
-    res.end(HTML_ERROR(errorMsg));
-    if (pendingAuths.has(state)) {
-      const pending = pendingAuths.get(state)!;
+    res.end(HTML_ERROR(parsed.error));
+    if (pendingAuths.has(parsed.state)) {
+      const pending = pendingAuths.get(parsed.state)!;
       clearTimeout(pending.timeout);
-      pendingAuths.delete(state);
-      setTimeout(() => pending.reject(new Error(errorMsg)), 0);
+      pendingAuths.delete(parsed.state);
+      setTimeout(() => pending.reject(new Error(parsed.error)), 0);
     }
     return;
   }
 
-  // Require authorization code
-  if (!code) {
-    res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
-    res.end(HTML_ERROR("No authorization code provided"));
-    return;
-  }
-
-  // Validate state parameter
-  if (!pendingAuths.has(state)) {
-    const errorMsg = "Invalid or expired state parameter - potential CSRF attack";
-    res.writeHead(400, { "Content-Type": "text/html", "Connection": "close" });
-    res.end(HTML_ERROR(errorMsg));
-    return;
-  }
-
-  const pending = pendingAuths.get(state)!;
+  const pending = pendingAuths.get(parsed.state)!;
 
   // Clear timeout and resolve the pending promise
   clearTimeout(pending.timeout);
-  pendingAuths.delete(state);
-  pending.resolve(code);
+  pendingAuths.delete(parsed.state);
+  pending.resolve(parsed.code);
 
   res.writeHead(200, { "Content-Type": "text/html", "Connection": "close" });
   res.end(HTML_SUCCESS);
 }
 
-function isLocalCallbackHost(hostname: string): boolean {
-  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
-}
-
 async function closeCurrentServer(): Promise<void> {
   if (!server) return;
 

package/src/callback-url.ts

@@ -0,0 +1,136 @@
+/**
+ * Pure URL validation and parsing helpers for MCP OAuth authorization and callbacks.
+ */
+
+export type CallbackUrlValidationReason =
+  | "invalid_url"
+  | "wrong_origin"
+  | "wrong_path"
+  | "missing_state"
+  | "invalid_state"
+  | "missing_code";
+
+export class CallbackUrlValidationError extends Error {
+  readonly reason: CallbackUrlValidationReason;
+
+  constructor(reason: CallbackUrlValidationReason, message: string) {
+    super(message);
+    this.name = "CallbackUrlValidationError";
+    this.reason = reason;
+  }
+}
+
+export interface ParseCallbackUrlOptions {
+  redirectUrl?: string | URL | undefined;
+  expectedState?: string | ((state: string) => boolean) | undefined;
+}
+
+export function isLocalCallbackHost(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "::1" ||
+    hostname === "[::1]"
+  );
+}
+
+/**
+ * Validate that an OAuth authorization URL is safe to pass to a system browser opener.
+ * Only allows `https:` URLs or loopback `http:` URLs (`localhost`, `127.0.0.1`, `::1`, `[::1]`).
+ */
+export function isSafeAuthorizationUrl(input: string | URL): boolean {
+  let url: URL;
+  try {
+    url = input instanceof URL ? input : new URL(input);
+  } catch {
+    return false;
+  }
+
+  if (url.protocol === "https:") {
+    return true;
+  }
+
+  if (url.protocol === "http:" && isLocalCallbackHost(url.hostname)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Parse and validate an OAuth callback URL (either from an incoming HTTP callback request
+ * or from a user-pasted redirect URL).
+ */
+export function parseCallbackUrl(
+  input: string,
+  options: ParseCallbackUrlOptions = {},
+): { state: string; code: string } | { state: string; error: string } {
+  const trimmed = input.trim();
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new CallbackUrlValidationError("invalid_url", "Invalid redirect URL");
+  }
+
+  if (options.redirectUrl !== undefined) {
+    const expected =
+      options.redirectUrl instanceof URL
+        ? options.redirectUrl
+        : new URL(String(options.redirectUrl));
+    if (
+      url.protocol !== expected.protocol ||
+      url.hostname !== expected.hostname ||
+      url.port !== expected.port
+    ) {
+      throw new CallbackUrlValidationError(
+        "wrong_origin",
+        `Redirect URL origin must match ${expected.origin}`,
+      );
+    }
+    if (url.pathname !== expected.pathname) {
+      throw new CallbackUrlValidationError(
+        "wrong_path",
+        `Redirect URL path must be ${expected.pathname}`,
+      );
+    }
+  } else if (url.pathname !== "/callback") {
+    throw new CallbackUrlValidationError("wrong_path", "Redirect URL path must be /callback");
+  }
+
+  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 (!state) {
+    throw new CallbackUrlValidationError(
+      "missing_state",
+      "Missing required state parameter - potential CSRF attack",
+    );
+  }
+
+  if (typeof options.expectedState === "string" && state !== options.expectedState) {
+    throw new CallbackUrlValidationError(
+      "invalid_state",
+      "Invalid or expired state parameter - potential CSRF attack",
+    );
+  }
+
+  if (error) {
+    return { state, error: errorDescription || error };
+  }
+
+  if (!code) {
+    throw new CallbackUrlValidationError("missing_code", "No authorization code provided");
+  }
+
+  if (typeof options.expectedState === "function" && !options.expectedState(state)) {
+    throw new CallbackUrlValidationError(
+      "invalid_state",
+      "Invalid or expired state parameter - potential CSRF attack",
+    );
+  }
+
+  return { state, code };
+}

package/src/index.ts

@@ -24,6 +24,7 @@ import {
   stopCallbackServer,
   callbackServerConfigFromRedirectUrl,
 } from "./callback-server.js";
+import { CallbackUrlValidationError, isSafeAuthorizationUrl, parseCallbackUrl } from "./callback-url.js";
 import { setCallbackPort, McpOAuthProvider, acquireAuthLock, type AuthLockHandle } from "./oauth-provider.js";
 import { auth } from "@modelcontextprotocol/sdk/client/auth.js";
 import { discoverManualAuthChallenge } from "./auth-challenge.js";
@@ -48,19 +49,25 @@ export function browserOpenCommand(url: string): BrowserOpenCommand {
  * Open a URL in the user's default browser.
  * Works on macOS, Linux, and Windows.
  */
-function openBrowser(url: string): void {
-  const { command, args } = browserOpenCommand(url);
-  const child = spawn(command, args, {
-    detached: true,
-    stdio: "ignore",
-    windowsHide: true,
-  });
+function openBrowser(url: string): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    const { command, args } = browserOpenCommand(url);
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
 
-  child.once("error", (err) => {
-    console.error(`[pi-mcp] Failed to open browser: ${err.message}`);
-  });
+    child.once("error", (err) => {
+      console.error(`[pi-mcp] Failed to open browser: ${err.message}`);
+      reject(err);
+    });
 
-  child.unref();
+    child.once("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
 }
 
 export class AuthCancelledError extends Error {
@@ -71,6 +78,7 @@ export class AuthCancelledError extends Error {
 }
 
 export const authRetryOption = "Retry: open browser again";
+export const authPasteOption = "Paste redirect URL";
 export const authCancelOption = "Cancel authentication";
 
 interface OAuthCallbackResult {
@@ -92,19 +100,35 @@ interface OAuthDialogAbortedResult {
   type: "dialogAborted";
 }
 
+interface OAuthUserInputResult {
+  type: "input";
+  value: string | undefined;
+}
+
 type OAuthWaitResult = OAuthCallbackResult | OAuthCallbackErrorResult | OAuthUserChoiceResult | OAuthDialogAbortedResult;
+type OAuthInputWaitResult = OAuthCallbackResult | OAuthCallbackErrorResult | OAuthUserInputResult | OAuthDialogAbortedResult;
+
+export interface OAuthPasteOptions {
+  redirectUrl?: string | URL | undefined;
+  expectedState?: string | undefined;
+  onPasteResolved?: (() => void) | undefined;
+}
 
 export async function waitForOAuthCallback(
   serverName: string,
   callbackPromise: Promise<string>,
-  reopenBrowser: () => void,
-  context: { hasUI: boolean; ui: Pick<ExtensionUIContext, "select"> },
+  reopenBrowser: () => void | Promise<void>,
+  context: {
+    hasUI: boolean;
+    ui: Pick<ExtensionUIContext, "select"> & Partial<Pick<ExtensionUIContext, "input" | "notify">>;
+  },
+  pasteOptions?: OAuthPasteOptions,
 ): Promise<string> {
   if (!context.hasUI) {
     throw new Error(`Authorization for ${serverName} requires an interactive Pi session`);
   }
 
-  const callbackResultPromise: Promise<OAuthWaitResult> = callbackPromise
+  const callbackResultPromise: Promise<OAuthCallbackResult | OAuthCallbackErrorResult> = callbackPromise
     .then((code): OAuthCallbackResult => ({ type: "callback", code }))
     .catch((error): OAuthCallbackErrorResult => ({ type: "callbackError", error }));
 
@@ -113,7 +137,7 @@ export async function waitForOAuthCallback(
     const choicePromise: Promise<OAuthWaitResult> = context.ui
       .select(
         `OAuth pending for ${serverName}`,
-        [authRetryOption, authCancelOption],
+        [authRetryOption, authPasteOption, authCancelOption],
         { signal: dialogAbortController.signal },
       )
       .then((choice): OAuthUserChoiceResult => ({ type: "choice", choice }))
@@ -141,10 +165,66 @@ export async function waitForOAuthCallback(
     }
 
     if (result.choice === authRetryOption) {
-      reopenBrowser();
+      await reopenBrowser();
       continue;
     }
 
+    if (result.choice === authPasteOption) {
+      if (!context.ui.input) {
+        continue;
+      }
+      const inputAbortController = new AbortController();
+      const inputPromise: Promise<OAuthInputWaitResult> = context.ui
+        .input(
+          `Paste redirect URL for ${serverName}`,
+          "http://127.0.0.1:19876/callback?code=...&state=...",
+          { signal: inputAbortController.signal },
+        )
+        .then((value): OAuthUserInputResult => ({ type: "input", value }))
+        .catch((error): OAuthDialogAbortedResult => {
+          if (inputAbortController.signal.aborted) {
+            return { type: "dialogAborted" };
+          }
+          throw error;
+        });
+
+      const inputResult = await Promise.race([callbackResultPromise, inputPromise]);
+
+      if (inputResult.type === "callback") {
+        inputAbortController.abort();
+        return inputResult.code;
+      }
+
+      if (inputResult.type === "callbackError") {
+        inputAbortController.abort();
+        throw inputResult.error;
+      }
+
+      if (inputResult.type === "dialogAborted" || !inputResult.value?.trim()) {
+        continue;
+      }
+
+      let parsed: ReturnType<typeof parseCallbackUrl>;
+      try {
+        parsed = parseCallbackUrl(inputResult.value, {
+          redirectUrl: pasteOptions?.redirectUrl,
+          expectedState: pasteOptions?.expectedState,
+        });
+      } catch (err) {
+        if (err instanceof CallbackUrlValidationError) {
+          context.ui.notify?.(`pi-mcp: Invalid redirect URL — ${err.message}`, "error");
+          continue;
+        }
+        throw err;
+      }
+
+      pasteOptions?.onPasteResolved?.();
+      if ("error" in parsed) {
+        throw new Error(parsed.error);
+      }
+      return parsed.code;
+    }
+
     dialogAbortController.abort();
     throw new AuthCancelledError(serverName);
   }
@@ -194,7 +274,7 @@ export function serverNameCompletions(
   return completions.length > 0 ? completions : null;
 }
 
-export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string; globalConfigPath?: string; authStorageDir?: string; browserOpen?: (url: string) => void } = {}): Promise<void> {
+export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string; globalConfigPath?: string; authStorageDir?: string; browserOpen?: (url: string) => void | Promise<void> } = {}): Promise<void> {
   // ── 1. Load and validate config ──────────────────────────────────────────
   // cwd is available on the ExtensionContext passed to event handlers.
   // We load config lazily on session_start to get the correct per-session cwd.
@@ -415,13 +495,34 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           .join("");
 
         // 3. Create the auth provider.
+        const launchAuthorizationBrowser = async (url: URL): Promise<void> => {
+          if (!isSafeAuthorizationUrl(url)) {
+            throw new McpError(
+              `Refusing to open unsafe authorization URL for "${serverName}": only HTTPS (or loopback HTTP) URLs are allowed`,
+              serverName,
+              "protocol",
+            );
+          }
+          latestAuthorizationUrl = new URL(url.toString());
+          if (signal.aborted || lockLost) return;
+          try {
+            await (paths.browserOpen ?? openBrowser)(url.toString());
+            ctx.ui.notify(
+              `pi-mcp: Authorize ${serverName}: ${url.toString()} (On SSH, forward the callback with ssh -L ${port}:127.0.0.1:${port}, or choose "${authPasteOption}".)`,
+              "info",
+            );
+          } catch (err) {
+            ctx.ui.notify(
+              `pi-mcp: Failed to open browser for ${serverName} (${err instanceof Error ? err.message : String(err)}). Open ${url.toString()} manually or choose "${authPasteOption}".`,
+              "error",
+            );
+          }
+        };
+
         const authProvider = new McpOAuthProvider(
           serverName,
           config.auth || { type: "oauth" },
-          (url: URL) => {
-            latestAuthorizationUrl = new URL(url.toString());
-            if (!signal.aborted && !lockLost) (paths.browserOpen ?? openBrowser)(url.toString());
-          },
+          launchAuthorizationBrowser,
           paths.authStorageDir,
           false,
           () => signal.aborted,
@@ -474,12 +575,6 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
           // Auth succeeded without needing browser interaction (e.g., had valid tokens).
           ctx.ui.notify(`pi-mcp: ${serverName} authenticated successfully. Starting MCP server...`, "info");
         } else if (authResult === "REDIRECT") {
-          // Browser was opened, wait for the callback from the user
-          ctx.ui.notify(
-            `pi-mcp: Browser opened for ${serverName}. Complete authorization to continue. Choose Retry to reopen the browser or Cancel to stop authentication.`,
-            "info",
-          );
-
           // 7. Wait for the callback while giving the user an escape hatch.
           const code = await waitForOAuthCallback(
             serverName,
@@ -492,9 +587,14 @@ export default async function (pi: ExtensionAPI, paths: { bootstrapCwd?: string;
                   "protocol",
                 );
               }
-              if (!signal.aborted && !lockLost) (paths.browserOpen ?? openBrowser)(latestAuthorizationUrl.toString());
+              return launchAuthorizationBrowser(latestAuthorizationUrl);
             },
             ctx,
+            {
+              redirectUrl: authProvider.redirectUrl,
+              expectedState: oauthState,
+              onPasteResolved: cancel,
+            },
           );
           if (signal.aborted) throw new AuthCancelledError(serverName);
           if (lockLost) throw new AuthLockError(serverName, `Authorization lock lost for ${serverName}; retry`);