# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Validate URL schemes and publicly routable network destinations.""" import ipaddress from urllib.parse import urlsplit import dns.exception import dns.resolver class AddressResolutionError(Exception): """A hostname could not be resolved (potentially transient).""" class UnsafeAddressError(ValueError): """A hostname or IP literal identifies a non-public network address.""" def public_addresses(hostname: str, *, lifetime: float | None = None) -> tuple[str, ...]: """Resolve *once* and return only checked, globally routable IP addresses. A DNS name with a mixture of public and private answers is rejected in its entirety. IP literals are handled without DNS, including IPv6 literals. The returned strings must be used for the actual TCP connection; checking them and then connecting to ``hostname`` reintroduces DNS rebinding. """ try: literal = ipaddress.ip_address(hostname) except ValueError: literal = None if literal is not None: addresses = (literal,) else: try: answers = dns.resolver.resolve_name(hostname, lifetime=lifetime) addresses = tuple(ipaddress.ip_address(a) for a in answers.addresses()) except (dns.exception.DNSException, ValueError) as exc: raise AddressResolutionError( f"Could not resolve hostname {hostname!r}" ) from exc if not addresses: raise AddressResolutionError(f"Could not resolve hostname {hostname!r}") if any(not address.is_global for address in addresses): raise UnsafeAddressError(f"Non-public network address for {hostname!r}") return tuple(str(address) for address in addresses) def is_public_url(url: str) -> bool: """Return whether the URL resolves entirely to public IP addresses. This is useful for diagnostics, but **not** sufficient to authorize a request: network connections must use the exact validated IP address. """ hostname = urlsplit(url).hostname if hostname is None: raise ValueError("No hostname was specified") try: public_addresses(hostname) except UnsafeAddressError: return False return True def is_http_url(url: str) -> bool: """ Check whether a URL is an absolute HTTP or HTTPS URL. :param url: URL to validate. :return: Whether the URL uses HTTP or HTTPS and contains a hostname. """ try: parsed = urlsplit(url) except ValueError: return False return parsed.scheme.lower() in {"http", "https"} and parsed.hostname is not None def is_safe_next_url(next_url: str) -> bool: """Allow redirects only to paths on this site.""" # Check the original string too: urlsplit("///evil.example").path is # "/evil.example", even though browsers can treat the original as external. if "\\" in next_url or not next_url.startswith("/") or next_url.startswith("//"): return False try: target = urlsplit(next_url) except ValueError: return False return ( not target.scheme and not target.netloc and target.path.startswith("/") and not target.path.startswith("//") )