plain 0.64.0__tar.gz → 0.65.0__tar.gz

{plain-0.64.0 → plain-0.65.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.64.0
+Version: 0.65.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain-0.64.0 → plain-0.65.0}/plain/CHANGELOG.md

@@ -1,5 +1,15 @@
 # plain changelog
 
+## [0.65.0](https://github.com/dropseed/plain/releases/plain@0.65.0) (2025-09-22)
+
+### What's changed
+
+- Added CIDR notation support to `ALLOWED_HOSTS` for IP address range validation ([c485d21](https://github.com/dropseed/plain/commit/c485d21a8b))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.64.0](https://github.com/dropseed/plain/releases/plain@0.64.0) (2025-09-19)
 
 ### What's changed

plain-0.65.0/plain/http/hosts.py

@@ -0,0 +1,147 @@
+"""
+Host validation utilities for ALLOWED_HOSTS functionality.
+
+This module provides functions for validating hosts against allowed patterns,
+including domain patterns, wildcards, and CIDR notation for IP ranges.
+"""
+
+import ipaddress
+
+from plain.utils.regex_helper import _lazy_re_compile
+
+host_validation_re = _lazy_re_compile(
+    r"^([a-z0-9.-]+|\[[a-f0-9]*:[a-f0-9\.:]+\])(:[0-9]+)?$"
+)
+
+
+def split_domain_port(host: str) -> tuple[str, str]:
+    """
+    Return a (domain, port) tuple from a given host.
+
+    Returned domain is lowercased. If the host is invalid, the domain will be
+    empty.
+    """
+    host = host.lower()
+
+    if not host_validation_re.match(host):
+        return "", ""
+
+    if host[-1] == "]":
+        # It's an IPv6 address without a port.
+        return host, ""
+    bits = host.rsplit(":", 1)
+    domain, port = bits if len(bits) == 2 else (bits[0], "")
+    # Remove a trailing dot (if present) from the domain.
+    domain = domain.removesuffix(".")
+    return domain, port
+
+
+def _is_same_domain(host: str, pattern: str) -> bool:
+    """
+    Return ``True`` if the host is either an exact match or a match
+    to the wildcard pattern.
+
+    Any pattern beginning with a period matches a domain and all of its
+    subdomains. (e.g. ``.example.com`` matches ``example.com`` and
+    ``foo.example.com``). Anything else is an exact string match.
+    """
+    if not pattern:
+        return False
+
+    pattern = pattern.lower()
+    return (
+        pattern[0] == "."
+        and (host.endswith(pattern) or host == pattern[1:])
+        or pattern == host
+    )
+
+
+def _parse_ip_address(
+    host: str,
+) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
+    """
+    Parse a host string as an IP address (IPv4 or IPv6).
+
+    Returns the ipaddress.ip_address object if valid, None otherwise.
+    Handles both bracketed and non-bracketed IPv6 addresses.
+    """
+    # Remove brackets from IPv6 addresses
+    if host.startswith("[") and host.endswith("]"):
+        host = host[1:-1]
+
+    try:
+        return ipaddress.ip_address(host)
+    except ValueError:
+        return None
+
+
+def _parse_cidr_pattern(
+    pattern: str,
+) -> ipaddress.IPv4Network | ipaddress.IPv6Network | None:
+    """
+    Parse a CIDR pattern and return the network object if valid.
+
+    Returns the ipaddress.ip_network object if valid CIDR notation, None otherwise.
+    """
+    # Check if it contains a slash (required for CIDR)
+    if "/" not in pattern:
+        return None
+
+    # Remove brackets from IPv6 CIDR patterns
+    test_pattern = pattern
+    if pattern.startswith("[") and "]/" in pattern:
+        # Handle format like [2001:db8::]/32
+        bracket_end = pattern.find("]/")
+        if bracket_end != -1:
+            ip_part = pattern[1:bracket_end]
+            cidr_part = pattern[bracket_end + 2 :]
+            test_pattern = f"{ip_part}/{cidr_part}"
+    elif pattern.startswith("[") and pattern.endswith("]") and "/" in pattern:
+        # Handle format like [2001:db8::/32] (slash inside brackets)
+        test_pattern = pattern[1:-1]
+
+    try:
+        return ipaddress.ip_network(test_pattern, strict=False)
+    except ValueError:
+        return None
+
+
+def validate_host(host: str, allowed_hosts: list[str]) -> bool:
+    """
+    Validate the given host for this site.
+
+    Check that the host looks valid and matches a host or host pattern in the
+    given list of ``allowed_hosts``. Supported patterns:
+
+    - ``*`` matches anything
+    - ``.example.com`` matches a domain and all its subdomains
+      (e.g. ``example.com`` and ``sub.example.com``)
+    - ``example.com`` matches exactly that domain
+    - ``192.168.1.0/24`` matches IP addresses in that CIDR range
+    - ``[2001:db8::]/32`` matches IPv6 addresses in that CIDR range
+    - ``192.168.1.1`` matches that exact IP address
+
+    Note: This function assumes that the given host is lowercased and has
+    already had the port, if any, stripped off.
+
+    Return ``True`` for a valid host, ``False`` otherwise.
+    """
+    # Parse the host as an IP address if possible
+    host_ip = _parse_ip_address(host)
+
+    for pattern in allowed_hosts:
+        # Wildcard matches everything
+        if pattern == "*":
+            return True
+
+        # Check CIDR notation patterns using walrus operator
+        if network := _parse_cidr_pattern(pattern):
+            if host_ip and host_ip in network:
+                return True
+            continue
+
+        # For non-CIDR patterns, use existing domain matching logic
+        if _is_same_domain(host, pattern):
+            return True
+
+    return False

{plain-0.64.0 → plain-0.65.0}/plain/http/request.py

@@ -27,12 +27,9 @@ from plain.utils.datastructures import (
     MultiValueDict,
 )
 from plain.utils.encoding import iri_to_uri
-from plain.utils.http import is_same_domain, parse_header_parameters
-from plain.utils.regex_helper import _lazy_re_compile
+from plain.utils.http import parse_header_parameters
 
-host_validation_re = _lazy_re_compile(
-    r"^([a-z0-9.-]+|\[[a-f0-9]*:[a-f0-9\.:]+\])(:[0-9]+)?$"
-)
+from .hosts import split_domain_port, validate_host
 
 
 class UnreadablePostError(OSError):
@@ -702,47 +699,5 @@ def bytes_to_text(s, encoding):
         return s
 
 
-def split_domain_port(host):
-    """
-    Return a (domain, port) tuple from a given host.
-
-    Returned domain is lowercased. If the host is invalid, the domain will be
-    empty.
-    """
-    host = host.lower()
-
-    if not host_validation_re.match(host):
-        return "", ""
-
-    if host[-1] == "]":
-        # It's an IPv6 address without a port.
-        return host, ""
-    bits = host.rsplit(":", 1)
-    domain, port = bits if len(bits) == 2 else (bits[0], "")
-    # Remove a trailing dot (if present) from the domain.
-    domain = domain.removesuffix(".")
-    return domain, port
-
-
-def validate_host(host, allowed_hosts):
-    """
-    Validate the given host for this site.
-
-    Check that the host looks valid and matches a host or host pattern in the
-    given list of ``allowed_hosts``. Any pattern beginning with a period
-    matches a domain and all its subdomains (e.g. ``.example.com`` matches
-    ``example.com`` and any subdomain), ``*`` matches anything, and anything
-    else must match exactly.
-
-    Note: This function assumes that the given host is lowercased and has
-    already had the port, if any, stripped off.
-
-    Return ``True`` for a valid host, ``False`` otherwise.
-    """
-    return any(
-        pattern == "*" or is_same_domain(host, pattern) for pattern in allowed_hosts
-    )
-
-
 def parse_accept_header(header):
     return [MediaType(token) for token in header.split(",") if token.strip()]

{plain-0.64.0 → plain-0.65.0}/plain/runtime/global_settings.py

@@ -24,6 +24,7 @@ URLS_ROUTER: str
 
 # Hosts/domain names that are valid for this site.
 # "*" matches anything, ".example.com" matches example.com and all subdomains
+# "192.168.1.0/24" matches IP addresses in that CIDR range
 ALLOWED_HOSTS: list[str] = []
 
 # Default headers for all responses.

{plain-0.64.0 → plain-0.65.0}/plain/utils/http.py

@@ -92,26 +92,6 @@ def int_to_base36(i):
     return b36
 
 
-def is_same_domain(host, pattern):
-    """
-    Return ``True`` if the host is either an exact match or a match
-    to the wildcard pattern.
-
-    Any pattern beginning with a period matches a domain and all of its
-    subdomains. (e.g. ``.example.com`` matches ``example.com`` and
-    ``foo.example.com``). Anything else is an exact string match.
-    """
-    if not pattern:
-        return False
-
-    pattern = pattern.lower()
-    return (
-        pattern[0] == "."
-        and (host.endswith(pattern) or host == pattern[1:])
-        or pattern == host
-    )
-
-
 def escape_leading_slashes(url):
     """
     If redirecting to an absolute path (two leading slashes), a slash must be

{plain-0.64.0 → plain-0.65.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain"
-version = "0.64.0"
+version = "0.65.0"
 description = "A web framework for building products with Python."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"

plain-0.65.0/tests/test_http_hosts.py

@@ -0,0 +1,214 @@
+import pytest
+
+from plain.http.hosts import split_domain_port, validate_host
+
+
+@pytest.mark.parametrize(
+    ("host", "expected_domain", "expected_port"),
+    [
+        # IPv4 addresses
+        ("127.0.0.1", "127.0.0.1", ""),
+        ("192.168.1.1", "192.168.1.1", ""),
+        ("127.0.0.1:8000", "127.0.0.1", "8000"),
+        ("192.168.1.1:443", "192.168.1.1", "443"),
+        # IPv6 addresses
+        ("[::1]", "[::1]", ""),
+        ("[2001:db8::1]", "[2001:db8::1]", ""),
+        (
+            "[2001:0db8:85a3:0000:0000:8a2e:0370:7334]",
+            "[2001:0db8:85a3:0000:0000:8a2e:0370:7334]",
+            "",
+        ),
+        ("[::1]:8000", "[::1]", "8000"),
+        ("[2001:db8::1]:443", "[2001:db8::1]", "443"),
+        # Domain names
+        ("example.com", "example.com", ""),
+        ("sub.example.com", "sub.example.com", ""),
+        ("deep.sub.example.com", "deep.sub.example.com", ""),
+        ("example.com:8080", "example.com", "8080"),
+        ("sub.example.com:443", "sub.example.com", "443"),
+        ("api.example.com:3000", "api.example.com", "3000"),
+        # Trailing dot removal
+        ("example.com.", "example.com", ""),
+        ("sub.example.com.:8080", "sub.example.com", "8080"),
+        # Case normalization
+        ("EXAMPLE.COM", "example.com", ""),
+        ("Example.Com:8080", "example.com", "8080"),
+        ("SUB.EXAMPLE.COM:443", "sub.example.com", "443"),
+        # Borderline valid cases
+        ("invalid..domain", "invalid..domain", ""),
+        # Invalid hosts
+        ("", "", ""),
+        ("::1", "", ""),  # IPv6 without brackets
+        ("not a valid host", "", ""),
+        ("example$.com", "", ""),
+        ("example.com:", "", ""),  # Trailing colon
+        ("[::1", "", ""),  # Incomplete brackets
+        ("example.com:8080:9000", "", ""),  # Multiple colons
+    ],
+)
+def test_split_domain_port(host, expected_domain, expected_port):
+    """Test split_domain_port function with various inputs."""
+    domain, port = split_domain_port(host)
+    assert domain == expected_domain
+    assert port == expected_port
+
+
+@pytest.mark.parametrize(
+    ("host", "allowed_hosts", "expected"),
+    [
+        # Wildcard matching
+        ("example.com", ["*"], True),
+        ("sub.example.com", ["*"], True),
+        ("127.0.0.1", ["*"], True),
+        ("[::1]", ["*"], True),
+        ("anything.at.all", ["*"], True),
+        # Subdomain pattern matching
+        ("example.com", [".example.com"], True),
+        ("sub.example.com", [".example.com"], True),
+        ("api.example.com", [".example.com"], True),
+        ("deep.sub.example.com", [".example.com"], True),
+        ("notexample.com", [".example.com"], False),
+        ("example.org", [".example.com"], False),
+        ("fakeexample.com", [".example.com"], False),
+        # Exact domain matching
+        ("example.com", ["example.com"], True),
+        ("sub.example.com", ["example.com"], False),
+        ("api.example.com", ["example.com"], False),
+        ("example.org", ["example.com"], False),
+        ("notexample.com", ["example.com"], False),
+        # Multiple patterns
+        ("example.com", ["example.com", ".api.example.com", "127.0.0.1"], True),
+        ("api.example.com", ["example.com", ".api.example.com", "127.0.0.1"], True),
+        ("v1.api.example.com", ["example.com", ".api.example.com", "127.0.0.1"], True),
+        ("127.0.0.1", ["example.com", ".api.example.com", "127.0.0.1"], True),
+        ("sub.example.com", ["example.com", ".api.example.com", "127.0.0.1"], False),
+        ("other.com", ["example.com", ".api.example.com", "127.0.0.1"], False),
+        # Literal asterisk pattern (not treated as wildcard)
+        ("*.test.com", ["*.test.com"], True),
+        ("anything.test.com", ["*.test.com"], False),
+        ("api.test.com", ["*.test.com"], False),
+        # IPv4 address matching
+        ("127.0.0.1", ["127.0.0.1", "192.168.1.1"], True),
+        ("192.168.1.1", ["127.0.0.1", "192.168.1.1"], True),
+        ("127.0.0.2", ["127.0.0.1", "192.168.1.1"], False),
+        ("10.0.0.1", ["127.0.0.1", "192.168.1.1"], False),
+        # IPv6 address matching
+        ("[::1]", ["[::1]", "[2001:db8::1]"], True),
+        ("[2001:db8::1]", ["[::1]", "[2001:db8::1]"], True),
+        ("[::2]", ["[::1]", "[2001:db8::1]"], False),
+        ("[2001:db8::2]", ["[::1]", "[2001:db8::1]"], False),
+        # Pattern case insensitive matching (host should be lowercase already)
+        ("example.com", [".Example.Com"], True),
+        ("sub.example.com", [".Example.Com"], True),
+        ("api.test.com", ["API.TEST.COM"], True),
+        # Empty allowed_hosts
+        ("example.com", [], False),
+        ("127.0.0.1", [], False),
+        ("[::1]", [], False),
+        # Empty pattern in allowed_hosts
+        ("", ["", "example.com"], False),
+        ("anything.com", ["", "example.com"], False),
+        ("example.com", ["", "example.com"], True),
+        # Complex subdomain patterns
+        ("api.example.com", [".api.example.com", ".staging.example.com"], True),
+        ("staging.example.com", [".api.example.com", ".staging.example.com"], True),
+        ("v1.api.example.com", [".api.example.com", ".staging.example.com"], True),
+        (
+            "beta.staging.example.com",
+            [".api.example.com", ".staging.example.com"],
+            True,
+        ),
+        ("example.com", [".api.example.com", ".staging.example.com"], False),
+        ("www.example.com", [".api.example.com", ".staging.example.com"], False),
+        # Wildcard overrides other patterns
+        (
+            "anything.com",
+            ["*", "exact.com", ".subdomain.com", "127.0.0.1", "[::1]"],
+            True,
+        ),
+        (
+            "random.domain.org",
+            ["*", "exact.com", ".subdomain.com", "127.0.0.1", "[::1]"],
+            True,
+        ),
+        (
+            "192.168.1.100",
+            ["*", "exact.com", ".subdomain.com", "127.0.0.1", "[::1]"],
+            True,
+        ),
+        # Edge cases
+        ("", ["example.com"], False),
+        ("example .com", ["example.com"], False),
+        ("a" * 50 + ".example.com", [".example.com"], True),  # Very long subdomain
+    ],
+)
+def test_validate_host(host, allowed_hosts, expected):
+    """Test validate_host function with various inputs."""
+    assert validate_host(host, allowed_hosts) is expected
+
+
+@pytest.mark.parametrize(
+    ("host", "allowed_hosts", "expected"),
+    [
+        # IPv4 CIDR tests
+        ("192.168.1.100", ["192.168.1.0/24"], True),
+        ("192.168.1.1", ["192.168.1.0/24"], True),
+        ("192.168.1.254", ["192.168.1.0/24"], True),
+        ("192.168.2.100", ["192.168.1.0/24"], False),
+        ("10.0.5.1", ["10.0.0.0/8"], True),
+        ("172.16.0.1", ["10.0.0.0/8"], False),
+        # IPv4 single IP as CIDR
+        ("192.168.1.1", ["192.168.1.1/32"], True),
+        ("192.168.1.2", ["192.168.1.1/32"], False),
+        # IPv4 larger networks
+        ("172.16.5.10", ["172.16.0.0/12"], True),
+        ("172.32.5.10", ["172.16.0.0/12"], False),
+        ("127.0.0.1", ["127.0.0.0/8"], True),
+        # IPv6 CIDR tests
+        ("[2001:db8::1]", ["[2001:db8::]/32"], True),
+        ("[2001:db8:1::1]", ["[2001:db8::]/32"], True),
+        ("[2001:db9::1]", ["[2001:db8::]/32"], False),
+        ("[::1]", ["[::]/0"], True),  # Match everything IPv6
+        ("[2001:db8::1]", ["[fe80::]/10"], False),
+        # IPv6 without brackets in pattern (should still work)
+        ("[2001:db8::1]", ["2001:db8::/32"], True),
+        ("[2001:db9::1]", ["2001:db8::/32"], False),
+        # IPv6 single address as CIDR
+        ("[::1]", ["[::1]/128"], True),
+        ("[::2]", ["[::1]/128"], False),
+        # Mixed CIDR and domain patterns
+        ("192.168.1.50", ["192.168.1.0/24", ".example.com"], True),
+        ("sub.example.com", ["192.168.1.0/24", ".example.com"], True),
+        ("192.168.2.50", ["192.168.1.0/24", ".example.com"], False),
+        ("other.com", ["192.168.1.0/24", ".example.com"], False),
+        # Multiple CIDR patterns
+        ("192.168.1.50", ["10.0.0.0/8", "192.168.0.0/16"], True),
+        ("10.5.0.1", ["10.0.0.0/8", "192.168.0.0/16"], True),
+        ("172.16.0.1", ["10.0.0.0/8", "192.168.0.0/16"], False),
+        # Domain names should not match CIDR patterns
+        ("example.com", ["192.168.1.0/24"], False),
+        ("192.168.1.com", ["192.168.1.0/24"], False),
+        # Non-IP strings should not match CIDR
+        ("not-an-ip", ["192.168.1.0/24"], False),
+        ("192.168.1", ["192.168.1.0/24"], False),  # Incomplete IP
+        # Invalid CIDR patterns should be ignored (treated as literal)
+        ("192.168.1.0/24", ["192.168.1.0/24"], False),  # Literal match of CIDR string
+        ("192.168.1.100", ["192.168.1.0/999"], False),  # Invalid CIDR
+        ("192.168.1.100", ["192.168.1.0/"], False),  # Invalid CIDR
+        # CIDR with wildcard - wildcard should take precedence
+        ("anything.com", ["*", "192.168.1.0/24"], True),
+        ("172.16.0.1", ["*", "192.168.1.0/24"], True),
+        # Edge cases
+        ("0.0.0.0", ["0.0.0.0/0"], True),  # Match all IPv4
+        ("255.255.255.255", ["0.0.0.0/0"], True),
+        (
+            "[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff]",
+            ["[::]/0"],
+            True,
+        ),  # Match all IPv6
+    ],
+)
+def test_validate_host_cidr(host, allowed_hosts, expected):
+    """Test validate_host function with CIDR notation patterns."""
+    assert validate_host(host, allowed_hosts) is expected