feat(auth): ✨ add configurable OAuth callback ports for all providers

Introduce environment variable configuration for OAuth callback server ports across Gemini CLI, Antigravity, and iFlow providers to prevent port conflicts and support multi-instance deployments.

- Add `*_OAUTH_PORT` environment variables (GEMINI_CLI_OAUTH_PORT, ANTIGRAVITY_OAUTH_PORT, IFLOW_OAUTH_PORT)
- Implement dynamic port resolution with fallback to hardcoded defaults
- Add comprehensive documentation section explaining port configuration methods
- Integrate port settings into Settings Tool UI for easy configuration
- Update provider implementations to use configurable ports via property/function
- Optimize launcher TUI startup by deferring heavy provider imports to Settings Tool
- Add validation and warning logging for invalid port values

Configuration can be managed via TUI settings menu or `.env` file. Port changes take effect on next authentication attempt without affecting existing tokens.

DOCUMENTATION.md

@@ -856,6 +856,42 @@ class AntigravityAuthBase(GoogleOAuthBase):
 - Headless environment detection
 - Sequential refresh queue processing
 
+#### OAuth Callback Port Configuration
+
+Each OAuth provider uses a local callback server during authentication. The callback port can be customized via environment variables to avoid conflicts with other services.
+
+**Default Ports:**
+
+| Provider | Default Port | Environment Variable |
+|----------|-------------|---------------------|
+| Gemini CLI | 8085 | `GEMINI_CLI_OAUTH_PORT` |
+| Antigravity | 51121 | `ANTIGRAVITY_OAUTH_PORT` |
+| iFlow | 11451 | `IFLOW_OAUTH_PORT` |
+
+**Configuration Methods:**
+
+1. **Via TUI Settings Menu:**
+   - Main Menu → `4. View Provider & Advanced Settings` → `1. Launch Settings Tool`
+   - Select the provider (Gemini CLI, Antigravity, or iFlow)
+   - Modify the `*_OAUTH_PORT` setting
+   - Use "Reset to Default" to restore the original port
+
+2. **Via `.env` file:**
+   ```env
+   # Custom OAuth callback ports (optional)
+   GEMINI_CLI_OAUTH_PORT=8085
+   ANTIGRAVITY_OAUTH_PORT=51121
+   IFLOW_OAUTH_PORT=11451
+   ```
+
+**When to Change Ports:**
+
+- If the default port conflicts with another service on your system
+- If running multiple proxy instances on the same machine
+- If firewall rules require specific port ranges
+
+**Note:** Port changes take effect on the next OAuth authentication attempt. Existing tokens are not affected.
+
 ---
 
 
@@ -877,8 +913,8 @@ The `GeminiCliProvider` is the most complex implementation, mimicking the Google
 
 #### Authentication (`gemini_auth_base.py`)
 
- *   **Device Flow**: Uses a standard OAuth 2.0 flow. The `credential_tool` spins up a local web server (`localhost:8085`) to capture the callback from Google's auth page.
-*   **Token Lifecycle**:
+ *   **Device Flow**: Uses a standard OAuth 2.0 flow. The `credential_tool` spins up a local web server (default: `localhost:8085`, configurable via `GEMINI_CLI_OAUTH_PORT`) to capture the callback from Google's auth page.
+ *   **Token Lifecycle**:
     *   **Proactive Refresh**: Tokens are refreshed 5 minutes before expiry.
     *   **Atomic Writes**: Credential files are updated using a temp-file-and-move strategy to prevent corruption during writes.
     *   **Revocation Handling**: If a `400` or `401` occurs during refresh, the token is marked as revoked, preventing infinite retry loops.
@@ -907,7 +943,7 @@ The provider employs a sophisticated, cached discovery mechanism to find a valid
 ### 3.3. iFlow (`iflow_provider.py`)
 
 *   **Hybrid Auth**: Uses a custom OAuth flow (Authorization Code) to obtain an `access_token`. However, the *actual* API calls use a separate `apiKey` that is retrieved from the user's profile (`/api/oauth/getUserInfo`) using the access token.
