Merge branch 'main' into fix/rust-validation-middleware-sidecar

Author: lucarlig

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "(^.secrets.baseline$|(^|/)Cargo\\.lock$)",
     "lines": null
   },
-  "generated_at": "2026-04-08T10:09:48Z",
+  "generated_at": "2026-04-08T09:51:23Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -242,63 +242,63 @@
         "hashed_secret": "b4673e578b9b30fe8bba1b555b7b59883444c697",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 487,
+        "line_number": 555,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "4a0a2df96d4c9a13a282268cab33ac4b8cbb2c72",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 575,
+        "line_number": 643,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 925,
+        "line_number": 993,
         "type": "Basic Auth Credentials",
         "verified_result": null
       },
       {
         "hashed_secret": "fa9beb99e4029ad5a6615399e7bbae21356086b3",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2291,
+        "line_number": 2359,
         "type": "Basic Auth Credentials",
         "verified_result": null
       },
       {
         "hashed_secret": "fa9beb99e4029ad5a6615399e7bbae21356086b3",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2382,
+        "line_number": 2450,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "ac371b6dcce28a86c90d12bc57d946a800eebf17",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2425,
+        "line_number": 2493,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "0b6ec68df700dec4dcd64babd0eda1edccddace1",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2430,
+        "line_number": 2498,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "4ad6f0082ee224001beb3ca5c3e81c8ceea5ed86",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 2435,
+        "line_number": 2503,
         "type": "Secret Keyword",
         "verified_result": null
       }
@@ -1452,15 +1452,15 @@
         "hashed_secret": "38297d822c960daea26f148a2fede848dcc2083b",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 619,
+        "line_number": 711,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "7373eb3c8f036e7f058bfc66fc27870f01231645",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 1261,
+        "line_number": 1440,
         "type": "Secret Keyword",
         "verified_result": null
       }

CHANGELOG.md

@@ -2,6 +2,74 @@
 
 > All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project **adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)**.
 
+## [UNRELEASED] - BREAKING CHANGE
+
+### ⚠️ Breaking Changes
+
+#### **🔌 Plugin Condition Evaluation: Hybrid AND/OR Logic** ([#3930](https://github.com/IBM/mcp-context-forge/issues/3930))
+
+**Action Required**: Plugin condition evaluation has changed from pure OR logic to hybrid AND/OR logic.
+
+**Previous Behavior (OR Logic):**
+- ANY field match in ANY condition triggered plugin execution
+- Example: `tenant_ids: ["healthcare"], tools: ["patient_reader"]` executed if tenant=healthcare **OR** tool=patient_reader
+
+**New Behavior (Hybrid AND/OR Logic):**
+- **Within a condition object:** ALL fields must match (AND logic)
+- **Across condition objects:** ANY object can match (OR logic)
+- Example: `tenant_ids: ["healthcare"], tools: ["patient_reader"]` executes ONLY if tenant=healthcare **AND** tool=patient_reader
+
+**Impact:**
+- Plugins with multiple fields in a single condition object will have different execution behavior
+- Security policies become more precise and restrictive by default
+- Enables defense-in-depth with multiple required conditions
+
+**Migration Steps:**
+
+1. **Audit Configuration**: Run the validation script to identify affected plugins
+   ```bash
+   python scripts/validate_plugin_conditions.py
+   ```
+
+2. **Redesign Conditions**: For each flagged plugin, determine desired behavior:
+   - **AND logic desired**: Keep fields in same object (no YAML changes needed)
+   - **OR logic desired**: Split fields into separate condition objects
+
+3. **Test Thoroughly**: Validate new behavior in non-production environment with debug logging
+   ```bash
+   LOG_LEVEL=DEBUG python -m mcpgateway.main
+   ```
+
+**Example Migration:**
+
+```yaml
+# OLD: Executed if tenant=healthcare OR tool=patient_reader
+conditions:
+  - tenant_ids: ["healthcare"]
+    tools: ["patient_reader"]
+
+# NEW Option 1: AND logic (more secure, no YAML change)
+conditions:
+  - tenant_ids: ["healthcare"]
+    tools: ["patient_reader"]
+# Executes ONLY if tenant=healthcare AND tool=patient_reader
+
+# NEW Option 2: OR logic (split into separate objects)
+conditions:
+  - tenant_ids: ["healthcare"]
+  - tools: ["patient_reader"]
+# Executes if tenant=healthcare OR tool=patient_reader
+```
+
+**Resources:**
+- **Migration Guide**: `docs/docs/architecture/MIGRATION-PLUGIN-CONDITIONS.md`
+- **Validation Script**: `scripts/validate_plugin_conditions.py`
+- **Architecture Docs**: `docs/docs/architecture/plugins.md#plugin-condition-evaluation`
+
+**Rollback**: Keep configuration backups. Restore previous `plugins/config.yaml` if issues arise.
+
+
+
 ## [1.0.0] - 2026-03-31 - General Availability
 
 ### Overview

