Update middleware combination example to prevent unintended backend execution (#2076)

Author: tusharpandey13

EXAMPLES.md

@@ -786,6 +786,13 @@ By default, the middleware does not protect any pages. It is used to mount the a
 
 You can combine multiple middleware, like so:
 
+> [!WARNING]
+> **Handling `x-middleware-next` Header**
+> The `auth0.middleware` response (`authResponse`) might contain an `x-middleware-next` header. This header signals to Next.js that the request should be forwarded to the backend application, regardless of the status code of the response you construct.
+>
+> When combining middleware, **do not** copy the `x-middleware-next` header from `authResponse` to your final response if your custom middleware intends to block the request (e.g., by returning a `NextResponse.json` with a 401 status, or a `NextResponse.redirect`). Copying this header in such cases will cause Next.js to still execute the backend route handler despite your middleware attempting to block access. Only copy headers that are necessary, like `set-cookie`.
+
+
 ```ts
 export async function middleware(request: NextRequest) {
   const authResponse = await auth0.middleware(request)
@@ -797,9 +804,14 @@ export async function middleware(request: NextRequest) {
 
   // call any other middleware here
   const someOtherResponse = await someOtherMiddleware(request)
+  const shouldProceed = someOtherResponse.headers.get('x-middleware-next');
 
   // add any headers from the auth middleware to the response
   for (const [key, value] of authResponse.headers) {
+    // Only copy 'x-middleware-next' if the custom middleware response intends to proceed.
+    if (key.toLowerCase() === 'x-middleware-next' && !shouldProceed) {
+      continue; // Skip copying this header if we are blocking/redirecting
+    }
     someOtherResponse.headers.set(key, value)
   }
 

examples/with-next-intl/middleware.ts

@@ -17,9 +17,25 @@ export async function middleware(request: NextRequest) {
   // call any other middleware here
   const intlRes = intlMiddleware(request)
 
-  // add any headers from auth to the response
+  // Combine headers from authResponse (from auth0.middleware) and intlRes (from intlMiddleware).
+  // If authResponse contains 'x-middleware-next' (signaling Next.js to proceed to the page),
+  // but intlRes is a response that should terminate the request chain (like a redirect or an error),
+  // we must NOT copy 'x-middleware-next' from authResponse. Doing so would override
+  // intlRes's decision to stop the request.
   for (const [key, value] of authResponse.headers) {
-    intlRes.headers.set(key, value)
+    if (key.toLowerCase() === 'x-middleware-next') {
+      // Check if intlRes is a redirect (3xx status code) or an error (4xx, 5xx status code).
+      const isIntlResponseTerminating = intlRes.status >= 300;
+      if (isIntlResponseTerminating) {
+        // If intlRes is already redirecting or returning an error,
+        // do not copy 'x-middleware-next' from authResponse.
+        // This allows intlRes's redirect/error to take effect.
+        continue;
+      }
+    }
+    // For all other headers, or if 'x-middleware-next' can be safely copied,
+    // set them on intlRes. This ensures session cookies from authResponse are preserved.
+    intlRes.headers.set(key, value);
   }
 
   return intlRes