Move remote MCP authentication handler to pkg/auth/remote (#2464)

Previously, RemoteAuthHandler and RemoteAuthConfig lived in pkg/runner/,
mixing authentication implementation with runner execution logic. This
change improves separation of concerns by moving auth logic to the auth
package while keeping configuration properly organized.

Changes:
- Created pkg/auth/remote/ package for remote MCP authentication
- Moved RemoteAuthHandler → authremote.Handler
- Moved RemoteAuthConfig → authremote.Config
- Updated all references in pkg/runner/, pkg/api/, and cmd/thv/app/
- Removed old remote_auth.go and remote_auth_test.go from pkg/runner/

Benefits:
- Clear package boundaries (runner executes, auth authenticates)
- Authentication logic can be tested independently of runner
- Follows existing pattern where RunConfig uses types from domain packages
  (similar to how it uses registry.Header, transport/types.MiddlewareConfig)
- Easier to reuse remote auth in other contexts

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: JAORMX

cmd/thv/app/run_flags.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/stacklok/toolhive/pkg/auth"
 	authoauth "github.com/stacklok/toolhive/pkg/auth/oauth"
+	"github.com/stacklok/toolhive/pkg/auth/remote"
 	"github.com/stacklok/toolhive/pkg/authz"
 	"github.com/stacklok/toolhive/pkg/cli"
 	cfg "github.com/stacklok/toolhive/pkg/config"
@@ -615,7 +616,7 @@ func extractTelemetryValues(config *telemetry.Config) (string, float64, []string
 func getRemoteAuthFromRemoteServerMetadata(
 	remoteServerMetadata *registry.RemoteServerMetadata,
 	runFlags *RunFlags,
-) (*runner.RemoteAuthConfig, error) {
+) (*remote.Config, error) {
 	if remoteServerMetadata == nil || remoteServerMetadata.OAuthConfig == nil {
 		return getRemoteAuthFromRunFlags(runFlags)
 	}
@@ -651,7 +652,7 @@ func getRemoteAuthFromRemoteServerMetadata(
 		}
 	}
 
-	authCfg := &runner.RemoteAuthConfig{
+	authCfg := &remote.Config{
 		ClientID:     f.RemoteAuthClientID,
 		ClientSecret: clientSecret,
 		SkipBrowser:  f.RemoteAuthSkipBrowser,
@@ -692,7 +693,7 @@ func getRemoteAuthFromRemoteServerMetadata(
 }
 
 // getRemoteAuthFromRunFlags creates RemoteAuthConfig from RunFlags
-func getRemoteAuthFromRunFlags(runFlags *RunFlags) (*runner.RemoteAuthConfig, error) {
+func getRemoteAuthFromRunFlags(runFlags *RunFlags) (*remote.Config, error) {
 	// Resolve OAuth client secret from multiple sources (flag, file, environment variable)
 	// This follows the same priority as resolveSecret: flag → file → environment variable
 	resolvedClientSecret, err := resolveSecret(
@@ -714,7 +715,7 @@ func getRemoteAuthFromRunFlags(runFlags *RunFlags) (*runner.RemoteAuthConfig, er
 		}
 	}
 
-	return &runner.RemoteAuthConfig{
+	return &remote.Config{
 		ClientID:     runFlags.RemoteAuthFlags.RemoteAuthClientID,
 		ClientSecret: clientSecret,
 		Scopes:       runFlags.RemoteAuthFlags.RemoteAuthScopes,

docs/server/docs.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"time"
 
+	"github.com/stacklok/toolhive/pkg/auth/remote"
 	"github.com/stacklok/toolhive/pkg/container/runtime"
 	"github.com/stacklok/toolhive/pkg/groups"
 	"github.com/stacklok/toolhive/pkg/logger"
@@ -116,7 +117,7 @@ func (s *WorkloadService) BuildFullRunConfig(ctx context.Context, req *createReq
 		return nil, fmt.Errorf("group '%s' does not exist", groupName)
 	}
 
-	var remoteAuthConfig *runner.RemoteAuthConfig
+	var remoteAuthConfig *remote.Config
 	var imageURL string
 	var imageMetadata *registry.ImageMetadata
 	var serverMetadata registry.ServerMetadata
@@ -151,7 +152,7 @@ func (s *WorkloadService) BuildFullRunConfig(ctx context.Context, req *createReq
 
 		if remoteServerMetadata, ok := serverMetadata.(*registry.RemoteServerMetadata); ok {
 			if remoteServerMetadata.OAuthConfig != nil {
-				remoteAuthConfig = &runner.RemoteAuthConfig{
+				remoteAuthConfig = &remote.Config{
 					ClientID:     req.OAuthConfig.ClientID,
 					Scopes:       remoteServerMetadata.OAuthConfig.Scopes,
 					CallbackPort: remoteServerMetadata.OAuthConfig.CallbackPort,
@@ -251,10 +252,10 @@ func (s *WorkloadService) BuildFullRunConfig(ctx context.Context, req *createReq
 func createRequestToRemoteAuthConfig(
 	_ context.Context,
 	req *createRequest,
-) *runner.RemoteAuthConfig {
+) *remote.Config {
 
 	// Create RemoteAuthConfig
-	remoteAuthConfig := &runner.RemoteAuthConfig{
+	remoteAuthConfig := &remote.Config{
 		ClientID:     req.OAuthConfig.ClientID,
 		Scopes:       req.OAuthConfig.Scopes,
 		Issuer:       req.OAuthConfig.Issuer,

docs/server/swagger.json

@@ -7,6 +7,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/stacklok/toolhive/pkg/auth"
+	"github.com/stacklok/toolhive/pkg/auth/remote"
 	"github.com/stacklok/toolhive/pkg/permissions"
 	"github.com/stacklok/toolhive/pkg/runner"
 	"github.com/stacklok/toolhive/pkg/transport/types"
@@ -152,7 +153,7 @@ func TestRunConfigToCreateRequest(t *testing.T) {
 
 		runConfig := &runner.RunConfig{
 			Name: "test-workload",
-			RemoteAuthConfig: &runner.RemoteAuthConfig{
+			RemoteAuthConfig: &remote.Config{
 				Issuer:       "https://oauth.example.com",
 				AuthorizeURL: "https://oauth.example.com/auth",
 				TokenURL:     "https://oauth.example.com/token",
@@ -189,7 +190,7 @@ func TestRunConfigToCreateRequest(t *testing.T) {
 
 		runConfig := &runner.RunConfig{
 			Name: "test-workload",
-			RemoteAuthConfig: &runner.RemoteAuthConfig{
+			RemoteAuthConfig: &remote.Config{
 				Issuer:       "https://oauth.example.com",
 				AuthorizeURL: "https://oauth.example.com/auth",
 				TokenURL:     "https://oauth.example.com/token",

docs/server/swagger.yaml

@@ -0,0 +1,97 @@
+package remote
+
+import (
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/stacklok/toolhive/pkg/registry"
+)
+
+// Config holds authentication configuration for remote MCP servers.
+// Supports OAuth/OIDC-based authentication with automatic discovery.
+type Config struct {
+	ClientID         string        `json:"client_id,omitempty" yaml:"client_id,omitempty"`
+	ClientSecret     string        `json:"client_secret,omitempty" yaml:"client_secret,omitempty"`
+	ClientSecretFile string        `json:"client_secret_file,omitempty" yaml:"client_secret_file,omitempty"`
+	Scopes           []string      `json:"scopes,omitempty" yaml:"scopes,omitempty"`
+	SkipBrowser      bool          `json:"skip_browser,omitempty" yaml:"skip_browser,omitempty"`
+	Timeout          time.Duration `json:"timeout,omitempty" yaml:"timeout,omitempty" swaggertype:"string" example:"5m"`
+	CallbackPort     int           `json:"callback_port,omitempty" yaml:"callback_port,omitempty"`
+	UsePKCE          bool          `json:"use_pkce" yaml:"use_pkce"`
+
+	// OAuth endpoint configuration (from registry)
+	Issuer       string `json:"issuer,omitempty" yaml:"issuer,omitempty"`
+	AuthorizeURL string `json:"authorize_url,omitempty" yaml:"authorize_url,omitempty"`
+	TokenURL     string `json:"token_url,omitempty" yaml:"token_url,omitempty"`
+
+	// Headers for HTTP requests
+	Headers []*registry.Header `json:"headers,omitempty" yaml:"headers,omitempty"`
+
+	// Environment variables for the client
+	EnvVars []*registry.EnvVar `json:"env_vars,omitempty" yaml:"env_vars,omitempty"`
+
+	// OAuth parameters for server-specific customization
+	OAuthParams map[string]string `json:"oauth_params,omitempty" yaml:"oauth_params,omitempty"`
+}
+
+// UnmarshalJSON implements custom JSON unmarshaling for backward compatibility
+// This handles both the old PascalCase format and the new snake_case format
+func (r *Config) UnmarshalJSON(data []byte) error {
+	// Parse the JSON to check which format is being used
+	var raw map[string]interface{}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+
+	// Check if this is the old PascalCase format by looking for old field name
+	// if one old field is present, then it's the old format
+	if _, isOld := raw["ClientID"]; isOld {
+		// Unmarshal using old PascalCase format
+		var oldFormat struct {
+			ClientID         string             `json:"ClientID,omitempty"`
+			ClientSecret     string             `json:"ClientSecret,omitempty"`
+			ClientSecretFile string             `json:"ClientSecretFile,omitempty"`
+			Scopes           []string           `json:"Scopes,omitempty"`
+			SkipBrowser      bool               `json:"SkipBrowser,omitempty"`
+			Timeout          time.Duration      `json:"Timeout,omitempty"`
+			CallbackPort     int                `json:"CallbackPort,omitempty"`
+			UsePKCE          bool               `json:"UsePKCE,omitempty"`
+			Issuer           string             `json:"Issuer,omitempty"`
+			AuthorizeURL     string             `json:"AuthorizeURL,omitempty"`
+			TokenURL         string             `json:"TokenURL,omitempty"`
+			Headers          []*registry.Header `json:"Headers,omitempty"`
+			EnvVars          []*registry.EnvVar `json:"EnvVars,omitempty"`
+			OAuthParams      map[string]string  `json:"OAuthParams,omitempty"`
+		}
+
+		if err := json.Unmarshal(data, &oldFormat); err != nil {
+			return fmt.Errorf("failed to unmarshal Config in old format: %w", err)
+		}
+
+		// Copy from old format to new format
+		r.ClientID = oldFormat.ClientID
+		r.ClientSecret = oldFormat.ClientSecret
+		r.ClientSecretFile = oldFormat.ClientSecretFile
+		r.Scopes = oldFormat.Scopes
+		r.SkipBrowser = oldFormat.SkipBrowser
+		r.Timeout = oldFormat.Timeout
+		r.CallbackPort = oldFormat.CallbackPort
+		r.UsePKCE = oldFormat.UsePKCE
+		r.Issuer = oldFormat.Issuer
+		r.AuthorizeURL = oldFormat.AuthorizeURL
+		r.TokenURL = oldFormat.TokenURL
+		r.Headers = oldFormat.Headers
+		r.EnvVars = oldFormat.EnvVars
+		r.OAuthParams = oldFormat.OAuthParams
+		return nil
+	}
+
+	// Use the new snake_case format
+	type Alias Config
+	alias := (*Alias)(r)
+	return json.Unmarshal(data, alias)
+}
+
+// DefaultCallbackPort is the default port for the OAuth callback server
+const DefaultCallbackPort = 8666

pkg/api/v1/workload_service.go

@@ -0,0 +1,15 @@
+// Package remote provides authentication handling for remote MCP servers.
+//
+// This package implements OAuth/OIDC-based authentication with automatic
+// discovery support for remote MCP servers. It handles:
+//   - OAuth issuer discovery (RFC 8414)
+//   - Protected resource metadata (RFC 9728)
+//   - OAuth flow execution (PKCE-based)
+//   - Token source creation for HTTP transports
+//
+// The main entry point is Handler.Authenticate() which takes a remote URL
+// and performs all necessary discovery and authentication steps.
+//
+// Configuration is defined in pkg/runner.RemoteAuthConfig as part of the
+// runner's RunConfig structure.
+package remote

pkg/api/v1/workloads_types_test.go

@@ -1,4 +1,4 @@
-package runner
+package remote
 
 import (
 	"context"
@@ -10,21 +10,21 @@ import (
 	"github.com/stacklok/toolhive/pkg/logger"
 )
 
-// RemoteAuthHandler handles authentication for remote MCP servers.
+// Handler handles authentication for remote MCP servers.
 // Supports OAuth/OIDC-based authentication with automatic discovery.
-type RemoteAuthHandler struct {
-	config *RemoteAuthConfig
+type Handler struct {
+	config *Config
 }
 
-// NewRemoteAuthHandler creates a new remote authentication handler
-func NewRemoteAuthHandler(config *RemoteAuthConfig) *RemoteAuthHandler {
-	return &RemoteAuthHandler{
+// NewHandler creates a new remote authentication handler
+func NewHandler(config *Config) *Handler {
+	return &Handler{
 		config: config,
 	}
 }
 
 // Authenticate is the main entry point for remote MCP server authentication
-func (h *RemoteAuthHandler) Authenticate(ctx context.Context, remoteURL string) (oauth2.TokenSource, error) {
+func (h *Handler) Authenticate(ctx context.Context, remoteURL string) (oauth2.TokenSource, error) {
 
 	// First, try to detect if authentication is required
 	authInfo, err := discovery.DetectAuthenticationFromServer(ctx, remoteURL, nil)
@@ -89,7 +89,7 @@ func (h *RemoteAuthHandler) Authenticate(ctx context.Context, remoteURL string)
 // discoverIssuerAndScopes attempts to discover the OAuth issuer and scopes from various sources
 // following RFC 8414 and RFC 9728 standards
 // If the issuer is not derived from Realm and Resource Metadata, it derives from the remote URL
-func (h *RemoteAuthHandler) discoverIssuerAndScopes(
+func (h *Handler) discoverIssuerAndScopes(
 	ctx context.Context,
 	authInfo *discovery.AuthInfo,
 	remoteURL string,
@@ -135,7 +135,7 @@ func (h *RemoteAuthHandler) discoverIssuerAndScopes(
 }
 
 // tryDiscoverFromResourceMetadata attempts to discover issuer and scopes from resource metadata
-func (h *RemoteAuthHandler) tryDiscoverFromResourceMetadata(
+func (h *Handler) tryDiscoverFromResourceMetadata(
 	ctx context.Context,
 	resourceMetadataURL string,
 ) (string, []string, *discovery.AuthServerInfo, error) {
@@ -172,7 +172,7 @@ func (h *RemoteAuthHandler) tryDiscoverFromResourceMetadata(
 }
 
 // findValidAuthServer validates authorization servers and returns the first valid one
-func (*RemoteAuthHandler) findValidAuthServer(
+func (*Handler) findValidAuthServer(
 	ctx context.Context,
 	authServers []string,
 ) (*discovery.AuthServerInfo, string) {
@@ -197,7 +197,7 @@ func (*RemoteAuthHandler) findValidAuthServer(
 // tryDiscoverFromWellKnown attempts to discover the actual OAuth issuer
 // by probing the server's well-known endpoints without validating issuer match
 // This is useful when the issuer differs from the server URL (e.g., Atlassian case)
-func (h *RemoteAuthHandler) tryDiscoverFromWellKnown(
+func (h *Handler) tryDiscoverFromWellKnown(
 	ctx context.Context,
 	remoteURL string,
 ) (string, []string, *discovery.AuthServerInfo, error) {