feat(auth): add routing source preference

Let routing prefer API-backed or file-backed credentials before cross-source priority so auth files can stay as fallback when API config is primary. Keep sticky bindings aligned with the preferred source layer as availability changes.

Author: NGLSL

config.example.yaml

@@ -107,6 +107,7 @@ quota-exceeded:
 # Routing strategy for selecting credentials when multiple match.
 routing:
   strategy: "round-robin" # round-robin (default), fill-first, sticky-round-robin
+  source-preference: "none" # none (default), api-first, file-first
   sticky-ttl: 1800 # Sticky binding TTL in seconds for sticky-round-robin
 
 # When true, enable authentication for the WebSocket API (/v1/ws).

internal/config/config.go

@@ -24,6 +24,7 @@ const (
 	DefaultPanelGitHubRepository     = "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"
 	DefaultPprofAddr                 = "127.0.0.1:8316"
 	DefaultRoutingStickyTTL          = 1800
+	DefaultRoutingSourcePreference   = "none"
 	DefaultQuotaCacheRefreshInterval = 3600
 )
 
@@ -222,6 +223,9 @@ type RoutingConfig struct {
 	// Strategy selects the credential selection strategy.
 	// Supported values: "round-robin" (default), "fill-first", "sticky-round-robin".
 	Strategy string `yaml:"strategy,omitempty" json:"strategy,omitempty"`
+	// SourcePreference controls whether routing prefers API-backed or file-backed sources first.
+	// Supported values: "none" (default), "api-first", "file-first".
+	SourcePreference string `yaml:"source-preference,omitempty" json:"source-preference,omitempty"`
 	// StickyTTL controls how long sticky-round-robin bindings remain valid, in seconds.
 	StickyTTL int `yaml:"sticky-ttl,omitempty" json:"sticky-ttl,omitempty"`
 }
@@ -569,6 +573,15 @@ func LoadConfig(configFile string) (*Config, error) {
 // LoadConfigOptional reads YAML from configFile.
 // If optional is true and the file is missing, it returns an empty Config.
 // If optional is true and the file is empty or invalid, it returns an empty Config.
+func normalizeRoutingSourcePreference(value string) string {
+	switch strings.TrimSpace(value) {
+	case "api-first", "file-first":
+		return strings.TrimSpace(value)
+	default:
+		return DefaultRoutingSourcePreference
+	}
+}
+
 func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 	// Read the entire configuration file into memory.
 	data, err := os.ReadFile(configFile)
@@ -601,6 +614,7 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 	cfg.Pprof.Addr = DefaultPprofAddr
 	cfg.AmpCode.RestrictManagementToLocalhost = false // Default to false: API key auth is sufficient
 	cfg.RemoteManagement.PanelGitHubRepository = DefaultPanelGitHubRepository
+	cfg.Routing.SourcePreference = DefaultRoutingSourcePreference
 	cfg.Routing.StickyTTL = DefaultRoutingStickyTTL
 	if err = yaml.Unmarshal(data, &cfg); err != nil {
 		if optional {
@@ -650,6 +664,8 @@ func LoadConfigOptional(configFile string, optional bool) (*Config, error) {
 		cfg.Pprof.Addr = DefaultPprofAddr
 	}
 
+	cfg.Routing.SourcePreference = normalizeRoutingSourcePreference(cfg.Routing.SourcePreference)
+
 	if cfg.Routing.StickyTTL <= 0 {
 		cfg.Routing.StickyTTL = DefaultRoutingStickyTTL
 	}
@@ -1341,6 +1357,8 @@ func isKnownDefaultValue(path []string, node *yaml.Node) bool {
 			return node.Value == DefaultPanelGitHubRepository
 		case "routing.strategy":
 			return node.Value == "round-robin"
+		case "routing.source-preference":
+			return node.Value == DefaultRoutingSourcePreference
 		}
 	}
 

internal/config/config_test.go

@@ -64,6 +64,72 @@ port: 8317
 	}
 }
 
