Add authServerRef CRD types, controller logic, and unit tests

[tgrunnagle]

Summary

The embedded auth server currently competes with outgoing auth types (like AWS STS) for the single externalAuthConfigRef slot on MCPServer and MCPRemoteProxy CRDs. Because MCPExternalAuthConfig enforces mutually exclusive types, users cannot configure both an embedded auth server for incoming client authentication and an outgoing token exchange on the same resource. This PR adds a dedicated authServerRef field to both CRDs, separating the embedded auth server from externalAuthConfigRef so both can coexist. This is Phase 1 of RFC-0050.

Closes #4640

Type of change

• New feature

Test plan

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

Changes

File	Change
api/v1alpha1/mcpserver_types.go	Add AuthServerRef field to MCPServerSpec and AuthServerConfigHash to MCPServerStatus
api/v1alpha1/mcpremoteproxy_types.go	Add AuthServerRef field to MCPRemoteProxySpec and AuthServerConfigHash to MCPRemoteProxyStatus
api/v1alpha1/zz_generated.deepcopy.go	Regenerated deepcopy for new fields
pkg/controllerutil/authserver.go	Add AddAuthServerRefOptions, ValidateAndAddAuthServerRefOptions, and GenerateAuthServerConfigFromRef utility functions
controllers/mcpserver_runconfig.go	Wire conflict validation and authServerRef resolution into MCPServer runconfig generation
controllers/mcpremoteproxy_runconfig.go	Wire conflict validation and authServerRef resolution into MCPRemoteProxy runconfig generation
controllers/mcpserver_controller.go	Add handleAuthServerRef for config hash tracking, extend watch handler and deployment builder for authServerRef
controllers/mcpremoteproxy_controller.go	Add handleAuthServerRef for config hash tracking, extend watch handler for authServerRef
controllers/mcpremoteproxy_deployment.go	Generate volumes/mounts/env vars from authServerRef in deployment builder
controllers/mcpexternalauthconfig_controller.go	Extend findReferencingMCPServers and findReferencingWorkloads to check authServerRef with deduplication; add reverse watch for authServerRef in SetupWithManager
pkg/controllerutil/authserver_test.go	Add unit tests for AddAuthServerRefOptions and ValidateAndAddAuthServerRefOptions covering nil ref, invalid kind, wrong type, valid ref, conflict detection, and combined auth paths
controllers/mcpexternalauthconfig_controller_test.go	Add unit tests for referencing logic finding resources via authServerRef
CRD YAMLs (4 files)	Regenerated CRD manifests with new fields

Does this introduce a user-facing change?

Yes. MCPServer and MCPRemoteProxy resources now accept an optional authServerRef field that references an MCPExternalAuthConfig of type embeddedAuthServer. This allows configuring the embedded auth server independently from externalAuthConfigRef, enabling use cases like embedded auth server + AWS STS token exchange on the same resource.

Special notes for reviewers

• The authServerRef field uses corev1.TypedLocalObjectReference (not the existing ExternalAuthConfigRef type) to future-proof for a dedicated auth server CRD.
• Conflict validation ensures both authServerRef and externalAuthConfigRef cannot point to an embeddedAuthServer type simultaneously.
• The MCPExternalAuthConfig controller's referencing logic queries each ref field separately and deduplicates, rather than using a single combined query.
• E2E tests are in Add E2E tests for authServerRef on MCPServer and MCPRemoteProxy #4641 and architecture docs in Update operator architecture documentation for authServerRef #4642 as follow-up work.

Generated with Claude Code

Large PR Justification

• Adds support for a new CRD field to configure embedded auth server for both MCPServer and MCPRemoteProxy. In retrospect it could have been split (e.g. CRD changes separate from controller changes, or MCPServer separate from MCPRemoteProxy).

[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 61.63683% with 150 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.86%. Comparing base (1ee7107) to head (cc091b1).
⚠️ Report is 12 commits behind head on main.

Files with missing lines	Patch %	Lines
...or/controllers/mcpexternalauthconfig_controller.go	34.84%	80 Missing and 6 partials ⚠️
...d/thv-operator/controllers/mcpserver_controller.go	71.87%	23 Missing and 4 partials ⚠️
...-operator/controllers/mcpremoteproxy_controller.go	76.08%	19 Missing and 3 partials ⚠️
cmd/thv-operator/pkg/controllerutil/authserver.go	82.97%	4 Missing and 4 partials ⚠️
...v-operator/controllers/mcpremoteproxy_runconfig.go	60.00%	1 Missing and 1 partial ⚠️
...md/thv-operator/controllers/mcpserver_runconfig.go	60.00%	1 Missing and 1 partial ⚠️
cmd/thv-operator/pkg/controllerutil/config.go	77.77%	1 Missing and 1 partial ⚠️
...-operator/controllers/mcpremoteproxy_deployment.go	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4644      +/-   ##
==========================================
- Coverage   68.88%   68.86%   -0.03%     
==========================================
  Files         505      509       +4     
  Lines       52437    53007     +570     
==========================================
+ Hits        36121    36501     +380     
- Misses      13525    13686     +161     
- Partials     2791     2820      +29     

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

Nice work on the consolidation in the last commit — the EmbeddedAuthServerConfigName + GenerateAuthServerConfigByName approach is much cleaner than the two separate code paths. A few thoughts inline.

Large PR justification has been provided. Thank you!

[github-actions]

✅ Large PR justification has been provided. The size review has been dismissed and this PR can now proceed with normal review.