-*   **Callback Server**: The auth flow spins up a local server on port `11451` to capture the redirect.
+*   **Callback Server**: The auth flow spins up a local server (default: port `11451`, configurable via `IFLOW_OAUTH_PORT`) to capture the redirect.
 *   **Token Management**: Automatically refreshes the OAuth token and re-fetches the API key if needed.
 *   **Schema Cleaning**: Similar to Qwen, it aggressively sanitizes tool schemas to prevent 400 errors.
 *   **Dedicated Logging**: Implements `_IFlowFileLogger` to capture raw chunks for debugging proprietary API behaviors.

src/proxy_app/launcher_tui.py

@@ -107,7 +107,7 @@ class SettingsDetector:
 
     @staticmethod
     def get_all_settings() -> dict:
-        """Returns comprehensive settings overview"""
+        """Returns comprehensive settings overview (includes provider_settings which triggers heavy imports)"""
         return {
             "credentials": SettingsDetector.detect_credentials(),
             "custom_bases": SettingsDetector.detect_custom_api_bases(),
@@ -117,6 +117,17 @@ class SettingsDetector:
             "provider_settings": SettingsDetector.detect_provider_settings(),
         }
 
+    @staticmethod
+    def get_basic_settings() -> dict:
+        """Returns basic settings overview without provider_settings (avoids heavy imports)"""
+        return {
+            "credentials": SettingsDetector.detect_credentials(),
+            "custom_bases": SettingsDetector.detect_custom_api_bases(),
+            "model_definitions": SettingsDetector.detect_model_definitions(),
+            "concurrency_limits": SettingsDetector.detect_concurrency_limits(),
+            "model_filters": SettingsDetector.detect_model_filters(),
+        }
+
     @staticmethod
     def detect_credentials() -> dict:
         """Detect API keys and OAuth credentials"""
@@ -277,8 +288,8 @@ class LauncherTUI:
         """Display main menu and handle selection"""
         clear_screen()
 
-        # Detect all settings
-        settings = SettingsDetector.get_all_settings()
+        # Detect basic settings (excludes provider_settings to avoid heavy imports)
+        settings = SettingsDetector.get_basic_settings()
         credentials = settings["credentials"]
         custom_bases = settings["custom_bases"]
 
@@ -363,18 +374,17 @@ class LauncherTUI:
         self.console.print("━" * 70)
         provider_count = len(credentials)
         custom_count = len(custom_bases)
-        provider_settings = settings.get("provider_settings", {})
+
+        self.console.print(f"   Providers:           {provider_count} configured")
+        self.console.print(f"   Custom Providers:    {custom_count} configured")
+        # Note: provider_settings detection is deferred to avoid heavy imports on startup
         has_advanced = bool(
             settings["model_definitions"]
             or settings["concurrency_limits"]
             or settings["model_filters"]
-            or provider_settings
         )
-
-        self.console.print(f"   Providers:           {provider_count} configured")
-        self.console.print(f"   Custom Providers:    {custom_count} configured")
         self.console.print(
-            f"   Advanced Settings:   {'Active (view in menu 4)' if has_advanced else 'None'}"
+            f"   Advanced Settings:   {'Active (view in menu 4)' if has_advanced else 'None (view menu 4 for details)'}"
         )
 
         # Show menu
@@ -659,13 +669,14 @@ class LauncherTUI:
         """Display provider/advanced settings (read-only + launch tool)"""
         clear_screen()
 
-        settings = SettingsDetector.get_all_settings()
+        # Use basic settings to avoid heavy imports - provider_settings deferred to Settings Tool
+        settings = SettingsDetector.get_basic_settings()
+
         credentials = settings["credentials"]
         custom_bases = settings["custom_bases"]
         model_defs = settings["model_definitions"]
         concurrency = settings["concurrency_limits"]
         filters = settings["model_filters"]