+func TestLoadConfigOptionalRoutingSourcePreference(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name: "defaults to none when field is absent",
+			content: `routing:
+  strategy: "round-robin"
+`,
+			want: DefaultRoutingSourcePreference,
+		},
+		{
+			name: "keeps api-first",
+			content: `routing:
+  source-preference: "api-first"
+`,
+			want: "api-first",
+		},
+		{
+			name: "keeps file-first",
+			content: `routing:
+  source-preference: "file-first"
+`,
+			want: "file-first",
+		},
+		{
+			name: "invalid value falls back to none",
+			content: `routing:
+  source-preference: "invalid"
+`,
+			want: DefaultRoutingSourcePreference,
+		},
+		{
+			name: "empty value falls back to none",
+			content: `routing:
+  source-preference: ""
+`,
+			want: DefaultRoutingSourcePreference,
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			configPath := filepath.Join(t.TempDir(), "config.yaml")
+			if err := os.WriteFile(configPath, []byte(tt.content), 0o644); err != nil {
+				t.Fatalf("write config: %v", err)
+			}
+
+			cfg, err := LoadConfigOptional(configPath, false)
+			if err != nil {
+				t.Fatalf("LoadConfigOptional() error = %v", err)
+			}
+			if cfg.Routing.SourcePreference != tt.want {
+				t.Fatalf("Routing.SourcePreference = %q, want %q", cfg.Routing.SourcePreference, tt.want)
+			}
+		})
+	}
+}
+
 func TestIsKnownDefaultValueRecognizesQuotaCacheRefreshInterval(t *testing.T) {
 	t.Parallel()
 
@@ -77,3 +143,17 @@ func TestIsKnownDefaultValueRecognizesQuotaCacheRefreshInterval(t *testing.T) {
 		t.Fatal("expected quota-cache-refresh-interval=120 not to be treated as known default")
 	}
 }
+
+func TestIsKnownDefaultValueRecognizesRoutingSourcePreference(t *testing.T) {
+	t.Parallel()
+
+	defaultNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: DefaultRoutingSourcePreference}
+	if !isKnownDefaultValue([]string{"routing", "source-preference"}, defaultNode) {
+		t.Fatal("expected routing.source-preference=none to be treated as known default")
+	}
+
+	nonDefaultNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: "api-first"}
+	if isKnownDefaultValue([]string{"routing", "source-preference"}, nonDefaultNode) {
+		t.Fatal("expected routing.source-preference=api-first not to be treated as known default")
+	}
+}

internal/watcher/synthesizer/config.go

