feedparser_rs/util/

base_url.rs

//! Base URL resolution for xml:base support
//!
//! This module provides URL resolution following RFC 3986, supporting
//! the `xml:base` attribute used in Atom and some RSS feeds.

use super::ssrf;
use url::Url;

/// Validates that a URL is safe for external use (no SSRF risks)
///
/// This function checks for common SSRF attack vectors including:
/// - Non-HTTP(S) schemes (file://, data://, etc.)
/// - Localhost addresses (127.0.0.1, `::1`, localhost)
/// - Private IP ranges (192.168.x.x, 10.x.x.x, 172.16-31.x.x)
/// - Cloud metadata endpoints (169.254.169.254)
///
/// Delegates to the same [`crate::http::validation::validate_url`] rule set used
/// by the HTTP fetcher, so `xml:base`-derived links and fetched feed URLs are
/// held to identical SSRF protections.
///
/// # Arguments
///
/// * `url` - The URL to validate
///
/// # Returns
///
/// `true` if the URL is safe to use, `false` if it poses SSRF risks
///
/// # Examples
///
/// ```
/// use feedparser_rs::util::base_url::is_safe_url;
///
/// // Safe URLs
/// assert!(is_safe_url("http://example.com/"));
/// assert!(is_safe_url("https://github.com/"));
///
/// // Unsafe URLs
/// assert!(!is_safe_url("file:///etc/passwd"));
/// assert!(!is_safe_url("http://localhost/"));
/// assert!(!is_safe_url("http://192.168.1.1/"));
/// assert!(!is_safe_url("http://169.254.169.254/"));
/// ```
#[must_use]
pub fn is_safe_url(url: &str) -> bool {
    ssrf::validate_url(url).is_ok()
}

/// Resolves a potentially relative URL against a base URL
///
/// If `href` is already absolute, returns it unchanged.
/// If `base` is None or invalid, returns `href` unchanged.
/// Otherwise, resolves `href` relative to `base`.
///
/// # Arguments
///
/// * `href` - The URL to resolve (may be relative or absolute)
/// * `base` - The base URL to resolve against (may be None)
///
/// # Returns
///
/// The resolved URL as a string
///
/// # Examples
///
/// ```
/// use feedparser_rs::util::base_url::resolve_url;
///
/// // Absolute URLs are returned unchanged
/// assert_eq!(
///     resolve_url("http://example.com/page", Some("http://other.com/")),
///     "http://example.com/page"
/// );
///
/// // Relative URLs are resolved against the base
/// assert_eq!(
///     resolve_url("page.html", Some("http://example.com/dir/")),
///     "http://example.com/dir/page.html"
/// );
///
/// // Without a base, relative URLs are returned unchanged
/// assert_eq!(resolve_url("page.html", None), "page.html");
/// ```
#[must_use]
pub fn resolve_url(href: &str, base: Option<&str>) -> String {
    // If href is already absolute, return it
    if href.starts_with("http://")
        || href.starts_with("https://")
        || href.starts_with("mailto:")
        || href.starts_with("tel:")
    {
        return href.to_string();
    }

    // If no base URL, return href unchanged
    let Some(base_str) = base else {
        return href.to_string();
    };

    // Try to parse base URL
    let Ok(base_url) = Url::parse(base_str) else {
        return href.to_string();
    };

    // Resolve href against base
    base_url
        .join(href)
        .map_or_else(|_| href.to_string(), |resolved| resolved.to_string())
}

