axum: serve_tls helper + mtls-identity example

[iainmcgin]

Closes #49.

What

Two commits, in the order #49 suggests landing them:

1. connectrpc::axum::serve_tls — a TLS-aware counterpart to axum::serve(listener, router) that owns the rustls accept loop and stamps PeerAddr / PeerCerts into request extensions, the same convention the standalone Server::with_tls uses. Handler code that reads ctx.extensions.get::<PeerCerts>() is now portable between the standalone Server and an axum app.

The returned ServeTls mirrors axum::serve::Serve's shape: a #[must_use] IntoFuture<Output = io::Result<()>> builder with .tls_handshake_timeout() and .with_graceful_shutdown() knobs. The accept loop reuses the standalone Server's conventions: slowloris-bounded handshake timeout (default DEFAULT_TLS_HANDSHAKE_TIMEOUT), transient accept() error skip, TCP_NODELAY, and hyper-util GracefulShutdown drain. Module docs spell out the differences from axum::serve (concrete Router only, ALPN setup, PeerCerts is conditional, no automatic panic catching).

2. examples/mtls-identity — the mTLS twin of examples/middleware: same secret-store-with-ACL shape, but the credential is the client certificate the TLS handshake verified, not a Bearer token. The handler reads PeerCerts from extensions, parses the leaf cert's DNS SAN with x509-parser, derives a single-label workload name under workloads.example.com, and gates an ACL on it.

Single self-contained binary: in-memory rcgen PKI (CA, server leaf, two workload client leafs), serve, call with both identities, graceful shutdown. No PEM files touch disk. The lib.rs exposes the proto, handler, identity extraction, and PKI helpers so tests/e2e.rs reuses them rather than duplicating cert generation.

Side fixes

• tokio/macros added to the server feature. server.rs and the new axum.rs both use tokio::select!, but the macro feature was previously only reachable via dev-dep unification. A downstream crate that enabled server without itself enabling tokio/macros would fail to compile; CI never caught it because both --all-targets (Check) and cargo test pull in dev-deps.
• docs/guide.md TLS-hosting drift fix. The guide claimed eliza wraps axum with tokio_rustls::TlsAcceptor for TLS; eliza actually switches to the standalone Server for the TLS path. Replaced with the new serve_tls snippet.

Tests

connectrpc/src/axum.rs (#[cfg(test)]):

• mTLS round-trip: PeerAddr + PeerCerts reach the handler with the verified leaf
• handshake timeout releases the per-connection watcher so graceful drain completes
• handshake error (garbage bytes) doesn't kill the accept loop; a subsequent valid client succeeds
• graceful shutdown anchors an in-flight request until the handler returns

examples/mtls-identity (tests/e2e.rs + lib.rs unit tests):

• WhoAmI reflects cert SAN and remote addr
• authorized read succeeds with x-served-by trailer
• permission denied for another workload's secret
• TLS client without a cert is rejected at the handshake
• extract_identity rejects no-cert, empty-prefix, multi-label-prefix, and unrelated-domain SANs

Notes for review

• pub mod axum shadows the extern axum crate within connectrpc's crate-root scope only. There's an in-source comment explaining the constraint (don't use axum::... in lib.rs); downstream use connectrpc::axum::serve_tls; is unambiguous. I considered connectrpc::axum_tls but the issue spec's connectrpc::axum::serve_tls reads better, and the shadowing is contained.
• serve_tls accepts a concrete axum::Router, not the make-service forms axum::serve is generic over. The module docs explain why (PeerAddr replaces ConnectInfo<SocketAddr>, so into_make_service_with_connect_info has no analogue). Generalising the bound would be possible but adds API surface I'd rather defer until someone needs it.
• The diff is over the soft 250-line target, split across two commits as examples/mtls-identity: demonstrate cert-SAN identity with axum + a helper for parity with standalone Server #49 suggests. Most of the example's lib.rs is the in-memory PKI helper, which is heavily commented because it doubles as a "what a deployment would load from a secret store" model.

Reviewer findings deferred (Low / Advisory)

Flagging these for a decision rather than addressing them in this PR:

• ServeTls doesn't expose an http1_keep_alive(bool) knob like BoundServer does. axum::serve doesn't either, so serve_tls is at parity with the thing it replaces. Easy to add later if anyone hits the stale-connection race on axum.
• No accept-rate / max-connections cap on the spawned per-connection tasks. Same shape as the standalone Server and axum::serve, both unbounded. Could grow a Semaphore-backed knob if it becomes a need.
• PeerAddr could derive Copy (it wraps a Copy SocketAddr). Public API change in server.rs, out of scope here.
• The axum.rs test fixture duplicates the pki() helper from server.rs's tests. They differ in what they return; hoisting to a shared #[cfg(test)] module is possible but increases coupling.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[asacamano]

I realize this is an example, but I wonder about this...

If an attacker-controlled CA is accepted by the mTLS exchange, could they just spoof everything? Not just "a.b", but also "trustedjob", and also maybe "a.b.workloads.example.com", or "trustedjob.workloads.example.com"?

[iainmcgin]

Yeah, this looks like nonsense, will fix

[iainmcgin]

[claude code] You're right — if the trust store accepts an attacker-controlled CA, the attacker can mint a cert for any SAN, including trustedjob.workloads.example.com, so the comment was overstating what this guard buys you. The empty/multi-label checks are about parsing intent (only direct subdomains map to ACL names), not a CA-compromise mitigation. Reworded the comment in 2f5777b to just state the intent and drop the spoofing framing.