feat(llm): hide api_key from all API responses and document max_tokens as reserved

Security Enhancement:
   - API keys are now always filtered to null in all LLM config API responses
   - Created LLMModelConfigDataWithoutSecret schema for response validation
   - Added _filter_api_key_from_config() helper in API routes
   - Modified repository to always hide api_key in get_user_effective_configs()
   - Update/create operations still accept and store api_key securely

   Documentation Updates:
   - Updated API key visibility section to reflect new security policy
   - Updated all response examples to show api_key as null
   - Marked max_tokens field as reserved for future use
   - Added "Reserved Fields" section explaining unused fields

   This defense-in-depth approach prevents API keys from being leaked through
   logs, browser devtools, or network monitoring.

gns3server/api/routes/controller/llm_model_configs.py

@@ -41,6 +41,21 @@ log = logging.getLogger(__name__)
 
 router = APIRouter()
 
+
+def _filter_api_key_from_config(config: dict) -> dict:
+    """
+    Remove API key from config dict for security.
+    API keys should NEVER be returned via API endpoints.
+
+    :param config: Configuration dictionary
+    :return: Configuration dictionary with api_key set to None
+    """
+    filtered = config.copy()
+    if "api_key" in filtered:
+        filtered["api_key"] = None
+    return filtered
+
+
 # ============================================================================
 # User LLM Model Configuration Endpoints
 # ============================================================================
