Feat: Implement OAuth Proxy for Remote MCP Servers

[teemow]

Summary

This PR implements the OAuth Proxy feature for remote MCP server authentication as outlined in Epic #144.

Changes

Phase 1: Foundation & Configuration

• Config types: Added OAuthConfig to MusterConfig.Aggregator with fields for publicUrl, clientId, callbackPath, and enabled
• CLI flags: Added --oauth, --oauth-public-url, and --oauth-client-id flags to muster serve
• Default values: Added sensible defaults including the CIMD URL and callback path

Phase 2: Server-Side OAuth Logic

• New internal/oauth package containing:

  • types.go: OAuth types including Token, AuthChallenge, OAuthState, OAuthMetadata, ClientMetadata, WWWAuthenticateParams
  • token_store.go: Thread-safe in-memory token storage with automatic cleanup
  • state_store.go: Thread-safe state parameter storage for CSRF protection (stores issuer and code verifier with state)
  • client.go: OAuth 2.1 client with PKCE support, metadata discovery (with thread-safe caching and TTL), token exchange, and refresh
  • www_authenticate.go: WWW-Authenticate header parser for extracting issuer and scope
  • handler.go: HTTP handler for OAuth callbacks with success/error pages
  • manager.go: Coordinates OAuth flows and integrates with the aggregator
  • api_adapter.go: Implements api.OAuthHandler following the service locator pattern

• API layer integration: Added OAuthHandler interface in internal/api/oauth.go with registration functions

• Aggregator integration: Updated aggregator to mount OAuth callback handler on the HTTP mux

Phase 3: Agent Integration

• Auth challenge detection: Agent detects auth_required responses and displays formatted messages using api.AuthChallenge
• User-friendly messages: Agent formats auth challenges with the auth URL for user authentication

Phase 4: Documentation

• CIMD file: Created docs/oauth-client.json for GitHub Pages hosting (Client ID Metadata Document)

Phase 5: Synthetic Tool Placeholder Pattern

Implemented the "Synthetic Tool Placeholder" pattern to solve the chicken-and-egg problem where OAuth authentication is required before the MCP protocol handshake can complete:

• 401 Detection: StreamableHTTPClient and SSEClient now detect 401 errors during initialization and return AuthRequiredError with parsed OAuth information from the WWW-Authenticate header
• AuthRequiredError: New error type in mcpserver/types.go containing URL and OAuth info (issuer, scope, resource metadata URL)
• ServerStatus: New enum in aggregator/types.go with StatusConnected, StatusDisconnected, and StatusAuthRequired
• Synthetic Auth Tools: When a server returns 401 during init, it's registered in StatusAuthRequired state with a synthetic authenticate_<server> tool
• Auth Tool Handler: Calling the synthetic tool creates an OAuth challenge with a sign-in link, or attempts to upgrade the server if a token already exists
• Server Upgrade: UpgradeToConnected() method in registry upgrades a pending auth server to connected status after successful OAuth

Synthetic Tool Flow

1. Server returns 401 during Initialize() → AuthRequiredError
2. Server registered in StatusAuthRequired with synthetic authenticate_<server> tool
3. User/Agent sees the auth tool in the tool list
4. User calls authenticate_<server>
5. If no token: returns OAuth challenge with sign-in URL
6. User authenticates in browser → callback → token stored
7. User retries tool or calls it again → server upgraded to connected
8. Real tools from the server become available

Phase 6: Helm Chart Configuration

Added OAuth proxy configuration to the Helm chart:

• values.yaml: Added muster.oauth section with:
  • enabled: Enable/disable OAuth proxy (default: false)
  • publicUrl: Publicly accessible URL for OAuth callbacks
  • clientId: OAuth client identifier (CIMD URL)
  • callbackPath: OAuth callback endpoint path (default: /oauth/callback)
• values.schema.json: Added schema validation for OAuth configuration
• deployment.yaml: Passes OAuth flags to the container when enabled
• README.md: Documented OAuth configuration with examples

Example Helm values:

muster:
  oauth:
    enabled: true
    publicUrl: "https://muster.example.com"
    clientId: "https://giantswarm.github.io/muster/oauth-client.json"
    callbackPath: "/oauth/callback"

Phase 7: Integration Testing & Bug Fixes

Tested with real remote MCP server (mcp-kubernetes on Gazelle cluster):

