[TESTING][PLUGINS]: Test, harden and document Cedar policy plugin

[madhu-mohan-jaishankar]

🧪 Summary

Sub-issue of #3735 — Test, harden, and document the Cedar Policy Plugin (plugins/external/cedar/) to bring it to production quality for the 1.0.0 release.

This plugin evaluates Cedar policies and a user-friendly custom-DSL on incoming requests to allow or deny tool invocations using RBAC-based decisions enforced via the cedarpy library. It supports both native Cedar policy syntax and a compact custom DSL mode for non-expert users.

---

🧱 Area Affected

• Plugin: plugins/external/cedar/ — External policy-as-code enforcement via Cedar

---

⚙️ Context / Rationale

The plugin is listed as Priority 2 in the parent issue. It provides fine-grained, policy-as-code RBAC enforcement for tool and resource access, and is noted in the parent issue as requiring additional setup for testing (Cedar policy engine via cedarpy).

Current state:

• Plugin exists in plugins/external/cedar/cedarpolicyplugin/plugin.py with schema in schema.py
• Plugin-local tests exist at plugins/external/cedar/tests/test_cedarpolicyplugin.py but are not integrated into the main gateway test suite
• README covers Cedar and custom-DSL modes but may lack complete examples and limitation notes
• External dependency on cedarpy; tests must account for its availability
• Known TODOs: main test suite integration, mock policy testing, output redaction coverage

---

📋 Acceptance Criteria

Testing

• Unit tests: Create or expand tests/unit/plugins/test_cedar_policy_plugin.py in the main test suite:
  • Cedar mode: Permit policy allows a matching principal/action/resource
  • Cedar mode: Forbid policy denies a matching request
  • Custom DSL mode: role-based allow/deny decisions are evaluated correctly
  • Missing or unavailable cedarpy dependency is handled gracefully (fail-open or clear error)
  • Invalid policy syntax raises a clear configuration error at load time
  • Output redaction based on view_redacted_output vs view_full_output keywords
• Integration tests: Test the plugin registered and active within the gateway pipeline:
  • Plugin loads and activates without errors
  • Tool calls are allowed/denied based on active Cedar policies
  • Plugin coexists correctly with other active plugins
• Edge cases:
  • Empty policy list (no policies defined)
  • Principal with no matching role
  • Action not listed in any policy
  • Conflicting Permit and Forbid policies (verify Cedar precedence rules apply correctly)
  • cedarpy not installed (verify documented failure mode)

Documentation

• README hardening: Expand plugins/external/cedar/README.md to include:
  • Full configuration reference for both cedar and custom_dsl modes
  • Complete working examples for both policy modes with expected outcomes
  • Explanation of output redaction via policy_output_keywords and policy_redaction_spec
  • External dependency requirements (cedarpy) and installation instructions
  • Known limitations and Cedar language version compatibility
• Inline docstrings: Verify all public methods have complete docstrings meeting interrogate standards
• Config docs: Ensure plugins/config.yaml has a complete example entry for this plugin

Hardening

• Config validation: Confirm schema.py rejects invalid policy structures at load time before the plugin activates
• Missing config keys: Verify partial configs (missing keys) fall back cleanly to defaults
• Error handling: Plugin exceptions (including cedarpy failures) must not propagate to caller — confirm failure mode is documented and consistent
• Logging: Ensure policy decisions are logged at appropriate levels; no sensitive payload data in logs
• Main test suite integration (stretch goal): Mirror or move plugins/external/cedar/tests/test_cedarpolicyplugin.py into tests/unit/plugins/ for CI inclusion

Overall

• CI passes with no regressions
• All new tests added to the appropriate test suite
• Plugin manifest (plugin-manifest.yaml) is accurate and complete

---

📁 Key Files

• plugins/external/cedar/cedarpolicyplugin/plugin.py — Plugin implementation
• plugins/external/cedar/cedarpolicyplugin/schema.py — Configuration schema
• plugins/external/cedar/cedarpolicyplugin/plugin-manifest.yaml — Plugin manifest
• plugins/external/cedar/README.md — Plugin documentation
• plugins/external/cedar/tests/test_cedarpolicyplugin.py — Existing plugin-local tests
• plugins/external/cedar/examples/ — Example configurations
• plugins/config.yaml — Plugin configuration
• plugins/AGENTS.md — Plugin development guidelines