fix(static): disable static path unescaping by default to prevent ACL bypass (GHSA-3pmx-cf9f-34xr)

[vishr]

Summary

Fixes GHSA-3pmx-cf9f-34xr, a bypass of the GHSA-vfp3-v2gw-7wfq fix (#3009).

The router matches the raw, still-encoded request path, so encoded separators and dot segments in a static wildcard are not treated as traversal during routing. Unescaping them in the static file resolver afterwards let an unauthenticated attacker read a file across a route-level middleware guard the encoded path never matched:

• /public/%2E%2E/admin/secret.txt → admin/secret.txt — high severity, default router
• /public%2F..%2Fadmin%2Fsecret.txt under UseEscapedPathForMatching=true, where the router decodes the path itself before the handler sees it — lower severity (non-default config)

Both returned 200 + the protected file on master at 5786024 (the exact commit the advisory tested).

Approach

Rather than keep extending an encoding denylist (the original fix blocked %2F/%5C but missed %2E%2E), this addresses the root cause: make static path unescaping opt-in. This follows @aldas's proposal (e85ee8f), rebased onto current master.

• echo: Config.EnablePathUnescapingStaticFiles (default false) controls unescaping for Echo.Static/StaticFS and Group.Static/StaticFS.
• middleware: StaticConfig.EnablePathUnescaping replaces the now-deprecated DisablePathUnescaping; the default is the safe, no-unescape mode.

With unescaping off, %2F/%5C/%2E%2E stay literal and never become separators or traversal.

As defense in depth — and to also close the UseEscapedPathForMatching variant, where the router (not the handler) does the decoding — any .. path segment in the resolved wildcard is rejected via pathutil.HasDotDotSegment, mirroring the fs.ValidPath "no .. element" invariant. The existing encoded-separator guard remains as a backstop on the opt-in unescaping path.

Verification

Variant	master (5786024)	this PR
/public/%2E%2E/admin/secret.txt (default router)	200 TOP-SECRET	404
/public%2F..%2Fadmin%2Fsecret.txt (UseEscapedPathForMatching)	200 TOP-SECRET	404
middleware equivalents (both router modes)	200 TOP-SECRET	404

Regression tests cover both variants in both router modes, the opt-in mode (encoded %20 filenames serve, but %2F/.. still rejected), and pathutil.HasDotDotSegment units. go test -race ./... and go vet ./... pass.

⚠️ Breaking change

Static files whose names contain URL-encoded characters (e.g. "hello world.txt" via /hello%20world.txt) are no longer served by default. Set EnablePathUnescapingStaticFiles (echo) / EnablePathUnescaping (middleware) to opt back in. Because this flips a default, suggest releasing as 5.3.0 with an upgrade note rather than a patch.

Notes for reviewers

• Omitted the RawPath-preferring directory-redirect tweak from e85ee8f to keep this scoped to the vuln; happy to fold it in.
• cc @aldas — this takes your disable-by-default approach plus the .. rejection needed to close the UseEscapedPathForMatching variant your patch didn't reach.

🤖 Generated with Claude Code

[aldas]

@vishr I just created #3016

[aldas]

@vishr , I do not think this HasDotDotSegment and any of pathutil is a maintainable solution. LLM can generate always another patch for leaking solution and complexity only grows.

[aldas]

Root problem here is that router and Static file serving methods and Static middleware are using path inconsistently. Creating functions to check path is just a fix for the symptom not the cause.

[vishr]

@aldas Let me take a look.