docs: explain event.url.pathname decoding

pi0 · pi0 · commit 3f8b5bc62129 · 2026-07-17T08:38:24.000Z
diff --git a/docs/1.guide/900.api/2.h3event.md b/docs/1.guide/900.api/2.h3event.md
@@ -101,6 +101,37 @@ app.get("/", async (event) => {
 
 Access to the full parsed request [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL).
 
+```ts
+app.get("/", (event) => {
+  const { pathname, search, searchParams } = event.url;
+
+  return "OK";
+});
+```
+
+#### Pathname decoding
+
+`event.url.pathname` is percent-decoded **once**, while `event.req.url` keeps the original encoding exactly as it arrived on the wire. H3 decodes eagerly so that route matching and any pathname-based middleware always compare the same normalized value — otherwise a request to `/%61dmin` would slip past an `/admin` guard and still reach the `/admin` route.
+
+Decoding is a single [`decodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) pass, and the result is re-serialized by the URL parser. This means only unreserved escapes visibly decode:
+
+| Request         | `event.url.pathname` | Why                                       |
+| --------------- | -------------------- | ----------------------------------------- |
+| `/%41`          | `/A`                 | Unreserved escape, decodes                |
+| `/a%2eb`        | `/a.b`               | Unreserved escape, decodes                |
+| `/a/%2e%2e/b`   | `/b`                 | Decoded `..` collapses during re-parse    |
+| `/x%2fy`        | `/x%2fy`             | Structural, kept encoded                  |
+| `/100%25`       | `/100%25`            | Structural, kept encoded                  |
+| `/a%20b`        | `/a%20b`             | Re-encoded by the URL serializer          |
+| `/caf%C3%A9`    | `/caf%C3%A9`         | Re-encoded by the URL serializer          |
+
+Either way, a route param can never contain a path separator that the router did not match on: `%2f` stays encoded, and `%5c` decodes to `\`, which the URL parser then normalizes into a real `/` the router splits on (`/a%5cb` matches the route `/a/:id`).
+
+> [!WARNING]
+> Never decode `event.url.pathname` again. A second `decodeURIComponent` can reintroduce a `/` or `..` that routing and middleware never saw, which is a path traversal vector when the value reaches a filesystem or an upstream URL. To read a route param in decoded form, use [`getRouterParams(event, { decode: true })`](/utils/request#getrouterparamsevent-opts-decode), which decodes everything else but keeps encoded separators encoded.
+
+Requests with malformed percent-encoding (such as `/foo%` or `/%ZZ`) are rejected with a `400 Bad Request` before any handler runs. Set the [`allowMalformedURL`](/guide/api/h3#h3-options) app option to receive the raw pathname instead.
+
 ### `H3Event.res`
 
 Prepared HTTP response status and headers.
diff --git a/src/event.ts b/src/event.ts
@@ -45,6 +45,26 @@ export class H3Event<
   /**
    * Access to the parsed request URL.
    *
+   * Unlike `event.req.url`, which keeps the original wire encoding, `event.url.pathname` is
+   * percent-decoded **once**, so route matching and every pathname-based
+   * middleware compare the same normalized value (`/%61dmin` cannot slip past an
+   * `/admin` guard). Decoding is a single `decodeURI` pass and the result is
+   * re-serialized by the URL parser, so:
+   *
+   * - Unreserved escapes decode: `/%41` → `/A`, `/a%2eb` → `/a.b` (and `%2e%2e`
+   *   segments then collapse, `/a/%2e%2e/b` → `/b`).
+   * - Structural escapes stay encoded: `%2F`, `%3F`, `%23`, `%25`. A `:param`
+   *   can therefore never hold a raw `/` the router did not match on.
+   * - Escapes the URL serializer re-adds stay encoded: `%20`, non-ASCII (`%C3%A9`).
+   *
+   * Never decode `pathname` a second time: it can reintroduce a `/` or `..` that
+   * routing and middleware never saw (path traversal). To read a route param in
+   * decoded form use `getRouterParams(event, { decode: true })`, which keeps
+   * encoded separators encoded.
+   *
+   * Malformed encoding (`/foo%`, `/%ZZ`) is rejected with a 400 before any
+   * handler runs, unless the `allowMalformedURL` app option is enabled.
+   *
    * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/URL)
    */
   url: URL;
