Security
Make serving static file releated methods and middleware not unescape path by default - so how the way Router interprets paths and Static methods/middleware is consistent.
Given following situation:
// 0.
// given folder structure:
// private.txt
// public/
// public/index.html
// public/text.txt
// public/admin/private.txt
// 1. share `public/` folder contents from the server root. This folder actually contains subfolder `admin` which
// contents we want to forbid from downloading
e.Static("/", "public")
// 2. naively assume that everything under /admin folder is now forbidden
e.GET("/admin/*", func(c *Context) error {
return ErrForbidden
})Then requests to /admin%2fprivate.txt would not be matched to GET /admin/* route (routing does not look unescaped path) and static file serving will use unescaped path to serve the file.
Note: this way of "guarding" subfolders will never work for for paths like /assets/../admin%2fprivate.txt which will path.Clean("/assets/../admin%2fprivate.txt") to /admin/private.txt and are servable if static file serving is configured to unescape paths.
If you want to guard routes - use middlewares on Static* methods and before Static middleware.
- revert PR #3009 changes to just disabling path escaping by default in static methods/middleware by @aldas in #3016
Closes GHSA-vfp3-v2gw-7wfq more completely: the previous fix (#3009) rejected explicitly encoded
separators at the handler level; this patch makes the no-unescape behavior the default so new configurations are safe without extra opt-out steps.
What changed: DisablePathUnescaping (on StaticConfig and StaticDirectoryHandlerConfig) is deprecated and replaced by EnablePathUnescaping (default false). Path unescaping is now opt-in.
What this protects: With EnablePathUnescaping: false (new default), encoded separators (%2F, %5C) are never decoded before routing or file lookup, so they cannot
bypass route-level authentication or other middleware guards.
What this does NOT protect: Serving a directory with Static, StaticFS, or StaticDirectoryHandler exposes its entire subtree. Sibling routes are not a reliable
ACL boundary — attach authorization middleware directly to the static mount, or serve sensitive sub-trees under separate guarded routes.
Breaking change / migration: If you serve files whose names contain URL-encoded characters (e.g., /hello%20world.txt → hello world.txt), you must now opt in:
// Static middleware
e.Use(middleware.StaticWithConfig(middleware.StaticConfig{
EnablePathUnescaping: true, // only safe when NOT relying on route-based ACL guards
...
}))
// StaticDirectoryHandler
middleware.StaticDirectoryHandler(fs, &middleware.StaticDirectoryHandlerConfig{
EnablePathUnescaping: true,
})Full Changelog: v5.2.0...v5.2.1
