use axum::extract::Request;
use log::{debug, warn};
use std::net::{IpAddr, SocketAddr};
const MAX_FORWARDED_HOPS: usize = 32;
#[derive(Debug, Clone)]
pub struct SecureIpExtractor<'a> {
trusted_proxies: &'a TrustedProxyConfig,
}
#[derive(Debug, Clone)]
pub struct TrustedProxyConfig {
pub enabled: bool,
proxies: Vec<String>,
parsed_proxies: std::sync::OnceLock<Vec<ipnetwork::IpNetwork>>,
}
impl Default for TrustedProxyConfig {
fn default() -> Self {
let settings = crate::config::settings::TrustedProxySettings::default();
Self::from_settings(settings.enabled, settings.proxies)
}
}
impl TrustedProxyConfig {
pub fn from_settings(enabled: bool, proxies: Vec<String>) -> Self {
Self {
enabled,
proxies,
parsed_proxies: std::sync::OnceLock::new(),
}
}
pub fn is_trusted(&self, ip: &IpAddr) -> bool {
use std::str::FromStr;
let networks = self.parsed_proxies.get_or_init(|| {
self.proxies
.iter()
.filter_map(|proxy| match ipnetwork::IpNetwork::from_str(proxy) {
Ok(network) => Some(network),
Err(e) => {
warn!("Ignoring invalid trusted proxy entry {:?}: {}", proxy, e);
None
}
})
.collect()
});
networks.iter().any(|network| network.contains(*ip))
}
}
impl<'a> SecureIpExtractor<'a> {
pub fn new(trusted_proxies: &'a TrustedProxyConfig) -> Self {
Self { trusted_proxies }
}
pub fn extract_client_ip_with_override(
&self,
req: &Request,
direct_ip_override: Option<std::net::IpAddr>,
) -> Option<String> {
if let Some(direct_ip) = direct_ip_override {
if !self.trusted_proxies.enabled {
debug!("Trusted proxy validation disabled, using forwarded headers");
return self
.extract_from_forwarded_headers(req)
.or_else(|| Some(direct_ip.to_string()));
}
if self.trusted_proxies.is_trusted(&direct_ip) {
debug!(
"Request from trusted proxy {}, extracting IP from forwarded headers",
direct_ip
);
return self.extract_from_forwarded_headers(req);
} else {
debug!(
"Request from non-trusted source {}, using direct IP",
direct_ip
);
return Some(direct_ip.to_string());
}
}
let direct_ip = req
.extensions()
.get::<axum::extract::ConnectInfo<SocketAddr>>()
.map(|ci| ci.0.ip());
if !self.trusted_proxies.enabled {
debug!("Trusted proxy validation disabled, using forwarded headers");
return self
.extract_from_forwarded_headers(req)
.or_else(|| direct_ip.map(|ip| ip.to_string()));
}
let direct_ip = match direct_ip {
Some(ip) => ip,
None => {
warn!("No direct connection IP found in request");
return None;
}
};
if self.trusted_proxies.is_trusted(&direct_ip) {
debug!(
"Request from trusted proxy {}, extracting IP from forwarded headers",
direct_ip
);
self.extract_from_forwarded_headers(req)
} else {
debug!(
"Request from non-trusted source {}, using direct IP",
direct_ip
);
Some(direct_ip.to_string())
}
}
pub fn extract_client_ip(&self, req: &Request) -> Option<String> {
self.extract_client_ip_with_override(req, None)
}
fn extract_from_forwarded_headers(&self, req: &Request) -> Option<String> {
use std::net::IpAddr;
if let Some(forwarded) = req.headers().get("x-forwarded-for") {
if let Ok(ip_str) = forwarded.to_str() {
let mut rightmost_valid: Option<IpAddr> = None;
for (index, hop) in ip_str.split(',').rev().enumerate() {
if index >= MAX_FORWARDED_HOPS {
warn!(
"X-Forwarded-For exceeds {} hops; ignoring remaining entries",
MAX_FORWARDED_HOPS
);
break;
}
if let Ok(ip) = hop.trim().parse::<IpAddr>() {
if rightmost_valid.is_none() {
rightmost_valid = Some(ip);
}
if !self.trusted_proxies.is_trusted(&ip) {
return Some(ip.to_string());
}
}
}
if let Some(ip) = rightmost_valid {
return Some(ip.to_string());
}
}
}
if !self.trusted_proxies.enabled {
if let Some(real_ip) = req.headers().get("x-real-ip") {
if let Ok(ip_str) = real_ip.to_str() {
let trimmed = ip_str.trim();
if self.is_valid_ip(trimmed) {
return Some(trimmed.to_string());
}
}
}
}
None
}
fn is_valid_ip(&self, ip_str: &str) -> bool {
ip_str.parse::<IpAddr>().is_ok()
}
}
pub fn get_secure_client_ip(req: &Request, trusted_proxies: &TrustedProxyConfig) -> String {
let extractor = SecureIpExtractor::new(trusted_proxies);
extractor
.extract_client_ip(req)
.unwrap_or_else(|| "unknown".to_string())
}
#[cfg(test)]
mod tests {
use super::*;
use axum::http::Request as HttpRequest;
#[test]
fn test_trusted_proxy_config_default() {
let config = TrustedProxyConfig::default();
assert!(config.enabled);
let ip: IpAddr = "10.0.0.1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "172.16.0.1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "192.168.1.1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "127.0.0.1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "8.8.8.8".parse().unwrap();
assert!(!config.is_trusted(&ip));
}
#[test]
fn test_trusted_proxy_config_ipv6() {
let config = TrustedProxyConfig::default();
let ip: IpAddr = "::1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "2001:db8::1".parse().unwrap();
assert!(!config.is_trusted(&ip));
}
#[test]
fn test_trusted_proxy_config_custom_cidr() {
let config = TrustedProxyConfig::from_settings(
true,
vec!["203.0.113.0/24".to_string(), "198.51.100.1".to_string()],
);
let ip: IpAddr = "203.0.113.100".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "198.51.100.1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "203.0.114.1".parse().unwrap();
assert!(!config.is_trusted(&ip));
}
#[test]
fn test_is_valid_ip() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
assert!(extractor.is_valid_ip("192.168.1.1"));
assert!(extractor.is_valid_ip("0.0.0.0"));
assert!(extractor.is_valid_ip("255.255.255.255"));
assert!(extractor.is_valid_ip("::1"));
assert!(extractor.is_valid_ip("2001:db8::1"));
assert!(!extractor.is_valid_ip(""));
assert!(!extractor.is_valid_ip("invalid"));
assert!(!extractor.is_valid_ip("256.256.256.256"));
assert!(!extractor.is_valid_ip("192.168.1"));
}
#[test]
fn test_extract_from_forwarded_headers() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", "203.0.113.1, 198.51.100.1, 192.0.2.1")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert_eq!(ip, Some("192.0.2.1".to_string()));
let req = HttpRequest::builder()
.header("x-forwarded-for", "1.2.3.4, 203.0.113.1, 10.0.0.1")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert_eq!(ip, Some("203.0.113.1".to_string()));
let dev_config = TrustedProxyConfig::from_settings(false, vec![]);
let dev_extractor = SecureIpExtractor::new(&dev_config);
let req = HttpRequest::builder()
.header("x-real-ip", "203.0.113.2")
.body(axum::body::Body::empty())
.unwrap();
let ip = dev_extractor.extract_from_forwarded_headers(&req);
assert_eq!(ip, Some("203.0.113.2".to_string()));
let ip = extractor.extract_from_forwarded_headers(&req);
assert!(ip.is_none(), "X-Real-IP must not be trusted in proxy mode");
let req = HttpRequest::builder()
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert!(ip.is_none());
}
#[test]
fn test_extract_from_forwarded_headers_with_spaces() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", " 203.0.113.1 , 198.51.100.1 ")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert_eq!(ip, Some("198.51.100.1".to_string()));
}
#[test]
fn test_extract_from_forwarded_headers_invalid_ip() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", "invalid-ip, 198.51.100.1")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert_eq!(ip, Some("198.51.100.1".to_string()));
}
#[test]
fn test_extract_forwarded_all_trusted_returns_rightmost() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", "10.1.2.3, 10.1.2.4")
.body(axum::body::Body::empty())
.unwrap();
assert_eq!(
extractor.extract_from_forwarded_headers(&req),
Some("10.1.2.4".to_string())
);
}
#[test]
fn test_extract_forwarded_hop_limit() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
let mut hops = vec!["203.0.113.9".to_string()];
hops.extend((1..=39).map(|i| format!("10.0.0.{i}")));
let req = HttpRequest::builder()
.header("x-forwarded-for", hops.join(", "))
.body(axum::body::Body::empty())
.unwrap();
assert_eq!(
extractor.extract_from_forwarded_headers(&req),
Some("10.0.0.39".to_string())
);
}
#[test]
fn test_secure_ip_extractor_new_constructor() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip(&req);
assert!(ip.is_none());
}
#[test]
fn test_trusted_proxy_config_from_settings_enabled() {
let config = TrustedProxyConfig::from_settings(
true,
vec!["10.0.0.1".to_string(), "192.168.1.0/24".to_string()],
);
assert!(config.enabled);
assert_eq!(config.proxies.len(), 2);
let ip: IpAddr = "10.0.0.1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "192.168.1.100".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "8.8.8.8".parse().unwrap();
assert!(!config.is_trusted(&ip));
}
#[test]
fn test_trusted_proxy_config_from_settings_disabled() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
assert!(!config.enabled);
assert!(config.proxies.is_empty());
let ip: IpAddr = "8.8.8.8".parse().unwrap();
assert!(!config.is_trusted(&ip));
}
#[test]
fn test_extract_client_ip_with_override_disabled_uses_forwarded() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let extractor = SecureIpExtractor::new(&config);
let direct_ip: IpAddr = "8.8.8.8".parse().unwrap();
let req = HttpRequest::builder()
.header("x-forwarded-for", "1.2.3.4")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip_with_override(&req, Some(direct_ip));
assert_eq!(ip, Some("1.2.3.4".to_string()));
}
#[test]
fn test_extract_client_ip_with_override_disabled_fallback_to_direct() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let extractor = SecureIpExtractor::new(&config);
let direct_ip: IpAddr = "8.8.8.8".parse().unwrap();
let req = HttpRequest::builder()
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip_with_override(&req, Some(direct_ip));
assert_eq!(ip, Some("8.8.8.8".to_string()));
}
#[test]
fn test_extract_client_ip_with_override_enabled_trusted_proxy() {
let config = TrustedProxyConfig::from_settings(true, vec!["10.0.0.1".to_string()]);
let extractor = SecureIpExtractor::new(&config);
let direct_ip: IpAddr = "10.0.0.1".parse().unwrap();
let req = HttpRequest::builder()
.header("x-forwarded-for", "203.0.113.1")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip_with_override(&req, Some(direct_ip));
assert_eq!(ip, Some("203.0.113.1".to_string()));
}
#[test]
fn test_extract_client_ip_with_override_enabled_trusted_proxy_no_forwarded() {
let config = TrustedProxyConfig::from_settings(true, vec!["10.0.0.1".to_string()]);
let extractor = SecureIpExtractor::new(&config);
let direct_ip: IpAddr = "10.0.0.1".parse().unwrap();
let req = HttpRequest::builder()
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip_with_override(&req, Some(direct_ip));
assert_eq!(ip, None);
}
#[test]
fn test_extract_client_ip_with_override_enabled_non_trusted() {
let config = TrustedProxyConfig::from_settings(true, vec!["10.0.0.1".to_string()]);
let extractor = SecureIpExtractor::new(&config);
let direct_ip: IpAddr = "8.8.8.8".parse().unwrap();
let req = HttpRequest::builder()
.header("x-forwarded-for", "1.2.3.4")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip_with_override(&req, Some(direct_ip));
assert_eq!(ip, Some("8.8.8.8".to_string()));
}
#[test]
fn test_extract_client_ip_with_override_none_with_connect_info_trusted() {
let config = TrustedProxyConfig::from_settings(true, vec!["127.0.0.1".to_string()]);
let extractor = SecureIpExtractor::new(&config);
let socket_addr: SocketAddr = "127.0.0.1:8080".parse().unwrap();
let mut req = HttpRequest::builder()
.header("x-forwarded-for", "203.0.113.5")
.body(axum::body::Body::empty())
.unwrap();
req.extensions_mut()
.insert(axum::extract::ConnectInfo(socket_addr));
let ip = extractor.extract_client_ip_with_override(&req, None);
assert_eq!(ip, Some("203.0.113.5".to_string()));
}
#[test]
fn test_extract_client_ip_with_override_none_with_connect_info_non_trusted() {
let config = TrustedProxyConfig::from_settings(true, vec!["127.0.0.1".to_string()]);
let extractor = SecureIpExtractor::new(&config);
let socket_addr: SocketAddr = "8.8.8.8:8080".parse().unwrap();
let mut req = HttpRequest::builder()
.header("x-forwarded-for", "1.2.3.4")
.body(axum::body::Body::empty())
.unwrap();
req.extensions_mut()
.insert(axum::extract::ConnectInfo(socket_addr));
let ip = extractor.extract_client_ip_with_override(&req, None);
assert_eq!(ip, Some("8.8.8.8".to_string()));
}
#[test]
fn test_extract_client_ip_with_override_none_no_connect_info_enabled() {
let config = TrustedProxyConfig::from_settings(true, vec!["127.0.0.1".to_string()]);
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", "1.2.3.4")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip_with_override(&req, None);
assert!(ip.is_none());
}
#[test]
fn test_extract_client_ip_with_override_none_no_connect_info_disabled() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", "1.2.3.4")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip_with_override(&req, None);
assert_eq!(ip, Some("1.2.3.4".to_string()));
let req = HttpRequest::builder()
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip_with_override(&req, None);
assert!(ip.is_none());
}
#[test]
fn test_extract_client_ip_delegates_to_with_override_none() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-real-ip", "203.0.113.99")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_client_ip(&req);
assert_eq!(ip, Some("203.0.113.99".to_string()));
}
#[test]
fn test_get_secure_client_ip_returns_ip() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let req = HttpRequest::builder()
.header("x-forwarded-for", "203.0.113.10")
.body(axum::body::Body::empty())
.unwrap();
let ip = get_secure_client_ip(&req, &config);
assert_eq!(ip, "203.0.113.10");
}
#[test]
fn test_get_secure_client_ip_returns_unknown() {
let config = TrustedProxyConfig::from_settings(true, vec!["127.0.0.1".to_string()]);
let req = HttpRequest::builder()
.body(axum::body::Body::empty())
.unwrap();
let ip = get_secure_client_ip(&req, &config);
assert_eq!(ip, "unknown");
}
#[test]
fn test_extract_from_forwarded_headers_invalid_ip_falls_through_to_x_real_ip() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", "invalid-ip")
.header("x-real-ip", "203.0.113.20")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert_eq!(ip, Some("203.0.113.20".to_string()));
}
#[test]
fn test_extract_from_forwarded_headers_invalid_ip_proxy_mode_ignores_x_real_ip() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", "invalid-ip")
.header("x-real-ip", "203.0.113.20")
.body(axum::body::Body::empty())
.unwrap();
assert!(extractor.extract_from_forwarded_headers(&req).is_none());
}
#[test]
fn test_extract_from_forwarded_headers_empty_x_forwarded_for() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-forwarded-for", "")
.header("x-real-ip", "203.0.113.21")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert_eq!(ip, Some("203.0.113.21".to_string()));
let req = HttpRequest::builder()
.header("x-forwarded-for", "")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert!(ip.is_none());
}
#[test]
fn test_extract_from_forwarded_headers_empty_x_real_ip() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
let req = HttpRequest::builder()
.header("x-real-ip", "")
.body(axum::body::Body::empty())
.unwrap();
let ip = extractor.extract_from_forwarded_headers(&req);
assert!(ip.is_none());
}
#[test]
fn test_is_trusted_with_invalid_proxy_entry_skips_and_continues() {
let config = TrustedProxyConfig::from_settings(
true,
vec!["not-a-valid-cidr-or-ip".to_string(), "10.0.0.1".to_string()],
);
let ip: IpAddr = "10.0.0.1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "8.8.8.8".parse().unwrap();
assert!(!config.is_trusted(&ip));
}
#[test]
fn test_is_trusted_all_invalid_entries_returns_false() {
let config = TrustedProxyConfig::from_settings(
true,
vec!["invalid1".to_string(), "invalid2".to_string()],
);
let ip: IpAddr = "10.0.0.1".parse().unwrap();
assert!(!config.is_trusted(&ip));
}
#[test]
fn test_extract_from_forwarded_headers_non_utf8_x_forwarded_for_falls_to_x_real_ip() {
let config = TrustedProxyConfig::from_settings(false, vec![]);
let extractor = SecureIpExtractor::new(&config);
let mut req = HttpRequest::builder()
.header("x-real-ip", "203.0.113.1")
.body(axum::body::Body::empty())
.unwrap();
req.headers_mut().insert(
"x-forwarded-for",
axum::http::HeaderValue::from_bytes(&[0x80, 0x81, 0x82]).unwrap(),
);
let ip = extractor.extract_from_forwarded_headers(&req);
assert_eq!(ip, Some("203.0.113.1".to_string()));
}
#[test]
fn test_extract_from_forwarded_headers_non_utf8_both_headers_returns_none() {
let config = TrustedProxyConfig::default();
let extractor = SecureIpExtractor::new(&config);
let mut req = HttpRequest::builder()
.body(axum::body::Body::empty())
.unwrap();
req.headers_mut().insert(
"x-forwarded-for",
axum::http::HeaderValue::from_bytes(&[0x80, 0x81]).unwrap(),
);
req.headers_mut().insert(
"x-real-ip",
axum::http::HeaderValue::from_bytes(&[0x82, 0x83]).unwrap(),
);
let ip = extractor.extract_from_forwarded_headers(&req);
assert!(ip.is_none());
}
#[test]
fn test_is_trusted_ipv6_cidr() {
let config = TrustedProxyConfig::from_settings(true, vec!["2001:db8::/32".to_string()]);
let ip: IpAddr = "2001:db8::1".parse().unwrap();
assert!(config.is_trusted(&ip));
let ip: IpAddr = "2001:db9::1".parse().unwrap();
assert!(!config.is_trusted(&ip));
}
}