2026-09-05 · 8 min read
- url
- ipv6
- networking
IPv6 addresses contain colons, which conflict with the colon used to introduce a URL port. URL syntax resolves the ambiguity by enclosing an IPv6 host literal in square brackets, as in https://[2001:db8::1]:8443/path.
The brackets belong to URL authority serialization. Many URL APIs expose a hostname without brackets and a host or authority with them, so manually copying fields between APIs can produce doubled brackets, missing delimiters, or incorrect allowlist comparisons.
Parse the complete URL once
Use a standards-aware URL parser at the trust boundary and retain structured scheme, hostname, port, path, query, and fragment fields. Do not split an authority on colons or rebuild it with generic string concatenation.
- Require brackets around IPv6 literals in absolute URLs.
- Normalize default ports only when the application contract permits it.
- Reject malformed, nested, or unmatched brackets.
- Disallow userinfo unless there is a specific supported use case.
Compare hosts with purpose-specific rules
One IPv6 address can have several textual spellings because leading zeros may be omitted and one zero run may be compressed. Parse addresses before equality or allowlist checks instead of comparing user-supplied strings.
DNS names, IPv4 addresses, and IPv6 literals have different canonicalization rules. Preserve exact request bytes for protocols that sign them, and define whether the signer uses the original authority or a documented normalized form.
Control zones, proxies, and outbound access
Zone identifiers scope some link-local addresses to an interface and require special URL escaping. They are rarely appropriate in public web application input; reject them unless the deployment has a narrow, tested need.
- Validate forwarded host data only from trusted proxies.
- Resolve and enforce outbound network policy against parsed destinations.
- Block loopback, private, link-local, and metadata targets when required.
- Recheck redirect destinations for server-side requests.
Exercise every serialization boundary
Use Flashman's URL tool with documentation-range examples, diff for serialized authorities, JSON formatter for sanitized proxy events, regex only for bounded log extraction, and hash to label public canonical-request fixtures.
Test expanded and compressed literals, explicit and default ports, paths, queries, fragments, redirects, zone identifiers, Host and Forwarded headers, signed requests, allowlists, DNS names, IPv4, malformed brackets, and every client and proxy on the deployed path.