/// Combines two base URLs, with child overriding parent
///
/// This handles nested `xml:base` attributes where a child element's
/// base URL may be relative to its parent's base.
///
/// # Arguments
///
/// * `parent_base` - The parent element's base URL (may be None)
/// * `child_base` - The child element's xml:base value (may be None)
///
/// # Returns
///
/// The effective base URL for the child element, or None if no base is set
///
/// # Examples
///
/// ```
/// use feedparser_rs::util::base_url::combine_bases;
///
/// // Child absolute base overrides parent
/// assert_eq!(
///     combine_bases(Some("http://parent.com/"), Some("http://child.com/")),
///     Some("http://child.com/".to_string())
/// );
///
/// // Child relative base is resolved against parent
/// assert_eq!(
///     combine_bases(Some("http://example.com/feed/"), Some("items/")),
///     Some("http://example.com/feed/items/".to_string())
/// );
///
/// // No child base, parent is used
/// assert_eq!(
///     combine_bases(Some("http://example.com/"), None),
///     Some("http://example.com/".to_string())
/// );
///
/// // No bases at all
/// assert_eq!(combine_bases(None, None), None);
/// ```
#[must_use]
pub fn combine_bases(parent_base: Option<&str>, child_base: Option<&str>) -> Option<String> {
    match (parent_base, child_base) {
        (_, Some(child)) => {
            // Child has a base - resolve it against parent if parent exists
            Some(resolve_url(child, parent_base))
        }
        (Some(parent), None) => Some(parent.to_string()),
        (None, None) => None,
    }
}

/// Context for tracking base URLs during parsing
///
/// This struct maintains the current base URL context and provides
/// methods for URL resolution within a parsing context.
#[derive(Debug, Clone)]
pub struct BaseUrlContext {
    /// The current effective base URL
    base: Option<String>,
    /// Whether `resolve`/`resolve_safe` actually resolve relative URLs against
    /// `base`, or pass `href` through unchanged (`ParseOptions::resolve_relative_uris`)
    resolve: bool,
}

impl Default for BaseUrlContext {
    fn default() -> Self {
        Self::new()
    }
}

impl BaseUrlContext {
    /// Creates a new context with no base URL
    #[must_use]
    pub const fn new() -> Self {
        Self {
            base: None,
            resolve: true,
        }
    }

    /// Creates a new context with an initial base URL
    #[must_use]
    pub fn with_base(base: impl Into<String>) -> Self {
        Self {
            base: Some(base.into()),
            resolve: true,
        }
    }

    /// Sets whether relative URL resolution is enabled (builder pattern)
    ///
    /// When `false`, [`Self::resolve`] never joins `href` against `base` — it
    /// always returns `href` unchanged. [`Self::resolve_safe`] is different:
    /// it still validates whatever `resolve` returns (dangerous schemes,
    /// SSRF/private-IP checks) even when this is `false`, so it does **not**
    /// simply return `href` unchanged — see its docs for why. Mirrors
    /// `ParseOptions::resolve_relative_uris`.
    #[must_use]
    pub const fn with_resolve(mut self, resolve: bool) -> Self {
        self.resolve = resolve;
        self
    }

    /// Gets the current base URL
    #[must_use]
    pub fn base(&self) -> Option<&str> {
        self.base.as_deref()
    }

    /// Updates the base URL with a new xml:base value
    ///
    /// The new base is resolved against the current base if it's relative.
    pub fn update_base(&mut self, xml_base: &str) {
        let new_base = resolve_url(xml_base, self.base.as_deref());
        self.base = Some(new_base);
    }

    /// Resolves a URL against the current base
    ///
    /// Returns `href` unchanged when relative URL resolution is disabled
    /// (see [`Self::with_resolve`]).
    #[must_use]
    pub fn resolve(&self, href: &str) -> String {
        if !self.resolve {
            return href.to_string();
        }
        resolve_url(href, self.base.as_deref())
    }

