Tighten bracketed-host parsing to RFC 3986 / RFC 6874 strict semantics

RFC 3986 §3.2.2 reserves bracket syntax for IPv6 literals
(``IP-literal = IPv6address / IPvFuture``). The parser previously
extracted the bracket contents and forwarded them to
``_canonicalize_host`` without enforcement, so ``[127.0.0.1]:9001``,
``[localhost]:9001``, and ``[example.com]:9001`` all silently
succeeded. The raw ``address`` string is stored verbatim on
``DqliteConnection._address`` and surfaces in repr / logs /
exception messages, so log audits and string-based diagnostics
fragmented across two surface forms for the same logical host.

Validate the bracket contents with ``ipaddress.ip_address`` and
require an ``IPv6Address`` (not ``IPv4Address``); reject empty and
whitespace-only contents.

RFC 6874 specifies that IPv6 zone identifiers may be percent-encoded
in URIs (``%25`` escapes the literal ``%`` zone separator). The
application-form ``[fe80::1%eth0]`` and the URI-form
``[fe80::1%25eth0]`` refer to the same logical zone but were treated
as distinct host strings. ``urllib.parse.unquote`` decodes the zone
suffix so both surface variants canonicalise to the same tuple —
allowlist policies holding one form match either.

Author: antoineleclair

src/dqliteclient/connection.py

@@ -628,14 +628,56 @@ def _parse_address(address: str) -> tuple[str, int]:
     non-ASCII, empty) raise ``ValueError``.
     """
     if address.startswith("["):
-        # Bracketed IPv6: [host]:port
+        # Bracketed IPv6: [host]:port. RFC 3986 §3.2.2 reserves the
+        # bracket form for ``IP-literal = IPv6address / IPvFuture``;
+        # bracketed IPv4 / hostname / empty contents are malformed
+        # surface variants that must be rejected so log audits and
+        # allowlists do not split across two distinct strings for
+        # the same logical host.
         if "]:" not in address:
             raise ValueError(
                 f"Invalid IPv6 address format: expected '[host]:port', got {address!r}"
             )
         bracket_end = address.index("]")
         host = address[1:bracket_end]
-        port_str = address[bracket_end + 2 :]  # Skip ']:
+        port_str = address[bracket_end + 2 :]  # Skip ']:'
+
+        # RFC 6874: zone identifiers may be percent-encoded as ``%25``
+        # in URIs. Percent-decode the zone-ID portion (everything
+        # after the first ``%``) so the URI form
+        # ``[fe80::1%25eth0]`` and the application form
+        # ``[fe80::1%eth0]`` canonicalise identically. Use
+        # ``urllib.parse.unquote`` so any RFC-3986 percent-encoded
+        # octet survives correctly (in practice only ``%25`` is
+        # expected, but the unquote is harmless on already-decoded
+        # input).
+        from urllib.parse import unquote
+
+        zone_sep = host.find("%")
+        if zone_sep != -1:
+            # Decode the entire ``%...`` suffix so ``%25`` collapses
+            # to a literal ``%`` (matching the application-form zone
+            # separator). ``unquote`` leaves a literal ``%`` followed
+            # by non-hex characters intact, so the no-encoding path
+            # round-trips byte-for-byte.
+            host = host[:zone_sep] + unquote(host[zone_sep:])
+
+        # Strict bracket discipline: validate the contents are an
+        # IPv6 literal. ``ipaddress.ip_address`` does not accept
+        # the ``%zone`` suffix, so strip it before the check.
+        ipv6_part = host.split("%", 1)[0]
+        try:
+            parsed = ipaddress.ip_address(ipv6_part)
+        except ValueError as e:
+            raise ValueError(
+                f"Bracket syntax in {address!r} is reserved for IPv6 "
+                f"literals; {host!r} is not an IPv6 address"
+            ) from e
+        if not isinstance(parsed, ipaddress.IPv6Address):
+            raise ValueError(
+                f"Bracket syntax in {address!r} is reserved for IPv6 "
+                f"literals; got {type(parsed).__name__}"
+            )
     else:
         if ":" not in address:
             raise ValueError(f"Invalid address format: expected 'host:port', got {address!r}")

tests/test_parse_address_bracket_strictness.py

@@ -0,0 +1,53 @@
+"""Pin: bracket syntax in ``_parse_address`` is reserved for IPv6
+literals (RFC 3986 §3.2.2). Bracketed IPv4 / hostname / empty
+contents must be rejected.
+
+Pin: IPv6 zone identifiers in bracketed form percent-decode per
+RFC 6874 (`%25` escapes the literal `%`). Both surface variants of
+the same logical zone canonicalise to the same tuple.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from dqliteclient.connection import _parse_address
+
+
+class TestBracketedNonIpv6Rejected:
+    @pytest.mark.parametrize(
+        "addr",
+        [
+            "[127.0.0.1]:9001",
+            "[localhost]:9001",
+            "[example.com]:9001",
+            "[]:9001",
+            "[ ]:9001",
+        ],
+    )
+    def test_bracketed_non_ipv6_raises(self, addr: str) -> None:
+        with pytest.raises(ValueError):
+            _parse_address(addr)
+
+    def test_real_ipv6_still_parses(self) -> None:
+        assert _parse_address("[::1]:9001") == ("::1", 9001)
+        assert _parse_address("[fe80::1]:9001") == ("fe80::1", 9001)
+        assert _parse_address("[2001:db8::1]:9001") == ("2001:db8::1", 9001)
+
+
+class TestIpv6ZoneIdPercentEncoding:
+    def test_zone_id_decoded_canonicalises_two_surface_forms(self) -> None:
+        """RFC 6874: the URI-form ``%25eth0`` and the application-form
+        ``%eth0`` must canonicalise to the same tuple so allowlist
+        policies match either surface variant."""
+        a = _parse_address("[fe80::1%eth0]:9001")
+        b = _parse_address("[fe80::1%25eth0]:9001")
+        assert a == b
+        assert "%eth0" in a[0]
+        # Post-decode form must NOT contain the URI-encoded sequence.
+        assert "%25" not in a[0]
+
+    def test_unencoded_zone_id_still_works(self) -> None:
+        host, port = _parse_address("[fe80::1%eth0]:9001")
+        assert host == "fe80::1%eth0"
+        assert port == 9001