feat: add OPA plugin for policy enforcement

[monshri]

✨ Feature / Enhancement PR

🔗 Epic / Issue

Closes # #271

🚀 Summary

This PR introduces an external OPA Plugin which is self-contained with the OPA server running as background service, with sample policies. The pre hooks on tools that talks to OPA server running as background service within the same container. Whenever a tool is invoked, if OPA Plugin is in action, a policy will be applied on the tool call to allow/deny it.

plugins:
  - name: "OPAPluginFilter"
    kind: "opapluginfilter.plugin.OPAPluginFilter"
    description: "An OPA plugin that enforces rego policies on requests and allows/denies requests as per policies"
    version: "0.1.0"
    author: "Shriti Priya"
    hooks: ["tool_pre_invoke"]
    tags: ["plugin"]
    mode: "enforce"  # enforce | permissive | disabled
    priority: 10
    applied_to:
      tools:
        - name: "fast-time-git-status"
          context:
            - "global.opa_policy_context.git_context"
          extensions:
            policy: "example"
            policy_endpoint: "allow"
    conditions:
      # Apply to specific tools/servers
      - server_ids: []  # Apply to all servers
        tenant_ids: []  # Apply to all tenants
    config:
      # Plugin config dict passed to the plugin constructor
      opa_base_url: "http://127.0.0.1:8181/v1/data/"

OPA Server

To define a policy file you need to go into opaserver/rego and create a sample policy file for you.
Example -example.rego is present.
Once you have this file created in this location, when building the server, the opa binaries will be downloaded and a container will be build.
In the run_server.sh file, the opa server will run as a background service in the container with the rego policy file.

OPA Plugin

The OPA plugin runs as an external plugin with pre/post tool invocations. So everytime, a tool invocation is made, and if OPAPluginFilter has been defined in config.yaml file, the tool invocation will pass through this OPA Plugin.

The applied_to key in config.yaml, has been used to selectively apply policies and provide context for a specific tool.
Here, using this, you can provide the name of the tool you want to apply policy on, you can also provide
context to the tool with the prefix global if it needs to check the context in global context provided.
The key opa_policy_context is used to get context for policies and you can have multiple contexts within this key using git_context key.
You can also provide policy within the extensions key where you can provide information to the plugin
related to which policy to run and what endpoint to call for that policy.
In the config key in config.yaml file OPAPlugin consists of the following things:
opa_base_url : It is the base url on which opa server is running.

More to come

1. Support for policy bundling
2. Implementation for post tool, prompt/resource pre and post invocations.

[crivetimihai]

OPA Plugin PR Review - Quick Summary

✅ What Works

• Plugin loads and runs correctly
• OPA server integration functional
• Policy enforcement working
• Documentation complete
• Rebase successful - branch is current

⚠️ Issues Found

Test Configuration Problems

# This fails in tests:
applied_to = AppliedTo(tools=[...])  # Pydantic validation error

# But YAML config works fine in runtime:
applied_to:
  tools:
    - tool_name: "fast-time-git-status"

Mock Server Port Conflicts

• Tests fail with "Address already in use: 8181"
• Multiple tests try to bind same port

🎯 Action Items

Before Merge

• Rebase complete
• Core functionality verified
• Documentation reviewed

After Merge (Follow-up PRs)

1. Fix test schema validation - applied_to field structure mismatch
2. Fix mock server conflicts - Use random ports or proper cleanup
3. Add integration tests - Test with real OPA server

🚀 Deploy Instructions

1. Build container:

   cd plugins/external/opa
   make build
   make start

2. Enable in gateway:

   # plugins/config.yaml
   - name: "OPAPluginFilter"
     kind: "external"
     priority: 10
     mcp:
       proto: STREAMABLEHTTP
       url: http://127.0.0.1:8000/mcp

3. Test:

   # Should fail (no "IBM")
   curl -X POST -H "Authorization: Bearer $TOKEN" \
     -d '{"jsonrpc":"2.0","id":1,"method":"fast-time-git-status","params":{"repo_path":"path/BIM"}}' \
     http://localhost:4444/rpc
   
   # Should pass (has "IBM") 
   curl -X POST -H "Authorization: Bearer $TOKEN" \
     -d '{"jsonrpc":"2.0","id":1,"method":"fast-time-git-status","params":{"repo_path":"path/IBM"}}' \
     http://localhost:4444/rpc

📋 Review Checklist

• Code quality good
• Security model appropriate
• Documentation comprehensive
• Integration works
• No breaking changes
• Tests need cleanup (post-merge)