🔒 security: harden proxy middleware against SSRF, redirect downgrades, and hop-by-hop smuggling

Security audit of middleware/proxy and the redirect path in client/
identified ten findings. This change implements secure-by-default
behavior for all of them. See middleware/proxy/SECURITY_AUDIT.md for
the full report and severity table.

New API
- proxy.SecurityPolicy (AllowedSchemes, AllowPrivateIPs,
  AllowHTTPSDowngrade, KeepHopByHopHeaders)
- proxy.DefaultSecurityPolicy, proxy.WithSecurityPolicy
- proxy.Config.SecurityPolicy, MaxResponseBodySize, MaxConnsPerHost
- Sentinel errors: ErrUpstreamSchemeNotAllowed, ErrUpstreamHostInvalid,
  ErrUpstreamHostBlocked, ErrRedirectDowngrade
- client.ErrRedirectDowngrade

Breaking changes (defaults)
- Upstream targets resolving to loopback, RFC 1918, link-local
  (including 169.254.169.254), multicast, unspecified, or RFC 6598
  CGNAT addresses are rejected. Set AllowPrivateIPs to opt in.
- Only http/https schemes are accepted; file://, gopher://, ftp://,
  etc. are rejected.
- DoRedirects rejects HTTPS→HTTP redirect downgrades.
- RFC 7230 §6.1 hop-by-hop headers (Connection, Keep-Alive,
  Proxy-Authenticate, Proxy-Authorization, TE, Trailer,
  Transfer-Encoding, Upgrade) are stripped both ways, plus every
  header listed in the Connection field.
- TLSConfig is cloned with MinVersion: tls.VersionTLS12 when no
  minimum is set; caller's struct is not mutated.
- Fiber HTTP client (client.composeRedirectURL) rejects HTTPS→HTTP
  redirect downgrades.

Bug fixes
- DomainForward/BalancerForward previously concatenated `addr +
  c.OriginalURL()`. A leading `//` in the request path could form a
  network-path reference that, when re-parsed, changed the upstream
  host. joinUpstreamPath now rebuilds the URL safely.
- Snapshot scheme/target into freshly allocated strings before
  SetRequestURI to fix an aliasing regression where a caller-supplied
  addr that was itself a slice of the request buffer got clobbered
  mid-request (produced "unsupported protocol ttp:" errors).

Tests
- middleware/proxy/security_test.go: scheme allowlist, private-IP
  blocking + opt-in, hop-by-hop stripping (request and response,
  including Connection-listed), file:// rejection, HTTPS→HTTP
  redirect blocking with a real TLS handshake, path-injection
  protection, and TLS minimum version cloning.
- middleware/proxy/fuzz_test.go: FuzzValidateUpstream,
  FuzzJoinUpstreamPath, FuzzConnectionListedHeaders (all pass with
  -fuzztime=10s).
- TestMain in proxy_test.go relaxes the policy for loopback tests so
  the rest of the suite continues to work; security_test.go installs
  the strict policy where it asserts the new defaults.
- client/transport_test.go: TestComposeRedirectURL_RejectsHTTPSDowngrade.

Docs
- docs/middleware/proxy.md gains a full Security section covering
  every default, the SecurityPolicy fields, and migration notes for
  the breaking defaults.

https://claude.ai/code/session_01FhTTWhze2oLocDUWAkEet2

Author: claude

client/errors.go

@@ -11,4 +11,10 @@ var (
 	errFileTypeAssertion         = errors.New("failed to type-assert to *File")
 	errCookieJarTypeAssertion    = errors.New("failed to type-assert to *CookieJar")
 	errSyncPoolBuffer            = errors.New("failed to retrieve buffer from a sync.Pool")
+
+	// ErrRedirectDowngrade is returned when DoRedirects encounters a
+	// redirect from an HTTPS origin to a plaintext HTTP target.
+	// Following such a redirect would leak any credentials, cookies, or
+	// session tokens that the original HTTPS handshake protected.
+	ErrRedirectDowngrade = errors.New("client: HTTPS to HTTP redirect blocked")
 )

client/transport.go

