footing 0.1.1

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

use std::{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 present = false;
    let mut chain = Vec::new();
    for value in &values {
        present = true;
        let value = value.to_str().map_err(|_| ())?;
        for hop in value.split(',') {
            chain.push(ClientIp::parse(hop.trim()).ok_or(())?);
        }
    }

    if !present {
        return Ok(None);
    }
    (!chain.is_empty()).then_some(chain).ok_or(()).map(Some)
}

fn parse_forwarded(headers: &HeaderMap) -> Result<Option<Vec<ClientIp>>, ()> {
    let values = headers.get_all("forwarded");
    let mut present = false;
    let mut chain = Vec::new();
    for value in &values {
        present = true;
        let value = value.to_str().map_err(|_| ())?;
        for element in value.split(',') {
            let mut forwarded_for = None;
            for parameter in element.split(';') {
                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(ClientIp::parse(value.trim()).ok_or(())?);
            }
            chain.push(forwarded_for.ok_or(())?);
        }
    }

    if !present {
        return Ok(None);
    }
    (!chain.is_empty()).then_some(chain).ok_or(()).map(Some)
}

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(config) => chain
            .iter()
            .rev()
            .find(|hop| !config.is_trusted(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)
}