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::Request,
9    http::StatusCode,
10    middleware::Next,
11    response::{IntoResponse, Response},
12};
13use std::time::{Duration, Instant};
14
15/// Sanitize a header value for safe inclusion in log output.
16/// Strips control characters (except space) and truncates to 200 chars
17/// to prevent log injection and log flooding.
18fn sanitize_header_for_log(value: &str) -> String {
19    value
20        .chars()
21        .filter(|c| !c.is_control() || *c == ' ')
22        .take(200)
23        .collect()
24}
25
26/// Rate limiting middleware backed by [`crate::distributed::rate_limiting::DistributedRateLimiter`].
27///
28/// Uses the client IP address (from `X-Forwarded-For`, then `X-Real-IP`, falling back to
29/// `"unknown"`) as the rate-limiting key.  Returns **429 Too Many Requests** when the limit
30/// is exceeded and adds standard `X-RateLimit-*` response headers on every response.
31#[allow(clippy::result_large_err)] // the Err type is part of the existing public signature; boxing it would change the API of a release line
32pub async fn rate_limit_middleware_with_state(
33    state: ApiState,
34    request: Request,
35    next: Next,
36) -> Result<Response, Response> {
37    // Derive a stable key from the client IP.
38    // SECURITY (H-4): Validate the extracted value as a real IP address before using it
39    // as a rate-limit key.  An attacker who can set arbitrary X-Forwarded-For headers
40    // could bypass per-IP limiting by injecting a fabricated first address.  Requiring a
41    // valid parse means only syntactically correct IPs are accepted; anything else falls
42    // through to the next header or the fallback string "unknown".
43    let client_key = request
44        .headers()
45        .get("x-forwarded-for")
46        .and_then(|v| v.to_str().ok())
47        .and_then(|s| s.split(',').next())
48        .map(str::trim)
49        .and_then(|s| s.parse::<std::net::IpAddr>().ok().map(|ip| ip.to_string()))
50        .or_else(|| {
51            request
52                .headers()
53                .get("x-real-ip")
54                .and_then(|v| v.to_str().ok())
55                .map(str::trim)
56                .and_then(|s| s.parse::<std::net::IpAddr>().ok().map(|ip| ip.to_string()))
57        })
58        .unwrap_or_else(|| {
59            tracing::warn!(
60                "Rate limiter: no identifiable client IP from X-Forwarded-For or X-Real-IP; \
61                 falling back to shared 'unidentified' bucket"
62            );
63            "unidentified".to_string()
64        });
65
66    match state.rate_limiter.check_rate_limit(&client_key).await {
67        Ok(RateLimitResult::Allowed {
68            remaining,
69            reset_at,
70        }) => {
71            let mut response = next.run(request).await;
72            let headers = response.headers_mut();
73            let reset_secs = reset_at
74                .checked_duration_since(Instant::now())
75                .unwrap_or(Duration::ZERO)
76                .as_secs();
77            if let Ok(v) = remaining.to_string().parse() {
78                headers.insert("X-RateLimit-Remaining", v);
79            }
80            if let Ok(v) = reset_secs.to_string().parse() {
81                headers.insert("X-RateLimit-Reset", v);
82            }
83            Ok(response)
84        }
85        Ok(RateLimitResult::Denied { retry_after, .. }) => {
86            tracing::warn!(client = %client_key, "Rate limit exceeded");
87            let mut response = ApiResponse::<()>::error(
88                "RATE_LIMIT_EXCEEDED",
89                "Too many requests — please retry after the indicated delay",
90            )
91            .into_response();
92            *response.status_mut() = StatusCode::TOO_MANY_REQUESTS;
93            let headers = response.headers_mut();
94            if let Ok(v) = retry_after.as_secs().to_string().parse() {
95                headers.insert("Retry-After", v);
96            }
97            Err(response)
98        }
99        Ok(RateLimitResult::Blocked { unblock_at, reason }) => {
100            tracing::warn!(client = %client_key, reason = %reason, "Client is blocked");
101            let mut response = ApiResponse::<()>::error(
102                "CLIENT_BLOCKED",
103                "Access temporarily blocked due to repeated rate limit violations",
104            )
105            .into_response();
106            *response.status_mut() = StatusCode::TOO_MANY_REQUESTS;
107            let unblock_secs = unblock_at
108                .checked_duration_since(Instant::now())
109                .unwrap_or(Duration::ZERO)
110                .as_secs();
111            if let Ok(v) = unblock_secs.to_string().parse() {
112                let headers = response.headers_mut();
113                headers.insert("Retry-After", v);
114            }
115            Err(response)
116        }
117        Err(e) => {
118            tracing::error!(error = %e, "Rate limiter error — rejecting request");
119            let mut response = ApiResponse::<()>::error(
120                "RATE_LIMIT_UNAVAILABLE",
121                "Rate limiting is temporarily unavailable; request rejected to protect the service",
122            )
123            .into_response();
124            *response.status_mut() = StatusCode::SERVICE_UNAVAILABLE;
125            Err(response)
126        }
127    }
128}
129
130// cors_middleware was removed: it set `Access-Control-Allow-Origin: *` which is
131// inappropriate for an authentication service.  Use tower-http's `CorsLayer`
132// with a configured `AllowOrigin` list instead.
133
134/// Log every incoming HTTP request with method, URI, client IP, and user-agent.
135///
136/// Elapsed time is logged on the response path.
137///
138/// # Example
139/// ```rust,ignore
140/// let app = Router::new()
141///     .layer(axum::middleware::from_fn(logging_middleware));
142/// ```
143pub async fn logging_middleware(request: Request, next: Next) -> Response {
144    let start = Instant::now();
145    let method = request.method().clone();
146    let uri = request.uri().clone();
147    let headers = request.headers().clone();
148
149    // Extract user agent and IP for logging, sanitized to prevent log injection
150    let user_agent = headers
151        .get("user-agent")
152        .and_then(|v| v.to_str().ok())
153        .unwrap_or("unknown");
154    let user_agent = sanitize_header_for_log(user_agent);
155
156    let forwarded_for = headers
157        .get("x-forwarded-for")
158        .and_then(|v| v.to_str().ok())
159        .unwrap_or("unknown");
160    let forwarded_for = sanitize_header_for_log(forwarded_for);
161
162    tracing::info!(
163        "Request started: {} {} from {} ({})",
164        method,
165        uri,
166        forwarded_for,
167        user_agent
168    );
169
170    let response = next.run(request).await;
171    let duration = start.elapsed();
172    let status = response.status();
173
174    tracing::info!(
175        "Request completed: {} {} {} in {:?}",
176        method,
177        uri,
178        status,
179        duration
180    );
181
182    response
183}
184
185/// Security headers middleware
186pub async fn security_headers_middleware(request: Request, next: Next) -> Response {
187    let response = next.run(request).await;
188
189    let mut response = response;
190    let headers = response.headers_mut();
191
192    // Security headers — all values are well-known static strings so from_static is safe.
193    headers.insert(
194        "X-Content-Type-Options",
195        axum::http::HeaderValue::from_static("nosniff"),
196    );
197    headers.insert(
198        "X-Frame-Options",
199        axum::http::HeaderValue::from_static("DENY"),
200    );
201    headers.insert(
202        "X-XSS-Protection",
203        axum::http::HeaderValue::from_static("1; mode=block"),
204    );
205    headers.insert(
206        "Strict-Transport-Security",
207        axum::http::HeaderValue::from_static("max-age=31536000; includeSubDomains"),
208    );
209    headers.insert(
210        "Referrer-Policy",
211        axum::http::HeaderValue::from_static("strict-origin-when-cross-origin"),
212    );
213    headers.insert(
214        "Permissions-Policy",
215        axum::http::HeaderValue::from_static("camera=(), microphone=(), geolocation=()"),
216    );
217    headers.insert(
218        "Content-Security-Policy",
219        axum::http::HeaderValue::from_static("default-src 'none'; frame-ancestors 'none'"),
220    );
221
222    response
223}
224
225/// Request timeout middleware
226#[allow(clippy::result_large_err)] // the Err type is part of the existing public signature; boxing it would change the API of a release line
227pub async fn timeout_middleware(request: Request, next: Next) -> Result<Response, Response> {
228    // Set a 30-second timeout for all requests
229    match tokio::time::timeout(Duration::from_secs(30), next.run(request)).await {
230        Ok(response) => Ok(response),
231        Err(_) => {
232            let error_response =
233                ApiResponse::<()>::error("REQUEST_TIMEOUT", "Request timed out after 30 seconds");
234            Err(error_response.into_response())
235        }
236    }
237}
238
239/// Check whether `auth_token` carries the given permission.
240///
241/// Supports exact matches, a wildcard `"*"`, and prefix wildcards such as
242/// `"read:*"` (matches `"read:users"`, `"read:settings"`, etc.).
243///
244/// # Example
245/// ```rust,ignore
246/// if check_permission(&token, "users:write") {
247///     // allow the operation
248/// }
249/// ```
250pub fn check_permission(auth_token: &crate::tokens::AuthToken, required_permission: &str) -> bool {
251    auth_token.permissions.iter().any(|perm| {
252        perm == required_permission
253            || perm == "*"
254            || (perm.ends_with("*") && required_permission.starts_with(&perm[..perm.len() - 1]))
255    })
256}
257
258/// Check whether `auth_token` carries the given role.
259///
260/// The `"admin"` role implicitly matches every role.
261///
262/// # Example
263/// ```rust,ignore
264/// if check_role(&token, "moderator") {
265///     // allow moderation actions
266/// }
267/// ```
268pub fn check_role(auth_token: &crate::tokens::AuthToken, required_role: &str) -> bool {
269    auth_token.roles.contains(required_role) || auth_token.roles.contains("admin") // Admin has all roles
270}
271
272#[cfg(test)]
273mod tests {
274    use super::*;
275    use crate::tokens::{AuthToken, TokenMetadata};
276
277    fn make_token(permissions: Vec<&str>, roles: Vec<&str>) -> AuthToken {
278        AuthToken {
279            token_id: "tid".into(),
280            user_id: "uid".into(),
281            access_token: "at".into(),
282            token_type: Some("Bearer".into()),
283            subject: Some("uid".into()),
284            issuer: Some("iss".into()),
285            refresh_token: None,
286            issued_at: chrono::Utc::now(),
287            expires_at: chrono::Utc::now(),
288            scopes: vec![].into(),
289            auth_method: "jwt".into(),
290            client_id: None,
291            user_profile: None,
292            permissions: permissions
293                .into_iter()
294                .map(String::from)
295                .collect::<Vec<_>>()
296                .into(),
297            roles: roles
298                .into_iter()
299                .map(String::from)
300                .collect::<Vec<_>>()
301                .into(),
302            metadata: TokenMetadata::default(),
303        }
304    }
305
306    // ── check_permission ────────────────────────────────────────────────
307
308    #[test]
309    fn test_check_permission_exact_match() {
310        let token = make_token(vec!["users:read"], vec![]);
311        assert!(check_permission(&token, "users:read"));
312    }
313
314    #[test]
315    fn test_check_permission_no_match() {
316        let token = make_token(vec!["users:read"], vec![]);
317        assert!(!check_permission(&token, "users:write"));
318    }
319
320    #[test]
321    fn test_check_permission_wildcard_all() {
322        let token = make_token(vec!["*"], vec![]);
323        assert!(check_permission(&token, "anything:at:all"));
324    }
325
326    #[test]
327    fn test_check_permission_wildcard_prefix() {
328        let token = make_token(vec!["users:*"], vec![]);
329        assert!(check_permission(&token, "users:read"));
330        assert!(check_permission(&token, "users:write"));
331        assert!(!check_permission(&token, "admin:read"));
332    }
333
334    #[test]
335    fn test_check_permission_empty() {
336        let token = make_token(vec![], vec![]);
337        assert!(!check_permission(&token, "anything"));
338    }
339
340    // ── check_role ──────────────────────────────────────────────────────
341
342    #[test]
343    fn test_check_role_exact_match() {
344        let token = make_token(vec![], vec!["editor"]);
345        assert!(check_role(&token, "editor"));
346    }
347
348    #[test]
349    fn test_check_role_no_match() {
350        let token = make_token(vec![], vec!["editor"]);
351        assert!(!check_role(&token, "moderator"));
352    }
353
354    #[test]
355    fn test_check_role_admin_has_all_roles() {
356        let token = make_token(vec![], vec!["admin"]);
357        assert!(check_role(&token, "anything"));
358        assert!(check_role(&token, "editor"));
359    }
360
361    #[test]
362    fn test_check_role_empty() {
363        let token = make_token(vec![], vec![]);
364        assert!(!check_role(&token, "user"));
365    }
366}