    /// Resolves a URL against the current base with SSRF protection
    ///
    /// This method performs URL resolution and validates the result to prevent
    /// Server-Side Request Forgery (SSRF) attacks via malicious xml:base attributes.
    ///
    /// # Security
    ///
    /// If the resolved URL fails SSRF safety checks (localhost, private IPs,
    /// dangerous schemes), the original `href` is returned unchanged instead
    /// of the resolved URL.
    ///
    /// # Security
    ///
    /// These safety checks run **unconditionally**, even when relative URL
    /// resolution is disabled via [`Self::with_resolve`]. `with_resolve(false)`
    /// only disables joining `href` against `base`; it never skips scheme/SSRF
    /// validation, so a feed-supplied `href` that is itself an absolute
    /// dangerous or private-network URL is still blocked (#438).
    ///
    /// # Arguments
    ///
    /// * `href` - The URL to resolve (may be relative or absolute)
    ///
    /// # Returns
    ///
    /// The resolved URL if safe, otherwise the original `href`
    ///
    /// # Examples
    ///
    /// ```
    /// use feedparser_rs::util::base_url::BaseUrlContext;
    ///
    /// // Safe URL resolution
    /// let ctx = BaseUrlContext::with_base("http://example.com/");
    /// assert_eq!(ctx.resolve_safe("page.html"), "http://example.com/page.html");
    ///
    /// // SSRF blocked - returns original href
    /// let dangerous_ctx = BaseUrlContext::with_base("http://localhost/");
    /// assert_eq!(dangerous_ctx.resolve_safe("admin"), "admin");
    ///
    /// // Safety checks still run when relative resolution is disabled
    /// let no_resolve_ctx = BaseUrlContext::new().with_resolve(false);
    /// assert_eq!(
    ///     no_resolve_ctx.resolve_safe("http://169.254.169.254/latest/meta-data/"),
    ///     ""
    /// );
    /// ```
    #[must_use]
    pub fn resolve_safe(&self, href: &str) -> String {
        // `self.resolve()` already respects `self.resolve`: it returns `href`
        // unchanged (no base joining) when relative resolution is disabled. The
        // scheme/SSRF checks below always run on whatever it returns, so a
        // feed-supplied absolute `href` is validated regardless of that setting.
        let resolved = self.resolve(href);

        // Use lowercase for case-insensitive scheme comparison (RFC 3986)
        let resolved_lower = resolved.to_lowercase();

        // Block dangerous schemes (file://, data://, javascript://, etc.)
        // Case-insensitive to prevent bypass via FILE://, JAVASCRIPT:, etc.
        if resolved_lower.starts_with("file://")
            || resolved_lower.starts_with("data:")
            || resolved_lower.starts_with("javascript:")
            || resolved_lower.starts_with("ftp://")
            || resolved_lower.starts_with("gopher://")
        {
            // Dangerous scheme - return original href
            return href.to_string();
        }

        // Validate HTTP(S) URLs for SSRF
        if resolved_lower.starts_with("http://") || resolved_lower.starts_with("https://") {
            if is_safe_url(&resolved) {
                resolved
            } else {
                // SSRF blocked - check if href itself is an unsafe absolute URL
                // If href is an absolute URL pointing to dangerous target, return empty
                // Otherwise return original relative href (safe since it requires base to resolve)
                let href_is_unsafe_absolute = Url::parse(href).is_ok_and(|parsed_href| {
                    let is_http_scheme = matches!(parsed_href.scheme(), "http" | "https");
                    is_http_scheme && !is_safe_url(href)
                });

                if href_is_unsafe_absolute {
                    String::new()
                } else {
                    href.to_string()
                }
            }
        } else {
            // Other schemes (mailto:, tel:) or relative URLs pass through
            resolved
        }
    }

    /// Creates a child context inheriting this context's base
    #[must_use]
    pub fn child(&self) -> Self {
        Self {
            base: self.base.clone(),
            resolve: self.resolve,
        }
    }

