Skip to main content

auth_framework/api/
middleware.rs

1//! API Middleware
2//!
3//! Authentication, authorization, rate limiting, and other middleware
4
5use crate::api::{ApiResponse, ApiState};
6use crate::distributed::rate_limiting::RateLimitResult;
7use axum::{
8    extract::{ConnectInfo, Request},
9    http::StatusCode,
10    middleware::Next,
11    response::{IntoResponse, Response},
12};
13use std::net::{IpAddr, SocketAddr};
14use std::time::{Duration, Instant};
15
16/// Sanitize a header value for safe inclusion in log output.
17/// Strips control characters (except space) and truncates to 200 chars
18/// to prevent log injection and log flooding.
19fn sanitize_header_for_log(value: &str) -> String {
20    value
21        .chars()
22        .filter(|c| !c.is_control() || *c == ' ')
23        .take(200)
24        .collect()
25}
26
27/// The address to rate-limit a request under.
28///
29/// A peer that is not a trusted proxy IS the client: its headers are ignored. A trusted
30/// proxy is believed: the client is the rightmost `X-Forwarded-For` entry that is not itself
31/// a trusted proxy (the entries to its left were supplied by the client and are ignored),
32/// else the proxy's own address (`X-Real-IP` is not consulted: many proxies pass a
33/// client-supplied copy through). Every trusted proxy must APPEND to `X-Forwarded-For`
34/// rather than pass it through. Anything unparsable falls back to the peer.
35pub(crate) fn forwarded_client_ip(
36    peer: IpAddr,
37    headers: &axum::http::HeaderMap,
38    trusted_proxies: &[IpAddr],
39) -> IpAddr {
40    let peer = peer.to_canonical();
41    let is_trusted = |ip: &IpAddr| trusted_proxies.iter().any(|t| t.to_canonical() == *ip);
42    if !is_trusted(&peer) {
43        return peer;
44    }
45    let entries: Vec<&str> = headers
46        .get_all("x-forwarded-for")
47        .iter()
48        .filter_map(|v| v.to_str().ok())
49        .flat_map(|v| v.split(','))
50        .map(str::trim)
51        .collect();
52    for entry in entries.iter().rev() {
53        match parse_forwarded_addr(entry) {
54            Some(ip) if is_trusted(&ip) => continue,
55            Some(ip) => return ip,
56            None => return peer,
57        }
58    }
59    peer
60}
61
62/// The rate-limit bucket for an address. IPv6 clients are bucketed by their /64 (the size of
63/// a single end-user allocation), so one client cannot mint a bucket per address.
64fn rate_limit_key(ip: IpAddr) -> String {
65    match ip {
66        IpAddr::V4(v4) => v4.to_string(),
67        IpAddr::V6(v6) => {
68            let o = v6.octets();
69            let prefix = std::net::Ipv6Addr::from([
70                o[0], o[1], o[2], o[3], o[4], o[5], o[6], o[7], 0, 0, 0, 0, 0, 0, 0, 0,
71            ]);
72            format!("{prefix}/64")
73        }
74    }
75}
76
77/// Parse one `X-Forwarded-For` entry: a bare address, `addr:port`, or `[v6]` / `[v6]:port`.
78fn parse_forwarded_addr(entry: &str) -> Option<IpAddr> {
79    if let Ok(ip) = entry.parse::<IpAddr>() {
80        return Some(ip.to_canonical());
81    }
82    if let Ok(sock) = entry.parse::<SocketAddr>() {
83        return Some(sock.ip().to_canonical());
84    }
85    entry
86        .strip_prefix('[')
87        .and_then(|rest| rest.strip_suffix(']'))
88        .and_then(|inner| inner.parse::<IpAddr>().ok())
89        .map(|ip| ip.to_canonical())
90}
91
92/// Rate limiting middleware backed by [`crate::distributed::rate_limiting::DistributedRateLimiter`].
93///
94/// Uses the connection's peer address (see [`forwarded_client_ip`]) as the rate-limiting key.  Returns **429 Too Many Requests** when the limit
95/// is exceeded and adds standard `X-RateLimit-*` response headers on every response.
96// Boxing the Err variant would require `Box<Response>` to implement Axum's
97// `IntoResponse`, which it does not by default; both arms are already the
98// same `Response` type this middleware pattern requires.
99#[allow(
100    clippy::result_large_err,
101    reason = "the Err arm is the axum Response this middleware pattern requires"
102)]
103pub async fn rate_limit_middleware_with_state(
104    state: ApiState,
105    request: Request,
106    next: Next,
107) -> Result<Response, Response> {
108    // The client is identified by the connection's peer address. `X-Forwarded-For` is
109    // client-controlled, so it is believed only when the peer is a configured trusted proxy.
110    let peer = request
111        .extensions()
112        .get::<ConnectInfo<SocketAddr>>()
113        .map(|info| info.0.ip());
114    let client_key = match peer {
115        Some(peer) => rate_limit_key(forwarded_client_ip(
116            peer,
117            request.headers(),
118            &state.trusted_proxies,
119        )),
120        None => {
121            static WARNED: std::sync::atomic::AtomicBool =
122                std::sync::atomic::AtomicBool::new(false);
123            if !WARNED.swap(true, std::sync::atomic::Ordering::Relaxed) {
124                tracing::warn!(
125                    "Rate limiter: requests carry no peer address, so all of them share one \
126                     bucket. Serve the router with \
127                     `into_make_service_with_connect_info::<SocketAddr>()`."
128                );
129            }
130            "unidentified".to_string()
131        }
132    };
133
134    match state.rate_limiter.check_rate_limit(&client_key).await {
135        Ok(RateLimitResult::Allowed {
136            remaining,
137            reset_at,
138        }) => {
139            let mut response = next.run(request).await;
140            let headers = response.headers_mut();
141            let reset_secs = reset_at
142                .checked_duration_since(Instant::now())
143                .unwrap_or(Duration::ZERO)
144                .as_secs();
145            if let Ok(v) = remaining.to_string().parse() {
146                headers.insert("X-RateLimit-Remaining", v);
147            }
148            if let Ok(v) = reset_secs.to_string().parse() {
149                headers.insert("X-RateLimit-Reset", v);
150            }
151            Ok(response)
152        }
153        Ok(RateLimitResult::Denied { retry_after, .. }) => {
154            tracing::warn!(client = %client_key, "Rate limit exceeded");
155            let mut response = ApiResponse::<()>::error(
156                "RATE_LIMIT_EXCEEDED",
157                "Too many requests — please retry after the indicated delay",
158            )
159            .into_response();
160            *response.status_mut() = StatusCode::TOO_MANY_REQUESTS;
161            let headers = response.headers_mut();
162            if let Ok(v) = retry_after.as_secs().to_string().parse() {
163                headers.insert("Retry-After", v);
164            }
165            Err(response)
166        }
167        Ok(RateLimitResult::Blocked { unblock_at, reason }) => {
168            tracing::warn!(client = %client_key, reason = %reason, "Client is blocked");
169            let mut response = ApiResponse::<()>::error(
170                "CLIENT_BLOCKED",
171                "Access temporarily blocked due to repeated rate limit violations",
172            )
173            .into_response();
174            *response.status_mut() = StatusCode::TOO_MANY_REQUESTS;
175            let unblock_secs = unblock_at
176                .checked_duration_since(Instant::now())
177                .unwrap_or(Duration::ZERO)
178                .as_secs();
179            if let Ok(v) = unblock_secs.to_string().parse() {
180                let headers = response.headers_mut();
181                headers.insert("Retry-After", v);
182            }
183            Err(response)
184        }
185        Err(e) => {
186            tracing::error!(error = %e, "Rate limiter error — rejecting request");
187            let mut response = ApiResponse::<()>::error(
188                "RATE_LIMIT_UNAVAILABLE",
189                "Rate limiting is temporarily unavailable; request rejected to protect the service",
190            )
191            .into_response();
192            *response.status_mut() = StatusCode::SERVICE_UNAVAILABLE;
193            Err(response)
194        }
195    }
196}
197
198// cors_middleware was removed: it set `Access-Control-Allow-Origin: *` which is
199// inappropriate for an authentication service.  Use tower-http's `CorsLayer`
200// with a configured `AllowOrigin` list instead.
201
202/// Log every incoming HTTP request with method, URI, client IP, and user-agent.
203///
204/// Elapsed time is logged on the response path.
205///
206/// # Example
207/// ```rust,ignore
208/// let app = Router::new()
209///     .layer(axum::middleware::from_fn(logging_middleware));
210/// ```
211pub async fn logging_middleware(request: Request, next: Next) -> Response {
212    let start = Instant::now();
213    let method = request.method().clone();
214    let uri = request.uri().clone();
215    let headers = request.headers().clone();
216
217    // Extract user agent and IP for logging, sanitized to prevent log injection
218    let user_agent = headers
219        .get("user-agent")
220        .and_then(|v| v.to_str().ok())
221        .unwrap_or("unknown");
222    let user_agent = sanitize_header_for_log(user_agent);
223
224    let forwarded_for = headers
225        .get("x-forwarded-for")
226        .and_then(|v| v.to_str().ok())
227        .unwrap_or("unknown");
228    let forwarded_for = sanitize_header_for_log(forwarded_for);
229
230    tracing::info!(
231        "Request started: {} {} from {} ({})",
232        method,
233        uri,
234        forwarded_for,
235        user_agent
236    );
237
238    let response = next.run(request).await;
239    let duration = start.elapsed();
240    let status = response.status();
241
242    tracing::info!(
243        "Request completed: {} {} {} in {:?}",
244        method,
245        uri,
246        status,
247        duration
248    );
249
250    response
251}
252
253/// Security headers middleware
254pub async fn security_headers_middleware(request: Request, next: Next) -> Response {
255    let response = next.run(request).await;
256
257    let mut response = response;
258    let headers = response.headers_mut();
259
260    // Security headers — all values are well-known static strings so from_static is safe.
261    headers.insert(
262        "X-Content-Type-Options",
263        axum::http::HeaderValue::from_static("nosniff"),
264    );
265    headers.insert(
266        "X-Frame-Options",
267        axum::http::HeaderValue::from_static("DENY"),
268    );
269    headers.insert(
270        "X-XSS-Protection",
271        axum::http::HeaderValue::from_static("1; mode=block"),
272    );
273    headers.insert(
274        "Strict-Transport-Security",
275        axum::http::HeaderValue::from_static("max-age=31536000; includeSubDomains"),
276    );
277    headers.insert(
278        "Referrer-Policy",
279        axum::http::HeaderValue::from_static("strict-origin-when-cross-origin"),
280    );
281    headers.insert(
282        "Permissions-Policy",
283        axum::http::HeaderValue::from_static("camera=(), microphone=(), geolocation=()"),
284    );
285    headers.insert(
286        "Content-Security-Policy",
287        axum::http::HeaderValue::from_static("default-src 'none'; frame-ancestors 'none'"),
288    );
289
290    response
291}
292
293/// Request timeout middleware
294// See the allow rationale on `rate_limit_middleware_with_state` above.
295#[allow(
296    clippy::result_large_err,
297    reason = "the Err arm is the axum Response this middleware pattern requires"
298)]
299pub async fn timeout_middleware(request: Request, next: Next) -> Result<Response, Response> {
300    // Set a 30-second timeout for all requests
301    match tokio::time::timeout(Duration::from_secs(30), next.run(request)).await {
302        Ok(response) => Ok(response),
303        Err(_) => {
304            let error_response =
305                ApiResponse::<()>::error("REQUEST_TIMEOUT", "Request timed out after 30 seconds");
306            Err(error_response.into_response())
307        }
308    }
309}
310
311/// Check whether `auth_token` carries the given permission.
312///
313/// Supports exact matches, a wildcard `"*"`, and prefix wildcards such as
314/// `"read:*"` (matches `"read:users"`, `"read:settings"`, etc.).
315///
316/// # Example
317/// ```rust,ignore
318/// if check_permission(&token, "users:write") {
319///     // allow the operation
320/// }
321/// ```
322pub fn check_permission(auth_token: &crate::tokens::AuthToken, required_permission: &str) -> bool {
323    auth_token.permissions.iter().any(|perm| {
324        perm == required_permission
325            || perm == "*"
326            || (perm.ends_with("*") && required_permission.starts_with(&perm[..perm.len() - 1]))
327    })
328}
329
330/// Check whether `auth_token` carries the given role.
331///
332/// The `"admin"` role implicitly matches every role.
333///
334/// # Example
335/// ```rust,ignore
336/// if check_role(&token, "moderator") {
337///     // allow moderation actions
338/// }
339/// ```
340pub fn check_role(auth_token: &crate::tokens::AuthToken, required_role: &str) -> bool {
341    auth_token.roles.contains(required_role) || auth_token.roles.contains("admin") // Admin has all roles
342}
343
344#[cfg(test)]
345mod tests {
346    use super::*;
347    use crate::tokens::{AuthToken, TokenMetadata};
348
349    fn make_token(permissions: Vec<&str>, roles: Vec<&str>) -> AuthToken {
350        AuthToken {
351            token_id: "tid".into(),
352            user_id: "uid".into(),
353            access_token: "at".into(),
354            token_type: Some("Bearer".into()),
355            subject: Some("uid".into()),
356            issuer: Some("iss".into()),
357            refresh_token: None,
358            issued_at: chrono::Utc::now(),
359            expires_at: chrono::Utc::now(),
360            scopes: vec![].into(),
361            auth_method: "jwt".into(),
362            client_id: None,
363            user_profile: None,
364            permissions: permissions
365                .into_iter()
366                .map(String::from)
367                .collect::<Vec<_>>()
368                .into(),
369            roles: roles
370                .into_iter()
371                .map(String::from)
372                .collect::<Vec<_>>()
373                .into(),
374            metadata: TokenMetadata::default(),
375        }
376    }
377
378    // ── check_permission ────────────────────────────────────────────────
379
380    #[test]
381    fn test_check_permission_exact_match() {
382        let token = make_token(vec!["users:read"], vec![]);
383        assert!(check_permission(&token, "users:read"));
384    }
385
386    #[test]
387    fn test_check_permission_no_match() {
388        let token = make_token(vec!["users:read"], vec![]);
389        assert!(!check_permission(&token, "users:write"));
390    }
391
392    #[test]
393    fn test_check_permission_wildcard_all() {
394        let token = make_token(vec!["*"], vec![]);
395        assert!(check_permission(&token, "anything:at:all"));
396    }
397
398    #[test]
399    fn test_check_permission_wildcard_prefix() {
400        let token = make_token(vec!["users:*"], vec![]);
401        assert!(check_permission(&token, "users:read"));
402        assert!(check_permission(&token, "users:write"));
403        assert!(!check_permission(&token, "admin:read"));
404    }
405
406    #[test]
407    fn test_check_permission_empty() {
408        let token = make_token(vec![], vec![]);
409        assert!(!check_permission(&token, "anything"));
410    }
411
412    // ── check_role ──────────────────────────────────────────────────────
413
414    #[test]
415    fn test_check_role_exact_match() {
416        let token = make_token(vec![], vec!["editor"]);
417        assert!(check_role(&token, "editor"));
418    }
419
420    #[test]
421    fn test_check_role_no_match() {
422        let token = make_token(vec![], vec!["editor"]);
423        assert!(!check_role(&token, "moderator"));
424    }
425
426    #[test]
427    fn test_check_role_admin_has_all_roles() {
428        let token = make_token(vec![], vec!["admin"]);
429        assert!(check_role(&token, "anything"));
430        assert!(check_role(&token, "editor"));
431    }
432
433    #[test]
434    fn test_check_role_empty() {
435        let token = make_token(vec![], vec![]);
436        assert!(!check_role(&token, "user"));
437    }
438
439    fn ip(s: &str) -> IpAddr {
440        s.parse().unwrap()
441    }
442
443    fn headers(pairs: &[(&str, &str)]) -> axum::http::HeaderMap {
444        let mut h = axum::http::HeaderMap::new();
445        for (k, v) in pairs {
446            h.append(
447                axum::http::HeaderName::from_bytes(k.as_bytes()).unwrap(),
448                v.parse().unwrap(),
449            );
450        }
451        h
452    }
453
454    #[test]
455    fn ipv6_clients_share_a_bucket_per_slash_64() {
456        assert_eq!(rate_limit_key(ip("203.0.113.7")), "203.0.113.7");
457        let a = rate_limit_key(ip("2001:db8:1:2:aaaa:bbbb:cccc:dddd"));
458        let b = rate_limit_key(ip("2001:db8:1:2::1"));
459        let c = rate_limit_key(ip("2001:db8:1:3::1"));
460        assert_eq!(a, b, "same /64");
461        assert_ne!(a, c, "different /64");
462    }
463
464    #[test]
465    fn forwarded_for_is_ignored_unless_the_peer_is_trusted() {
466        let h = headers(&[("x-forwarded-for", "1.2.3.4"), ("x-real-ip", "5.6.7.8")]);
467        assert_eq!(forwarded_client_ip(ip("9.9.9.9"), &h, &[]), ip("9.9.9.9"));
468        assert_eq!(
469            forwarded_client_ip(ip("9.9.9.9"), &h, &[ip("10.0.0.1")]),
470            ip("9.9.9.9")
471        );
472    }
473
474    #[test]
475    fn a_trusted_proxy_is_believed_from_the_right() {
476        let proxies = [ip("10.0.0.1"), ip("10.0.0.2")];
477        // client-supplied "6.6.6.6", then what the proxies appended
478        let h = headers(&[("x-forwarded-for", "6.6.6.6, 203.0.113.7, 10.0.0.2")]);
479        assert_eq!(
480            forwarded_client_ip(ip("10.0.0.1"), &h, &proxies),
481            ip("203.0.113.7")
482        );
483        // several header lines are one list
484        let h = headers(&[
485            ("x-forwarded-for", "6.6.6.6"),
486            ("x-forwarded-for", "203.0.113.7"),
487        ]);
488        assert_eq!(
489            forwarded_client_ip(ip("10.0.0.1"), &h, &proxies),
490            ip("203.0.113.7")
491        );
492        // an IPv4-mapped IPv6 peer is the same proxy
493        assert_eq!(
494            forwarded_client_ip(ip("::ffff:10.0.0.1"), &h, &proxies),
495            ip("203.0.113.7")
496        );
497    }
498
499    #[test]
500    fn unusable_forwarding_headers_fall_back_to_the_proxy_or_real_ip() {
501        let proxies = [ip("10.0.0.1")];
502        let h = headers(&[("x-forwarded-for", "203.0.113.7, garbage")]);
503        assert_eq!(
504            forwarded_client_ip(ip("10.0.0.1"), &h, &proxies),
505            ip("10.0.0.1")
506        );
507        assert_eq!(
508            forwarded_client_ip(ip("10.0.0.1"), &headers(&[]), &proxies),
509            ip("10.0.0.1")
510        );
511        // X-Real-IP is never consulted, with or without X-Forwarded-For
512        let h = headers(&[("x-real-ip", "198.51.100.4")]);
513        assert_eq!(
514            forwarded_client_ip(ip("10.0.0.1"), &h, &proxies),
515            ip("10.0.0.1")
516        );
517        let h = headers(&[
518            ("x-forwarded-for", "203.0.113.7"),
519            ("x-real-ip", "198.51.100.4"),
520        ]);
521        assert_eq!(
522            forwarded_client_ip(ip("10.0.0.1"), &h, &proxies),
523            ip("203.0.113.7")
524        );
525        // a chain made only of trusted proxies identifies the last proxy
526        let h = headers(&[("x-forwarded-for", "10.0.0.2, 10.0.0.1")]);
527        assert_eq!(
528            forwarded_client_ip(ip("10.0.0.1"), &h, &[ip("10.0.0.1"), ip("10.0.0.2")]),
529            ip("10.0.0.1")
530        );
531    }
532
533    #[test]
534    fn forwarded_entries_with_ports_and_brackets_are_understood() {
535        let proxies = [ip("10.0.0.1")];
536        for (entry, want) in [
537            ("203.0.113.7:51234", "203.0.113.7"),
538            ("[2001:db8::7]", "2001:db8::7"),
539            ("[2001:db8::7]:443", "2001:db8::7"),
540            ("::ffff:203.0.113.7", "203.0.113.7"),
541        ] {
542            let h = headers(&[("x-forwarded-for", entry)]);
543            assert_eq!(
544                forwarded_client_ip(ip("10.0.0.1"), &h, &proxies),
545                ip(want),
546                "{entry}"
547            );
548        }
549    }
550}