Add Auth debugger tab (#355)

* wip auth debugger

* cleanup types and validation

* more cleanup

* draft test

* wip clean up some

* rm toasts

* consolidate state management

* prettier

* hoist state up to App

* working with quick and guided

* sort out displaying debugger

* prettier

* cleanup types

* fix tests

* cleanup comment

* prettier

* fixup types in tests

* prettier

* refactor debug to avoid toasting

* callback shuffling

* linting

* types

* rm toast in test

* bump typescript sdk version to 0.11.2 for scope parameter passing

* use proper scope handling

* test scope parameter passing

* move functions and s/sseUrl/serverUrl/

* extract status message into component

* refactor progress and steps into components

* fix test

* rename quick handler

* one less click

* last step complete

* add state machine

* test and types

client/src/lib/auth-types.ts

@@ -0,0 +1,38 @@
+import {
+  OAuthMetadata,
+  OAuthClientInformationFull,
+  OAuthClientInformation,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+
+// OAuth flow steps
+export type OAuthStep =
+  | "metadata_discovery"
+  | "client_registration"
+  | "authorization_redirect"
+  | "authorization_code"
+  | "token_request"
+  | "complete";
+
+// Message types for inline feedback
+export type MessageType = "success" | "error" | "info";
+
+export interface StatusMessage {
+  type: MessageType;
+  message: string;
+}
+
+// Single state interface for OAuth state
+export interface AuthDebuggerState {
+  isInitiatingAuth: boolean;
+  oauthTokens: OAuthTokens | null;
+  loading: boolean;
+  oauthStep: OAuthStep;
+  oauthMetadata: OAuthMetadata | null;
+  oauthClientInfo: OAuthClientInformationFull | OAuthClientInformation | null;
+  authorizationUrl: string | null;
+  authorizationCode: string;
+  latestError: Error | null;
+  statusMessage: StatusMessage | null;
+  validationError: string | null;
+}

client/src/lib/auth.ts

@@ -4,11 +4,13 @@ import {
   OAuthClientInformation,
   OAuthTokens,
   OAuthTokensSchema,
+  OAuthClientMetadata,
+  OAuthMetadata,
 } from "@modelcontextprotocol/sdk/shared/auth.js";
 import { SESSION_KEYS, getServerSpecificKey } from "./constants";
 
 export class InspectorOAuthClientProvider implements OAuthClientProvider {
-  constructor(private serverUrl: string) {
+  constructor(public serverUrl: string) {
     // Save the server URL to session storage
     sessionStorage.setItem(SESSION_KEYS.SERVER_URL, serverUrl);
   }
@@ -17,7 +19,7 @@ export class InspectorOAuthClientProvider implements OAuthClientProvider {
     return window.location.origin + "/oauth/callback";
   }
 
-  get clientMetadata() {
+  get clientMetadata(): OAuthClientMetadata {
     return {
       redirect_uris: [this.redirectUrl],
       token_endpoint_auth_method: "none",
@@ -101,3 +103,38 @@ export class InspectorOAuthClientProvider implements OAuthClientProvider {
     );
   }
 }
+
+// Overrides debug URL and allows saving server OAuth metadata to
+// display in debug UI.
+export class DebugInspectorOAuthClientProvider extends InspectorOAuthClientProvider {
+  get redirectUrl(): string {
+    return `${window.location.origin}/oauth/callback/debug`;
+  }
+
+  saveServerMetadata(metadata: OAuthMetadata) {
+    const key = getServerSpecificKey(
+      SESSION_KEYS.SERVER_METADATA,
+      this.serverUrl,
+    );
+    sessionStorage.setItem(key, JSON.stringify(metadata));
+  }
+
+  getServerMetadata(): OAuthMetadata | null {
+    const key = getServerSpecificKey(
+      SESSION_KEYS.SERVER_METADATA,
+      this.serverUrl,
+    );
+    const metadata = sessionStorage.getItem(key);
+    if (!metadata) {
+      return null;
+    }
+    return JSON.parse(metadata);
+  }
+
+  clear() {
+    super.clear();
+    sessionStorage.removeItem(
+      getServerSpecificKey(SESSION_KEYS.SERVER_METADATA, this.serverUrl),
+    );
+  }
+}

client/src/lib/constants.ts

@@ -6,6 +6,7 @@ export const SESSION_KEYS = {
   SERVER_URL: "mcp_server_url",
   TOKENS: "mcp_tokens",
   CLIENT_INFORMATION: "mcp_client_information",
+  SERVER_METADATA: "mcp_server_metadata",
 } as const;
 
 // Generate server-specific session storage keys

client/src/lib/oauth-state-machine.ts

@@ -0,0 +1,181 @@
+import { OAuthStep, AuthDebuggerState } from "./auth-types";
+import { DebugInspectorOAuthClientProvider } from "./auth";
+import {
+  discoverOAuthMetadata,
+  registerClient,
+  startAuthorization,
+  exchangeAuthorization,
+} from "@modelcontextprotocol/sdk/client/auth.js";
+import { OAuthMetadataSchema } from "@modelcontextprotocol/sdk/shared/auth.js";
+
+export interface StateMachineContext {
+  state: AuthDebuggerState;
+  serverUrl: string;
+  provider: DebugInspectorOAuthClientProvider;
+  updateState: (updates: Partial<AuthDebuggerState>) => void;
+}
+
+export interface StateTransition {
+  canTransition: (context: StateMachineContext) => Promise<boolean>;
+  execute: (context: StateMachineContext) => Promise<void>;
+  nextStep: OAuthStep;
+}
+
+// State machine transitions
+export const oauthTransitions: Record<OAuthStep, StateTransition> = {
+  metadata_discovery: {
+    canTransition: async () => true,
+    execute: async (context) => {
+      const metadata = await discoverOAuthMetadata(context.serverUrl);
+      if (!metadata) {
+        throw new Error("Failed to discover OAuth metadata");
+      }
+      const parsedMetadata = await OAuthMetadataSchema.parseAsync(metadata);
+      context.provider.saveServerMetadata(parsedMetadata);
+      context.updateState({
+        oauthMetadata: parsedMetadata,
+        oauthStep: "client_registration",
+      });
+    },
+    nextStep: "client_registration",
+  },
+
+  client_registration: {
+    canTransition: async (context) => !!context.state.oauthMetadata,
+    execute: async (context) => {
+      const metadata = context.state.oauthMetadata!;
+      const clientMetadata = context.provider.clientMetadata;
+
+      // Add all supported scopes to client registration
+      if (metadata.scopes_supported) {
+        clientMetadata.scope = metadata.scopes_supported.join(" ");
+      }
+
+      const fullInformation = await registerClient(context.serverUrl, {
+        metadata,
+        clientMetadata,
+      });
+
+      context.provider.saveClientInformation(fullInformation);
+      context.updateState({
+        oauthClientInfo: fullInformation,
+        oauthStep: "authorization_redirect",
+      });
+    },
+    nextStep: "authorization_redirect",
+  },
+
+  authorization_redirect: {
+    canTransition: async (context) =>
+      !!context.state.oauthMetadata && !!context.state.oauthClientInfo,
+    execute: async (context) => {
+      const metadata = context.state.oauthMetadata!;
+      const clientInformation = context.state.oauthClientInfo!;
+
+      let scope: string | undefined = undefined;
+      if (metadata.scopes_supported) {
+        scope = metadata.scopes_supported.join(" ");
+      }
+
+      const { authorizationUrl, codeVerifier } = await startAuthorization(
+        context.serverUrl,
+        {
+          metadata,
+          clientInformation,
+          redirectUrl: context.provider.redirectUrl,
+          scope,
+        },
+      );
+
+      context.provider.saveCodeVerifier(codeVerifier);
+      context.updateState({
+        authorizationUrl: authorizationUrl.toString(),
+        oauthStep: "authorization_code",
+      });
+    },
+    nextStep: "authorization_code",
+  },
+
+  authorization_code: {
+    canTransition: async () => true,
+    execute: async (context) => {
+      if (
+        !context.state.authorizationCode ||
+        context.state.authorizationCode.trim() === ""
+      ) {
+        context.updateState({
+          validationError: "You need to provide an authorization code",
+        });
+        // Don't advance if no code
+        throw new Error("Authorization code required");
+      }
+      context.updateState({
+        validationError: null,
+        oauthStep: "token_request",
+      });
+    },
+    nextStep: "token_request",
+  },
+
+  token_request: {
+    canTransition: async (context) => {
+      return (
+        !!context.state.authorizationCode &&
+        !!context.provider.getServerMetadata() &&
+        !!(await context.provider.clientInformation())
+      );
+    },
+    execute: async (context) => {
+      const codeVerifier = context.provider.codeVerifier();
+      const metadata = context.provider.getServerMetadata()!;
+      const clientInformation = (await context.provider.clientInformation())!;
+
+      const tokens = await exchangeAuthorization(context.serverUrl, {
+        metadata,
+        clientInformation,
+        authorizationCode: context.state.authorizationCode,
+        codeVerifier,
+        redirectUri: context.provider.redirectUrl,
+      });
+
+      context.provider.saveTokens(tokens);
+      context.updateState({
+        oauthTokens: tokens,
+        oauthStep: "complete",
+      });
+    },
+    nextStep: "complete",
+  },
+
+  complete: {
+    canTransition: async () => false,
+    execute: async () => {
+      // No-op for complete state
+    },
+    nextStep: "complete",
+  },
+};
+
+export class OAuthStateMachine {
+  constructor(
+    private serverUrl: string,
+    private updateState: (updates: Partial<AuthDebuggerState>) => void,
+  ) {}
+
+  async executeStep(state: AuthDebuggerState): Promise<void> {
+    const provider = new DebugInspectorOAuthClientProvider(this.serverUrl);
+    const context: StateMachineContext = {
+      state,
+      serverUrl: this.serverUrl,
+      provider,
+      updateState: this.updateState,
+    };
+
+    const transition = oauthTransitions[state.oauthStep];
+    if (!(await transition.canTransition(context))) {
+      throw new Error(`Cannot transition from ${state.oauthStep}`);
+    }
+
+    await transition.execute(context);
+  }
+}