docs(web): add guidance on using RoutingContext#normalizedPath() for security-sensitive path checks

Signed-off-by: Matthaios Stavrou <[email protected]>

Author: mathias82

vertx-web/src/main/asciidoc/index.adoc

@@ -167,6 +167,41 @@ to {@link io.vertx.ext.web.Router#handle}.
 
 So, that's the basics. Now we'll look at things in more detail:
 
+== Raw path vs normalized path
+
+When working with routes, it is important to understand that
+`HttpServerRequest#path()` returns the *raw* request path as it was
+sent by the client. This value may still contain segments such as
+`.` or `..`, or repeated `/` characters.
+
+Vert.x Web internally uses a *normalized* version of the path when
+matching routes. To obtain this normalized value inside a handler,
+use `RoutingContext#normalizedPath()`:
+
+[source,java]
+----
+router.route("/secured/*").handler(ctx -> {
+  // Raw path as sent by the client (may contain "..")
+  String raw = ctx.request().path();
+
+  // Normalized path as used by the router for matching
+  String normalized = ctx.normalizedPath();
+
+  // For security-sensitive checks, prefer the normalized path
+  if ("/secured/data".equals(normalized)) {
+    // ...
+  }
+});
+----
+
+[NOTE]
+====
+For logging or authorization decisions that depend on the request path,
+prefer `RoutingContext#normalizedPath()` instead of `HttpServerRequest#path()`,
+to avoid surprises with paths like `/secured/../secured/data`.
+====
+
+
 == Handling requests and calling the next handler
 
 When Vert.x-Web decides to route a request to a matching route, it calls the handler of the route passing in an instance

vertx-web/src/main/java/io/vertx/ext/web/RoutingContext.java

@@ -178,15 +178,25 @@ public interface RoutingContext {
   @Nullable Route currentRoute();
 
   /**
-   * Normalizes a path as per <a href="http://tools.ietf.org/html/rfc3986#section-5.2.4>rfc3986</a>.
+   * Returns the normalized path of the current request.
    * <p>
-   * There are 2 extra transformations that are not part of the spec but kept for backwards compatibility:
+   * Unlike {@link io.vertx.core.http.HttpServerRequest#path()}, which returns
+   * the <em>raw</em> path as sent by the client, this value is normalized for
+   * routing purposes. The normalization process:
+   * <ul>
+   *   <li>resolves dot-segments such as {@code ".."} and {@code "."},</li>
+   *   <li>collapses multiple {@code '/'} characters into a single slash,</li>
+   *   <li>ensures the path always starts with {@code '/'},</li>
+   *   <li>normalizes {@code null} paths to {@code "/"}</li>
+   * </ul>
    * <p>
-   * double slash // will be converted to single slash and the path will always start with slash.
-   * <p>
-   * Null paths are normalized to {@code /}.
+   * This is the value used internally by Vert.x Web when matching routes. For
+   * any security-sensitive checks or custom authorization logic, prefer using
+   * this normalized path instead of {@code request().path()}, as the raw path
+   * may still contain traversal-like sequences (e.g. {@code "/a/../b"}) that
+   * resolve to the same route.
    *
-   * @return normalized path
+   * @return the normalized path
    */
   String normalizedPath();