feat(api): capture client IP via proxy headers & SPIFFE (#358 follow-up)

[ymh1874]

Follow-up to #842 for the reopened #358. #842 captured the raw TCP peer on the public HTTP listener; per the maintainer comment two gaps remained (proxy header parsing, SPIFFE), while UDS is acceptable to skip.

Proxy header parsing (config-gated, off by default)

New [oslo_middleware] enable_proxy_headers_parsing flag mirroring upstream Python Keystone's oslo.middleware (HTTPProxyToWSGI), off by default. When enabled, a middleware on the public interface parses RFC 7239 Forwarded (preferred) then X-Forwarded-For, takes the leftmost originating client, and overwrites ConnectInfo<SocketAddr>. Every downstream consumer (the request tracing span's client.addr, the API-Key IP allowlist, any future IP-based login control) transparently sees the real client.

Enabling it asserts the immediate peer is a trusted proxy; left off by default, a deployment not behind such a proxy cannot be tricked into trusting a spoofed header. The layer is wired only on the public interface — never on the internal SPIFFE / admin listeners.

SPIFFE internal interface (client_info was not covered)

The internal mTLS listener uses hyper::service::service_fn, which bypasses axum's make-service, so it never populated ConnectInfo. The accepted TCP peer address is now injected by hand alongside the existing SVID / Interface extensions, so client.addr is captured on the internal interface too. Extracted into a small attach_request_context helper for testability.

The admin UDS interface is intentionally left uncovered — a Unix socket has no meaningful SocketAddr (acceptable per the issue).

Tests

• Proxy-header parsing units (IPv4, ip:port, bracketed/bare IPv6, RFC 7239 params, obfuscated identifiers, precedence) + in-process middleware tests driving the real into_make_service_with_connect_info path.
• A composed public-listener test proving proxy rewrite + trailing-slash normalization (Implement default redirects for trailing slash in the url #734) + connect-info all compose, and that the layer runs before routing/normalization.
• A [oslo_middleware] config deserialization test.
• A SPIFFE attach_request_context unit test asserting ConnectInfo/Interface/SVID are attached.

cargo fmt --check and cargo clippy --lib --tests clean; full keystone lib + config suites pass.

🤖 Generated with Claude Code

[gtema]

While it is good that you add certain compliance to oslo_middleware and rely on it's configuration, it does not by default implement sufficient security:

Proper model: don't blindly trust leftmost entry from any peer just cuz flag on. Standard practice (nginx, oslo.middleware, Go's httputil, etc):

1. Trusted-proxy allowlist, not just boolean flag.
   Config should hold list of trusted proxy CIDRs (trusted_proxies = [...]). Middleware only rewrites ConnectInfo if immediate TCP peer is in that list. Else ignore header entirely — untrusted client hitting listener directly could forge X-Forwarded-For and set whatever IP it wants (bypass IP allowlist, spoof audit logs).

2. Walk chain right-to-left, strip trusted hops.
   X-Forwarded-For: client, proxy1, proxy2 — proxy2 (closest, direct peer) appended last. Correct algo:

• start from rightmost entry
• if it's a trusted proxy, pop it, check next-left
• first entry NOT in trusted set = real client
• leftmost entry alone (current impl) is trivially spoofable — attacker just prepends fake IP as first hop, no proxy needed to strip it since nothing validates chain length/authenticity of entries left of the real edge proxy.

3. Cap hop count / header length. Guard against unbounded comma list (DoS on parsing) — set max hops parsed (e.g. 5-10).

4. Same treatment for Forwarded header — parse for= chain right-to-left same way, by= optionally cross-checked against known proxy identity.

---

I would at least extend the oslo_middleware config with the 'trusted_proxies' to do more secure extraction

[gtema]

you do not need to refer to the issue here. It make sense only for some critical behavior (vulnerabilities, bugs, etc), but not a regular feature trackers

[ymh1874]

Done — removed the issue reference from the doc comment (and the other gratuitous #358 references in the touched comments).

[ymh1874]

Thanks — you were right that the boolean flag plus leftmost-X-Forwarded-For was spoofable. Reworked the extraction to the trusted-proxy model:

1. Trusted-proxy allowlist — added [oslo_middleware] trusted_proxies (CIDR list). The forwarding header is honoured only when the immediate TCP peer is within it; an empty list (default) trusts no one, so the raw peer is always kept.
2. Right-to-left walk — the effective client is now the rightmost address in the chain that is not itself a trusted proxy, so a prepended spoofed leftmost entry is never taken.
3. Hop cap — parsing is bounded to the rightmost 10 hops to guard against an unbounded comma list.
4. Forwarded too — the same right-to-left for= walk is applied to the RFC 7239 header.

As you noted this correlates with the API-key ingress, so rather than a second near-identical resolver I extracted the logic into a shared core::api::forwarded::resolve_client_ip that both the SCIM ingress and this middleware call; the shared version also picked up Forwarded support and the hop cap. ConnectInfo is only overwritten when a different upstream client is recovered, so a direct client keeps its real source port. Tests cover the peer-trust gate, the right-to-left walk, spoofed-leftmost, Forwarded, IPv6/port, and the hop cap.