Add debug oauth commands: list, remove, and login

Add 'docker agent debug oauth list' to show all stored OAuth tokens.
Add 'docker agent debug oauth remove' to delete a token by resource URL.
Add 'docker agent debug oauth login' to trigger an OAuth flow for a remote MCP server.

The keyring token store now maintains an index key to minimize keychain
prompts when listing tokens, with a fallback to Keys() for pre-existing tokens.

Assisted-By: docker-agent

Author: dgageot

cmd/root/debug.go

@@ -55,6 +55,7 @@ func newDebugCmd() *cobra.Command {
 	addRuntimeConfigFlags(cmd, &flags.runConfig)
 
 	cmd.AddCommand(newDebugAuthCmd())
+	cmd.AddCommand(newDebugOAuthCmd())
 
 	return cmd
 }

cmd/root/debug_oauth.go

@@ -0,0 +1,257 @@
+package root
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/docker/docker-agent/pkg/config"
+	"github.com/docker/docker-agent/pkg/config/latest"
+	"github.com/docker/docker-agent/pkg/telemetry"
+	"github.com/docker/docker-agent/pkg/tools/mcp"
+)
+
+func newDebugOAuthCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "oauth",
+		Short: "OAuth token management",
+	}
+
+	cmd.AddCommand(newDebugOAuthListCmd())
+	cmd.AddCommand(newDebugOAuthRemoveCmd())
+	cmd.AddCommand(newDebugOAuthLoginCmd())
+
+	return cmd
+}
+
+func newDebugOAuthListCmd() *cobra.Command {
+	var jsonOutput bool
+
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List all stored OAuth tokens",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) (commandErr error) {
+			ctx := cmd.Context()
+			telemetry.TrackCommand(ctx, "debug", []string{"oauth", "list"})
+			defer func() {
+				telemetry.TrackCommandError(ctx, "debug", []string{"oauth", "list"}, commandErr)
+			}()
+
+			w := cmd.OutOrStdout()
+
+			entries, err := mcp.ListOAuthTokens()
+			if err != nil {
+				return fmt.Errorf("failed to list OAuth tokens: %w", err)
+			}
+
+			if len(entries) == 0 {
+				if jsonOutput {
+					return json.NewEncoder(w).Encode([]any{})
+				}
+				fmt.Fprintln(w, "No OAuth tokens stored.")
+				return nil
+			}
+
+			if jsonOutput {
+				return printOAuthListJSON(w, entries)
+			}
+
+			printOAuthListText(w, entries)
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&jsonOutput, "json", false, "Output in JSON format")
+
+	return cmd
+}
+
+type oauthListEntry struct {
+	ResourceURL  string    `json:"resource_url"`
+	TokenType    string    `json:"token_type,omitempty"`
+	Scope        string    `json:"scope,omitempty"`
+	ExpiresAt    time.Time `json:"expires_at,omitzero"`
+	Expired      bool      `json:"expired"`
+	AccessToken  string    `json:"access_token"`
+	RefreshToken bool      `json:"has_refresh_token"`
+}
+
+func printOAuthListJSON(w io.Writer, entries []mcp.OAuthTokenEntry) error {
+	var out []oauthListEntry
+	for _, e := range entries {
+		out = append(out, oauthListEntry{
+			ResourceURL:  e.ResourceURL,
+			TokenType:    e.Token.TokenType,
+			Scope:        e.Token.Scope,
+			ExpiresAt:    e.Token.ExpiresAt,
+			Expired:      e.Token.IsExpired(),
+			AccessToken:  truncateToken(e.Token.AccessToken),
+			RefreshToken: e.Token.RefreshToken != "",
+		})
+	}
+	enc := json.NewEncoder(w)
+	enc.SetIndent("", "  ")
+	return enc.Encode(out)
+}
+
+func printOAuthListText(w io.Writer, entries []mcp.OAuthTokenEntry) {
+	for i, e := range entries {
+		if i > 0 {
+			fmt.Fprintln(w)
+		}
+		fmt.Fprintf(w, "Resource:       %s\n", e.ResourceURL)
+		if e.Token.TokenType != "" {
+			fmt.Fprintf(w, "Token Type:     %s\n", e.Token.TokenType)
+		}
+		if e.Token.Scope != "" {
+			fmt.Fprintf(w, "Scope:          %s\n", e.Token.Scope)
+		}
+		fmt.Fprintf(w, "Access Token:   %s\n", truncateToken(e.Token.AccessToken))
+		fmt.Fprintf(w, "Refresh Token:  %v\n", e.Token.RefreshToken != "")
+		if !e.Token.ExpiresAt.IsZero() {
+			fmt.Fprintf(w, "Expires at:     %s\n", e.Token.ExpiresAt.Local().Format(time.RFC3339))
+		}
+		if e.Token.IsExpired() {
+			fmt.Fprintln(w, "Status:         ❌ Expired")
+		} else {
+			fmt.Fprintln(w, "Status:         ✅ Valid")
+		}
+	}
+}
+
+func truncateToken(token string) string {
+	const previewLen = 10
+	if len(token) <= previewLen*2 {
+		return token
+	}
+	return token[:previewLen] + "..." + token[len(token)-previewLen:]
+}
+
+func newDebugOAuthRemoveCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "remove <resource-url>",
+		Short: "Remove a stored OAuth token",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) (commandErr error) {
+			ctx := cmd.Context()
+			telemetry.TrackCommand(ctx, "debug", []string{"oauth", "remove"})
+			defer func() {
+				telemetry.TrackCommandError(ctx, "debug", []string{"oauth", "remove"}, commandErr)
+			}()
+
+			if err := mcp.RemoveOAuthToken(args[0]); err != nil {
+				return err
+			}
+
+			fmt.Fprintf(cmd.OutOrStdout(), "Removed OAuth token for %s\n", args[0])
+			return nil
+		},
+	}
+}
+
+func newDebugOAuthLoginCmd() *cobra.Command {
+	var flags debugFlags
+
+	cmd := &cobra.Command{
+		Use:   "login <agent-file> <mcp-name>",
+		Short: "Perform OAuth login for a remote MCP server",
+		Args:  cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) (commandErr error) {
+			ctx := cmd.Context()
+			telemetry.TrackCommand(ctx, "debug", []string{"oauth", "login"})
+			defer func() {
+				telemetry.TrackCommandError(ctx, "debug", []string{"oauth", "login"}, commandErr)
+			}()
+
+			agentFile := args[0]
+			mcpName := args[1]
+
+			// Load the agent config to find the MCP server URL.
+			agentSource, err := config.Resolve(agentFile, flags.runConfig.EnvProvider())
+			if err != nil {
+				return err
+			}
+
+			cfg, err := config.Load(ctx, agentSource)
+			if err != nil {
+				return err
+			}
+
+			serverURL, err := findMCPRemoteURL(cfg, mcpName)
+			if err != nil {
+				return err
+			}
+
+			w := cmd.OutOrStdout()
+			fmt.Fprintf(w, "Starting OAuth login for %s (%s)...\n", mcpName, serverURL)
+
+			if err := mcp.PerformOAuthLogin(ctx, serverURL); err != nil {
+				return fmt.Errorf("OAuth login failed: %w", err)
+			}
+
+			fmt.Fprintf(w, "✅ OAuth login successful for %s\n", serverURL)
+			return nil
+		},
+	}
+
+	addRuntimeConfigFlags(cmd, &flags.runConfig)
+
+	return cmd
+}
+
+// findMCPRemoteURL looks up the remote URL for the named MCP server in the config.
+// It matches by name (top-level mcps key or toolset name), by URL substring,
+// or returns the only remote MCP if there is exactly one.
+func findMCPRemoteURL(cfg *latest.Config, name string) (string, error) {
+	// Collect all remote MCP URLs with their identifiers.
+	type mcpEntry struct {
+		label string
+		url   string
+	}
+	var all []mcpEntry
+
+	for k, m := range cfg.MCPs {
+		if m.Remote.URL != "" {
+			all = append(all, mcpEntry{label: k, url: m.Remote.URL})
+		}
+	}
+	for _, agent := range cfg.Agents {
+		for _, ts := range agent.Toolsets {
+			if ts.Type == "mcp" && ts.Remote.URL != "" {
+				label := ts.Name
+				if label == "" {
+					label = ts.Remote.URL
+				}
+				all = append(all, mcpEntry{label: label, url: ts.Remote.URL})
+			}
+		}
+	}
+
+	// Exact match by name/label.
+	for _, e := range all {
+		if e.label == name {
+			return e.url, nil
+		}
+	}
+
+	// Exact match by URL.
+	for _, e := range all {
+		if e.url == name {
+			return e.url, nil
+		}
+	}
+
+	// Build helpful error.
+	var labels []string
+	for _, e := range all {
+		labels = append(labels, e.label)
+	}
+	if len(labels) > 0 {
+		return "", fmt.Errorf("MCP %q not found; available: %v", name, labels)
+	}
+	return "", fmt.Errorf("MCP %q not found; no remote MCPs found in config", name)
+}

