Description

Summary By MatterAI

🔄 What Changed

This pull request introduces a new metadata guardrail plugin. This plugin allows for enforcing policies based on key-value pairs present in the request context's metadata. It supports 'any', 'all', and 'none' operators for matching, along with a 'not' flag for negation. New unit tests have been added to default.test.ts to cover various scenarios for this new handler.

🔍 Impact of the Change

This new plugin enhances the system's ability to apply fine-grained access control or routing logic based on custom metadata attached to requests. It provides a flexible and configurable way to validate metadata, improving the overall security and control capabilities of the platform. The addition of comprehensive unit tests ensures the reliability and correctness of the new functionality.

📁 Total Files Changed

3 files were changed:

• plugins/default/default.test.ts: Modified to include tests for the new metadata handler.
• plugins/default/metadata.ts: New file added, containing the implementation of the metadata guardrail handler.
• plugins/index.ts: Modified to export and register the new defaultmetadata handler.

🧪 Test Added

Unit tests were added in plugins/default/default.test.ts for the metadata handler:

• should return true when any pair matches: Tests the any operator where at least one key-value pair in the parameters matches the context metadata.
• should return false when not all pairs match: Tests the all operator where not all specified key-value pairs are found in the context metadata.
• should return true when none of the pairs match: Tests the none operator where no specified key-value pairs are found in the context metadata.
• should return false when any pair matches but not is true: Tests the any operator combined with the not flag, expecting a false verdict when a match occurs but should not.

🔒Security Vulnerabilities

No security vulnerabilities were detected in the changes. The new plugin implements input validation for pairs and handles cases where context.metadata is missing, contributing to robust error handling.

Motivation

To provide a new guardrail plugin that allows users to define policies based on metadata key-value pairs present in the request context, enabling more flexible and powerful request filtering and routing.

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

N/A

Sequence Diagram

sequenceDiagram
    actor User
    participant PluginManager
    participant metadataHandler

    User->>PluginManager: Initiates Request (with metadata in context)
    PluginManager->>metadataHandler: Call handler(context: PluginContext, parameters: PluginParameters, eventType: HookEventType)
    metadataHandler-->>metadataHandler: Validate parameters (pairs, operator)
    alt Missing or Invalid Pairs
        metadataHandler-->>metadataHandler: Throw Error
    else No metadata in context
        metadataHandler-->>metadataHandler: Set verdict based on 'not' flag
        metadataHandler-->>metadataHandler: Set data with 'No metadata provided' explanation
    else Process Metadata
        metadataHandler-->>metadataHandler: Iterate Object.entries(parameters.pairs)
        metadataHandler-->>metadataHandler: Compare context.metadata[key] === value
        metadataHandler-->>metadataHandler: Populate foundKeys[] and missingKeys[]
        metadataHandler-->>metadataHandler: Determine result based on parameters.operator ('any', 'all', 'none')
        metadataHandler-->>metadataHandler: Apply parameters.not to final verdict
        metadataHandler-->>metadataHandler: Construct data object with verdict, foundKeys, missingKeys, explanation
    end
    metadataHandler-->>PluginManager: Return { error, verdict, data }
    PluginManager->>User: Respond based on plugin verdict

Hey! Closing this PR as we have already added requiredMetadataKeys plugin in #1147 . We can extend the same plugin for any new functionality, if requested by the community.