@@ -350,7 +350,8 @@ func doRedirectsWithClient(req *fasthttp.Request, resp *fasthttp.Response, maxRe
 // composeRedirectURL resolves a redirect target relative to the current request
 // URL while rejecting suspicious payloads (e.g. control characters) and
 // restricting schemes to HTTP/S so caller-provided Location headers cannot
-// trigger arbitrary transports.
+// trigger arbitrary transports. Redirects from HTTPS to plaintext HTTP are
+// rejected to prevent credentials from leaking after a TLS handshake.
 func composeRedirectURL(base string, location []byte, disablePathNormalizing bool) (string, error) {
 	for _, b := range location {
 		if b < 0x20 || b == 0x7f {
@@ -362,16 +363,22 @@ func composeRedirectURL(base string, location []byte, disablePathNormalizing boo
 	defer fasthttp.ReleaseURI(uri)
 
 	uri.Update(base)
+	wasHTTPS := bytes.EqualFold(uri.Scheme(), httpsScheme)
 	uri.UpdateBytes(location)
 	uri.DisablePathNormalizing = disablePathNormalizing
 
-	if scheme := uri.Scheme(); len(scheme) > 0 && !bytes.EqualFold(scheme, httpScheme) && !bytes.EqualFold(scheme, httpsScheme) {
+	scheme := uri.Scheme()
+	if len(scheme) > 0 && !bytes.EqualFold(scheme, httpScheme) && !bytes.EqualFold(scheme, httpsScheme) {
 		return "", fasthttp.ErrorInvalidURI
 	}
 
-	if len(uri.Scheme()) > 0 && len(uri.Host()) == 0 {
+	if len(scheme) > 0 && len(uri.Host()) == 0 {
 		return "", fasthttp.ErrorInvalidURI
 	}
 
+	if wasHTTPS && bytes.EqualFold(scheme, httpScheme) {
+		return "", ErrRedirectDowngrade
+	}
+
 	return uri.String(), nil
 }

client/transport_test.go

@@ -325,6 +325,30 @@ func TestDoRedirectsWithClientBranches(t *testing.T) {
 	require.ErrorIs(t, doRedirectsWithClient(req, resp, 1, client), fasthttp.ErrTooManyRedirects)
 }
 
+// TestComposeRedirectURL_RejectsHTTPSDowngrade verifies that redirects
+// from HTTPS origins to plaintext HTTP targets are refused so cookies
+// and credentials never leave the TLS boundary.
+func TestComposeRedirectURL_RejectsHTTPSDowngrade(t *testing.T) {
+	t.Parallel()
+	_, err := composeRedirectURL("https://example.com/login", []byte("http://example.com/after"), false)
+	require.ErrorIs(t, err, ErrRedirectDowngrade)
+
+	// Same-origin HTTP→HTTP is fine.
+	out, err := composeRedirectURL("http://example.com/a", []byte("http://example.com/b"), false)
+	require.NoError(t, err)
+	require.Equal(t, "http://example.com/b", out)
+
+	// HTTPS→HTTPS is fine.
+	out, err = composeRedirectURL("https://example.com/a", []byte("https://example.com/b"), false)
+	require.NoError(t, err)
+	require.Equal(t, "https://example.com/b", out)
+
+	// HTTP→HTTPS upgrade is fine.
+	out, err = composeRedirectURL("http://example.com/a", []byte("https://example.com/b"), false)
+	require.NoError(t, err)
+	require.Equal(t, "https://example.com/b", out)
+}
+
 func TestDoRedirectsWithClientDefaultLimit(t *testing.T) {
 	t.Parallel()
 

docs/middleware/proxy.md

@@ -29,16 +29,48 @@ func BalancerForward(servers []string, clients ...*fasthttp.Client) fiber.Handle
 
 ## Security
 
-The `Forward`, `DomainForward`, and `BalancerForward` functions automatically set the `X-Real-IP` header to the actual client IP address obtained from `c.IP()` before forwarding the request upstream. This protects against IP spoofing attacks where a malicious client attempts to forge their IP address by sending a fake `X-Real-IP` header. Any existing `X-Real-IP` header on the incoming request is overwritten with the real client IP. Note that `DomainForward` only applies this overwrite when the request host matches the configured hostname; non-matching requests are not forwarded and are passed through unchanged.
+The proxy middleware applies several defenses by default. They can be relaxed via `Config.SecurityPolicy` (for `Balancer`) or `proxy.WithSecurityPolicy` (for the runtime helpers `Do`, `Forward`, `DoRedirects`, `DoTimeout`, `DoDeadline`).
 
-If you're using the `Balancer` function with the `Config` struct, you can achieve the same protection by using the `ModifyRequest` callback as shown in the examples below.
+### SSRF protection
 
-When using `Do`, `DoRedirects`, `DoDeadline`, or `DoTimeout` directly, the `X-Real-IP` header is not automatically set. You should set it manually if your upstream server requires it:
+Upstream addresses that resolve to loopback, RFC 1918 private, link-local (including the `169.254.169.254` cloud-metadata address), multicast, unspecified, or RFC 6598 CGNAT ranges are rejected with `ErrUpstreamHostBlocked`. Hostnames are resolved at validation time; if any returned IP falls in a blocked range the upstream is rejected, mitigating DNS-rebinding attempts that return a mix of public and private answers.
+
+Set `SecurityPolicy.AllowPrivateIPs = true` to opt out — required when proxying to internal services on the same network.
+
+### Scheme allowlist
+
+Only `http` and `https` upstream schemes are accepted by default; `file://`, `gopher://`, `ftp://`, and other schemes are rejected. Override via `SecurityPolicy.AllowedSchemes`.
+
+### HTTPS-to-HTTP redirect downgrades
+
+`DoRedirects` rejects redirects from HTTPS origins to plaintext HTTP targets with `ErrRedirectDowngrade`. Following such a redirect would leak any cookies or `Authorization` headers established under TLS. Set `SecurityPolicy.AllowHTTPSDowngrade = true` to override.
+
+### RFC 7230 hop-by-hop header stripping
+
+`Connection`, `Keep-Alive`, `Proxy-Authenticate`, `Proxy-Authorization`, `TE`, `Trailer`, `Transfer-Encoding`, and `Upgrade` are stripped from both the outbound request and the inbound response, along with every header listed in the `Connection` field per RFC 7230 §6.1. This prevents request smuggling (`TE`/`Transfer-Encoding`), proxy-credential forwarding, and protocol-upgrade leaks. The legacy `KeepConnectionHeader` option preserves only the literal `Connection` header for backwards compatibility; the other hop-by-hop headers are still stripped. To preserve every hop-by-hop header (not recommended), set `SecurityPolicy.KeepHopByHopHeaders = true`.
+
+### TLS minimum version
+
+`Config.TLSConfig` is cloned with `MinVersion: tls.VersionTLS12` if no minimum is configured, so deprecated TLS versions cannot be negotiated by accident.
+
+### Response body size and connection caps
+
+`Config.MaxResponseBodySize` bounds upstream response bodies to protect against memory exhaustion. `Config.MaxConnsPerHost` (default `1024`) caps concurrent connections per upstream to limit fan-out from a single hot host.
+
+### X-Real-IP spoof prevention
+
+`Forward`, `DomainForward`, and `BalancerForward` automatically overwrite the `X-Real-IP` header with `c.IP()` before forwarding, so clients cannot spoof their address. `DomainForward` only applies the overwrite when the request host matches the configured hostname; non-matching requests are passed through unchanged.
+
+If you're using `Balancer` with the `Config` struct, you can replicate the protection in `ModifyRequest`. When using `Do`, `DoRedirects`, `DoDeadline`, or `DoTimeout` directly, the `X-Real-IP` header is not set automatically — set it manually if needed:
 
 ```go
 c.Request().Header.Set("X-Real-IP", c.IP())
 ```
 
+### Path concatenation safety
+
+`DomainForward` and `BalancerForward` previously concatenated the configured upstream with `c.OriginalURL()`. Crafted request paths beginning with `//` could exploit URL parsing to redirect the proxy at a different host (network-path reference injection). The proxy now sanitises the joined path so the upstream host pinned in configuration is preserved regardless of the inbound request.
+
 ## Examples
 
 Import the middleware package:
@@ -59,11 +91,24 @@ proxy.WithClient(&fasthttp.Client{
     DisablePathNormalizing:   true,
     MaxConnsPerHost:          2048,
     // Allow self-signed certificates when proxying to HTTPS targets.
+    // SECURITY: disables certificate verification — use only when the
+    // upstream is on a trusted network.
     TLSConfig: &tls.Config{
         InsecureSkipVerify: true,
+        MinVersion:         tls.VersionTLS12,
     },
 })
 
+// Relax SSRF protection for local development against loopback servers.
+// SECURITY: in production, leave AllowPrivateIPs false (the default) and
+// list explicit upstream hosts so the proxy cannot be coerced into
+// reaching internal services or cloud-metadata endpoints.
+prev := proxy.WithSecurityPolicy(proxy.SecurityPolicy{
+    AllowedSchemes:  []string{"http", "https"},
+    AllowPrivateIPs: true,
+})
+defer proxy.WithSecurityPolicy(prev)
+
 // Forward requests for a specific domain with proxy.DomainForward.
 app.Get("/payments", proxy.DomainForward("docs.gofiber.io", "http://localhost:8000"))
 
@@ -181,10 +226,12 @@ app.Use(proxy.Balancer(proxy.Config{
 | MaxConnsPerHost | `int`                                          | Maximum number of connections per upstream host. The default proxy client and balancer host clients use this limit unless you override it with `WithClient`, a per-handler client, or `proxy.Config`.                         | `1024`          |
 | ReadBufferSize  | `int`                                          | Per-connection buffer size for requests' reading. This also limits the maximum header size. Increase this buffer if your clients send multi-KB RequestURIs and/or multi-KB headers (for example, BIG cookies).                     | (Not specified) |
 | WriteBufferSize | `int`                                          | Per-connection buffer size for responses' writing.                                                                                                                                                                                 | (Not specified) |
-| KeepConnectionHeader | `bool` | Keeps the `Connection` header when set to `true`. By default the header is removed to comply with RFC 7230 §6.1 and avoid proxy loops. | `false` |
-| TLSConfig       | `*tls.Config` | TLS config for the HTTP client. | `nil`           |
+| KeepConnectionHeader | `bool` | Keeps the `Connection` header when set to `true`. By default the header is removed to comply with RFC 7230 §6.1 and avoid proxy loops. Other hop-by-hop headers are still stripped regardless of this setting. | `false` |
+| TLSConfig       | `*tls.Config` | TLS config for the HTTP client. Cloned with `MinVersion: tls.VersionTLS12` when no minimum is set. | `nil`           |
 | DialDualStack   | `bool`                                         | Client will attempt to connect to both IPv4 and IPv6 host addresses if set to true.                                                                                                                                                | `false`         |
 | Client          | `*fasthttp.LBClient`                           | Client is a custom client when client config is complex.                                                                                                                                                                           | `nil`           |
+| SecurityPolicy  | `*SecurityPolicy`                              | Overrides the default SSRF, redirect, and hop-by-hop header rules for this balancer. When `nil`, the package-level policy set via `WithSecurityPolicy` is used. See [Security](#security).                                          | `nil`           |
+| MaxResponseBodySize | `int`                                       | Maximum upstream response body size in bytes. `0` keeps fasthttp's unlimited default.                                                                                                                                              | `0`             |
 
 ## Default Config
 
@@ -198,3 +245,16 @@ var ConfigDefault = Config{
     KeepConnectionHeader: false,
 }
 ```
+
+## Default SecurityPolicy
+
+When `Config.SecurityPolicy` is `nil` (and `proxy.WithSecurityPolicy` has not been called), the package falls back to:
+
+```go
+var DefaultSecurityPolicy = proxy.SecurityPolicy{
+    AllowedSchemes:      []string{"http", "https"},
+    AllowPrivateIPs:     false,
+    AllowHTTPSDowngrade: false,
+    KeepHopByHopHeaders: false,
+}
+```