pkg/tools/mcp/oauth_login.go

@@ -0,0 +1,125 @@
+package mcp
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/url"
+	"time"
+
+	"golang.org/x/oauth2"
+)
+
+// PerformOAuthLogin performs a standalone OAuth flow for the given MCP server URL.
+// It discovers the authorization server metadata, performs dynamic client registration,
+// opens the browser for user authorization, and stores the resulting token in the keyring.
+func PerformOAuthLogin(ctx context.Context, serverURL string) error {
+	tokenStore := NewKeyringTokenStore()
+
+	o := &oauth{metadataClient: &http.Client{Timeout: 5 * time.Second}}
+
+	// Derive the base origin (scheme + host) from the server URL.
+	// The well-known endpoints live at the origin, not under the SSE/path.
+	parsed, err := url.Parse(serverURL)
+	if err != nil {
+		return fmt.Errorf("invalid server URL: %w", err)
+	}
+	baseURL := parsed.Scheme + "://" + parsed.Host
+
+	// Discover protected resource metadata.
+	resourceURL := baseURL + "/.well-known/oauth-protected-resource"
+	resp, err := http.Get(resourceURL) //nolint:gosec // URL is user-provided
+	if err != nil {
+		return fmt.Errorf("failed to fetch protected resource metadata: %w", err)
+	}
+	defer resp.Body.Close()
+
+	authServer := baseURL
+	if resp.StatusCode == http.StatusOK {
+		var resourceMetadata protectedResourceMetadata
+		if decErr := json.NewDecoder(resp.Body).Decode(&resourceMetadata); decErr == nil && len(resourceMetadata.AuthorizationServers) > 0 {
+			authServer = resourceMetadata.AuthorizationServers[0]
+		}
+	}
+
+	// Discover authorization server metadata.
+	authServerMetadata, err := o.getAuthorizationServerMetadata(ctx, authServer)
+	if err != nil {
+		return fmt.Errorf("failed to fetch authorization server metadata: %w", err)
+	}
+
+	// Set up the callback server for the redirect.
+	callbackServer, err := NewCallbackServer()
+	if err != nil {
+		return fmt.Errorf("failed to create callback server: %w", err)
+	}
+	defer func() {
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+		if err := callbackServer.Shutdown(shutdownCtx); err != nil {
+			slog.Error("Failed to shutdown callback server", "error", err)
+		}
+	}()
+
+	if err := callbackServer.Start(); err != nil {
+		return fmt.Errorf("failed to start callback server: %w", err)
+	}
+
+	redirectURI := callbackServer.GetRedirectURI()
+
+	// Dynamic client registration.
+	var clientID, clientSecret string
+	if authServerMetadata.RegistrationEndpoint != "" {
+		clientID, clientSecret, err = RegisterClient(ctx, authServerMetadata, redirectURI, nil)
+		if err != nil {
+			return fmt.Errorf("dynamic client registration failed: %w", err)
+		}
+	} else {
+		return errors.New("authorization server does not support dynamic client registration")
+	}
+
+	// Generate PKCE and state.
+	state, err := GenerateState()
+	if err != nil {
+		return fmt.Errorf("failed to generate state: %w", err)
+	}
+	callbackServer.SetExpectedState(state)
+	verifier := GeneratePKCEVerifier()
+
+	authURL := BuildAuthorizationURL(
+		authServerMetadata.AuthorizationEndpoint,
+		clientID,
+		redirectURI,
+		state,
+		oauth2.S256ChallengeFromVerifier(verifier),
+		serverURL,
+	)
+
+	// Open the browser and wait for the callback.
+	code, receivedState, err := RequestAuthorizationCode(ctx, authURL, callbackServer, state)
+	if err != nil {
+		return fmt.Errorf("failed to get authorization code: %w", err)
+	}
+
+	if receivedState != state {
+		return errors.New("state mismatch in authorization response")
+	}
+
+	// Exchange the code for a token.
+	token, err := ExchangeCodeForToken(ctx, authServerMetadata.TokenEndpoint, code, verifier, clientID, clientSecret, redirectURI)
+	if err != nil {
+		return fmt.Errorf("failed to exchange code for token: %w", err)
+	}
+
+	token.ClientID = clientID
+	token.ClientSecret = clientSecret
+
+	if err := tokenStore.StoreToken(serverURL, token); err != nil {
+		return fmt.Errorf("failed to store token: %w", err)
+	}
+
+	return nil
+}