@@ -101,7 +116,7 @@ async def get_user_own_llm_model_configs(
                 config_id=config.config_id,
                 name=config.name,
                 model_type=config.model_type,
-                config=config.config,
+                config=_filter_api_key_from_config(config.config),
                 user_id=config.user_id,
                 group_id=config.group_id,
                 is_default=config.is_default,
@@ -146,7 +161,7 @@ async def get_user_default_llm_model_config(
             config_id=config.config_id,
             name=config.name,
             model_type=config.model_type,
-            config=config.config,
+            config=_filter_api_key_from_config(config.config),
             user_id=config.user_id,
             group_id=config.group_id,
             is_default=config.is_default,
@@ -213,7 +228,7 @@ async def create_user_llm_model_config(
             config_id=new_config.config_id,
             name=new_config.name,
             model_type=new_config.model_type,
-            config=new_config.config,
+            config=_filter_api_key_from_config(new_config.config),
             user_id=new_config.user_id,
             group_id=new_config.group_id,
             is_default=new_config.is_default,
@@ -273,7 +288,7 @@ async def update_user_llm_model_config(
             config_id=updated_config.config_id,
             name=updated_config.name,
             model_type=updated_config.model_type,
-            config=updated_config.config,
+            config=_filter_api_key_from_config(updated_config.config),
             user_id=updated_config.user_id,
             group_id=updated_config.group_id,
             is_default=updated_config.is_default,
@@ -362,7 +377,7 @@ async def set_user_default_llm_model_config(
             config_id=config.config_id,
             name=config.name,
             model_type=config.model_type,
-            config=config.config,
+            config=_filter_api_key_from_config(config.config),
             user_id=config.user_id,
             group_id=config.group_id,
             is_default=config.is_default,
@@ -406,7 +421,7 @@ async def get_group_llm_model_configs(
                 config_id=config.config_id,
                 name=config.name,
                 model_type=config.model_type,
-                config=config.config,
+                config=_filter_api_key_from_config(config.config),
                 user_id=config.user_id,
                 group_id=config.group_id,
                 is_default=config.is_default,
@@ -468,7 +483,7 @@ async def get_group_default_llm_model_config(
             config_id=config.config_id,
             name=config.name,
             model_type=config.model_type,
-            config=config.config,
+            config=_filter_api_key_from_config(config.config),
             user_id=config.user_id,
             group_id=config.group_id,
             is_default=config.is_default,
@@ -535,7 +550,7 @@ async def create_group_llm_model_config(
             config_id=new_config.config_id,
             name=new_config.name,
             model_type=new_config.model_type,
-            config=new_config.config,
+            config=_filter_api_key_from_config(new_config.config),
             user_id=new_config.user_id,
             group_id=new_config.group_id,
             is_default=new_config.is_default,
@@ -595,7 +610,7 @@ async def update_group_llm_model_config(
             config_id=updated_config.config_id,
             name=updated_config.name,
             model_type=updated_config.model_type,
-            config=updated_config.config,
+            config=_filter_api_key_from_config(updated_config.config),
             user_id=updated_config.user_id,
             group_id=updated_config.group_id,
             is_default=updated_config.is_default,
@@ -684,7 +699,7 @@ async def set_group_default_llm_model_config(
             config_id=config.config_id,
             name=config.name,
             model_type=config.model_type,
-            config=config.config,
+            config=_filter_api_key_from_config(config.config),
             user_id=config.user_id,
             group_id=config.group_id,
             is_default=config.is_default,

gns3server/db/repositories/llm_model_configs.py

@@ -31,6 +31,20 @@ log = logging.getLogger(__name__)
 class LLMModelConfigsRepository(BaseRepository):
     """Repository for LLM model configurations with inheritance support."""
 
+    @staticmethod
+    def _hide_api_key(config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Remove API key from config dict for security.
+        API keys should NEVER be returned via API endpoints.
+
+        :param config: Configuration dictionary
+        :return: Configuration dictionary with api_key set to None
+        """
+        config_copy = config.copy()
+        if "api_key" in config_copy:
+            config_copy["api_key"] = None
+        return config_copy
+
     # User configuration methods
 
     async def get_user_config(self, config_id: UUID) -> Optional[models.LLMModelConfig]:
@@ -409,15 +423,8 @@ class LLMModelConfigsRepository(BaseRepository):
         Get user's effective configurations (own + inherited from groups).
         Returns a dict with 'configs' list and 'default_config'.
 
-        API key visibility rules:
-        - Users viewing own configs: CAN see API keys in user configs, CANNOT see API keys in group configs
-        - Admins viewing other users' configs: CANNOT see ANY API keys
+        API key visibility: ALWAYS hidden for security (never returned via API).
         """
-        from gns3server.utils.encryption import decrypt, is_encrypted
-
-        # Determine if current user is viewing their own configs
-        is_viewing_own = current_user_id == user_id if current_user_id else False
-
         # Get user's own configs
         user_configs = await self.get_user_configs(user_id)
 
@@ -437,26 +444,14 @@ class LLMModelConfigsRepository(BaseRepository):
                 group_configs_map[group.user_group_id] = configs
                 group_names_map[group.user_group_id] = group.name
 
-        # Decrypt API keys and build result
+        # Build result with API keys always hidden
         configs_with_source = []
         default_config = None
 
         # Add user's configs
         for config in user_configs:
-            config_dict = config.config.copy()
-
-            # API key visibility: only show if viewing own configs
-            if "api_key" in config_dict and config_dict["api_key"]:
-                if is_viewing_own:
-                    try:
-                        if is_encrypted(config_dict["api_key"]):
-                            config_dict["api_key"] = decrypt(config_dict["api_key"])
-                    except Exception as e:
-                        log.warning(f"Failed to decrypt API key for config {config.config_id}: {e}")
-                        config_dict["api_key"] = None
-                else:
-                    # Hide API key for admins viewing other users' configs
-                    config_dict["api_key"] = None
+            # Always hide API key for security
+            config_dict = self._hide_api_key(config.config)
 
             configs_with_source.append({
                 "config_id": config.config_id,
@@ -476,11 +471,8 @@ class LLMModelConfigsRepository(BaseRepository):
         # Add inherited group configs (always shown, regardless of user configs)
         for group_id, configs in group_configs_map.items():
             for config in configs:
-                config_dict = config.config.copy()
-
-                # API key visibility: NEVER show API keys from inherited group configs
-                if "api_key" in config_dict and config_dict["api_key"]:
-                    config_dict["api_key"] = None
+                # Always hide API key for security
+                config_dict = self._hide_api_key(config.config)
 
                 configs_with_source.append({
                     "config_id": config.config_id,

gns3server/schemas/controller/llm_model_configs.py

@@ -133,14 +133,39 @@ class LLMModelConfigUpdate(BaseModel):
         return v
 
 
+# Response schema without API key (for security)
+class LLMModelConfigDataWithoutSecret(BaseModel):
+    """LLM model configuration data WITHOUT sensitive information."""
+
+    provider: str = Field(..., description="LLM provider (e.g., 'openai', 'anthropic', 'ollama')")
+    base_url: str = Field(..., description="API base URL")
+    model: str = Field(..., description="Model name")
+    temperature: float = Field(default=0.7, ge=0.0, le=2.0, description="Temperature parameter")
+    api_key: Optional[str] = Field(None, description="API key (always hidden in API responses)")
+    max_tokens: Optional[int] = Field(None, gt=0, description="Max tokens for generation")
+    context_limit: int = Field(
+        ..., gt=0, description="Model context window limit in K tokens (e.g., 128 = 128K tokens)"
+    )
+    context_strategy: Literal["conservative", "balanced", "aggressive"] = Field(
+        "balanced", description="Context trimming strategy: conservative (60%), balanced (75%), aggressive (85%)"
+    )
+    copilot_mode: Optional[str] = Field(
+        None,
+        description="GNS3-Copilot mode: 'teaching_assistant' or 'lab_automation_assistant'"
+    )
+
+    # Allow extra fields for extensibility
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
 # Response schemas
 class LLMModelConfigResponse(DateTimeModelMixin):
-    """LLM model configuration response."""
+    """LLM model configuration response (without API key for security)."""
 
     config_id: UUID
     name: str
     model_type: ModelType
-    config: LLMModelConfigData
+    config: LLMModelConfigDataWithoutSecret
     user_id: Optional[UUID] = None
     group_id: Optional[UUID] = None
     is_default: bool
@@ -150,12 +175,12 @@ class LLMModelConfigResponse(DateTimeModelMixin):
 
 
 class LLMModelConfigWithSource(DateTimeModelMixin):
-    """Model configuration with source information (for inheritance)."""
+    """Model configuration with source information (for inheritance, without API key for security)."""
 
     config_id: UUID
     name: str
     model_type: ModelType
-    config: LLMModelConfigData
+    config: LLMModelConfigDataWithoutSecret
     user_id: Optional[UUID] = None
     group_id: Optional[UUID] = None
     is_default: bool