docs/docs/architecture/plugins.md

@@ -1,3 +1,4 @@
+
 # Plugin Framework Specification
 
 **Version**: 1.0
@@ -257,6 +258,97 @@ The `conditions` array contains objects that specify when plugins should execute
 | `user_patterns` | `string[]` | Execute for users matching regex patterns | `["admin_.*", ".*@company.com"]` |
 | `content_types` | `string[]` | Execute for specific content types | `["application/json", "text/plain"]` |
 
+The plugin framework uses **hybrid AND/OR condition evaluation** for precise control over plugin execution.
+
+#### Evaluation Logic
+
+**Behavior:**
+- **Within a condition object**: ALL fields must match (AND logic)
+- **Across condition objects**: ANY object can match (OR logic)
+
+This enables expressions like: `(tenant=X AND tool=Y) OR (server=Z AND user=W)`
+
+**Evaluation Order within each condition object:**
+1. GlobalContext conditions (server_id, tenant_id, user_patterns)
+2. Payload-specific conditions (tools, prompts, resources, agents)
+
+**Short-circuit:**
+- Within a condition object: Evaluation stops at the first non-matching field (fail-fast)
+- Across condition objects: Evaluation stops at the first fully matching object (first-match-wins)
+
+#### Configuration Examples
+
+#### Single Condition Object
+
+```yaml
+plugins:
+  - name: "TenantFilter"
+    conditions:
+      - tenant_ids: ["healthcare", "finance"]
+    # Executes ONLY for healthcare OR finance tenants
+```
+
+#### Multiple Fields in Single Condition (AND Logic)
+
+```yaml
+plugins:
+  - name: "PIIFilterPlugin"
+    conditions:
+      - tenant_ids: ["healthcare"]
+        tools: ["patient_data_reader"]
+        server_ids: ["prod-server"]
+    # Executes ONLY when ALL match:
+    # - tenant = healthcare AND
+    # - tool = patient_data_reader AND
+    # - server = prod-server
+```
+
+#### Multiple Condition Objects (OR Logic)
+
+```yaml
+plugins:
+  - name: "SecurityPlugin"
+    conditions:
+      - tenant_ids: ["enterprise"]
+        tools: ["sensitive_tool"]
+      - server_ids: ["prod-server"]
+        user_patterns: ["admin_.*"]
+    # Executes when:
+    # (tenant=enterprise AND tool=sensitive_tool) OR
+    # (server=prod-server AND user matches admin_.*)
+    #
+    # This means the plugin runs if EITHER:
+    # - Request is from enterprise tenant using sensitive_tool, OR
+    # - Request is on prod-server from a user matching admin_.*
+```
+
+### Use Cases
+
+| Scenario | Configuration Pattern |
+|----------|----------------------|
+| Tenant-specific plugin | `tenant_ids: ["tenant1"]` |
+| Tool-specific security | `tools: ["sensitive_tool"]` |
+| Multi-factor control | `tenant_ids: [...], tools: [...], user_patterns: [...]` (all in one object) |
+| Production-only | `server_ids: ["prod-server"]` |
+| Admin-only operations | `user_patterns: ["admin_.*"]` |
+| Multiple independent scenarios | Multiple condition objects with different field combinations |
+
+#### Debugging Condition Evaluation
+
+Enable debug logging to see condition evaluation details:
+
+```bash
+LOG_LEVEL=DEBUG python -m mcpgateway.main
+```
+
+Log output includes:
+- Number of condition objects being evaluated
+- Which condition object is being checked (1/N, 2/N, etc.)
+- GlobalContext mismatch details (server_id, tenant_id, user)
+- Payload mismatch details (tool name, prompt_id, etc.)
+- Success message when condition fully matches
+- Final execution decision (execute or skip)
+
 #### MCP Configuration Fields
 
 For external plugins (`kind: "external"`), the `mcp` object configures the MCP server connection:
