Add JWT-bearer assertion grant

[jhrozek]

Summary

• ToolHive needs a constrained way for trusted external workloads to obtain MCP access tokens without registering a ToolHive OAuth client; this adds the plain RFC 7523 JWT-bearer assertion grant and keeps its trust boundary separate from RFC 8693 delegation.
• Validate trusted issuer signatures, authorization-server audiences, assertion age, exact subject/resource bindings, replay consumption, asymmetric signing algorithms, and ID-token markers before issuing an access token.
• Expose the per-issuer policy through MCPExternalAuthConfig, publish it in discovery and generated API schemas only when enabled, and share issuer validation/JWKS state with token exchange.
• Add replay-safe memory and Redis storage, synthetic client persistence for clientless requests, generated documentation, and unit/integration/operator E2E coverage.

Fixes #6336
Fixes #6337

Type of change

• New feature

Test plan

• Unit tests (task test)
• E2E tests (task test-e2e)
• Linting (task lint-fix)
• Manual testing (describe below)

task lint passed. task test-e2e was attempted but is blocked before feature setup by the locally installed ToolHive Desktop CLI conflict guard; it fails across the suite, independent of this branch.

API Compatibility

• This PR does not break the v1beta1 API, OR the api-break-allowed label is applied and the migration guidance is described above.

Changes

File area	Change
pkg/authserver/server/tokenexchange/	Add the RFC 7523 handler, validation, replay checks, shared-validator wiring, and regression coverage.
pkg/authserver/storage/	Persist single-use assertion consumption safely across memory, Redis, and CIMD-decorated storage.
cmd/thv-operator/ and CRD artifacts	Configure issuer JWT-bearer policies, including accepted AS audiences, through the operator API.
docs/	Regenerate server/operator API references and document the trust, replay, and storage model.
test/e2e/	Exercise token issuance and MCP proxy access through the operator.

Does this introduce a user-facing change?

Yes. Administrators can configure trusted external issuers to exchange signed RFC 7523 assertions for short-lived, resource-bound ToolHive access tokens without OAuth client credentials.

Implementation plan

Approved implementation plan

1. Add trusted-issuer policy and replay-safe storage for a plain RFC 7523 JWT-bearer grant.
2. Validate assertions and issue bounded, resource-scoped tokens through the embedded authorization server.
3. Expose the policy through the operator CRD, generate API artifacts, and verify the real operator-to-proxy flow.
4. Harden the resulting feature with focused security, validation, persistence, and documentation review fixes.

Special notes for reviewers

• The handler intentionally overwrites any resolved request client with a synthetic public client. This preserves clientless-request persistence and prevents supplied DCR clients from affecting registration-TTL renewal.
• acceptedAudiences identifies authorization-server identities, not resources. Startup rejects an overlap with allowedAudiences so a resource-scoped upstream access token cannot be used as a clientless assertion.

[codecov]

Codecov Report

❌ Patch coverage is 82.93737% with 79 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.70%. Comparing base (39a85c8) to head (28d33a4).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...hserver/server/tokenexchange/jwt_bearer_handler.go	85.85%	29 Missing ⚠️
...ver/server/tokenexchange/multi_issuer_validator.go	78.44%	25 Missing ⚠️
...perator/api/v1beta1/mcpexternalauthconfig_types.go	30.76%	9 Missing ⚠️
pkg/authserver/storage/memory.go	80.00%	5 Missing ⚠️
pkg/authserver/config.go	75.00%	3 Missing ⚠️
pkg/authserver/storage/redis.go	86.95%	3 Missing ⚠️
pkg/authserver/server/tokenexchange/factory.go	81.81%	2 Missing ⚠️
pkg/authserver/server_impl.go	90.00%	2 Missing ⚠️
pkg/authserver/runner/embeddedauthserver.go	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6391      +/-   ##
==========================================
- Coverage   77.72%   77.70%   -0.02%     
==========================================
  Files         748      750       +2     
  Lines       71826    72563     +737     
==========================================
+ Hits        55827    56387     +560     
- Misses      15994    16171     +177     
  Partials        5        5              

☔ View full report in Codecov by Harness.
📢 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.

[samuv]

Thanks for the thorough implementation and the unusually clear trust-model documentation. I found six issues worth addressing before merge. The most immediate one is that the operator validation converter drops JWTBearerGrant, which causes grant-only configurations to be rejected. I also left focused comments on supplied Basic credentials, OAuth error classification, replay-store failures, Redis synthetic-client identification, and mixed RFC 7523/RFC 8693 configuration validation.

Checklist

• Tests: CI unit, integration, and E2E checks are currently passing. A reconciliation/status assertion is still needed for the grant-only operator path.
• Docs: Updated and detailed.
• Registry impact: None.
• Security: Client authentication and replay-store error handling need attention.
• Backwards compatibility: The v1beta1 additions are additive, but mixed-mode validation should reject unusable configurations at admission time.

[jhrozek]

Thanks for the thorough review — all six findings confirmed and fixed:

• Basic-auth credential bypass in CanSkipClientAuth
• replay-store failures now return a server error instead of invalid_grant
• validateAssertionType now returns invalid_grant per RFC 7523
• buildTrustedIssuerConfigs was dropping JWTBearerGrant (the grant-only-issuer bug) — also added the reconcile/Valid=True status test you asked for
• tightened the mixed RFC 7523/8693 validation at both the CEL and Go level
• synthetic client IDs are now rejected at registration time so a colliding admin-configured client can't be reconstructed as unregistered after a Redis round-trip

Replied inline on each thread with the specific fix. CI's green again.

[samuv]

Thanks for the follow-up. I rechecked the two remaining items on 28d33a4:

• CanSkipClientAuth now keys off BasicAuth() ok alone, including an empty-username header. The test helper no longer injects a password into credential-free cases, and there is an explicit empty-username regression.
• Mixed RFC 7523/RFC 8693 validation now treats non-empty allowedActors as a delegation signal in both CEL and validateDelegationPolicy, with admission and runtime coverage.

The earlier findings (grant conversion, replay-store errors, invalid_grant classification, and the reserved synthetic prefix) still look solid. CI is green. LGTM.