Final fixes as proposed by @ReneWerner87

Author: Antonio Nesic

docs/middleware/hostauthorization.md

@@ -42,11 +42,11 @@ app.Get("/users", func(c fiber.Ctx) error {
 
 ### Subdomain Wildcards
 
-A leading dot matches any subdomain but **not** the bare domain itself:
+A `*.` prefix matches any subdomain but **not** the bare domain itself:
 
 ```go
 app.Use(hostauthorization.New(hostauthorization.Config{
-    AllowedHosts: []string{".myapp.com"},
+    AllowedHosts: []string{"*.myapp.com"},
 }))
 
 // Host: api.myapp.com  → 200 OK
@@ -57,34 +57,27 @@ app.Use(hostauthorization.New(hostauthorization.Config{
 To allow both the bare domain and all subdomains, include both:
 
 ```go
-AllowedHosts: []string{"myapp.com", ".myapp.com"},
+AllowedHosts: []string{"myapp.com", "*.myapp.com"},
 ```
 
-### CIDR Ranges
+### Internationalized Domain Names (IDN)
 
-Useful for services accessed directly by IP (e.g. internal tooling) where the `Host` header will be a raw IP address. This matches the **Host header value** against a CIDR range — it does not filter by client IP address:
+Browsers always transmit the `Host` header in ASCII (Punycode) form, so IDN entries in `AllowedHosts` are converted to Punycode at startup. You can configure entries in either form — they are equivalent:
 
 ```go
-app.Use(hostauthorization.New(hostauthorization.Config{
-    AllowedHosts: []string{
-        "internal.myapp.com",
-        "10.0.0.0/8",       // Host header IPs in this range are allowed
-        "127.0.0.1",        // Host header must be exactly this IP
-    },
-}))
-
-// Host: internal.myapp.com → 200 OK
-// Host: 10.0.50.3          → 200 OK  (Host header IP is in 10.0.0.0/8)
-// Host: 169.254.169.254    → 403 Forbidden (Host header IP not in allowlist)
+AllowedHosts: []string{"münchen.example.com"}                 // Unicode
+AllowedHosts: []string{"xn--mnchen-3ya.example.com"}          // Punycode (what the browser sends)
 ```
 
+Both match an incoming request whose Host header is `xn--mnchen-3ya.example.com`.
+
 ### Skipping Health Checks
 
 Use `Next` to bypass host validation for specific paths:
 
 ```go
 app.Use(hostauthorization.New(hostauthorization.Config{
-    AllowedHosts: []string{"myapp.com", ".myapp.com"},
+    AllowedHosts: []string{"myapp.com", "*.myapp.com"},
     Next: func(c fiber.Ctx) bool {
         return c.Path() == "/healthz"
     },
@@ -111,7 +104,7 @@ app.Use(hostauthorization.New(hostauthorization.Config{
 
 ```go
 app.Use(hostauthorization.New(hostauthorization.Config{
-    AllowedHosts: []string{"myapp.com", ".myapp.com"},
+    AllowedHosts: []string{"myapp.com", "*.myapp.com"},
     AllowedHostsFunc: func(host string) bool {
         return isRegisteredCustomDomain(host)
     },
@@ -120,7 +113,10 @@ app.Use(hostauthorization.New(hostauthorization.Config{
 
 ### Custom Error Response
 
+The default response is **403 Forbidden**. **421 Misdirected Request** ([RFC 9110 §15.5.20](https://www.rfc-editor.org/rfc/rfc9110#section-15.5.20)) is a semantically closer choice for "wrong host for this server" — CDNs like Cloudflare and Fastly use it for this case. Either is reasonable; pick one via `ErrorHandler`:
+
 ```go
+// 403 with a JSON body
 app.Use(hostauthorization.New(hostauthorization.Config{
     AllowedHosts: []string{"myapp.com"},
     ErrorHandler: func(c fiber.Ctx, err error) error {
@@ -129,6 +125,14 @@ app.Use(hostauthorization.New(hostauthorization.Config{
         })
     },
 }))
+
+// 421 Misdirected Request — closer to the RFC-defined semantics
+app.Use(hostauthorization.New(hostauthorization.Config{
+    AllowedHosts: []string{"myapp.com"},
+    ErrorHandler: func(c fiber.Ctx, _ error) error {
+        return c.SendStatus(fiber.StatusMisdirectedRequest) // 421
+    },
+}))
 ```
 
 ### Combined with Domain() Router
@@ -138,7 +142,7 @@ app.Use(hostauthorization.New(hostauthorization.Config{
 ```go
 // Security layer — reject anything not from our hosts
 app.Use(hostauthorization.New(hostauthorization.Config{
-    AllowedHosts: []string{"myapp.com", ".myapp.com"},
+    AllowedHosts: []string{"myapp.com", "*.myapp.com"},
     Next: func(c fiber.Ctx) bool {
         return c.Path() == "/healthz"
     },
@@ -155,8 +159,8 @@ app.Get("/healthz", healthCheck)
 | Property         | Type                          | Description                                                                                       | Default |
 |:-----------------|:------------------------------|:--------------------------------------------------------------------------------------------------|:--------|
 | Next             | `func(fiber.Ctx) bool`        | Defines a function to skip this middleware when returned true.                                     | `nil`   |
-| AllowedHosts     | `[]string`                    | List of permitted hosts. Supports exact match, subdomain wildcard (`.example.com`), and CIDR.     | `nil`   |
-| AllowedHostsFunc | `func(string) bool`           | Dynamic validator called only when no static AllowedHosts rule matches. Receives the normalized hostname: port stripped, trailing dot removed, IPv6 brackets removed, lowercased.  | `nil`   |
+| AllowedHosts     | `[]string`                    | List of permitted hosts. Supports exact match and subdomain wildcard (`*.example.com`).            | `nil`   |
+| AllowedHostsFunc | `func(string) bool`           | Dynamic validator called only when no static AllowedHosts rule matches. Receives the normalized hostname: port stripped, trailing dot removed, IPv6 brackets removed, lowercased, IDN converted to Punycode.  | `nil`   |
 | ErrorHandler     | `fiber.ErrorHandler`          | Called when a request is rejected. Receives `ErrForbiddenHost` as the error.                      | 403     |
 
 Either `AllowedHosts` or `AllowedHostsFunc` (or both) must be provided. The middleware panics at startup if neither is set.
@@ -173,23 +177,26 @@ There is no useful default — you must provide at least `AllowedHosts` or `Allo
 
 The middleware matches hosts in this order:
 
-1. **Exact match** — case-insensitive, port and trailing dot stripped
-2. **Subdomain wildcard** — `".myapp.com"` matches `api.myapp.com` but not `myapp.com`
-3. **CIDR range** — host is parsed as IP and checked against the network
-4. **AllowedHostsFunc** — called only if no static rule matched
+1. **Exact match** — case-insensitive, port and trailing dot stripped, IDN labels in Punycode form
+2. **Subdomain wildcard** — `"*.myapp.com"` matches `api.myapp.com` but not `myapp.com`
+3. **AllowedHostsFunc** — called only if no static rule matched
 
 The first match wins. If nothing matches, `ErrorHandler` is called.
 
 ## Host Normalization
 
-Before matching, the incoming host is normalized:
+Before matching, both incoming hosts and `AllowedHosts` entries are normalized at startup:
 
-- Port is stripped (via `c.Hostname()`)
+- Port is stripped (`example.com:8080` → `example.com`)
 - Trailing dot removed (`example.com.` → `example.com`)
 - IPv6 brackets removed (`[::1]` → `::1`)
 - Lowercased
+- IDN labels converted to ASCII/Punycode (`münchen.example.com` → `xn--mnchen-3ya.example.com`)
+- RFC 1035 length limits enforced at startup: ≤253 chars total, ≤63 chars per label (panic on violation)
+
+## Filtering by Client IP
 
-`AllowedHosts` entries are also lowercased at initialization.
+This middleware filters by the `Host` *header*, not by the client's source IP. To restrict access by client IP, use Fiber's [`TrustProxy` / `TrustProxyConfig`](https://docs.gofiber.io/whats_new#trusted-proxies) configuration — those are the correct knobs for IP allowlisting and CIDR ranges of trusted proxies.
 
 ## Proxy Support
 
@@ -202,6 +209,7 @@ fasthttp itself is HTTP/1.x only. HTTP/2 support requires an external library (e
 - **RFC 9110 Section 7.2** — Host and port are separate components; port is stripped before matching
 - **RFC 9110 Section 17.1** — Origin servers should reject misdirected requests
 - **RFC 9112 Section 3.2** — Requests with missing Host headers should be rejected
+- **RFC 1035** — `AllowedHosts` entries are validated against the 253-char total / 63-char per-label limits
 - Returns **403 Forbidden** (not 400) because the request is syntactically valid but semantically unauthorized
 
 :::note

middleware/hostauthorization/config.go

@@ -32,12 +32,13 @@ type Config struct {
 	ErrorHandler fiber.ErrorHandler
 
 	// AllowedHosts is the list of permitted host values.
-	// Supports three match types:
+	// Supports two match types:
 	//   - Exact:     "api.myapp.com"
-	//   - Subdomain: ".myapp.com" (leading dot matches any subdomain, NOT the bare domain)
-	//   - CIDR:      "10.0.0.0/8" (matches hosts that are IPs in the range)
+	//   - Subdomain: "*.myapp.com" (matches any subdomain, NOT the bare domain — list both for apex+subdomains)
 	//
-	// Entries containing "/" are always treated as CIDR; a parse failure panics at startup.
+	// Entries are normalized at startup: port stripped, trailing dot removed,
+	// lowercased, IDN labels converted to Punycode, RFC 1035 length limits enforced
+	// (≤253 total / ≤63 per-label).
 	//
 	// Required if AllowedHostsFunc is nil.
 	AllowedHosts []string

middleware/hostauthorization/hostauthorization.go

@@ -1,25 +1,30 @@
 package hostauthorization
 
 import (
+	"fmt"
 	"net"
 	"strings"
 
 	"github.com/gofiber/fiber/v3"
 	"github.com/gofiber/utils/v2"
 	utilsstrings "github.com/gofiber/utils/v2/strings"
+	"golang.org/x/net/idna"
+)
+
+// RFC 1035 length limits.
+const (
+	maxDomainLength = 253
+	maxLabelLength  = 63
 )
 
-// parsedHosts holds the pre-parsed host matching structures.
 type parsedHosts struct {
 	exact            map[string]struct{}
 	wildcardSuffixes []string
-	cidrNets         []*net.IPNet
 }
 
-// parseAllowedHosts categorizes AllowedHosts into exact, wildcard, and CIDR groups.
-// Any entry containing "/" is treated as a CIDR attempt; a parse failure panics so
-// misconfigured ranges surface at startup rather than silently becoming an exact entry
-// that can never match a real host. Non-canonical CIDRs (host bits set) also panic.
+// parseAllowedHosts splits AllowedHosts into exact and wildcard groups,
+// normalizing entries (port strip, lowercase, IDN→Punycode) and enforcing
+// RFC 1035 length limits. Panics on misconfiguration so it surfaces at startup.
 func parseAllowedHosts(hosts []string) parsedHosts {
 	parsed := parsedHosts{
 		exact: make(map[string]struct{}, len(hosts)),
@@ -30,97 +35,108 @@ func parseAllowedHosts(hosts []string) parsedHosts {
 		if h == "" {
 			continue
 		}
+
+		// Reject the leading-dot form some other tools use; we want "*.example.com".
+		if len(h) > 1 && h[0] == '.' {
+			panic("hostauthorization: invalid host " + h + " — subdomain wildcards use the \"*.example.com\" form")
+		}
+
+		isWildcard := strings.HasPrefix(h, "*.")
+		if isWildcard {
+			h = h[2:]
+		}
+
 		h = normalizeHost(h)
 		if h == "" {
 			continue
 		}
 
-		switch {
-		case strings.Contains(h, "/"):
-			hostIP, cidr, err := net.ParseCIDR(h)
-			if err != nil {
-				panic("hostauthorization: invalid CIDR entry: " + h)
-			}
-			// Reject non-canonical CIDRs (host bits set): "10.0.0.5/8" would
-			// silently expand to 10.0.0.0/8, allowing far more than intended.
-			if !hostIP.Equal(cidr.IP) {
-				panic("hostauthorization: CIDR has host bits set, use canonical form: " + h)
-			}
-			parsed.cidrNets = append(parsed.cidrNets, cidr)
-		case strings.HasPrefix(h, "."):
-			// Subdomain wildcard — store with leading dot to avoid allocation in hot path
-			parsed.wildcardSuffixes = append(parsed.wildcardSuffixes, h)
-		default:
+		validateHostLength(h)
+
+		if isWildcard {
+			// Stored with leading dot so the hot-path HasSuffix check stays alloc-free.
+			parsed.wildcardSuffixes = append(parsed.wildcardSuffixes, "."+h)
+		} else {
 			parsed.exact[h] = struct{}{}
 		}
 	}
 
 	return parsed
 }
 
-// normalizeHost normalizes a hostname for matching: port stripped, trailing dot
-// removed, IPv6 brackets removed, lowercased.
-// Safe to call on both c.Hostname() output (already port-stripped) and raw
-// AllowedHosts entries (which may include a port like "example.com:8080").
+func validateHostLength(host string) {
+	if len(host) > maxDomainLength {
+		panic(fmt.Sprintf("hostauthorization: host %q exceeds RFC 1035 maximum of %d characters (%d chars)",
+			host, maxDomainLength, len(host)))
+	}
+	// IPv6 hosts contain colons and aren't dotted labels.
+	if strings.IndexByte(host, ':') >= 0 {
+		return
+	}
+	for _, label := range strings.Split(host, ".") {
+		if len(label) > maxLabelLength {
+			panic(fmt.Sprintf("hostauthorization: host %q has label %q exceeding RFC 1035 limit of %d characters (%d chars)",
+				host, label, maxLabelLength, len(label)))
+		}
+	}
+}
+
+// normalizeHost strips port, trailing dot, and IPv6 brackets, lowercases,
+// and converts IDN labels to Punycode (matching what browsers send).
 func normalizeHost(host string) string {
-	// Fast path for plain hostnames (no IPv6 brackets, no port).
-	// net.SplitHostPort allocates a *AddrError on every error path; skipping
-	// it for the common case avoids one allocation per request.
+	// Fast path for plain hostnames — avoids net.SplitHostPort's error allocation.
 	if host != "" && host[0] != '[' && strings.IndexByte(host, ':') < 0 {
 		host = strings.TrimSuffix(host, ".")
-		return utilsstrings.ToLower(host)
+		host = utilsstrings.ToLower(host)
+		return toPunycode(host)
 	}
 
-	// Handle "[::1]:port", "[::1]", and "host:port" forms.
 	if h, _, err := net.SplitHostPort(host); err == nil {
 		host = h
 	} else {
-		// No port: strip bare IPv6 brackets (e.g. "[::1]" → "::1").
 		host = strings.TrimPrefix(host, "[")
 		host = strings.TrimSuffix(host, "]")
 	}
 
 	host = strings.TrimSuffix(host, ".")
-	return utilsstrings.ToLower(host)
+	host = utilsstrings.ToLower(host)
+	return toPunycode(host)
+}
+
+func toPunycode(host string) string {
+	if host == "" || strings.IndexByte(host, ':') >= 0 || isASCII(host) {
+		return host
+	}
+	if ascii, err := idna.Lookup.ToASCII(host); err == nil {
+		return ascii
+	}
+	// Non-convertible input falls through; it won't match any Punycode entry,
+	// which is the correct security default.
+	return host
+}
+
+func isASCII(s string) bool {
+	for i := 0; i < len(s); i++ {
+		if s[i] >= 0x80 {
+			return false
+		}
+	}
+	return true
 }
 
-// matchHost checks if the given host matches any of the parsed allowed hosts.
-// Evaluation order: exact → wildcard → CIDR → AllowedHostsFunc.
-// AllowedHostsFunc is a fallback called only when no static rule matches,
-// matching the CORS AllowOriginsFunc convention and avoiding unnecessary calls
-// to potentially expensive dynamic validators (e.g. database lookups).
+// matchHost evaluates exact → wildcard → AllowedHostsFunc.
+// The func is a fallback only — never called when a static rule matched.
 func matchHost(host string, parsed parsedHosts, allowedHostsFunc func(string) bool) bool {
-	// Exact match
 	if _, ok := parsed.exact[host]; ok {
 		return true
 	}
 
-	// Subdomain wildcard: ".myapp.com" matches "api.myapp.com" but NOT "myapp.com"
 	for _, suffix := range parsed.wildcardSuffixes {
 		if strings.HasSuffix(host, suffix) {
 			return true
 		}
 	}
 
-	// CIDR match: parse host as IP and check against CIDR ranges.
-	// Pre-check to skip net.ParseIP for obvious non-IP hostnames (e.g. "api.myapp.com"):
-	//   - IPv4 addresses start with a digit
-	//   - IPv6 addresses always contain ":" (port is already stripped by normalizeHost)
-	// Regular hostnames won't match either condition.
-	if len(parsed.cidrNets) > 0 && host != "" {
-		firstByte := host[0]
-		if (firstByte >= '0' && firstByte <= '9') || strings.IndexByte(host, ':') >= 0 {
-			if ip := net.ParseIP(host); ip != nil {
-				for _, cidr := range parsed.cidrNets {
-					if cidr.Contains(ip) {
-						return true
-					}
-				}
-			}
-		}
-	}
-
-	// Dynamic validator — fallback only; not called when a static rule matched.
 	if allowedHostsFunc != nil && allowedHostsFunc(host) {
 		return true
 	}