@@ -1,6 +1,41 @@
 # Changelog
 
 
+## v5.4.0 - 2026-09-27
+
+**Security**
+
+This release fixes several security issues. Upgrading is recommended. Some fixes change behavior; read "Behavior changes to check before upgrading" below.
+
+* **Request scheme:** `Context.Scheme()` now uses the `X-Forwarded-Proto`, `X-Forwarded-Protocol`, `X-Forwarded-Ssl` and `X-Url-Scheme` headers only when the request comes directly from a loopback, link-local or private network address or a unix socket. Before this, any client could send `X-Forwarded-Proto: https` over plain HTTP and skip `HTTPSRedirect`. When `X-Forwarded-Proto` is present, only it is used (its last value), and the scheme is returned in lowercase. `Echo#SchemeExtractor` (and `Config.SchemeExtractor`) selects the strategy: `ExtractSchemeFromHeaders(...TrustOption)` (default), `ExtractSchemeDirect()` or `LegacySchemeExtractor()`. The Secure middleware now sets HSTS based on `Context.Scheme()`. The Proxy middleware always sets `X-Forwarded-Proto` from `Context.Scheme()` and removes `X-Forwarded-Ssl`, `X-Forwarded-Protocol` and `X-Url-Scheme` before forwarding. [GHSA-2ffq-g2xg-c22p](https://github.com/labstack/echo/security/advisories/GHSA-2ffq-g2xg-c22p)
+* **Proxy middleware:** always sets `X-Real-IP` from `Context.RealIP()`, so a client can no longer pass a spoofed `X-Real-IP` to the upstream. [GHSA-99jh-6h7p-pp36](https://github.com/labstack/echo/security/advisories/GHSA-99jh-6h7p-pp36)
+* **JSONP:** `Context.JSONP` and `Context.JSONPBlob` accept only a callback that is empty, a JavaScript identifier or a dot-separated path of identifiers (ASCII letters, digits, `_` and `$`). Any other callback returns a 400 Bad Request error that wraps the new `ErrInvalidJSONPCallback`, and nothing is written. JSONP responses now carry `X-Content-Type-Options: nosniff`. JSONP lets any website read the response with the user's cookies, so do not use it for data that needs authentication. [GHSA-h9g5-28mm-hx3g](https://github.com/labstack/echo/security/advisories/GHSA-h9g5-28mm-hx3g)
+* **MethodOverride:** a POST can no longer be overridden to `GET`, `HEAD`, `OPTIONS`, `TRACE` or `CONNECT`. Before this, with the `MethodFromForm` or `MethodFromQuery` getter and MethodOverride registered with `Use` before the CSRF middleware, `_method=GET` skipped the CSRF check. Register MethodOverride with `Echo#Pre`. [GHSA-r7w9-592q-9vg4](https://github.com/labstack/echo/security/advisories/GHSA-r7w9-592q-9vg4)
+* **Redirects:** the trailing slash middlewares and the static directory redirect percent-encode control characters in the redirect path. Before this, `/%09/evil.example/` redirected browsers to `evil.example`. [GHSA-v753-g4cw-jm48](https://github.com/labstack/echo/security/advisories/GHSA-v753-g4cw-jm48)
+* **Static files:** with the default settings, the Static middleware resolves files from the same form of the path that the router matched, so `/admin%2Fsecret.txt` or `/%61dmin/secret.txt` can no longer reach a file under a guarded `/admin/*` route. [GHSA-375p-5qhx-8wq4](https://github.com/labstack/echo/security/advisories/GHSA-375p-5qhx-8wq4) The Static middleware and `StaticDirectoryHandler` (used by `Echo.Static`, `Echo.StaticFS`, `Group.Static` and `Group.StaticFS`) no longer serve paths with a `.`, `..` or empty segment, such as `/assets/../admin/secret.txt`, also after path unescaping. [GHSA-3pmx-cf9f-34xr](https://github.com/labstack/echo/security/advisories/GHSA-3pmx-cf9f-34xr)
+
+**Behavior changes to check before upgrading**
+
+* **Proxies or load balancers with public IP addresses.** If a proxy connects to your app from a public (or `100.64.0.0/10`) address, its `X-Forwarded-Proto` is now ignored: `HTTPSRedirect` redirects in a loop and the Secure middleware stops sending HSTS. This affects, for example, Cloudflare, CloudFront and Azure Front Door connecting to a public origin, the GCP external HTTP(S) load balancer including GKE Ingress (`35.191.0.0/16`, `130.211.0.0/22`), and networks that use `100.64.0.0/10` (such as Alibaba Cloud SLB or EKS custom networking). Trust the proxy's address ranges:
+  ```go
+  _, gclb1, _ := net.ParseCIDR("35.191.0.0/16")
+  _, gclb2, _ := net.ParseCIDR("130.211.0.0/22")
+  e.SchemeExtractor = echo.ExtractSchemeFromHeaders(echo.TrustIPRange(gclb1), echo.TrustIPRange(gclb2))
+  ```
+  Proxies on the same host, in a private network (AWS ALB, in-cluster ingress controllers such as ingress-nginx or Traefik, most PaaS routers) or on a unix socket keep working without changes. `echo.LegacySchemeExtractor()` restores the old behavior but is not safe unless every request passes through a proxy that sets these headers. Serverless adapters or middleware that set `RemoteAddr` to the client's address also make `X-Forwarded-Proto` ignored (or, if they take it from a header, spoofable).
+* **Trusted proxies must set `X-Forwarded-Proto`.** A proxy on a trusted address that passes the client's `X-Forwarded-Proto` through (for example nginx without `proxy_set_header X-Forwarded-Proto $scheme;`) still lets the client choose the scheme. An invalid `X-Forwarded-Proto` value now results in `http` instead of falling back to the other scheme headers.
+* **Your own tests.** `httptest.NewRequest` sets `RemoteAddr` to `192.0.2.1:1234`, which is not trusted, so tests that set `X-Forwarded-Proto` now see `http`. Set `req.RemoteAddr = "10.0.0.1:1234"` or use `e.SchemeExtractor = echo.LegacySchemeExtractor()` in such tests.
+* **Proxy middleware headers.** `X-Real-IP` sent to the upstream is now always `Context.RealIP()`. In a chain like nginx → Echo Proxy → upstream, configure `Echo#IPExtractor` (for example `echo.ExtractIPFromRealIPHeader()`) to pass the client address on. `X-Forwarded-Ssl`, `X-Forwarded-Protocol` and `X-Url-Scheme` are no longer forwarded; `X-Forwarded-Proto` carries the scheme.
+* **MethodOverride.** Overriding a POST to `GET` (for example with `X-HTTP-Method-Override: GET` to send a long query in a POST body) is no longer done; such requests keep the POST method.
+* **Static files.** Paths with a double slash or dot segment (for example `/assets//app.js`) now return 404; in HTML5 mode the index is still served. The Static middleware no longer finds file names that the client sends with non-default escaping (for example `%2C`, `%40` or lowercase hex like `%c3%a9`) unless `StaticConfig.EnablePathUnescaping` is set; `Echo.Static` has behaved this way since v5.2.1. With `StaticConfig.EnablePathUnescaping` or `Config.EnablePathUnescapingStaticFiles`, encoded dots (`%2e%2e`) no longer traverse directories, but encoded slashes are still decoded, so do not combine these options with route-based access control.
+* **JSONP.** `Context.JSONP` returns an error for callbacks that are not JavaScript identifiers.
+
+**Documentation**
+
+* `IPExtractor` docs: corrected the description of the default (the direct peer address has been used since v5.1.0).
+* Static middleware: when registered with `Echo#Use` it runs before route and group middleware, so route guards do not protect the files it serves.
+
+
 ## v5.3.1 - 2026-07-21
 
 **Fixes**
 
@@ -195,38 +195,20 @@ func (c *Context) IsWebSocket() bool {
 	return strings.EqualFold(upgrade, "websocket") && strings.Contains(strings.ToLower(connection), "upgrade")
 }
 
-func isValidProto(proto string) bool {
-	if proto == "" {
-		return false
-	}
-	for _, p := range []string{"http", "https", "ws", "wss"} {
-		if strings.EqualFold(proto, p) {
-			return true
-		}
-	}
-	return false
-}
-
-// Scheme returns the HTTP protocol scheme, `http` or `https`.
+// Scheme returns the protocol scheme in lowercase: `http` or `https`, or `ws` or `wss` when a trusted proxy reports
+// them.
+//
+// Echo#SchemeExtractor decides how the scheme is determined. When it is not set, the forwarding headers
+// (`X-Forwarded-Proto`, `X-Forwarded-Protocol`, `X-Forwarded-Ssl` and `X-Url-Scheme`) are used only for requests
+// that come directly from a loopback, link-local or private network address or a unix socket.
+// See ExtractSchemeFromHeaders.
 func (c *Context) Scheme() string {
 	// Can't use `r.Request.URL.Scheme`
 	// See: https://groups.google.com/forum/#!topic/golang-nuts/pMUkBlQBDF0
-	if c.IsTLS() {
-		return "https"
-	}
-	if scheme := c.request.Header.Get(HeaderXForwardedProto); isValidProto(scheme) {
-		return scheme
+	if c.echo != nil && c.echo.SchemeExtractor != nil {
+		return c.echo.SchemeExtractor(c.request)
 	}
-	if scheme := c.request.Header.Get(HeaderXForwardedProtocol); isValidProto(scheme) {
-		return scheme
-	}
-	if ssl := c.request.Header.Get(HeaderXForwardedSsl); ssl == "on" {
-		return "https"
-	}
-	if scheme := c.request.Header.Get(HeaderXUrlScheme); isValidProto(scheme) {
-		return scheme
-	}
-	return "http"
+	return extractScheme(c.request, defaultSchemeChecker)
 }
 
 // RealIP returns the client IP address using the configured extraction strategy.
@@ -524,9 +506,50 @@ func (c *Context) String(code int, s string) (err error) {
 	return c.Blob(code, MIMETextPlainCharsetUTF8, stringToBytes(s))
 }
 
-func (c *Context) jsonPBlob(code int, callback string, i any) (err error) {
+// isValidJSONPCallback reports whether callback can be used as a JSONP function name: an empty string, a JavaScript
+// identifier or a dot-separated path of identifiers (e.g. `cb`, `jQuery_123`, `ns.handlers.cb`). Only ASCII letters,
+// digits, `_` and `$` are allowed, so the callback cannot inject other JavaScript into the response.
+func isValidJSONPCallback(callback string) bool {
+	if callback == "" {
+		return true
+	}
+	atStart := true // at the start of an identifier
+	for i := 0; i < len(callback); i++ {
+		ch := callback[i]
+		switch {
+		case ch == '.':
+			if atStart {
+				return false
+			}
+			atStart = true
+		case ch == '_' || ch == '$' || ('a' <= ch && ch <= 'z') || ('A' <= ch && ch <= 'Z'):
+			atStart = false
+		case '0' <= ch && ch <= '9':
+			if atStart {
+				return false
+			}
+		default:
+			return false
+		}
+	}
+	return !atStart
+}
+
+// writeJSONPHeader validates the callback and writes the JSONP response headers.
+func (c *Context) writeJSONPHeader(code int, callback string) error {
+	if !isValidJSONPCallback(callback) {
+		return ErrBadRequest.Wrap(ErrInvalidJSONPCallback)
+	}
 	c.writeContentType(MIMEApplicationJavaScriptCharsetUTF8)
+	c.response.Header().Set(HeaderXContentTypeOptions, "nosniff")
 	c.response.WriteHeader(code)
+	return nil
+}
+
+func (c *Context) jsonPBlob(code int, callback string, i any) (err error) {
+	if err = c.writeJSONPHeader(code, callback); err != nil {
+		return
+	}
 	if _, err = c.response.Write(stringToBytes(callback)); err != nil {
 		return
 	}
@@ -581,15 +604,23 @@ func (c *Context) JSONBlob(code int, b []byte) (err error) {
 
 // JSONP sends a JSONP response with status code. It uses `callback` to construct
 // the JSONP payload.
+//
+// The callback must be empty, a JavaScript identifier or a dot-separated path of identifiers using only ASCII
+// letters, digits, `_` and `$`. Otherwise nothing is written and a 400 Bad Request error wrapping
+// ErrInvalidJSONPCallback is returned. The response has the `X-Content-Type-Options: nosniff` header.
+//
+// Any website can load a JSONP response with a <script> tag, including the user's cookies. Do not use JSONP for
+// data that requires authentication; use JSON with CORS instead.
 func (c *Context) JSONP(code int, callback string, i any) (err error) {
 	return c.jsonPBlob(code, callback, i)
 }
 
 // JSONPBlob sends a JSONP blob response with status code. It uses `callback`
-// to construct the JSONP payload.
+// to construct the JSONP payload. The callback is validated like in Context.JSONP.
 func (c *Context) JSONPBlob(code int, callback string, b []byte) (err error) {
-	c.writeContentType(MIMEApplicationJavaScriptCharsetUTF8)
-	c.response.WriteHeader(code)
+	if err = c.writeJSONPHeader(code, callback); err != nil {
+		return
+	}
 	if _, err = c.response.Write(stringToBytes(callback)); err != nil {
 		return
 	}
 
@@ -260,6 +260,64 @@ func TestContextJSONWithNotEchoResponse(t *testing.T) {
 	assert.Empty(t, rec.Body.String())       // body must not be sent to the client
 }
 
+func TestContextJSONP_callbackValidation(t *testing.T) {
+	var testCases = []struct {
+		name          string
+		givenCallback string
+		expectValid   bool
+	}{
+		{name: "simple identifier", givenCallback: "callback", expectValid: true},
+		{name: "jQuery style", givenCallback: "jQuery331_1700000000000", expectValid: true},
+		{name: "dollar", givenCallback: "$", expectValid: true},
+		{name: "underscore prefix", givenCallback: "_cb", expectValid: true},
+		{name: "dotted path", givenCallback: "ns.handlers.cb", expectValid: true},
+		{name: "empty", givenCallback: "", expectValid: true},
+		{name: "function call injection", givenCallback: "alert(1)//", expectValid: false},
+		{name: "statement injection", givenCallback: "cb;alert(1)", expectValid: false},
+		{name: "html", givenCallback: "<script>", expectValid: false},
+		{name: "space", givenCallback: "a b", expectValid: false},
+		{name: "dash", givenCallback: "a-b", expectValid: false},
+		{name: "leading digit", givenCallback: "1abc", expectValid: false},
+		{name: "digit after dot", givenCallback: "a.1b", expectValid: false},
+		{name: "leading dot", givenCallback: ".cb", expectValid: false},
+		{name: "trailing dot", givenCallback: "cb.", expectValid: false},
+		{name: "double dot", givenCallback: "a..b", expectValid: false},
+		{name: "brackets", givenCallback: "a[0]", expectValid: false},
+		{name: "newline", givenCallback: "cb\nalert(1)", expectValid: false},
+		{name: "non-ASCII", givenCallback: "caf\u00e9", expectValid: false},
+	}
+
+	for _, tc := range testCases {
+		for _, method := range []string{"JSONP", "JSONPBlob"} {
+			t.Run(method+" "+tc.name, func(t *testing.T) {
+				e := New()
+				rec := httptest.NewRecorder()
+				req := httptest.NewRequest(http.MethodGet, "/", nil)
+				c := e.NewContext(req, rec)
+
+				var err error
+				if method == "JSONP" {
+					err = c.JSONP(http.StatusOK, tc.givenCallback, user{ID: 1, Name: "Jon Snow"})
+				} else {
+					err = c.JSONPBlob(http.StatusOK, tc.givenCallback, []byte(userJSON))
+				}
+
+				if tc.expectValid {
+					assert.NoError(t, err)
+					assert.Equal(t, http.StatusOK, rec.Code)
+					assert.Equal(t, "nosniff", rec.Header().Get(HeaderXContentTypeOptions))
+					assert.True(t, strings.HasPrefix(rec.Body.String(), tc.givenCallback+"("))
+					return
+				}
+				assert.ErrorIs(t, err, ErrInvalidJSONPCallback)
+				assert.Equal(t, http.StatusBadRequest, StatusCode(err))
+				assert.Equal(t, 0, rec.Body.Len())
+				assert.Equal(t, "", rec.Header().Get(HeaderContentType))
+			})
+		}
+	}
+}
+
 func TestContextJSONPretty(t *testing.T) {
 	e := New()
 	rec := httptest.NewRecorder()
@@ -1091,10 +1149,11 @@ func TestContext_Request(t *testing.T) {
 
 func TestContext_Scheme(t *testing.T) {
 	var testCases = []struct {
-		name         string
-		givenIsTLS   bool
-		givenHeaders http.Header
-		expect       string
+		name            string
+		givenIsTLS      bool
+		givenRemoteAddr string // defaults to a trusted reverse proxy in a private network
+		givenHeaders    http.Header
+		expect          string
 	}{
 		{
 			name:         "defaults to http without TLS or headers",
@@ -1138,7 +1197,7 @@ func TestContext_Scheme(t *testing.T) {
 			givenHeaders: http.Header{
 				HeaderXForwardedProto: []string{"HTTPS"},
 			},
-			expect: "HTTPS",
+			expect: "https", // lowercase, so `Scheme() == "https"` checks (HTTPSRedirect, Secure) work
 		},
 		{
 			name:       "uses X-Forwarded-Proto ws",
@@ -1157,13 +1216,35 @@ func TestContext_Scheme(t *testing.T) {
 			expect: "wss",
 		},
 		{
-			name:       "ignores invalid X-Forwarded-Proto and uses X-Forwarded-Protocol",
+			name:       "invalid X-Forwarded-Proto falls back to http, not to other headers",
 			givenIsTLS: false,
 			givenHeaders: http.Header{
 				HeaderXForwardedProto:    []string{"ftp"},
 				HeaderXForwardedProtocol: []string{"https"},
 			},
-			expect: "https",
+			expect: "http",
+		},
+		{
+			name: "uses last value of comma separated X-Forwarded-Proto (added by the nearest proxy)",
+			givenHeaders: http.Header{
+				HeaderXForwardedProto: []string{"https, http"},
+			},
+			expect: "http",
+		},
+		{
+			name: "uses last X-Forwarded-Proto header line (added by the nearest proxy)",
+			givenHeaders: http.Header{
+				HeaderXForwardedProto: []string{"https", "http"},
+			},
+			expect: "http",
+		},
+		{
+			name: "X-Forwarded-Ssl can not override X-Forwarded-Proto list",
+			givenHeaders: http.Header{
+				HeaderXForwardedProto: []string{"http, http"},
+				HeaderXForwardedSsl:   []string{"on"},
+			},
+			expect: "http",
 		},
 		{
 			name:       "uses X-Forwarded-Protocol",
@@ -1244,11 +1325,70 @@ func TestContext_Scheme(t *testing.T) {
 			},
 			expect: "https",
 		},
+		{
+			name:            "ignores X-Forwarded-Proto from untrusted client",
+			givenRemoteAddr: "203.0.113.10:1234",
+			givenHeaders:    http.Header{HeaderXForwardedProto: []string{"https"}},
+			expect:          "http",
+		},
+		{
+			name:            "ignores X-Forwarded-Protocol from untrusted client",
+			givenRemoteAddr: "203.0.113.10:1234",
+			givenHeaders:    http.Header{HeaderXForwardedProtocol: []string{"https"}},
+			expect:          "http",
+		},
+		{
+			name:            "ignores X-Forwarded-Ssl from untrusted client",
+			givenRemoteAddr: "203.0.113.10:1234",
+			givenHeaders:    http.Header{HeaderXForwardedSsl: []string{"on"}},
+			expect:          "http",
+		},
+		{
+			name:            "ignores X-Url-Scheme from untrusted client",
+			givenRemoteAddr: "203.0.113.10:1234",
+			givenHeaders:    http.Header{HeaderXUrlScheme: []string{"https"}},
+			expect:          "http",
+		},
+		{
+			name:            "returns https for TLS from untrusted client",
+			givenIsTLS:      true,
+			givenRemoteAddr: "203.0.113.10:1234",
+			givenHeaders:    http.Header{HeaderXForwardedProto: []string{"http"}},
+			expect:          "https",
+		},
+		{
+			name:            "trusts X-Forwarded-Proto from loopback",
+			givenRemoteAddr: "127.0.0.1:1234",
+			givenHeaders:    http.Header{HeaderXForwardedProto: []string{"https"}},
+			expect:          "https",
+		},
+		{
+			name:            "trusts X-Forwarded-Proto from IPv6 loopback",
+			givenRemoteAddr: "[::1]:1234",
+			givenHeaders:    http.Header{HeaderXForwardedProto: []string{"https"}},
+			expect:          "https",
+		},
+		{
+			name:            "trusts X-Forwarded-Proto from unix socket peer",
+			givenRemoteAddr: "@",
+			givenHeaders:    http.Header{HeaderXForwardedProto: []string{"https"}},
+			expect:          "https",
+		},
+		{
+			name:            "ignores X-Forwarded-Proto from unparsable remote address",
+			givenRemoteAddr: "not-an-ip:1234",
+			givenHeaders:    http.Header{HeaderXForwardedProto: []string{"https"}},
+			expect:          "http",
+		},
 	}
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
 			req := httptest.NewRequest(http.MethodGet, "/", nil)
+			req.RemoteAddr = "10.0.0.1:1234"
+			if tc.givenRemoteAddr != "" {
+				req.RemoteAddr = tc.givenRemoteAddr
+			}
 			if tc.givenHeaders != nil {
 				req.Header = tc.givenHeaders
 			}