feat: add custom scheme to handle cursor and other native tools

Author: ar4s

config.go

@@ -16,6 +16,7 @@ type Config struct {
 	RedirectURIs                 string // Redirect URIs allowlist (single or comma-separated)
 	FixedRedirectURI             string // Optional fixed redirect URI used for proxying callbacks
 	AllowedClientRedirectDomains string // Optional comma-separated list of domain suffixes allowed for client redirect URIs in fixed redirect mode (in addition to localhost)
+	AllowedClientRedirectSchemes string // Optional comma-separated list of custom URI schemes allowed for client redirect URIs (e.g. "cursor,vscode") per RFC 8252
 
 	// OIDC configuration
 	Issuer       string
@@ -240,6 +241,13 @@ func (b *ConfigBuilder) WithAllowedClientRedirectDomains(domains string) *Config
 	return b
 }
 
+// WithAllowedClientRedirectSchemes sets allowed custom URI schemes for client redirect URIs
+// per RFC 8252 (OAuth 2.0 for Native Apps). Example: "cursor,vscode"
+func (b *ConfigBuilder) WithAllowedClientRedirectSchemes(schemes string) *ConfigBuilder {
+	b.config.AllowedClientRedirectSchemes = schemes
+	return b
+}
+
 // WithIssuer sets the OIDC issuer
 func (b *ConfigBuilder) WithIssuer(issuer string) *ConfigBuilder {
 	b.config.Issuer = issuer
@@ -364,6 +372,7 @@ func FromEnv() (*Config, error) {
 		WithRedirectURIs(getEnv("OAUTH_REDIRECT_URIS", "")).
 		WithFixedRedirectURI(getEnv("OAUTH_FIXED_REDIRECT_URI", "")).
 		WithAllowedClientRedirectDomains(getEnv("OAUTH_ALLOWED_CLIENT_REDIRECT_DOMAINS", "")).
+		WithAllowedClientRedirectSchemes(getEnv("OAUTH_ALLOWED_CLIENT_REDIRECT_SCHEMES", "")).
 		WithIssuer(getEnv("OIDC_ISSUER", "")).
 		WithAudience(getEnv("OIDC_AUDIENCE", "")).
 		WithClientID(getEnv("OIDC_CLIENT_ID", "")).

config_test.go

@@ -89,6 +89,20 @@ func TestConfigBuilder(t *testing.T) {
 			},
 			wantErr: true,
 		},
+		{
+			name: "config with allowed client redirect schemes",
+			buildFunc: func() (*Config, error) {
+				return NewConfigBuilder().
+					WithProvider("hmac").
+					WithAudience("test-audience").
+					WithJWTSecret([]byte("secret")).
+					WithAllowedClientRedirectSchemes("cursor,vscode").
+					Build()
+			},
+			wantURL:      "http://localhost:8080",
+			wantMode:     "native",
+			wantProvider: "hmac",
+		},
 	}
 
 	for _, tt := range tests {
@@ -110,6 +124,11 @@ func TestConfigBuilder(t *testing.T) {
 			if cfg.Provider != tt.wantProvider {
 				t.Errorf("Provider = %v, want %v", cfg.Provider, tt.wantProvider)
 			}
+			if tt.name == "config with allowed client redirect schemes" {
+				if cfg.AllowedClientRedirectSchemes != "cursor,vscode" {
+					t.Errorf("AllowedClientRedirectSchemes = %v, want %v", cfg.AllowedClientRedirectSchemes, "cursor,vscode")
+				}
+			}
 		})
 	}
 }

docs/CONFIGURATION.md

