fix(middleware): align encoded path matching (#2802)

* fix(middleware): align encoded path matching

* test(pages): separate matcher and route identity

* fix(middleware): preserve delimiter matcher parity

* fix(middleware): preserve trailing source delimiters

* test(middleware): align trailing source expectations

* fix(middleware): align trailing slash matcher normalization

Author: james-elicx

packages/vinext/src/server/middleware-matcher.ts

@@ -4,7 +4,6 @@ import {
   type RequestContext,
 } from "../config/config-matchers.js";
 import type { NextI18nConfig } from "../config/next-config.js";
-import { removeTrailingSlash } from "../utils/base-path.js";
 import {
   compileMiddlewareMatcherPattern,
   isValidMiddlewareMatcherObjectConfig,
@@ -13,6 +12,10 @@ import {
 
 export type MatcherConfig = string | Array<string | MiddlewareMatcherObject>;
 
+export type MiddlewareLocaleMatchContext =
+  | { kind: "defaulted"; defaultLocale: string }
+  | { kind: "internal" | "literal" };
+
 const EMPTY_MIDDLEWARE_REQUEST_CONTEXT: RequestContext = {
   headers: new Headers(),
   cookies: {},
@@ -30,13 +33,14 @@ export function matchesMiddleware(
   matcher: MatcherConfig | undefined,
   request?: Request,
   i18nConfig?: NextI18nConfig | null,
+  localeContext?: MiddlewareLocaleMatchContext,
 ): boolean {
   if (!matcher) {
     return true;
   }
 
   if (typeof matcher === "string") {
-    return matchMatcherPattern(pathname, matcher, i18nConfig);
+    return matchMatcherPattern(pathname, matcher, i18nConfig, localeContext);
   }
   if (!Array.isArray(matcher)) {
     return true;
@@ -48,7 +52,7 @@ export function matchesMiddleware(
 
   for (const m of matcher) {
     if (typeof m === "string") {
-      if (matchMatcherPattern(pathname, m, i18nConfig)) {
+      if (matchMatcherPattern(pathname, m, i18nConfig, localeContext)) {
         return true;
       }
       continue;
@@ -57,7 +61,7 @@ export function matchesMiddleware(
     if (!isValidMiddlewareMatcherObjectConfig(m)) {
       return true;
     }
-    if (!matchObjectMatcher(pathname, m, i18nConfig)) {
+    if (!matchObjectMatcher(pathname, m, i18nConfig, localeContext)) {
       continue;
     }
 
@@ -75,9 +79,18 @@ function matchMatcherPattern(
   pathname: string,
   pattern: string,
   i18nConfig?: NextI18nConfig | null,
+  localeContext?: MiddlewareLocaleMatchContext,
 ): boolean {
   if (!i18nConfig) return matchPattern(pathname, pattern);
 
+  if (localeContext) {
+    if (localeContext.kind === "internal") return false;
+    return matchPattern(
+      localeContext.kind === "literal" ? stripFirstPathSegment(pathname) : pathname,
+      pattern,
+    );
+  }
+
   const localeStrippedPathname = stripLocalePrefix(pathname, i18nConfig);
   return matchPattern(localeStrippedPathname ?? pathname, pattern);
 }
@@ -86,35 +99,50 @@ function matchObjectMatcher(
   pathname: string,
   matcher: MiddlewareMatcherObject,
   i18nConfig?: NextI18nConfig | null,
+  localeContext?: MiddlewareLocaleMatchContext,
 ): boolean {
-  return matcher.locale === false
-    ? matchPattern(pathname, matcher.source)
-    : matchMatcherPattern(pathname, matcher.source, i18nConfig);
+  if (matcher.locale !== false) {
+    return matchMatcherPattern(pathname, matcher.source, i18nConfig, localeContext);
+  }
+
+  const matchPathname =
+    localeContext?.kind === "defaulted"
+      ? `/${localeContext.defaultLocale}${pathname === "/" ? "" : pathname}`
+      : pathname;
+  return matchPattern(matchPathname, matcher.source);
 }
 
 function stripLocalePrefix(pathname: string, i18nConfig: NextI18nConfig): string | null {
   if (pathname === "/") return null;
 
   const segments = pathname.split("/");
   const firstSegment = segments[1];
-  if (!firstSegment || !i18nConfig.locales.includes(firstSegment)) {
+  const lowerFirstSegment = firstSegment?.toLowerCase();
+  if (
+    !lowerFirstSegment ||
+    !i18nConfig.locales.some((locale) => locale.toLowerCase() === lowerFirstSegment)
+  ) {
     return null;
   }
 
-  return "/" + segments.slice(2).join("/");
+  return stripFirstPathSegment(pathname);
+}
+
+function stripFirstPathSegment(pathname: string): string {
+  return "/" + pathname.split("/").slice(2).join("/");
 }
 
 export function matchPattern(pathname: string, pattern: string): boolean {
-  const hasPatternSyntax = /[\\():*+?]/.test(pattern);
-  const normalizedPattern = hasPatternSyntax ? pattern : removeTrailingSlash(pattern);
-  let cached = _mwPatternCache.get(normalizedPattern);
+  if (pattern === "/" && (pathname === "//" || pathname === "/?" || pathname === "/#")) {
+    return false;
+  }
+  let cached = _mwPatternCache.get(pattern);
   if (cached === undefined) {
-    cached = compileMatcherPattern(normalizedPattern);
-    _mwPatternCache.set(normalizedPattern, cached);
+    cached = compileMatcherPattern(pattern);
+    _mwPatternCache.set(pattern, cached);
   }
   if (cached === UNSAFE_MATCHER_PATTERN) return true;
-  if (cached.test(pathname)) return true;
-  return pathname.endsWith("/") && cached.test(removeTrailingSlash(pathname));
+  return cached.test(pathname);
 }
 
 function compileMatcherPattern(pattern: string): CompiledMatcherPattern {

packages/vinext/src/server/middleware-runtime.ts

@@ -1,5 +1,6 @@
 import "./server-globals.js";
 import type { NextI18nConfig } from "../config/next-config.js";
+import { normalizeHost } from "../config/request-context.js";
 import { normalizePathnameForRouteMatchStrict } from "../routing/utils.js";
 import path from "pathslash";
 import {
@@ -14,7 +15,11 @@ import {
   MIDDLEWARE_NEXT_HEADER,
   MIDDLEWARE_REWRITE_HEADER,
 } from "./headers.js";
-import { matchesMiddleware, type MatcherConfig } from "./middleware-matcher.js";
+import {
+  matchesMiddleware,
+  type MatcherConfig,
+  type MiddlewareLocaleMatchContext,
+} from "./middleware-matcher.js";
 import { shouldKeepMiddlewareHeader } from "../utils/middleware-request-headers.js";
 import { processMiddlewareHeaders } from "./request-pipeline.js";
 import { badRequestResponse, internalServerErrorResponse } from "./http-error-responses.js";
@@ -25,6 +30,7 @@ import {
   removeTrailingSlash,
   stripBasePath,
 } from "../utils/base-path.js";
+import { normalizeDefaultLocalePathname } from "./pages-i18n.js";
 
 export type MiddlewareModule = Record<string, unknown>;
 
@@ -320,15 +326,16 @@ export async function executeMiddleware(
   if (normalizedPathname instanceof Response) {
     return { continue: false, response: normalizedPathname };
   }
+  const requestUrl = new URL(options.request.url);
+  const requestPathname = requestUrl.pathname;
 
   // Default: derive in-basePath state from the request URL. The Pages
   // prod/deploy adapters pass the original URL — prefixed for in-basePath
   // requests, bare for out-of-basePath requests — so the URL itself is the
   // source of truth. Callers that pass pre-stripped URLs (dev server, App
   // Router) override this with an explicit `hadBasePath: true`.
   const hadBasePath =
-    options.hadBasePath ??
-    (!options.basePath || hasBasePath(new URL(options.request.url).pathname, options.basePath));
+    options.hadBasePath ?? (!options.basePath || hasBasePath(requestPathname, options.basePath));
 
   // Matcher patterns use basePath-stripped paths (e.g. /about, not /root/about),
   // matching Next.js behavior where the matcher is evaluated against the path
@@ -341,15 +348,104 @@ export async function executeMiddleware(
     ? stripBasePath(normalizedPathname, options.basePath)
     : normalizedPathname;
   const matchPathname = basePathStrippedPathname;
+  // Next.js tests the normalized encoded pathname first, then retries after
+  // decoding the full path once. Testing only a segment-decoded form lets
+  // percent-encoded line terminators turn into characters that `.` cannot
+  // match, while preserving encoded delimiters misses matchers that Next.js
+  // evaluates against their decoded path structure.
+  // https://github.com/vercel/next.js/blob/canary/packages/next/src/server/next-server.ts
+  // Next.js removes the request pathname's terminal slash before evaluating
+  // the compiled middleware matcher. The matcher compiler still appends its
+  // own optional terminal delimiter, so a source without a slash matches both
+  // request spellings while a source that includes a slash remains distinct.
+  // https://github.com/vercel/next.js/blob/v16.2.6/packages/next/src/server/next-server.ts
+  const encodedRequestPathname = removeTrailingSlash(normalizePath(requestPathname));
+  const matcher = middlewareMatcher(options.module);
+  const prepareMatcherPathname = (candidate: string): string | null => {
+    if (!options.basePath) return candidate;
+    if (hasBasePath(candidate, options.basePath)) {
+      return stripBasePath(candidate, options.basePath);
+    }
+    if (
+      candidate.length === options.basePath.length + 1 &&
+      candidate.startsWith(options.basePath) &&
+      (candidate.endsWith("?") || candidate.endsWith("#"))
+    ) {
+      return "/";
+    }
+    // App Router and Pages dev may pass a URL that the adapter already
+    // stripped after recording that it crossed the configured basePath.
+    if (options.hadBasePath === true) return candidate;
+    // Next.js prefixes configured matchers with basePath at build time. Keep
+    // default middleware eligible on absolute paths, but custom matchers must
+    // not apply outside the basePath.
+    return matcher === undefined ? candidate : null;
+  };
+  const encodedMatchPathname = prepareMatcherPathname(encodedRequestPathname);
+  let decodedMatchPathname = encodedMatchPathname;
+  try {
+    if (encodedMatchPathname !== null) {
+      decodedMatchPathname = decodeURIComponent(encodedMatchPathname);
+    } else if (!options.i18nConfig) {
+      // Without i18n, Next.js can discover an encoded basePath on the decoded
+      // matcher attempt. With i18n, default-locale insertion has already made
+      // that path ineligible for the compiled basePath-prefixed matcher.
+      decodedMatchPathname = prepareMatcherPathname(decodeURIComponent(encodedRequestPathname));
+    }
+  } catch {
+    // Match Next.js: malformed encoding is non-fatal for matcher eligibility.
+  }
 
-  if (
-    !matchesMiddleware(
-      matchPathname,
-      middlewareMatcher(options.module),
+  let localeContext: MiddlewareLocaleMatchContext | undefined;
+  if (options.i18nConfig && encodedMatchPathname !== null) {
+    const hostname = normalizeHost(options.request.headers.get("host"), requestUrl.hostname);
+    const firstSegment = encodedMatchPathname.split("/", 3)[1];
+    const hasLiteralLocale =
+      firstSegment !== undefined &&
+      options.i18nConfig.locales.some(
+        (locale) => locale.toLowerCase() === firstSegment.toLowerCase(),
+      );
+    if (hasLiteralLocale) {
+      localeContext = { kind: "literal" };
+    } else {
+      const localeDefaultedPathname = normalizeDefaultLocalePathname(
+        encodedMatchPathname,
+        options.i18nConfig,
+        { hostname },
+      );
+      localeContext =
+        localeDefaultedPathname === encodedMatchPathname
+          ? { kind: "internal" }
+          : {
+              defaultLocale: normalizeDefaultLocalePathname("/", options.i18nConfig, {
+                hostname,
+              }).slice(1),
+              kind: "defaulted",
+            };
+    }
+  }
+  const encodedMatches =
+    encodedMatchPathname !== null &&
+    matchesMiddleware(
+      encodedMatchPathname,
+      matcher,
       options.request,
       options.i18nConfig,
-    )
-  ) {
+      localeContext,
+    );
+  const decodedMatches =
+    !encodedMatches &&
+    decodedMatchPathname !== null &&
+    decodedMatchPathname !== encodedMatchPathname &&
+    matchesMiddleware(
+      decodedMatchPathname,
+      matcher,
+      options.request,
+      options.i18nConfig,
+      localeContext,
+    );
+
+  if (!encodedMatches && !decodedMatches) {
     return { continue: true };
   }
 

tests/fixtures/middleware-matcher-auth/app/[locale]/admin/[page]/page.tsx

@@ -0,0 +1,3 @@
+export default function LocalizedAdminPage() {
+  return <main>protected localized admin page</main>;
+}

tests/fixtures/middleware-matcher-auth/app/billing/invoices/[[...path]]/route.ts

@@ -0,0 +1,3 @@
+export function GET() {
+  return new Response("protected invoice route handler");
+}

tests/fixtures/middleware-matcher-auth/middleware.ts

@@ -33,5 +33,24 @@ export const config = {
       ],
       missing: [{ type: "query", key: "blocked", value: "1" }],
     },
+    {
+      // Matches the negative-lookahead shape recommended in the Next.js docs.
+      // The header keeps this broad matcher isolated to the encoded-path auth
+      // regression without changing the fixture's existing public routes.
+      source: "/((?!api|_next/static|_next/image|favicon.ico).*)",
+      has: [{ type: "header", key: "x-encoded-path-auth", value: "1" }],
+    },
+    {
+      source: "/orders/:id(\\d+)",
+      has: [{ type: "header", key: "x-encoded-delimiter-auth", value: "1" }],
+    },
+    {
+      source: "/xx/admin/dash/board",
+      has: [{ type: "header", key: "x-encoded-delimiter-auth", value: "1" }],
+    },
+    {
+      source: "/billing/invoices/current/q3",
+      has: [{ type: "header", key: "x-encoded-delimiter-auth", value: "1" }],
+    },
   ],
 };

tests/fixtures/middleware-matcher-auth/pages/orders/[id].tsx

@@ -0,0 +1,3 @@
+export default function OrderPage() {
+  return <main>protected order page</main>;
+}