Log when authorization policies filter list responses

[jerm-dro]

Summary

When Cedar policies deny tools, prompts, or resources during list filtering, items are silently removed from the response with zero log output. This makes it difficult for operators to diagnose authorization issues — the MCP client shows empty capabilities ("Capabilities: None") with no explanation of why. A community user hit this after upgrading to v0.15.0 when PR #4448 switched Cedar to evaluate upstream IDP access token claims, which had different claim keys than expected.

• Add a generic AtMost utility (pkg/syncutil) that executes a function at most once per configurable interval, safe for concurrent use
• Use it in the Cedar authorizer to emit a rate-limited (every 30s) DEBUG log of resolved JWT claim keys, so operators can see what claims are available for writing policies
• Add DEBUG-level logs for denied items and filtering summaries during list operations
• All authz diagnostic logs use DEBUG per the "silent success" convention — enable with TOOLHIVE_DEBUG=true in proxyConfig.env

Type of change

• New feature

Test plan

• Unit tests (task test)
• Linting (task lint-fix)

Changes

File	Change
pkg/syncutil/atmost.go	New generic rate-limited invocation utility
pkg/syncutil/atmost_test.go	Tests using injectable fake clock
pkg/authz/authorizers/cedar/core.go	Rate-limited claim key logging in resolveClaims()
pkg/authz/tool_filter.go	DEBUG logs for denied tools and filtering summary
pkg/authz/response_filter.go	DEBUG logs for denied prompts/resources and filtering summaries

Does this introduce a user-facing change?

When TOOLHIVE_DEBUG=true is set in proxyConfig.env, operators will see:

• Resolved JWT claim keys available for Cedar policy evaluation (rate-limited to every 30s)
• Per-item denied tools/prompts/resources and filtering summaries

Special notes for reviewers

The AtMost utility is intentionally generic (not logging-specific) so it can be reused for any rate-limited side-effect. It uses atomic.Int64 CAS for lock-free concurrent safety, and accepts an injectable func() time.Time for deterministic testing without time.Sleep.

Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.68%. Comparing base (495b86e) to head (fcaecce).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4690      +/-   ##
==========================================
- Coverage   68.78%   68.68%   -0.11%     
==========================================
  Files         506      508       +2     
  Lines       52599    52878     +279     
==========================================
+ Hits        36180    36318     +138     
- Misses      13617    13741     +124     
- Partials     2802     2819      +17     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jhrozek]

fantastic