• Bug Fix - Auth Required Server Registration: The orchestrator now properly catches AuthRequiredError and registers servers in auth_required state with the aggregator via RegisterServerPendingAuth
• Bug Fix - Event Handler Deregistration: Event handler now skips deregistration for servers in auth_required state (they should remain registered with their synthetic auth tool)
• Bug Fix - Nil Pointer in Deregister: Fixed nil pointer dereference when deregistering servers without a client (auth_required servers have nil clients until authenticated)
• New API Method: Added RegisterServerPendingAuth to AggregatorHandler interface and implemented in api_adapter.go
• New Callback: Added isServerAuthRequired callback to event handler for checking server status

Verified working flow:

MCPServer kubernetes-gazelle requires authentication, registering pending auth
Registered pending auth server: kubernetes-gazelle (requires authentication)
Skipping deregistration of kubernetes-gazelle - server is in auth_required state
Server kubernetes-gazelle requires auth, exposing synthetic tool
GetAllTools: returning 96 tools from 6 connected + 1 auth_required servers

Security Review & Improvements

A comprehensive security review was conducted and the following findings were identified:

Security Strengths (Already Present)

• PKCE Implementation: Uses S256 code challenge method with 32-byte crypto/rand verifiers
• State Parameter Security: Cryptographically random nonces, single-use states, 10-minute expiry
• XSS Prevention: html.EscapeString() for all user-controlled HTML output
• Information Disclosure Prevention: Error responses don't expose token response bodies
• Token Security: Tokens stored server-side only, never sent to agent
• Thread Safety: All stores protected with RWMutex, no race conditions

Security Review Findings (All Addressed)

Finding	Severity	Resolution
Session ID logging	Low	Session IDs now truncated to first 8 chars in logs
Token refresh monitoring	Info	Added INFO-level logging with duration metrics
TLS requirements	Medium	Comprehensive TLS documentation in doc.go
Rate limiting	Medium	Rate limiting recommendations in Helm values/README
CIMD redirect URI limitation	Medium	Documented in Helm README with instructions for custom deployments
stdio session fallback	Low	Added warning log when default session is used
Metadata cache without signature validation	Low	Added TLS assumption comment; TLS provides integrity
No token encryption at rest	Info	Documented in-memory-only storage in doc.go

Critical: Session Isolation (Multi-User Security)

How Session IDs Work:

The mcp-go library provides unique session IDs for each MCP connection:

• SSE Transport: Each connection gets a UUID session ID via uuid.New().String()
• Streamable HTTP Transport: Each connection gets a unique session ID from sessionIdManager.Generate()

The session ID is automatically injected into the context by the mcp-go library and retrieved using server.ClientSessionFromContext(ctx).

Token Isolation:

Tokens are stored with a composite key: (SessionID, Issuer, Scope). This ensures:

• User A's tokens are never accessible by User B
• Each user must authenticate independently to remote MCP servers
• SSO works within a single user's session (same session, different servers using same IdP)

Stdio Fallback:

For stdio transport (single-user CLI), falls back to "default-session" which is acceptable since stdio is inherently single-user (one process = one user). A warning is now logged when this fallback is used.

Security Test Coverage:

Added TestTokenStore_SessionIsolation which explicitly verifies:

• User 1's session cannot access User 2's tokens
• User 2's session cannot access User 1's tokens
• GetByIssuer() respects session boundaries
• Exact token count validation (one per user)

Security Fixes Applied

1. Session ID Extraction: Uses server.ClientSessionFromContext(ctx) to extract the mcp-go library's unique session ID
2. Security Headers on HTML Responses: Added comprehensive security headers to OAuth callback pages:
   • X-Content-Type-Options: nosniff
   • X-Frame-Options: DENY
   • Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'
   • Referrer-Policy: no-referrer
   • Cache-Control: no-store, no-cache, must-revalidate
3. Metadata Cache TTL: Reduced from 1 hour to 30 minutes for faster key rotation updates
4. TLS Documentation: Added security comments about TLS requirements for production
5. In-Memory Storage Documentation: Enhanced doc.go with security notes about token storage
6. Session ID Truncation: Logs now show truncated session IDs (first 8 chars) to prevent exposure
7. Token Refresh Monitoring: INFO-level logging for token refresh with duration metrics
8. Rate Limiting Documentation: Added rate limiting recommendations to Helm values.yaml and README

Code Quality Improvements (Post-Review)

Applied the following improvements based on Go code review:

1. DRY: Removed duplicate AuthChallenge type from agent package - now uses api.AuthChallenge
2. Thread Safety: Added mutex protection to metadataCache in OAuth client to prevent race conditions
3. KISS: Removed redundant pendingFlows from Handler and pendingVerifiers from Manager
4. Bug Fix: Store issuer and code verifier with OAuth state to fix empty issuer bug in callback handler
5. Consolidation: Simplified callback handling by keeping all state data in the StateStore
6. DRY (Latest): Extracted duplicated checkForAuthRequiredError and parseAuthInfoFromError from SSEClient and StreamableHTTPClient to shared helper functions in mcpserver/types.go
7. DRY (Latest): Replaced duplicate AuthInfo and AuthRequiredError types in aggregator/types.go with type alias to mcpserver.AuthInfo, reducing code duplication by ~90 lines

Latest Code Quality Improvements (Post-Security-Review)

8. DRY: Extracted tokenToAPIToken helper function to remove duplicate Token → OAuthToken conversion in api_adapter.go
9. Constants: Defined tokenExpiryMargin constant (30s) to eliminate magic numbers in token expiration checks
10. Embedded Templates: Moved HTML templates to internal/oauth/templates/ using Go's embed package for better maintainability and syntax highlighting
11. Singleflight: Added singleflight.Group to fetchMetadata to prevent concurrent duplicate fetches for the same issuer (fixes TOCTOU race condition)
12. Security: OAuth error responses now use generic messages instead of forwarding error_description from OAuth providers (prevents information disclosure)
13. API Simplification: Simplified StateStore.GenerateState to return only encodedState (the nonce is embedded within and callers don't need it separately)

Code Review Improvements (Latest Commit)

14. Test Coverage: Increased OAuth package test coverage from 53% to 82%+ (above 80% threshold)
    • Added comprehensive tests for api_adapter.go (was 0%)
    • Added tests for token/state store cleanup functions
    • Added manager method tests for nil-safety and edge cases
15. DRY: Use strings.TrimSuffix consistently in config/types.go (removed custom trimTrailingSlash function)
16. Constants: Extracted httpClientTimeout (30s) and softwareVersion ("1.0.0") constants in OAuth client
17. Code Cleanup: Fixed unused variable assignment in server.go GetToolsWithStatus
18. Refactor: Removed time.Sleep from OnToolsUpdated - goroutine scheduling provides sufficient separation
19. Documentation: Added goroutine lifecycle requirements to TokenStore and StateStore godocs (callers MUST call Stop())
20. Session ID Logging: Added truncateSessionID helper to truncate session IDs to first 8 chars in all log output
21. Token Refresh Logging: Upgraded to INFO level with duration metrics for operations monitoring

Unit Tests

Comprehensive unit tests added for the internal/oauth package (82%+ coverage):

• token_store_test.go: Token storage, retrieval, expiration, SSO lookup by issuer, deletion, cleanup, session isolation security
• state_store_test.go: State generation, validation, CSRF protection, code verifier security, state expiration, cleanup
• www_authenticate_test.go: WWW-Authenticate header parsing, OAuth challenge detection, issuer extraction
• client_test.go: Redirect URI generation, PKCE generation, token storage/retrieval, metadata fetching with caching, code exchange, token refresh
• handler_test.go: OAuth callback handling, error cases, success/error page rendering, parameter validation, security headers verification, CIMD serving
• manager_test.go: Manager lifecycle, server registration, nil-safety, configuration handling, GetToken flows
• api_adapter_test.go: Adapter methods, token conversion, registration delegation

Architecture

The OAuth proxy follows the architecture outlined in docs/explanation/decisions/004-oauth-proxy.md:

1. Muster Server acts as the OAuth client and proxy
2. Tokens are stored server-side - never sent to the Agent
3. SSO is supported through token reuse by (SessionID, Issuer, Scope)
4. PKCE is used for enhanced security
5. User authenticates via their browser
6. Synthetic Tool Placeholder pattern handles OAuth required before MCP handshake
7. Session isolation ensures multi-user security

Testing

• All 135 existing BDD scenarios pass
• Unit tests pass with race detection enabled (82%+ coverage for OAuth package)
• Helm chart lints successfully
• Code formatted with goimports and go fmt
• Integration tested with mcp-kubernetes on Gazelle cluster (401 detection and synthetic tool registration verified)

Related

Implements #144

Security Review Checklist (All Passed)

Check	Status
PKCE implementation	PASS
State parameter CSRF protection	PASS
State single-use (deleted after validation)	PASS
State expiration (10 min)	PASS
Code verifier not exposed in state	PASS
XSS prevention (HTML escaping)	PASS
Security headers on responses	PASS
Session isolation	PASS
No token logging	PASS
Error message sanitization	PASS
HTTPS requirement documented	PASS
Metadata cache TTL	PASS (30 min)
HTTP client timeout	PASS (30 sec)
Thread-safe stores	PASS
Background cleanup goroutines	PASS
Proper Stop() cleanup	PASS
Session ID truncation in logs	PASS
Token refresh monitoring	PASS
Rate limiting documented	PASS