@@ -1010,6 +1102,93 @@ class PluginCondition(BaseModel):
     content_types: Optional[list[str]] = None  # Execute for specific content types
 ```
 
+#### Content Type Filtering
+
+Plugins can be configured to execute only for specific content types using the `content_types` condition. This enables fine-grained control over when plugins process requests based on the HTTP `Content-Type` header.
+
+**Configuration Example:**
+
+```yaml
+plugins:
+  - name: "JsonValidator"
+    kind: "plugins.json_validator.JsonValidator"
+    hooks: ["tool_pre_invoke"]
+    conditions:
+      - content_types: ["application/json"]
+```
+
+**Matching Behavior:**
+
+- **Case-insensitive**: `APPLICATION/JSON` matches `application/json`
+- **Parameter stripping**: `application/json; charset=utf-8` matches `application/json`
+- **Multiple types**: Supports OR logic - plugin executes if any content type matches
+- **Permissive default**: If `content_types` is not specified or request has no Content-Type header, plugin executes normally
+
+**Common Content Types:**
+
+| Content Type | Description | Use Case |
+|--------------|-------------|----------|
+| `application/json` | JSON data | API requests, structured data validation |
+| `text/plain` | Plain text | Simple text processing, logging |
+| `text/html` | HTML documents | Web scraping, content extraction |
+| `application/xml` | XML data | Legacy API integration, SOAP services |
+| `multipart/form-data` | File uploads | File validation, virus scanning |
+| `application/x-www-form-urlencoded` | Form submissions | Form data validation |
+
+**Example: JSON-Only Security Plugin**
+
+```yaml
+plugins:
+  - name: "JsonSecurityScanner"
+    kind: "plugins.security.json_scanner.JsonSecurityScanner"
+    hooks: ["tool_pre_invoke", "tool_post_invoke"]
+    mode: "enforce"
+    priority: 10
+    conditions:
+      - content_types: ["application/json"]
+        server_ids: ["production-api"]
+```
+
+**Example: Multi-Format Data Validator**
+
+```yaml
+plugins:
+  - name: "DataValidator"
+    kind: "plugins.validation.data_validator.DataValidator"
+    hooks: ["tool_pre_invoke"]
+    conditions:
+      - content_types:
+          - "application/json"
+          - "application/xml"
+          - "text/csv"
+```
+
+**Combined Conditions:**
+
+Content type filtering works seamlessly with other conditions:
+
+```yaml
+plugins:
+  - name: "TeamJsonProcessor"
+    kind: "plugins.processors.json_processor.JsonProcessor"
+    hooks: ["tool_pre_invoke"]
+    conditions:
+      - content_types: ["application/json"]
+        tenant_ids: ["team-alpha", "team-beta"]
+        tools: ["data_analysis", "report_generation"]
+```
+
+**Security Considerations:**
+
+!!! warning "Content-Type Spoofing"
+    Clients can set arbitrary Content-Type headers. Use `content_types` for filtering and optimization, not as a security boundary. Combine with other conditions (server_ids, tenant_ids) for defense-in-depth.
+
+**Performance Benefits:**
+
+- **Reduced overhead**: Skip expensive processing for irrelevant content types
+- **Targeted validation**: Apply format-specific validators only when needed
+- **Resource optimization**: Prevent unnecessary plugin execution
+
 ## Hook Reference Documentation
 
 The plugin framework provides two main categories of hooks, each documented in detail in separate files: