fix(resolveDotSegments): preserve trailing slash on trailing dot segments

pi0 · pi0 · commit ca7de072c8cf · 2026-07-13T21:46:33.000Z
diff --git a/docs/2.utils/4.security.md b/docs/2.utils/4.security.md
@@ -140,6 +140,6 @@ Also decodes percent-encoded dot segments at any `%25`-nesting depth (`%2e`, `%2
 
 `%2f`/`%5c` (encoded path separators) are left untouched by default — see {@link ResolveDotSegmentsOptions.decodeSlashes}.
 
-Only `.`/`..` resolution and the decodes above alter the string; every other percent-encoding (`%20`, non-ASCII, `%3A`, and any `%2e` not forming a whole segment) is left intact, so the result stays in the same representation as an un-decoded `event.url.pathname` and matches routes/rules consistently. Interior empty segments are preserved (`/a//b` stays `/a//b`, per WHATWG URL normalization) — only the leading slash is guaranteed single, so a consumer doing exact prefix matching should normalize its allowlist the same way. To collapse them instead (the reading a slash-merging downstream resolves), see {@link ResolveDotSegmentsOptions.mergeSlashes}.
+Only `.`/`..` resolution and the decodes above alter the string; every other percent-encoding (`%20`, non-ASCII, `%3A`, and any `%2e` not forming a whole segment) is left intact, so the result stays in the same representation as an un-decoded `event.url.pathname` and matches routes/rules consistently. A trailing `.`/`..` resolves to a directory and keeps its trailing slash (`/a/b/..` -> `/a/`, `/a/.` -> `/a/`), per RFC 3986 §5.2.4 and matching what a WHATWG/nginx downstream resolves — so a scope check sees the directory form, not its file-form sibling. Interior empty segments are preserved (`/a//b` stays `/a//b`) — like WHATWG, this never merges slashes, so empty segments survive rather than collapsing. The one exception is a _leading_ run: it is always clamped to a single `/` (WHATWG would keep `//host`), so only the leading slash is guaranteed single and a consumer doing exact prefix matching should normalize its allowlist the same way. To collapse interior runs too (the reading a slash-merging downstream resolves), see {@link ResolveDotSegmentsOptions.mergeSlashes}.
 
 <!-- /automd -->
diff --git a/src/utils/path.ts b/src/utils/path.ts
@@ -93,11 +93,17 @@ const ENCODED_DOT_RE_G = /%(?:25)*2e/gi;
  * percent-encoding (`%20`, non-ASCII, `%3A`, and any `%2e` not forming a whole
  * segment) is left intact, so the result stays in the same representation as an
  * un-decoded `event.url.pathname` and matches routes/rules consistently.
- * Interior empty segments are preserved (`/a//b` stays `/a//b`, per WHATWG URL
- * normalization) — only the leading slash is guaranteed single, so a consumer
- * doing exact prefix matching should normalize its allowlist the same way. To
- * collapse them instead (the reading a slash-merging downstream resolves), see
- * {@link ResolveDotSegmentsOptions.mergeSlashes}.
+ * A trailing `.`/`..` resolves to a directory and keeps its trailing slash
+ * (`/a/b/..` -> `/a/`, `/a/.` -> `/a/`), per RFC 3986 §5.2.4 and matching what a
+ * WHATWG/nginx downstream resolves — so a scope check sees the directory form,
+ * not its file-form sibling.
+ * Interior empty segments are preserved (`/a//b` stays `/a//b`) — like WHATWG,
+ * this never merges slashes, so empty segments survive rather than collapsing.
+ * The one exception is a *leading* run: it is always clamped to a single `/`
+ * (WHATWG would keep `//host`), so only the leading slash is guaranteed single
+ * and a consumer doing exact prefix matching should normalize its allowlist the
+ * same way. To collapse interior runs too (the reading a slash-merging
+ * downstream resolves), see {@link ResolveDotSegmentsOptions.mergeSlashes}.
  */
 export function resolveDotSegments(path: string, opts?: ResolveDotSegmentsOptions): string {
   // Normalize to a single leading slash (treating a leading `\` as a
@@ -137,6 +143,7 @@ export function resolveDotSegments(path: string, opts?: ResolveDotSegmentsOption
     const normalizedSegment = segment.includes("%")
       ? segment.replace(ENCODED_DOT_RE_G, ".")
       : segment;
+    const isDotSegment = normalizedSegment === "." || normalizedSegment === "..";
     if (normalizedSegment === "..") {
       // Never pop past the root (first empty segment from leading slash)
       if (resolved.length > 1) {
@@ -148,9 +155,17 @@ export function resolveDotSegments(path: string, opts?: ResolveDotSegmentsOption
       // separators a `/{2,}` -> `/` collapse would remove. Skipping them here,
       // rather than collapsing the string first, is equivalent and lets a `..`
       // that an empty segment would otherwise shield pop its real parent.
-    } else if (normalizedSegment !== ".") {
+    } else if (!isDotSegment) {
       resolved.push(segment);
     }
+    // A trailing `.`/`..` resolves to a directory, so preserve the trailing
+    // slash by leaving an empty final segment (`/a/b/..` -> `/a/`, `/a/.` ->
+    // `/a/`). This matches RFC 3986 §5.2.4 and what a WHATWG/nginx downstream
+    // resolves, so a scope check does not see the file-form sibling of a path
+    // the downstream serves the directory index of.
+    if (isDotSegment && i === lastIndex) {
+      resolved.push("");
+    }
   }
   const result = resolved.join("/") || "/";
   // Decoded/normalized separators can prepend extra empty segments; collapse
diff --git a/src/utils/static.ts b/src/utils/static.ts
@@ -106,7 +106,10 @@ export async function serveStatic(
   // reached instead of a 500. A `%`-free path (the common case) skips the
   // decode entirely, matching the fast-path guards at the event layer and in
   // `resolveDotSegments`.
-  const resolvedId = resolveDotSegments(withoutTrailingSlash(event.url.pathname));
+  // Strip the trailing slash AFTER resolving: a trailing `.`/`..` now resolves
+  // to a directory-form path (`/a/b/..` -> `/a/`), and the on-disk id must stay
+  // slash-free either way.
+  const resolvedId = withoutTrailingSlash(resolveDotSegments(event.url.pathname));
   let originalId = resolvedId;
   if (resolvedId.includes("%")) {
     try {
diff --git a/test/unit/path.test.ts b/test/unit/path.test.ts
@@ -107,13 +107,31 @@ describe("resolveDotSegments", () => {
 
   it("preserves interior empty segments by default", () => {
     expect(resolveDotSegments("/api/orders//list.json")).toBe("/api/orders//list.json");
-    // The empty segment shields the `..` from popping `a`
-    expect(resolveDotSegments("/a//..")).toBe("/a");
+    // The empty segment shields the `..` from popping `a` (it pops the empty
+    // segment instead), leaving the directory-form `/a/`.
+    expect(resolveDotSegments("/a//..")).toBe("/a/");
     expect(resolveDotSegments("/api/foo/%2e%2e/%2fadmin/secret", { decodeSlashes: true })).toBe(
       "/api//admin/secret",
     );
   });
 
+  it("preserves the trailing slash of a trailing dot segment (RFC 3986 §5.2.4)", () => {
+    // A trailing `.`/`..` resolves to a directory: `/a/b/..` -> `/a/`, not `/a`,
+    // matching what a WHATWG `URL`/nginx downstream resolves.
+    expect(resolveDotSegments("/a/b/..")).toBe("/a/");
+    expect(resolveDotSegments("/a/.")).toBe("/a/");
+    expect(resolveDotSegments("/a/b/.")).toBe("/a/b/");
+    // Encoded and nested forms resolve the same way.
+    expect(resolveDotSegments("/a/b/%2e%2e")).toBe("/a/");
+    expect(resolveDotSegments("/a/b/%252e")).toBe("/a/b/");
+    // Popping down to the root still yields a single-slash root, not `//`.
+    expect(resolveDotSegments("/a/..")).toBe("/");
+    expect(resolveDotSegments("/..")).toBe("/");
+    expect(resolveDotSegments("/a/../..")).toBe("/");
+    // Merge mode preserves it too.
+    expect(resolveDotSegments("/a/b/..", { mergeSlashes: true })).toBe("/a/");
+  });
+
   describe("mergeSlashes", () => {
     it("collapses runs of literal separators", () => {
       expect(resolveDotSegments("/api/orders//list.json", { mergeSlashes: true })).toBe(
