feat: add Allowed Request Types plugin to control request processing

[roh26it]

This pull request introduces a new guardrail plugin, allowedRequestTypes, which provides fine-grained control over which request types (endpoints) can be processed. The plugin supports both allowlist and blocklist approaches, can be configured via parameters or metadata, and is integrated into the plugin system for use in request validation.

New Guardrail Plugin: Allowed Request Types

• Added allowedRequestTypes plugin implementation in plugins/default/allowedRequestTypes.ts, supporting allowlist, blocklist, and combined modes, with conflict detection and detailed explanations. The plugin can read configuration from parameters or metadata and returns a verdict on whether a request type is permitted.

Manifest and Plugin System Integration

• Registered the new allowedRequestTypes guardrail in plugins/default/manifest.json with a comprehensive parameter schema and descriptions for configuration via UI or metadata.
• Imported and exposed the allowedRequestTypes handler in the plugin index (plugins/index.ts), making it available as part of the default plugin set. [1] [2]

[matter-code-review]

Summary By MatterAI

🔄 What Changed

This pull request introduces a new allowedRequestTypes plugin. This plugin enables granular control over request processing by defining allowed and blocked request types. It supports configuring these restrictions via plugin parameters (allowedTypes, blockedTypes) or context metadata (supported_endpoints, blocked_endpoints), with parameters taking precedence. The plugin handles both array and comma-separated string inputs for type lists, detects conflicts between allowed and blocked lists, and provides detailed explanations for its verdict. The default.test.ts file has been updated with extensive unit tests for the new plugin, and plugins/index.ts registers the new plugin.

🔍 Impact of the Change

This new plugin significantly enhances the system's ability to enforce security policies and manage resource usage by restricting which types of requests are processed. It provides a flexible and configurable mechanism to prevent unauthorized or unintended API calls, improving overall system robustness and control. The detailed explanations returned by the plugin will aid in debugging and understanding policy enforcement.

📁 Total Files Changed

• plugins/default/allowedRequestTypes.ts: New plugin implementation for controlling request types.
• plugins/default/default.test.ts: Added comprehensive unit tests for the allowedRequestTypes plugin.
• plugins/index.ts: Registered the new allowedRequestTypes plugin.

🧪 Test Added

Extensive unit tests were added for the Allowed Request Types Plugin in default.test.ts. These tests cover:

• Allowing requests when the type is in the allowed list (from parameters).
• Rejecting requests when the type is not in the allowed list.
• Handling comma-separated strings for allowedTypes in parameters.
• Handling streaming request types correctly.
• Using metadata (supported_endpoints) when parameters are not provided.
• Handling comma-separated strings for supported_endpoints in metadata.
• Prioritizing parameters over metadata for allowed types.
• Default behavior: allowing all request types when no restrictions are configured.
• Error handling for missing requestType in context.
• Complex scenarios with multiple allowed types and rejection for unlisted types.
• Handling various endpoint types from PluginContext interface.
• Blocking request types specified in the blockedTypes list (from parameters).
• Allowing request types not in the blocklist.
• Handling comma-separated strings for blockedTypes in parameters.
• Using blocked_endpoints from metadata.
• Prioritizing parameter blockedTypes over metadata.
• Combining allowedTypes and blockedTypes without conflicts.
• Blocking types in the blocklist even if they appear in the allowlist (blocklist precedence).
• Erroring when conflicts exist between allowedTypes and blockedTypes.
• Handling blocklist with streaming endpoints.

🔒Security Vulnerabilities

No new security vulnerabilities were introduced. The plugin itself is a security enhancement, providing a mechanism to restrict request types, thereby reducing the attack surface.

Motivation

To provide a flexible and configurable mechanism to control and restrict the types of requests processed by the system, enhancing security and operational control.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)

How Has This Been Tested?

• Unit Tests
• Integration Tests
• Manual Testing

Screenshots (if applicable)

N/A

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Related Issues

.

Tip

Quality Recommendations

1. Add JSDoc comments to the handler function and its parameters in allowedRequestTypes.ts for improved documentation and maintainability.

2. Extract the split(',').map((t: string) => t.trim()) logic into a reusable helper function to reduce code duplication and improve readability.

3. Consider refining test contexts to avoid type assertions like (mockContext as any).requestType for better type safety in tests.

Tanka Poem ♫

New rules now take hold,
Requests flow, or are denied,
Order in the code.
Security's firm embrace,
Logic's shield, a silent grace. 🛡️

Sequence Diagram

sequenceDiagram
    participant Caller as System Caller
    participant Plugin as AllowedRequestTypesPlugin

    Note over Caller,Plugin: Request processing initiated

    Caller->>Plugin: handler(context, parameters, eventType)
    Note over Plugin: context: {requestType, metadata}, parameters: {allowedTypes, blockedTypes}

    Plugin->>Plugin: Parse allowedTypes from parameters or metadata
    Plugin->>Plugin: Parse blockedTypes from parameters or metadata

    alt Conflict Detected (allowedTypes ∩ blockedTypes ≠ ∅)
        Plugin-->>Caller: { error: ConflictError, verdict: false, data: {explanation} }
    else No Conflict
        Plugin->>Plugin: Determine verdict based on requestType, allowedTypes, blockedTypes
        alt Request Allowed
            Plugin-->>Caller: { error: null, verdict: true, data: {explanation} }
        else Request Blocked
            Plugin-->>Caller: { error: null, verdict: false, data: {explanation} }
        end
    end

    Note over Caller,Plugin: Plugin execution complete

Loading

[matter-code-review]

Added new plugin to control request processing based on allowed/blocked types with comprehensive test coverage.

Skipped files

• plugins/default/manifest.json: Skipped file pattern

[matter-code-review]

🛠️ Code Refactor

Issue: Redundant check for allowedTypes.length > 0 in ternary condition.
Fix: Simplify the condition by removing redundant check.
Impact: Improves code readability and reduces complexity.

Suggested change

	...(allowedTypes.length > 0
	? { allowedTypes }
	: mode === 'unrestricted'
	? { allowedTypes: ['all'] }
	: {}),
	? { allowedTypes }
	: { allowedTypes: ['all'] },

[matter-code-review]

Added new plugin to control request processing based on allowed/blocked types with comprehensive test coverage.

[matter-code-review]

🛠️ Code Refactor

Issue: Redundant check for allowedTypes.length > 0 in ternary condition.
Fix: Simplify the condition by removing redundant check.
Impact: Improves code readability and reduces complexity.

Suggested change

	...(allowedTypes.length > 0
	? { allowedTypes }
	: mode === 'unrestricted'
	? { allowedTypes: ['all'] }
	: {}),
	? { allowedTypes }
	: { allowedTypes: ['all'] },