@@ -28,6 +28,7 @@ type Config struct {
     // Optional - Fixed Redirect Mode (for mcp-remote)
     FixedRedirectURI             string // Single fixed redirect URI for proxying callbacks
     AllowedClientRedirectDomains string // Comma-separated domain suffixes allowed for client redirects
+    AllowedClientRedirectSchemes string // Comma-separated custom URI schemes (e.g. "cursor,vscode") per RFC 8252
 
     // Optional - Token Validation
     Scopes              []string // OAuth scopes
@@ -68,6 +69,7 @@ See [SECURITY.md](SECURITY.md) for detailed migration guide.
 - **Option 1:** `RedirectURIs` - Comma-separated allowlist of exact URIs
 - **Option 2:** `FixedRedirectURI` - Single fixed URI for proxying callbacks
 - **Additional:** `AllowedClientRedirectDomains` - Domain suffixes allowed for client redirects (in addition to localhost)
+- **Additional:** `AllowedClientRedirectSchemes` - Custom URI schemes for native app redirect URIs per RFC 8252 (e.g. `cursor,vscode`)
 
 **Mode Detection:**
 - `Mode = "native"` - Token validation only (ClientID not set)
@@ -137,6 +139,7 @@ _, oauthOption, _ := oauth.WithOAuth(mux, cfg)
 - `MCP_PORT` - Server port (default: 8080)
 - `HTTPS_CERT_FILE` - TLS cert file (enables HTTPS)
 - `HTTPS_KEY_FILE` - TLS key file (enables HTTPS)
+- `OAUTH_ALLOWED_CLIENT_REDIRECT_SCHEMES` - Custom URI schemes for native apps (e.g. "cursor,vscode")
 
 **Benefits:**
 

docs/SECURITY.md

@@ -387,6 +387,31 @@ oauth.WithOAuth(mux, &oauth.Config{
 - No fragment allowed (per OAuth 2.0 spec)
 - Exact match validation (no wildcards)
 
+### Custom URI Schemes (RFC 8252)
+
+Native desktop applications like Cursor and VS Code use custom URI schemes (e.g. `cursor://`, `vscode://`) for OAuth callbacks per [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252).
+
+Custom schemes are **opt-in** via `AllowedClientRedirectSchemes`. When not configured, only `http` (localhost) and `https` are accepted.
+
+```go
+oauth.WithOAuth(mux, &oauth.Config{
+    AllowedClientRedirectSchemes: "cursor,vscode",
+    // ...
+})
+```
+
+```
+ok:  cursor://anysphere.cursor-mcp/oauth/callback  (when "cursor" configured)
+ok:  vscode://vscode.github-authentication/callback (when "vscode" configured)
+bad: cursor://anysphere.cursor-mcp/oauth/callback   (when not configured)
+```
+
+**Security considerations:**
+
+- Any application on the device can register a custom URI scheme handler — PKCE is essential (already enforced by the OAuth flow)
+- Only allowlist schemes you explicitly trust
+- Custom scheme URIs bypass the domain suffix check (`AllowedClientRedirectDomains`) since they don't use traditional hostnames
+
 ---
 
 ## 🎫 Token Security

fixed_redirect_test.go

@@ -60,7 +60,7 @@ func TestFixedRedirectModeLocalhostOnly(t *testing.T) {
 			expectedError: "must not contain fragment",
 		},
 		{
-			name:          "Custom scheme rejected",
+			name:          "Custom scheme rejected when not configured",
 			clientURI:     "custom://localhost:8080/callback",
 			shouldPass:    false,
 			expectedError: "Invalid redirect_uri scheme",
@@ -88,15 +88,73 @@ func TestFixedRedirectModeSecurityModel(t *testing.T) {
 	t.Log("Fixed Redirect Mode Security Model:")
 	t.Log("- Single OAUTH_REDIRECT_URI configured (no commas)")
 	t.Log("- Server uses fixed URI to communicate with OAuth provider")
-	t.Log("- Client redirect URIs MUST be localhost for security")
+	t.Log("- Client redirect URIs MUST be localhost or an allowed custom scheme for security")
 	t.Log("- HMAC-signed state prevents redirect URI tampering")
 	t.Log("")
 	t.Log("Attack Prevention:")
 	t.Log("1. Open Redirect → Localhost-only restriction prevents external redirects")
 	t.Log("2. State Tampering → HMAC signature verification prevents modification")
 	t.Log("3. Code Theft → PKCE prevents token exchange without code_verifier")
 	t.Log("4. HTTP Exposure → HTTPS required for non-localhost URIs")
+	t.Log("5. Custom Schemes → Only explicitly configured schemes accepted (RFC 8252)")
 	t.Log("")
 	t.Log("Use Case: Development tools (MCP Inspector) running on localhost")
+	t.Log("Use Case: Native apps (Cursor, VS Code) using custom URI schemes")
 	t.Log("Production: Use allowlist mode instead")
 }
+
+func TestFixedRedirectModeCustomSchemes(t *testing.T) {
+	tests := []struct {
+		name       string
+		schemes    string
+		clientURI  string
+		shouldPass bool
+	}{
+		{
+			name:       "Cursor scheme allowed when configured",
+			schemes:    "cursor",
+			clientURI:  "cursor://anysphere.cursor-mcp/oauth/callback",
+			shouldPass: true,
+		},
+		{
+			name:       "Cursor scheme rejected when not configured",
+			schemes:    "",
+			clientURI:  "cursor://anysphere.cursor-mcp/oauth/callback",
+			shouldPass: false,
+		},
+		{
+			name:       "VSCode scheme allowed when configured",
+			schemes:    "vscode",
+			clientURI:  "vscode://vscode.github-authentication/callback",
+			shouldPass: true,
+		},
+		{
+			name:       "Multiple schemes configured",
+			schemes:    "cursor, vscode",
+			clientURI:  "cursor://anysphere.cursor-mcp/oauth/callback",
+			shouldPass: true,
+		},
+		{
+			name:       "HTTP localhost still works with custom schemes configured",
+			schemes:    "cursor",
+			clientURI:  "http://localhost:8080/callback",
+			shouldPass: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			handler := &OAuth2Handler{
+				config: &OAuth2Config{
+					AllowedClientRedirectSchemes: tt.schemes,
+				},
+				logger: &defaultLogger{},
+			}
+
+			got := handler.isAllowedClientRedirectURI(tt.clientURI)
+			if got != tt.shouldPass {
+				t.Errorf("isAllowedClientRedirectURI(%q) = %v, want %v (schemes=%q)", tt.clientURI, got, tt.shouldPass, tt.schemes)
+			}
+		})
+	}
+}

handlers.go

@@ -53,6 +53,10 @@ type OAuth2Config struct {
 	// that are allowed for client redirect URIs in fixed redirect mode (in addition to localhost).
 	AllowedClientRedirectDomains string
 
+	// AllowedClientRedirectSchemes is an optional comma-separated list of custom URI schemes
+	// allowed for client redirect URIs (e.g. "cursor,vscode") per RFC 8252.
+	AllowedClientRedirectSchemes string
+
 	// OIDC configuration
 	Issuer       string
 	Audience     string
@@ -219,6 +223,7 @@ func NewOAuth2ConfigFromConfig(cfg *Config, version string) *OAuth2Config {
 		RedirectURIs:                 cfg.RedirectURIs,
 		FixedRedirectURI:             cfg.FixedRedirectURI,
 		AllowedClientRedirectDomains: cfg.AllowedClientRedirectDomains,
+		AllowedClientRedirectSchemes: cfg.AllowedClientRedirectSchemes,
 		Issuer:                       cfg.Issuer,
 		Audience:                     cfg.Audience,
 		ClientID:                     cfg.ClientID,
@@ -368,14 +373,14 @@ func (h *OAuth2Handler) HandleAuthorize(w http.ResponseWriter, r *http.Request)
 			return
 		}
 
-		// Additional security checks for client redirect URI
-		if parsedURI.Scheme != "http" && parsedURI.Scheme != "https" {
-			h.logger.Warn("SECURITY: Invalid redirect URI scheme: %s (must be http or https)", parsedURI.Scheme)
+		// Additional security checks for client redirect URI scheme
+		if !h.isAllowedScheme(parsedURI.Scheme) {
+			h.logger.Warn("SECURITY: Invalid redirect URI scheme: %s (must be http, https, or an allowed custom scheme)", parsedURI.Scheme)
 			http.Error(w, "Invalid redirect_uri scheme", http.StatusBadRequest)
 			return
 		}
 
-		// Enforce HTTPS for non-localhost URIs
+		// Enforce HTTPS for non-localhost URIs (only applies to http scheme; custom schemes skip this)
 		if parsedURI.Scheme == "http" && !isLocalhostURI(clientRedirectURI) {
 			h.logger.Warn("SECURITY: HTTP redirect URI not allowed for non-localhost: %s", clientRedirectURI)
 			http.Error(w, "HTTPS required for non-localhost redirect_uri", http.StatusBadRequest)
@@ -922,17 +927,22 @@ func (h *OAuth2Handler) isAllowedClientRedirectURI(uri string) bool {
 		return true
 	}
 
-	// For non-localhost URIs, require explicit domain suffix configuration
-	if h.config.AllowedClientRedirectDomains == "" {
+	parsedURI, err := url.Parse(uri)
+	if err != nil {
 		return false
 	}
 
-	parsedURI, err := url.Parse(uri)
-	if err != nil {
+	// Allow explicitly configured custom schemes (e.g. cursor://, vscode://) per RFC 8252
+	if h.isCustomScheme(parsedURI.Scheme) {
+		return true
+	}
+
+	// For non-localhost URIs with standard schemes, require explicit domain suffix configuration
+	if h.config.AllowedClientRedirectDomains == "" {
 		return false
 	}
 
-	// Only allow HTTPS for non-localhost URIs
+	// Only allow HTTPS for non-localhost URIs with standard schemes
 	if parsedURI.Scheme != "https" {
 		return false
 	}
@@ -956,6 +966,28 @@ func (h *OAuth2Handler) isAllowedClientRedirectURI(uri string) bool {
 	return false
 }
 
+// isAllowedScheme returns true for http, https, or any explicitly configured custom scheme.
+func (h *OAuth2Handler) isAllowedScheme(scheme string) bool {
+	if scheme == "http" || scheme == "https" {
+		return true
+	}
+	return h.isCustomScheme(scheme)
+}
+
+// isCustomScheme checks if scheme is in the configured AllowedClientRedirectSchemes list.
+func (h *OAuth2Handler) isCustomScheme(scheme string) bool {
+	if h.config.AllowedClientRedirectSchemes == "" {
+		return false
+	}
+	scheme = strings.ToLower(scheme)
+	for _, s := range strings.Split(h.config.AllowedClientRedirectSchemes, ",") {
+		if strings.TrimSpace(strings.ToLower(s)) == scheme {
+			return true
+		}
+	}
+	return false
+}
+
 // isValidRedirectURI validates redirect URI against allowlist for security
 func (h *OAuth2Handler) isValidRedirectURI(uri string) bool {
 	if h.config.RedirectURIs == "" {

security_test.go

@@ -77,7 +77,8 @@ func TestRedirectURIValidation(t *testing.T) {
 func TestIsAllowedClientRedirectURI(t *testing.T) {
 	tests := []struct {
 		name      string
-		allowed   string
+		allowed   string // AllowedClientRedirectDomains
+		schemes   string // AllowedClientRedirectSchemes
 		uri       string
 		isAllowed bool
 	}{
@@ -136,7 +137,7 @@ func TestIsAllowedClientRedirectURI(t *testing.T) {
 			isAllowed: false,
 		},
 		{
-			name:      "Non-HTTPS scheme rejected",
+			name:      "Non-HTTPS scheme rejected when not configured",
 			allowed:   "example.com",
 			uri:       "custom://example.com/callback",
 			isAllowed: false,
@@ -147,20 +148,56 @@ func TestIsAllowedClientRedirectURI(t *testing.T) {
 			uri:       "not-a-valid-uri",
 			isAllowed: false,
 		},
+		{
+			name:      "Custom scheme allowed when configured",
+			schemes:   "cursor",
+			uri:       "cursor://anysphere.cursor-mcp/oauth/callback",
+			isAllowed: true,
+		},
+		{
+			name:      "Custom scheme rejected when not configured",
+			uri:       "cursor://anysphere.cursor-mcp/oauth/callback",
+			isAllowed: false,
+		},
+		{
+			name:      "Unconfigured custom scheme rejected",
+			schemes:   "vscode",
+			uri:       "cursor://anysphere.cursor-mcp/oauth/callback",
+			isAllowed: false,
+		},
+		{
+			name:      "Multiple custom schemes - first match",
+			schemes:   "cursor, vscode",
+			uri:       "cursor://anysphere.cursor-mcp/oauth/callback",
+			isAllowed: true,
+		},
+		{
+			name:      "Multiple custom schemes - second match",
+			schemes:   "cursor, vscode",
+			uri:       "vscode://vscode.github-authentication/callback",
+			isAllowed: true,
+		},
+		{
+			name:      "Custom scheme case insensitive",
+			schemes:   "Cursor",
+			uri:       "cursor://anysphere.cursor-mcp/oauth/callback",
+			isAllowed: true,
+		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			handler := &OAuth2Handler{
 				config: &OAuth2Config{
 					AllowedClientRedirectDomains: tt.allowed,
+					AllowedClientRedirectSchemes: tt.schemes,
 				},
 				logger: &defaultLogger{},
 			}
 
 			got := handler.isAllowedClientRedirectURI(tt.uri)
 			if got != tt.isAllowed {
-				t.Errorf("isAllowedClientRedirectURI(%q) = %v, want %v (allowed=%q)", tt.uri, got, tt.isAllowed, tt.allowed)
+				t.Errorf("isAllowedClientRedirectURI(%q) = %v, want %v (domains=%q, schemes=%q)", tt.uri, got, tt.isAllowed, tt.allowed, tt.schemes)
 			}
 		})
 	}