Auth coverage: mTLS client certs, token refresh, SigV4 posture, worked examples

[aaylward]

Broken out of #49 (its last unchecked adoption item, verbatim: "Auth is bearer/api-key only; SigV4 explicitly punted, mTLS/token-refresh uncovered, and the only interceptor sample is a logging/bearer stub. No non-trivial worked example.").

What exists today

• @httpBearerAuth / @httpApiKeyAuth: config.bearer_token / config.api_key callbacks, invoked per request — so rotation already works mechanically; what's missing is the worked example (caching, expiry, refresh-on-401).
• Interceptors (smithy/client/interceptor.h): ModifyBeforeTransmit sees the full HttpRequest per attempt — sufficient surface for signing schemes; the production guide's only sample is a logging/bearer stub.
• TLS: Production transport knobs live on ClientConfig; Beast builds FromConfig (#49) #87 moved client verification knobs onto ClientConfig (config.tls.verify_peer/ca_pem, the shared smithy::http::TlsOptions), and the server side terminates TLS (tls_certificate_chain_pem/tls_private_key_pem). No client certificate fields exist anywhere — mTLS is impossible today without a custom transport.

Work items (roughly in value/effort order)

1. mTLS client certificates — the natural next extension of Production transport knobs live on ClientConfig; Beast builds FromConfig (#49) #87's knob placement: config.tls grows client_certificate_chain_pem + client_private_key_pem (PEM text, matching the server-side naming), TlsOptions stays the single shared struct so FromConfig carries them for free, and beast_src.cc's SSL context wiring adds use_certificate_chain/use_private_key. Test: the Beast TLS test server gains a require-client-cert mode; behavior tests for presented/absent/wrong-cert. (Server-side verification of client certs is the matching half — decide whether it rides along or splits out.)
2. Token refresh worked example — a caching bearer_token callback (expiry-aware, single-flight refresh) in the production guide, compiled and mirror-pinned per the repo convention (QuickstartMirrorTest/ProductionGuideMirrorTest precedent) rather than free-floating prose.
3. SigV4 posture — currently punted by design ("implement as an Interceptor"). Decide: keep the punt but ship a reference signing interceptor proving the surface suffices (request canonicalization + payload hashing need nothing the interceptor doesn't already see), or graduate first-class @aws.auth#sigv4 support to its own issue. The punt without a worked example is the current gap.
4. Production-guide auth section overhaul — one coherent section walking bearer→api-key→mTLS→signing, replacing the stub.

Constraints / prior art in-repo

• Dep-light rule (ADR-0005): signing must not drag a crypto dependency into :client; BoringSSL is available behind //runtime:http_beast only. A SigV4 reference impl needs SHA-256/HMAC — either a tiny standalone implementation in the example, or the example lives Beast-side.
• Test-first workflow per docs/development.md; Beast-linking tests are CI-only behind proxies (same recipe as Production transport knobs live on ClientConfig; Beast builds FromConfig (#49) #87/Boost 1.90: beast/asio to 1.90.0.bcr.1, boringssl pinned to match #89).

Refs: #49 (origin), #87 (TlsOptions placement this builds on), ADR-0007 (Beast TLS), docs/production-guide.md Authentication section.