Implement bearer token controller logic and environment variable management

[amirejaz]

Summary

Implements the controller logic and runtime integration for bearer token authentication in Kubernetes, building on the foundation laid in PR #3224. This completes the bearer token authentication flow by adding reconciliation, RunConfig generation, environment variable management, and secret watching capabilities.

Context

This PR builds on PR #3224 which added:

• BearerTokenConfig CRD type in MCPExternalAuthConfig
• ExternalAuthTypeBearerToken enum value
• Webhook validation for bearer token configuration
• Basic type definitions and API structure

This PR implements the operational logic to make bearer tokens work end-to-end.

Changes

Controller Implementation

• MCPExternalAuthConfig Controller:

  • Added reconciliation logic for bearerToken type in mcpexternalauthconfig_controller.go
  • Implements secret watch to trigger reconciliation when referenced secrets change
  • Calculates config hash including secret content (SHA256, truncated to 16 hex chars) for change detection
  • Refactored secret reference finding into dedicated functions:
    • findMCPExternalAuthConfigsReferencingSecret() - finds configs referencing a secret
    • configReferencesSecret() - checks if a config references a specific secret

• MCPRemoteProxy Controller:

  • Integrated bearer token configuration into RunConfig generation (mcpremoteproxy_runconfig.go)
  • Converts Kubernetes Secret references to CLI format ("secret-name,target=bearer_token")
  • Validates secret existence and key presence before deployment
  • Generates environment variables for bearer token secrets

Environment Variable Management

• GenerateBearerTokenEnvVar(): Creates TOOLHIVE_SECRET_{secret-name} env vars from Secret references
• EnsureRequiredEnvVars(): Auto-detects TOOLHIVE_SECRET_* env vars and sets TOOLHIVE_SECRETS_PROVIDER=environment
  • Checks all env vars (not just specific ones) for TOOLHIVE_SECRET_* prefix
  • Only sets provider when actual secrets are present (excludes provider env var itself)
  • Ensures secrets provider is correctly configured for CLI-format secret resolution

Secret Resolution Flow

1. User creates MCPExternalAuthConfig with bearerToken type referencing a Kubernetes Secret
2. Controller validates secret exists and contains required key
3. Controller generates TOOLHIVE_SECRET_{secret-name} env var in pod spec
4. EnsureRequiredEnvVars detects secret env vars and sets TOOLHIVE_SECRETS_PROVIDER=environment
5. RunConfig contains CLI-format secret reference: "secret-name,target=bearer_token"
6. At runtime, EnvironmentProvider resolves secret from TOOLHIVE_SECRET_* env var
7. Bearer token is injected into Authorization header for remote MCP server requests

Testing

• Comprehensive unit tests for bearer token RunConfig generation (mcpremoteproxy_runconfig_test.go)
• Tests for environment variable generation and validation
• Tests for EnsureRequiredEnvVars with 13 test cases covering:
  • Default env var setting
  • Secret detection with different naming patterns
  • Edge cases (empty lists, mixed vars, provider exclusion, etc.)
• Tests for secret watch and reconciliation triggers (mcpexternalauthconfig_controller_test.go)
• Integration tests for end-to-end bearer token flow

Examples & Documentation

• Added mcpremoteproxy_with_bearer_token.yaml example demonstrating bearer token configuration
• Updated example files to use generic names (removed PostHog-specific references)
• Cleaned up examples to focus on essential configuration

Security

• Only secret references supported (no plaintext values)
• Secrets validated before deployment
• Secret changes trigger automatic reconciliation via watch mechanism
• Config hash includes secret content for change detection (ensures dependent resources reconcile when secrets change)

Technical Details

Secret Watch Implementation

• Controller watches Secrets and triggers reconciliation of MCPExternalAuthConfig resources that reference them
• Uses Watches(&corev1.Secret{}, secretHandler) in SetupWithManager
• Ensures changes to secret values propagate to dependent resources

Config Hash with Secret Content

• calculateConfigHash() now includes SHA256 hash (truncated to 16 hex chars) of referenced secret values
• Enables change detection when secrets are updated
• Triggers reconciliation of dependent MCPServer and MCPRemoteProxy resources

Related

• Builds on PR add bearerToken type to MCPExternalAuthConfig CRD #3224: Bearer token CRD types and validation
• Part of Phase 3: External Authentication implementation
• Enables authenticating to remote MCP servers that require bearer tokens

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.

[codecov]

Codecov Report

❌ Patch coverage is 83.13253% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.68%. Comparing base (c3549f6) to head (7c2845d).

Files with missing lines	Patch %	Lines
...d/thv-operator/pkg/controllerutil/tokenexchange.go	79.59%	5 Missing and 5 partials ⚠️
...-operator/controllers/mcpremoteproxy_deployment.go	66.66%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3487      +/-   ##
==========================================
- Coverage   65.71%   65.68%   -0.04%     
==========================================
  Files         410      410              
  Lines       40624    40704      +80     
==========================================
+ Hits        26697    26736      +39     
- Misses      11846    11886      +40     
- Partials     2081     2082       +1     

☔ 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.

PR size has been reduced below the XL threshold. Thank you for splitting this up!

[github-actions]

✅ PR size has been reduced below the XL threshold. The size review has been dismissed and this PR can now proceed with normal review. Thank you for splitting this up!

[JAORMX]

Is this the only way of doing this? I was explicitly not adding this capability because a compromise of the operator will grant folks the ability to read secrets.

[amirejaz]

Good catch! Removed it, this PR doesn't actually need secret access since it only hashes the spec, not secret values. We can revisit secret permissions when the other PR adds secret-aware hashing.