-        provider_settings = settings.get("provider_settings", {})
 
         self.console.print(
             Panel.fit(
@@ -740,23 +751,13 @@ class LauncherTUI:
                 status = " + ".join(status_parts) if status_parts else "None"
                 self.console.print(f"   • {provider:15} ✅ {status}")
 
-        # Provider-Specific Settings
+        # Provider-Specific Settings (deferred to Settings Tool to avoid heavy imports)
         self.console.print()
         self.console.print("[bold]🔬 Provider-Specific Settings[/bold]")
         self.console.print("━" * 70)
-        try:
-            from proxy_app.settings_tool import PROVIDER_SETTINGS_MAP
-        except ImportError:
-            from .settings_tool import PROVIDER_SETTINGS_MAP
-        for provider in PROVIDER_SETTINGS_MAP.keys():
-            display_name = provider.replace("_", " ").title()
-            modified = provider_settings.get(provider, 0)
-            if modified > 0:
-                self.console.print(
-                    f"   • {display_name:20} [yellow]{modified} setting{'s' if modified > 1 else ''} modified[/yellow]"
-                )
-            else:
-                self.console.print(f"   • {display_name:20} [dim]using defaults[/dim]")
+        self.console.print(
+            "   [dim]Launch Settings Tool to view/configure provider-specific settings[/dim]"
+        )
 
         # Actions
         self.console.print()
@@ -827,7 +828,23 @@ class LauncherTUI:
 
     def launch_settings_tool(self):
         """Launch settings configuration tool"""
-        from proxy_app.settings_tool import run_settings_tool
+        import time
+
+        clear_screen()
+
+        self.console.print("━" * 70)
+        self.console.print("Advanced Settings Configuration Tool")
+        self.console.print("━" * 70)
+
+        _start_time = time.time()
+
+        with self.console.status("Initializing settings tool...", spinner="dots"):
+            from proxy_app.settings_tool import run_settings_tool
+
+        _elapsed = time.time() - _start_time
+        self.console.print(f"✓ Settings tool ready in {_elapsed:.2f}s")
+
+        time.sleep(0.3)
 
         run_settings_tool()
         # Reload environment after settings tool

src/proxy_app/settings_tool.py

@@ -14,6 +14,29 @@ from dotenv import set_key, unset_key
 
 console = Console()
 
+# Import default OAuth port values from provider modules
+# These serve as the source of truth for default port values
+try:
+    from rotator_library.providers.gemini_auth_base import GeminiAuthBase
+
+    GEMINI_CLI_DEFAULT_OAUTH_PORT = GeminiAuthBase.CALLBACK_PORT
+except ImportError:
+    GEMINI_CLI_DEFAULT_OAUTH_PORT = 8085
+
+try:
+    from rotator_library.providers.antigravity_auth_base import AntigravityAuthBase
+
+    ANTIGRAVITY_DEFAULT_OAUTH_PORT = AntigravityAuthBase.CALLBACK_PORT
+except ImportError:
+    ANTIGRAVITY_DEFAULT_OAUTH_PORT = 51121
+
+try:
+    from rotator_library.providers.iflow_auth_base import (
+        CALLBACK_PORT as IFLOW_DEFAULT_OAUTH_PORT,
+    )
+except ImportError:
+    IFLOW_DEFAULT_OAUTH_PORT = 11451
+
 
 def clear_screen():
     """
@@ -383,6 +406,11 @@ ANTIGRAVITY_SETTINGS = {
         "default": "\n\nSTRICT PARAMETERS: {params}.",
         "description": "Template for Claude strict parameter hints in tool descriptions",
     },
+    "ANTIGRAVITY_OAUTH_PORT": {
+        "type": "int",
+        "default": ANTIGRAVITY_DEFAULT_OAUTH_PORT,
+        "description": "Local port for OAuth callback server during authentication",
+    },
 }
 
 # Gemini CLI provider environment variables
@@ -427,12 +455,27 @@ GEMINI_CLI_SETTINGS = {
         "default": "",
         "description": "GCP Project ID for paid tier users (required for paid tiers)",
     },
+    "GEMINI_CLI_OAUTH_PORT": {
+        "type": "int",
+        "default": GEMINI_CLI_DEFAULT_OAUTH_PORT,
+        "description": "Local port for OAuth callback server during authentication",
+    },
+}
+
+# iFlow provider environment variables
+IFLOW_SETTINGS = {
+    "IFLOW_OAUTH_PORT": {
+        "type": "int",
+        "default": IFLOW_DEFAULT_OAUTH_PORT,
+        "description": "Local port for OAuth callback server during authentication",
+    },
 }
 
 # Map provider names to their settings definitions
 PROVIDER_SETTINGS_MAP = {
     "antigravity": ANTIGRAVITY_SETTINGS,
     "gemini_cli": GEMINI_CLI_SETTINGS,
+    "iflow": IFLOW_SETTINGS,
 }
 
 

src/rotator_library/providers/google_oauth_base.py

@@ -54,6 +54,25 @@ class GoogleOAuthBase:
     CALLBACK_PATH: str = "/oauth2callback"
     REFRESH_EXPIRY_BUFFER_SECONDS: int = 30 * 60  # 30 minutes
 
+    @property
+    def callback_port(self) -> int:
+        """
+        Get the OAuth callback port, checking environment variable first.
+
+        Reads from {ENV_PREFIX}_OAUTH_PORT environment variable, falling back
+        to the class's CALLBACK_PORT default if not set.
+        """
+        env_var = f"{self.ENV_PREFIX}_OAUTH_PORT"
+        env_value = os.getenv(env_var)
+        if env_value:
+            try:
+                return int(env_value)
+            except ValueError:
+                lib_logger.warning(
+                    f"Invalid {env_var} value: {env_value}, using default {self.CALLBACK_PORT}"
+                )
+        return self.CALLBACK_PORT
+
     def __init__(self):
         # Validate that subclass has set required attributes
         if self.CLIENT_ID is None:
@@ -701,14 +720,14 @@ class GoogleOAuthBase:
 
         try:
             server = await asyncio.start_server(
-                handle_callback, "127.0.0.1", self.CALLBACK_PORT
+                handle_callback, "127.0.0.1", self.callback_port
             )
             from urllib.parse import urlencode
 
             auth_url = "https://accounts.google.com/o/oauth2/v2/auth?" + urlencode(
                 {
                     "client_id": self.CLIENT_ID,
-                    "redirect_uri": f"http://localhost:{self.CALLBACK_PORT}{self.CALLBACK_PATH}",
+                    "redirect_uri": f"http://localhost:{self.callback_port}{self.CALLBACK_PATH}",
                     "scope": " ".join(self.OAUTH_SCOPES),
                     "access_type": "offline",
                     "response_type": "code",
@@ -783,7 +802,7 @@ class GoogleOAuthBase:
                     "code": auth_code.strip(),
                     "client_id": self.CLIENT_ID,
                     "client_secret": self.CLIENT_SECRET,
-                    "redirect_uri": f"http://localhost:{self.CALLBACK_PORT}{self.CALLBACK_PATH}",
+                    "redirect_uri": f"http://localhost:{self.callback_port}{self.CALLBACK_PATH}",
                     "grant_type": "authorization_code",
                 },
             )

src/rotator_library/providers/iflow_auth_base.py

@@ -39,6 +39,25 @@ IFLOW_CLIENT_SECRET = "4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW"
 # Local callback server port
 CALLBACK_PORT = 11451
 
+
+def get_callback_port() -> int:
+    """
+    Get the OAuth callback port, checking environment variable first.
+
+    Reads from IFLOW_OAUTH_PORT environment variable, falling back
+    to the default CALLBACK_PORT if not set.
+    """
+    env_value = os.getenv("IFLOW_OAUTH_PORT")
+    if env_value:
+        try:
+            return int(env_value)
+        except ValueError:
+            logging.getLogger("rotator_library").warning(
+                f"Invalid IFLOW_OAUTH_PORT value: {env_value}, using default {CALLBACK_PORT}"
+            )
+    return CALLBACK_PORT
+
+
 # Refresh tokens 24 hours before expiry
 REFRESH_EXPIRY_BUFFER_SECONDS = 24 * 60 * 60
 
@@ -931,7 +950,8 @@ class IFlowAuthBase:
         state = secrets.token_urlsafe(32)
 
         # Build authorization URL
-        redirect_uri = f"http://localhost:{CALLBACK_PORT}/oauth2callback"
+        callback_port = get_callback_port()
+        redirect_uri = f"http://localhost:{callback_port}/oauth2callback"
         auth_params = {
             "loginMethod": "phone",
             "type": "phone",
@@ -942,7 +962,7 @@ class IFlowAuthBase:
         auth_url = f"{IFLOW_OAUTH_AUTHORIZE_ENDPOINT}?{urlencode(auth_params)}"
 
         # Start OAuth callback server
-        callback_server = OAuthCallbackServer(port=CALLBACK_PORT)
+        callback_server = OAuthCallbackServer(port=callback_port)
         try:
             await callback_server.start(expected_state=state)