Add CEL actor matching for trusted issuers

[jhrozek]

Summary

Trusted issuers currently authorize external-actor delegation only through
AllowedActors, a literal allowlist of one claim's values. That doesn't
scale to IdPs where the trust signal is a role, group, or combination of
claims rather than a single client identifier — every new value requires an
operator to edit and re-apply config. This adds TrustedIssuer.ActorMatcher,
an admin-authored CEL expression evaluated against the subject token's
complete signature-verified claims, as an additional (not replacement)
consent signal alongside AllowedActors.

• Add TrustedIssuer.ActorMatcher / CRD field TrustedIssuerConfig.actorMatcher,
  compiled once at validator construction via toolhive-core's CEL engine
  (existing cost/length limits apply, so no new DoS surface).
• Replace resolveAllowedActor call sites with resolveActorAuthorization,
  which tries the allowlist first and falls back to the matcher; either
  signal is sufficient.
• Add ValidatedClaims.ExternalActorAuthorized and switch
  checkDelegationConsent's external-actor case to key on it instead of
  ExternalActor != "", since a matcher-only authorization leaves
  ExternalActor empty (a matcher need not resolve a single actor claim).
• Validate the expression at both config-time (RunConfig.Validate) and
  validator construction (defence in depth), matching the existing
  ActorClaim/AllowedDelegateClients checks.
• Update docs/arch/17-token-exchange-delegation.md with the new consent
  path, CEL variable shape, and a misconfiguration warning (write the
  predicate against an issuer-controlled identifier claim, not a
  user-editable profile attribute).

Part of #6322 (actor matching only; client-assertion auth is separate
follow-up work).

Type of change

• Bug fix
• New feature
• Refactoring (no behavior change)
• Dependency update
• Documentation
• Other (describe):

Test plan

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

Added unit tests for CEL compilation (accepts any well-typed expression,
denies a non-bool result only at evaluation time), the multi-issuer
validator's authorization precedence (allowlist bypasses a false matcher,
matcher-only authorization with no allowlist, matcher evaluation failure
denies and doesn't leak token/claims into logs), and a new kind e2e suite
(virtualmcp_trusted_issuer_actormatcher_test.go) proving both a
matcher-only grant and a fail-closed rejection through a real
VirtualMCPServer/CRD deployment.

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.

ActorMatcher is a new optional field; no existing field changes shape.

Does this introduce a user-facing change?

Yes — operators can now set trustedIssuers[].actorMatcher (a CEL
expression) on MCPExternalAuthConfig / VirtualMCPServer embedded auth
server config to authorize external-actor delegation by claim predicate
instead of (or in addition to) a literal allowedActors list.

Special notes for reviewers

An expression that compiles but doesn't return bool (e.g. claims.foo
where foo is a string) is only caught the first time a real token
evaluates it — every token is then denied, since the expression can never
return bool. This is a runtime error, not a config error, so it does not
fail reconciliation; it's surfaced only via the per-token auth-server debug
log. Flagged this tradeoff explicitly in code comments since there's no
static way to check a CEL AST's result type through toolhive-core's
cel.Engine.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.05%. Comparing base (7a0c0a5) to head (a8dbcc1).
⚠️ Report is 12 commits behind head on main.

Files with missing lines	Patch %	Lines
...ver/server/tokenexchange/multi_issuer_validator.go	95.83%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6364      +/-   ##
==========================================
+ Coverage   72.97%   73.05%   +0.07%     
==========================================
  Files         742      744       +2     
  Lines       78398    78651     +253     
==========================================
+ Hits        57208    57455     +247     
+ Misses      17201    17172      -29     
- Partials     3989     4024      +35     

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

Summary

This is a thoughtful, well-tested addition that keeps the existing allowlist path and adds matcher authorization with fail-closed evaluation. I left three inline comments. The main concern is that raw CEL evaluation errors can include claim values and are currently logged. The other two comments cover configuration validation and generated API documentation.

Checklist

• Tests: Unit, integration, operator E2E, lint, and the reported CI checks are green.
• Docs: Architecture, Swagger, and CRD docs are included. One CRD description still reflects the pre-matcher behavior.
• Registry impact: None.
• Security: Authorization remains fail closed, but evaluation errors should be redacted before logging.
• Backwards compatibility: The fields are optional and additive, and CRD schema compatibility checks pass.

[samuv]

Follow-up review

The CEL error redaction is correct and the regression test now exercises the actual value-leaking operator. The CRD descriptions are also updated consistently. I left one inline comment for the equivalent standalone auth-server description, which still feeds stale text into Swagger. The non-boolean result-type validation remains safe to defer to a tracked toolhive-core follow-up because runtime evaluation fails closed.

Checklist

• Tests: Focused regression coverage is appropriate. Several latest CI jobs are still running; completed lint, codegen, docs, security, and CRD compatibility checks pass.
• Docs: CRD docs are fixed. One standalone Swagger source comment still needs the matching update.
• Registry impact: None.
• Security: Raw CEL errors and claim values are now redacted.
• Backwards compatibility: No new compatibility concern found.

[samuv]

Approved. The CEL error redaction is safe and covered by a regression test, the CRD and standalone Swagger documentation are aligned, and the static boolean result-type check is tracked in stacklok/toolhive-core#239 as a non-blocking follow-up.

Checklist:

• Tests: The required check passes. Unit tests, lint, documentation, code generation, security, and compatibility checks are green.
• Docs: Architecture, CRD, and Swagger documentation are aligned.
• Registry impact: None.
• Security: CEL evaluation errors no longer expose claim values.
• Backwards compatibility: The new matcher field remains optional and additive.