footing 0.3.1

Feature-gated foundations for Rust backend services
Documentation
//! Trusted forwarded-header client-IP resolution.

use std::{borrow::Cow, fmt, net::IpAddr};

use axum::http::HeaderMap;
use serde::{Deserialize, Serialize};

use crate::{http::trusted_proxy::ForwardedHeadersPolicy, net::ClientIp};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
/// Enumerates the supported client IP source values.
pub enum ClientIpSource {
    /// Indicates peer.
    Peer,
    /// Indicates x forwarded for.
    XForwardedFor,
    /// Indicates x real IP.
    XRealIp,
    /// Indicates forwarded.
    Forwarded,
    /// Indicates explicit.
    Explicit,
}

impl ClientIpSource {
    #[must_use]
    /// Returns this value as str.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Peer => "peer",
            Self::XForwardedFor => "x_forwarded_for",
            Self::XRealIp => "x_real_ip",
            Self::Forwarded => "forwarded",
            Self::Explicit => "explicit",
        }
    }
}

impl fmt::Display for ClientIpSource {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.as_str())
    }
}

pub(super) fn client_ip_from_forwarded_headers(
    headers: &HeaderMap,
    peer_client_ip: Option<IpAddr>,
    policy: &ForwardedHeadersPolicy,
) -> Option<(ClientIp, ClientIpSource)> {
    if !policy.should_trust(peer_client_ip) {
        return None;
    }

    match forwarding_chain(headers) {
        Ok(Some((chain, source))) => {
            forwarded_chain_client_ip(&chain, policy).map(|client_ip| (client_ip, source))
        }
        Ok(None) => single_proxy_real_ip(headers)
            .ok()
            .flatten()
            .map(|client_ip| (client_ip, ClientIpSource::XRealIp)),
        Err(()) => None,
    }
}

fn forwarding_chain(headers: &HeaderMap) -> Result<Option<(Vec<ClientIp>, ClientIpSource)>, ()> {
    let forwarded_for = parse_x_forwarded_for(headers)?;
    let forwarded = parse_forwarded(headers)?;

    match (forwarded_for, forwarded) {
        (None, None) => Ok(None),
        (Some(chain), None) => Ok(Some((chain, ClientIpSource::XForwardedFor))),
        (None, Some(chain)) => Ok(Some((chain, ClientIpSource::Forwarded))),
        (Some(forwarded_for), Some(forwarded)) if forwarded_for == forwarded => {
            Ok(Some((forwarded, ClientIpSource::Forwarded)))
        }
        (Some(_), Some(_)) => Err(()),
    }
}

fn parse_x_forwarded_for(headers: &HeaderMap) -> Result<Option<Vec<ClientIp>>, ()> {
    let values = headers.get_all("x-forwarded-for");
    let mut chain = Vec::new();
    for value in &values {
        let value = value.to_str().map_err(|_| ())?;
        for hop in value.split(',') {
            chain.push(ClientIp::parse(hop.trim()).ok_or(())?);
        }
    }

    Ok((!chain.is_empty()).then_some(chain))
}

fn parse_forwarded(headers: &HeaderMap) -> Result<Option<Vec<ClientIp>>, ()> {
    let values = headers.get_all("forwarded");
    let mut chain = Vec::new();
    for value in &values {
        let value = value.to_str().map_err(|_| ())?;
        for element in split_forwarded_quoted(value, b',')? {
            let mut forwarded_for = None;
            for parameter in split_forwarded_quoted(element, b';')? {
                let (name, value) = parameter.split_once('=').ok_or(())?;
                if !name.trim().eq_ignore_ascii_case("for") {
                    continue;
                }
                if forwarded_for.is_some() {
                    return Err(());
                }
                forwarded_for = Some(parse_forwarded_for(value.trim())?);
            }
            chain.push(forwarded_for.ok_or(())?);
        }
    }

    Ok((!chain.is_empty()).then_some(chain))
}

// RFC 7239 values can contain separators and escaped quotes inside quoted strings.
fn split_forwarded_quoted(value: &str, separator: u8) -> Result<Vec<&str>, ()> {
    let mut parts = Vec::new();
    let mut start = 0;
    let mut quoted = false;
    let mut escaped = false;
    for (index, byte) in value.bytes().enumerate() {
        if escaped {
            escaped = false;
        } else if quoted && byte == b'\\' {
            escaped = true;
        } else if byte == b'"' {
            quoted = !quoted;
        } else if !quoted && byte == separator {
            parts.push(&value[start..index]);
            start = index + 1;
        }
    }
    if quoted || escaped {
        return Err(());
    }
    parts.push(&value[start..]);
    Ok(parts)
}

fn parse_forwarded_for(value: &str) -> Result<ClientIp, ()> {
    let value = if let Some(quoted) = value.strip_circumfix('"', '"') {
        if quoted.contains('\\') {
            let mut decoded = String::with_capacity(quoted.len());
            let mut chars = quoted.chars();
            while let Some(ch) = chars.next() {
                decoded.push(if ch == '\\' {
                    chars.next().ok_or(())?
                } else {
                    ch
                });
            }
            Cow::Owned(decoded)
        } else {
            Cow::Borrowed(quoted)
        }
    } else {
        Cow::Borrowed(value)
    };
    // The generic client-IP normalizer accepts quotes; a decoded node must not.
    if value.contains('"') {
        return Err(());
    }
    ClientIp::parse(&value).ok_or(())
}

fn forwarded_chain_client_ip(
    chain: &[ClientIp],
    policy: &ForwardedHeadersPolicy,
) -> Option<ClientIp> {
    match policy {
        ForwardedHeadersPolicy::Never => None,
        // `Always` has no trusted-hop set, so the nearest asserted hop is the
        // only conservative client candidate. Multi-proxy deployments should
        // use `TrustedProxies` instead.
        ForwardedHeadersPolicy::Always => chain.last().cloned(),
        ForwardedHeadersPolicy::TrustedProxies(networks) => chain
            .iter()
            .rev()
            .find(|hop| !networks.contains(hop.as_ip_addr()))
            .cloned(),
    }
}

fn single_proxy_real_ip(headers: &HeaderMap) -> Result<Option<ClientIp>, ()> {
    let mut values = headers.get_all("x-real-ip").iter();
    let Some(value) = values.next() else {
        return Ok(None);
    };
    if values.next().is_some() {
        return Err(());
    }

    let value = value.to_str().map_err(|_| ())?;
    if value.contains(',') {
        return Err(());
    }
    ClientIp::parse(value.trim()).ok_or(()).map(Some)
}