    /// Creates a child context with an additional xml:base
    #[must_use]
    pub fn child_with_base(&self, xml_base: &str) -> Self {
        let new_base = combine_bases(self.base.as_deref(), Some(xml_base));
        Self {
            base: new_base,
            resolve: self.resolve,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_resolve_absolute_url() {
        assert_eq!(
            resolve_url("http://example.com/page", Some("http://other.com/")),
            "http://example.com/page"
        );
        assert_eq!(
            resolve_url("https://example.com/page", Some("http://other.com/")),
            "https://example.com/page"
        );
    }

    #[test]
    fn test_resolve_relative_url() {
        assert_eq!(
            resolve_url("page.html", Some("http://example.com/dir/")),
            "http://example.com/dir/page.html"
        );
        assert_eq!(
            resolve_url("/absolute/path", Some("http://example.com/dir/")),
            "http://example.com/absolute/path"
        );
        assert_eq!(
            resolve_url("../sibling/page", Some("http://example.com/dir/sub/")),
            "http://example.com/dir/sibling/page"
        );
    }

    #[test]
    fn test_resolve_without_base() {
        assert_eq!(resolve_url("page.html", None), "page.html");
        assert_eq!(
            resolve_url("http://example.com", None),
            "http://example.com"
        );
    }

    #[test]
    fn test_resolve_invalid_base() {
        assert_eq!(
            resolve_url("page.html", Some("not a valid url")),
            "page.html"
        );
    }

    #[test]
    fn test_resolve_special_schemes() {
        assert_eq!(
            resolve_url("mailto:test@example.com", Some("http://example.com/")),
            "mailto:test@example.com"
        );
        assert_eq!(
            resolve_url("tel:+1234567890", Some("http://example.com/")),
            "tel:+1234567890"
        );
    }

    #[test]
    fn test_combine_bases_child_absolute() {
        assert_eq!(
            combine_bases(Some("http://parent.com/"), Some("http://child.com/")),
            Some("http://child.com/".to_string())
        );
    }

    #[test]
    fn test_combine_bases_child_relative() {
        assert_eq!(
            combine_bases(Some("http://example.com/feed/"), Some("items/")),
            Some("http://example.com/feed/items/".to_string())
        );
    }

    #[test]
    fn test_combine_bases_no_child() {
        assert_eq!(
            combine_bases(Some("http://example.com/"), None),
            Some("http://example.com/".to_string())
        );
    }

    #[test]
    fn test_combine_bases_no_parent() {
        assert_eq!(
            combine_bases(None, Some("http://example.com/")),
            Some("http://example.com/".to_string())
        );
    }

    #[test]
    fn test_combine_bases_none() {
        assert_eq!(combine_bases(None, None), None);
    }

    #[test]
    fn test_context_new() {
        let ctx = BaseUrlContext::new();
        assert!(ctx.base().is_none());
    }

    #[test]
    fn test_context_with_base() {
        let ctx = BaseUrlContext::with_base("http://example.com/");
        assert_eq!(ctx.base(), Some("http://example.com/"));
    }

    #[test]
    fn test_context_update_base() {
        let mut ctx = BaseUrlContext::with_base("http://example.com/feed/");
        ctx.update_base("items/");
        assert_eq!(ctx.base(), Some("http://example.com/feed/items/"));
    }

    #[test]
    fn test_context_resolve() {
        let ctx = BaseUrlContext::with_base("http://example.com/feed/");
        assert_eq!(
            ctx.resolve("item.html"),
            "http://example.com/feed/item.html"
        );
        assert_eq!(ctx.resolve("http://other.com/"), "http://other.com/");
    }

    #[test]
    fn test_context_child() {
        let parent = BaseUrlContext::with_base("http://example.com/");
        let child = parent.child();
        assert_eq!(child.base(), Some("http://example.com/"));
    }

    #[test]
    fn test_context_resolve_disabled() {
        let ctx = BaseUrlContext::with_base("http://example.com/feed/").with_resolve(false);
        assert_eq!(ctx.resolve("item.html"), "item.html");
        assert_eq!(ctx.resolve_safe("item.html"), "item.html");
    }

    #[test]
    fn test_context_resolve_disabled_propagates_to_children() {
        let ctx = BaseUrlContext::with_base("http://example.com/").with_resolve(false);
        assert_eq!(ctx.child().resolve("page.html"), "page.html");
        assert_eq!(
            ctx.child_with_base("sub/").resolve("page.html"),
            "page.html"
        );
    }

    #[test]
    fn test_context_child_with_base() {
        let parent = BaseUrlContext::with_base("http://example.com/feed/");
        let child = parent.child_with_base("items/");
        assert_eq!(child.base(), Some("http://example.com/feed/items/"));
    }

    #[test]
    fn test_fragment_preservation() {
        assert_eq!(
            resolve_url("#section", Some("http://example.com/page.html")),
            "http://example.com/page.html#section"
        );
    }

    #[test]
    fn test_query_string_preservation() {
        assert_eq!(
            resolve_url("?query=value", Some("http://example.com/page.html")),
            "http://example.com/page.html?query=value"
        );
    }

    #[test]
    fn test_empty_href() {
        // Empty href should resolve to base URL itself
        assert_eq!(
            resolve_url("", Some("http://example.com/page.html")),
            "http://example.com/page.html"
        );
    }

    // SSRF Protection Tests
    #[test]
    fn test_is_safe_url_file_scheme() {
        assert!(!is_safe_url("file:///etc/passwd"));
        assert!(!is_safe_url("file:///C:/Windows/System32/config/sam"));
    }

    #[test]
    fn test_is_safe_url_localhost() {
        assert!(!is_safe_url("http://localhost/"));
        assert!(!is_safe_url("http://127.0.0.1/"));
        assert!(!is_safe_url("http://[::1]/"));
        assert!(!is_safe_url("https://localhost:8080/api"));
    }

    #[test]
    fn test_is_safe_url_private_ip() {
        // 192.168.x.x range
        assert!(!is_safe_url("http://192.168.1.1/"));
        assert!(!is_safe_url("http://192.168.0.1/"));
        assert!(!is_safe_url("http://192.168.255.255/"));

        // 10.x.x.x range
        assert!(!is_safe_url("http://10.0.0.1/"));
        assert!(!is_safe_url("http://10.255.255.255/"));

        // 172.16-31.x.x range
        assert!(!is_safe_url("http://172.16.0.1/"));
        assert!(!is_safe_url("http://172.31.255.255/"));
        assert!(!is_safe_url("http://172.20.10.5/"));

        // 127.x.x.x range
        assert!(!is_safe_url("http://127.0.0.2/"));
        assert!(!is_safe_url("http://127.255.255.255/"));
    }

    #[test]
    fn test_is_safe_url_cloud_metadata() {
        assert!(!is_safe_url("http://169.254.169.254/"));
        assert!(!is_safe_url("http://169.254.169.254/latest/meta-data/"));
        assert!(!is_safe_url("http://metadata.google.internal/"));
    }

    #[test]
    fn test_is_safe_url_valid_urls() {
        assert!(is_safe_url("http://example.com/"));
        assert!(is_safe_url("https://github.com/"));
        assert!(is_safe_url("http://1.1.1.1/"));
        assert!(is_safe_url("https://8.8.8.8/"));
        assert!(is_safe_url("http://example.com:8080/path"));
    }

    #[test]
    fn test_is_safe_url_other_schemes() {
        assert!(!is_safe_url("ftp://example.com/"));
        assert!(!is_safe_url("data:text/html,<script>alert('xss')</script>"));
        assert!(!is_safe_url("javascript:alert('xss')"));
        assert!(!is_safe_url("gopher://example.com/"));
    }

    #[test]
    fn test_is_safe_url_ipv6() {
        // Loopback
        assert!(!is_safe_url("http://[::1]/"));
        assert!(!is_safe_url("http://[0:0:0:0:0:0:0:1]/"));

        // Private ULA (fc00::/7)
        assert!(!is_safe_url("http://[fc00::1]/"));
        assert!(!is_safe_url("http://[fd00::1]/"));

        // Public IPv6 should be allowed
        assert!(is_safe_url("http://[2001:4860:4860::8888]/"));
    }

    #[test]
    fn test_is_safe_url_ipv4_mapped_ipv6_loopback_blocked() {
        // Regression pin: before consolidating onto `util::ssrf`, this
        // module's own is_private_ip()/is_loopback() checks did not unwrap
        // IPv4-mapped IPv6 addresses, so `::ffff:127.0.0.1` (which reaches
        // 127.0.0.1 on the wire) passed as "safe" through xml:base
        // resolution.
        assert!(!is_safe_url("http://[::ffff:127.0.0.1]/"));
    }

    #[test]
    fn test_is_safe_url_invalid_urls() {
        assert!(!is_safe_url("not a url"));
        assert!(!is_safe_url(""));
        assert!(!is_safe_url("://invalid"));
    }
}