feat(gateway): support mandatory TLS client certificates alongside OIDC

Start with the cited configuration and verifier paths in crates/openshell-server/src/cli.rs and crates/openshell-server/src/tls.rs, then read architecture/gateway.md and trace the existing Helm configuration. Define the opt-in policy and validation flow before adding integration coverage for certificate and OIDC credential combinations. Done means the gateway and Helm settings are documented, invalid configurations fail clearly, and the listed listener flows preserve existing authorization behavior.

User Story

As an operator deploying an OpenShell gateway with OIDC, I want to optionally require a trusted TLS client certificate as well as a valid OIDC bearer token, so that I can use managed client certificates for connection admission while retaining OIDC identities, roles, and workspace authorization.

Problem Statement

The gateway currently makes TLS client certificates optional when an OIDC issuer is configured, even when a client CA is supplied. There is no operator-facing setting to require both on that listener.

Verified against upstream main at 470a34635db7d2615d5cae5c61804dcbdec04eeb:

• Gateway configuration derives require_client_auth as has_client_ca && !has_oidc.
• TLS verifier construction permits clients without a certificate when that requirement is false.

This request is for an explicit combined mode: client-certificate validation at the transport layer and OIDC authentication/authorization at the application layer. It does not request certificate-only user authentication or certificate-derived roles.

Impact / Why This Matters

Operators who use both enterprise client PKI and OIDC cannot express that connection policy directly in the gateway. They must introduce a separate TLS enforcement proxy and manage its certificate rotation, routing, streaming compatibility, and access to the gateway listener. Native configuration would reduce those additional deployment components and make the intended behavior easier to validate.

Proposed Design

Provide an opt-in gateway TLS setting that requires a trusted client certificate independently of whether OIDC is enabled. Exact field names and implementation are left to maintainers.

Operator workflow:

1. Configure the gateway server certificate and trusted client CA.
2. Configure the existing OIDC issuer, audience, and authorization settings.
3. Explicitly enable mandatory client-certificate validation through supported gateway configuration and Helm deployment configuration.
4. Clients present both their certificate/key and bearer token. Certificate validation admits the TLS connection; OIDC continues to determine the user identity and permissions.

Preserve current behavior when this setting is omitted. Report the effective certificate requirement in configuration validation or startup diagnostics. Document the listener-wide effect, including CLI/SDK clients, supervisor/bootstrap connections, streaming calls, and health probes. Supported callers sharing the listener must have a documented certificate provisioning path; incompatible configurations should produce actionable diagnostics.

Acceptance Criteria

• With OIDC and the new option enabled, a client without a certificate is rejected at the TLS layer even if it has a valid bearer token.
• Untrusted or expired client certificates are rejected; a valid trusted certificate allows the connection to proceed to application authentication.
• A valid client certificate alone does not satisfy OIDC authentication for protected user RPCs: missing, invalid, or expired bearer tokens are rejected.
• With both credentials valid, existing OIDC role and workspace authorization decisions still apply. A certificate does not grant additional application roles.
• Existing OIDC deployments retain their behavior when the option is omitted, and certificate-only modes retain their documented behavior.
• Enabling the option without TLS or without a usable client CA fails configuration validation with a clear message.
• Gateway and Helm configuration expose and document the setting, its default, and effective behavior.
• Integration tests cover the certificate/token combinations above and legitimate CLI/SDK, supervisor/bootstrap, and streaming flows under the selected listener policy.
• Certificate rotation and health-probe requirements are documented and tested for the supported deployment configuration.

Alternatives Considered

• A separate mTLS enforcement proxy: viable, but adds another deployment, certificate lifecycle, and routing configuration to operate.
• Certificate-only user authentication: does not retain the existing OIDC identity and authorization workflow.
• Requiring certificates by default whenever a client CA exists: could disrupt current OIDC clients; an explicit opt-in setting preserves compatibility.

Agent Investigation

Reviewed current upstream gateway configuration, TLS verifier construction, and architecture/gateway.md. The TLS implementation already distinguishes required and optional client certificates; the startup configuration derives that choice from OIDC presence. The requested feature exposes an independent operator policy rather than replacing OIDC.

Related proposals have different scopes:

• #3071 concerns roles for certificate-authenticated identities without OIDC.
• #3542 concerns Kubernetes-backed user/admin authorization.

This proposal composes transport certificate validation with the existing OIDC path and does not depend on either proposal.

Checklist

• I've reviewed existing issues and the architecture docs.
• This is a design proposal with observable acceptance criteria.