@@ -57,8 +57,9 @@ func (s *ConfigSynthesizer) synthesizeGeminiKeys(ctx *SynthesisContext) []*corea
 		proxyURL := strings.TrimSpace(entry.ProxyURL)
 		id, token := idGen.Next("gemini:apikey", key, base)
 		attrs := map[string]string{
-			"source":  fmt.Sprintf("config:gemini[%s]", token),
-			"api_key": key,
+			"source":      fmt.Sprintf("config:gemini[%s]", token),
+			"source_type": "api",
+			"api_key":     key,
 		}
 		if entry.Priority != 0 {
 			attrs["priority"] = strconv.Itoa(entry.Priority)
@@ -104,8 +105,9 @@ func (s *ConfigSynthesizer) synthesizeClaudeKeys(ctx *SynthesisContext) []*corea
 		base := strings.TrimSpace(ck.BaseURL)
 		id, token := idGen.Next("claude:apikey", key, base)
 		attrs := map[string]string{
-			"source":  fmt.Sprintf("config:claude[%s]", token),
-			"api_key": key,
+			"source":      fmt.Sprintf("config:claude[%s]", token),
+			"source_type": "api",
+			"api_key":     key,
 		}
 		if ck.Priority != 0 {
 			attrs["priority"] = strconv.Itoa(ck.Priority)
@@ -151,8 +153,9 @@ func (s *ConfigSynthesizer) synthesizeCodexKeys(ctx *SynthesisContext) []*coreau
 		prefix := strings.TrimSpace(ck.Prefix)
 		id, token := idGen.Next("codex:apikey", key, ck.BaseURL)
 		attrs := map[string]string{
-			"source":  fmt.Sprintf("config:codex[%s]", token),
-			"api_key": key,
+			"source":      fmt.Sprintf("config:codex[%s]", token),
+			"source_type": "api",
+			"api_key":     key,
 		}
 		if ck.Priority != 0 {
 			attrs["priority"] = strconv.Itoa(ck.Priority)
@@ -211,6 +214,7 @@ func (s *ConfigSynthesizer) synthesizeOpenAICompat(ctx *SynthesisContext) []*cor
 			id, token := idGen.Next(idKind, key, base, proxyURL)
 			attrs := map[string]string{
 				"source":       fmt.Sprintf("config:%s[%s]", providerName, token),
+				"source_type":  "api",
 				"base_url":     base,
 				"compat_name":  compat.Name,
 				"provider_key": providerName,
@@ -245,6 +249,7 @@ func (s *ConfigSynthesizer) synthesizeOpenAICompat(ctx *SynthesisContext) []*cor
 			id, token := idGen.Next(idKind, base)
 			attrs := map[string]string{
 				"source":       fmt.Sprintf("config:%s[%s]", providerName, token),
+				"source_type":  "api",
 				"base_url":     base,
 				"compat_name":  compat.Name,
 				"provider_key": providerName,
@@ -291,6 +296,7 @@ func (s *ConfigSynthesizer) synthesizeVertexCompat(ctx *SynthesisContext) []*cor
 		id, token := idGen.Next(idKind, key, base, proxyURL)
 		attrs := map[string]string{
 			"source":       fmt.Sprintf("config:vertex-apikey[%s]", token),
+			"source_type":  "api",
 			"base_url":     base,
 			"provider_key": providerName,
 		}

internal/watcher/synthesizer/config_test.go

@@ -615,3 +615,38 @@ func TestConfigSynthesizer_AllProviders(t *testing.T) {
 		}
 	}
 }
+
+func TestConfigSynthesizer_SetsSourceTypeAPIForSynthesizedAuths(t *testing.T) {
+	synth := NewConfigSynthesizer()
+	ctx := &SynthesisContext{
+		Config: &config.Config{
+			GeminiKey: []config.GeminiKey{{APIKey: "gemini-key"}},
+			ClaudeKey: []config.ClaudeKey{{APIKey: "claude-key"}},
+			CodexKey:  []config.CodexKey{{APIKey: "codex-key"}},
+			OpenAICompatibility: []config.OpenAICompatibility{{
+				Name:    "compat",
+				BaseURL: "https://compat.example.com",
+			}},
+			VertexCompatAPIKey: []config.VertexCompatKey{{
+				APIKey:  "vertex-key",
+				BaseURL: "https://vertex.example.com",
+			}},
+		},
+		Now:         time.Now(),
+		IDGenerator: NewStableIDGenerator(),
+	}
+
+	auths, err := synth.Synthesize(ctx)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(auths) != 5 {
+		t.Fatalf("expected 5 auths, got %d", len(auths))
+	}
+
+	for _, auth := range auths {
+		if got := auth.Attributes["source_type"]; got != "api" {
+			t.Fatalf("expected auth %s (%s) to have source_type api, got %q", auth.ID, auth.Provider, got)
+		}
+	}
+}

internal/watcher/synthesizer/file.go

@@ -129,8 +129,9 @@ func synthesizeFileAuths(ctx *SynthesisContext, fullPath string, data []byte) []
 		Status:   status,
 		Disabled: disabled,
 		Attributes: map[string]string{
-			"source": fullPath,
-			"path":   fullPath,
+			"source":      fullPath,
+			"source_type": "file",
+			"path":        fullPath,
 		},
 		ProxyURL:  proxyURL,
 		Metadata:  metadata,
@@ -205,6 +206,7 @@ func SynthesizeGeminiVirtualAuths(primary *coreauth.Auth, metadata map[string]an
 	primary.Attributes["virtual_children"] = strings.Join(projects, ",")
 	source := primary.Attributes["source"]
 	authPath := primary.Attributes["path"]
+	sourceType := strings.TrimSpace(primary.Attributes["source_type"])
 	originalProvider := primary.Provider
 	if originalProvider == "" {
 		originalProvider = "gemini-cli"
@@ -226,6 +228,9 @@ func SynthesizeGeminiVirtualAuths(primary *coreauth.Auth, metadata map[string]an
 		if authPath != "" {
 			attrs["path"] = authPath
 		}
+		if sourceType != "" {
+			attrs["source_type"] = sourceType
+		}
 		// Propagate priority from primary auth to virtual auths
 		if priorityVal, hasPriority := primary.Attributes["priority"]; hasPriority && priorityVal != "" {
 			attrs["priority"] = priorityVal

internal/watcher/synthesizer/file_test.go

@@ -955,3 +955,70 @@ func TestFileSynthesizer_Synthesize_MultiProjectGeminiWithNote(t *testing.T) {
 		}
 	}
 }
+
+func TestFileSynthesizer_Synthesize_SetsSourceTypeFile(t *testing.T) {
+	tempDir := t.TempDir()
+	authData := map[string]any{
+		"type":  "claude",
+		"email": "file@example.com",
+	}
+	data, _ := json.Marshal(authData)
+	errWriteFile := os.WriteFile(filepath.Join(tempDir, "auth.json"), data, 0644)
+	if errWriteFile != nil {
+		t.Fatalf("failed to write auth file: %v", errWriteFile)
+	}
+
+	synth := NewFileSynthesizer()
+	ctx := &SynthesisContext{
+		Config:      &config.Config{},
+		AuthDir:     tempDir,
+		Now:         time.Now(),
+		IDGenerator: NewStableIDGenerator(),
+	}
+
+	auths, errSynthesize := synth.Synthesize(ctx)
+	if errSynthesize != nil {
+		t.Fatalf("unexpected error: %v", errSynthesize)
+	}
+	if len(auths) != 1 {
+		t.Fatalf("expected 1 auth, got %d", len(auths))
+	}
+	if got := auths[0].Attributes["source_type"]; got != "file" {
+		t.Fatalf("expected source_type file, got %q", got)
+	}
+}
+
+func TestSynthesizeGeminiVirtualAuths_InheritsFileSourceType(t *testing.T) {
+	now := time.Now()
+	primary := &coreauth.Auth{
+		ID:       "primary-id",
+		Provider: "gemini-cli",
+		Label:    "test@example.com",
+		Attributes: map[string]string{
+			"source":      "test-source",
+			"path":        "/path/to/auth",
+			"source_type": "file",
+			"priority":    "7",
+		},
+	}
+	metadata := map[string]any{
+		"project_id": "proj-a, proj-b",
+		"email":      "test@example.com",
+		"type":       "gemini",
+	}
+
+	virtuals := SynthesizeGeminiVirtualAuths(primary, metadata, now)
+
+	if len(virtuals) != 2 {
+		t.Fatalf("expected 2 virtuals, got %d", len(virtuals))
+	}
+
+	for i, v := range virtuals {
+		if got := v.Attributes["source_type"]; got != "file" {
+			t.Fatalf("virtual %d: expected source_type file, got %q", i, got)
+		}
+		if got := v.Attributes["priority"]; got != "7" {
+			t.Fatalf("virtual %d: expected priority 7, got %q", i, got)
+		}
+	}
+}

sdk/cliproxy/auth/conductor.go

@@ -363,6 +363,7 @@ func (m *Manager) SetConfig(cfg *internalconfig.Config) {
 	m.runtimeConfig.Store(cfg)
 	if m.scheduler != nil {
 		m.scheduler.setStickyTTL(cfg.Routing.StickyTTL)
+		m.scheduler.setSourcePreference(cfg.Routing.SourcePreference)
 	}
 	m.rebuildAPIKeyModelAliasFromRuntimeConfig()
 }