Case study: the middleware bypass

One header that skipped the check

In March 2025, many Next.js apps guarded their private pages the way the tea shop guards /stock: a middleware.ts that sends visitors without a session cookie to /sign-in. (Since Next.js 16 the same file is proxy.ts.) On March 21, 2025, a security advisory, CVE-2025-29927, said that anyone could skip that file entirely. No cookie, no password: one extra header in the request.

1GET /stock HTTP/1.12Host: tea-shop.example3x-middleware-subrequest: middleware:middleware:middleware:middleware:middleware

Line 1 asks for the staff page, and line 2 names the shop. Line 3 is the whole attack: a header called x-middleware-subrequest, whose value is the word middleware five times. On an affected Next.js, served with next start, middleware didn't run for this request, so its redirect never happened, and the page answered as if the visitor were signed in.

No recording here installs an affected Next.js: the code from before the fix is quoted from its release instead. What can be recorded is today's behavior. Here is the shop's staff page in Next.js 16.4.3, with the same check in proxy.ts, asked for with the same header:

1import { NextResponse, type NextRequest } from "next/server";2 3export function proxy(request: NextRequest) {4  if (!request.cookies.has("session")) {5    return NextResponse.redirect(new URL("/sign-in", request.url));6  }7  return NextResponse.next();8}9 10export const config = { matcher: "/stock/:path*" };

/sign-in

Line 4 of proxy.ts checks for a cookie named session, and line 5 redirects without one. Line 10's matcher covers /stock and everything under it. The Network tab opens on the request with the 2025 header: 307, location: /sign-in, the same answer as without it. The third request sends the trick with proxy's name instead, proxy:proxy:proxy:proxy:proxy: 307 again. proxy.ts ran every time.

Why Next.js trusted the header

Middleware can call fetch, and it can fetch a page of its own app. That request comes back through the server, and middleware runs for it too. If that run fetches again, the app calls itself forever. So Next.js marked the requests middleware made: each one carried x-middleware-subrequest, a list of the middleware names that had already run, joined by colons. When the list got long enough, Next.js stopped running middleware for that request.

Here is the check, from lines 94 to 114 of sandbox.ts in Next.js 15.2.2, the last 15.2 release before the fix. Its line 1 is line 94 of the file:

1export const run = withTaggedErrors(async function runWithTaggedErrors(params) {2  const runtime = await getRuntimeContext(params)3  const subreq = params.request.headers[`x-middleware-subrequest`]4  const subrequests = typeof subreq === 'string' ? subreq.split(':') : []5 6  const MAX_RECURSION_DEPTH = 57  const depth = subrequests.reduce(8    (acc, curr) => (curr === params.name ? acc + 1 : acc),9    010  )11 12  if (depth >= MAX_RECURSION_DEPTH) {13    return {14      waitUntil: Promise.resolve(),15      response: new runtime.context.Response(null, {16        headers: {17          'x-middleware-next': '1',18        },19      }),20    }21  }

In plain words, line by line:

1. Line 3 reads the header from the incoming request. Nothing checks who added it: Next.js itself, or a visitor.
2. Line 4 splits it at each colon: middleware:middleware becomes two names.
3. Line 6 sets the limit to 5. Lines 7 to 10 count how many of the names are this middleware's name, params.name, which is middleware for a middleware.ts at the project's root.
4. Line 12: when the count reaches 5, lines 13 to 20 return an answer without running middleware at all. Its header, x-middleware-next: 1, means "carry on to the route", the same as NextResponse.next().

So middleware:middleware:middleware:middleware:middleware counts 5, and middleware is skipped. In Next.js 12, the check was simpler: lines 73 to 84 of sandbox.ts at v12.3.4 skipped middleware if the name appeared even once.

The mistake wasn't the loop protection. It was believing a header that the outside world can send. Headers are text the browser, or any program, writes; a request can carry any header with any value.

Who was affected

The advisory, GHSA-f82v-jwr5-mffw, lists the affected versions in ranges, one per release line. Each row gives the first affected version and the first version with the fix; everything from the first up to, but not including, the second was open.

Next.js's own advisory starts the first range at 11.1.4, and gives 11.x no fix, only the workaround below. GitHub's advisory database, the one npm audit reads, starts that range at 12.0.0. When two copies of an advisory disagree, go by the stricter one.

The version wasn't enough. Where the app ran mattered too. Each row is one way to run a Next.js app:

These come from Vercel's postmortem, published on March 25, 2025: a report, after the fact, of what happened and when. It also explains why the bug sat for a while. The first report, on February 27, was about 12.x, so it got a low priority; it reached the Next.js team on March 14, and 14.2.25 and 15.2.3 shipped on March 17 and 18.

And an app was only open if middleware was where it made a security decision. Skipping a middleware that only rewrote addresses or added a header did no harm of that kind. Sort these apps:

The fix and the upgrade

The fix shipped in 15.2.3 on March 18, 2025, in commit 52a078d. When the server starts, it now makes a random id, and the requests middleware makes carry it in a second header, x-middleware-subrequest-id. This function, from lines 53 to 72 of server-ipc/utils.ts at that commit, runs on every request that comes in:

1export const filterInternalHeaders = (2  headers: Record<string, undefined | string | string[]>3) => {4  for (const header in headers) {5    if (INTERNAL_HEADERS.includes(header)) {6      delete headers[header]7    }8 9    // If this request didn't origin from this session we filter10    // out the "x-middleware-subrequest" header so we don't skip11    // middleware incorrectly12    if (13      header === 'x-middleware-subrequest' &&14      headers['x-middleware-subrequest-id'] !==15        (globalThis as any)[Symbol.for('@next/middleware-subrequest-id')]16    ) {17      delete headers['x-middleware-subrequest']18    }19  }20}

Lines 5 to 7 were already there: they delete headers from a list that only Next.js may set. Lines 9 to 18 are new. Lines 12 to 16 ask whether the request has x-middleware-subrequest without this server's id, and if so, line 17 deletes the header. A visitor can't know the id, which is new every time the server starts, so their header is gone before the check in sandbox.ts reads it.

Six days later, 15.2.4 (with 14.2.26) went further, in commit 3da7082: it removed the header's handling altogether, because middleware on the Node.js runtime had never had it. Nothing in Next.js 16.4.3 reads the header. Pick each file name and read the Network tab:

1import { NextResponse, type NextRequest } from "next/server";2 3export function proxy(request: NextRequest) {4  if (!request.cookies.has("session")) {5    return NextResponse.redirect(new URL("/sign-in", request.url));6  }7  return NextResponse.next();8}9 10export const config = { matcher: "/stock/:path*" };

/sign-in

Both answer 307 with the header. The old name, middleware.ts, still runs on the Edge runtime in Next.js 16.4.3, where the 2025 check lived, and its build warns that the name is deprecated.

To fix an affected app, find the version it runs, then upgrade to at least the fixed release of its line: 12.3.5, 13.5.9, 14.2.25 or 15.2.3. No 11.x release has the fix, so an 11.x app must move to a patched, supported major version, and until it can, strip the header in the server in front of Next.js, as shown below. For an app on 15.x:

npm ls next
npm install next@15

Line 1 prints the next your lockfile installed. Line 2 moves to the newest 15.x, which holds this fix, at least 15.2.3, and every fix after it. On an older major, the newest release of that major has at least its line's fix, but 13.x and 14.x get no fixes any more, so plan the move to 15.x or 16.x. The previous lesson covers the lockfile and npm ci. If you can't upgrade today, the advisory's workaround is to stop the header before it reaches Next.js. With nginx, a common server in front of next start, that is one line:

1location / {2  proxy_set_header x-middleware-subrequest "";3  proxy_pass http://127.0.0.1:3000;4}

Line 2 sets the header to an empty value, and nginx doesn't send a header whose value is empty, so Next.js never sees it. Line 3 sends the rest of the request on to next start.

Defense in depth: a second check next to the data

Some apps on affected versions lost nothing, because middleware wasn't their only check. Keeping more than one layer, so that one failing doesn't open everything, is called defense in depth. Next.js's docs describe the two layers: a quick optimistic check in proxy.ts, which only looks at the cookie, and a real check next to the data, in the functions that read it.

The header can't skip proxy.ts in Next.js 16.4.3, but the shop's proxy.ts can still be passed: it only checks that a cookie named session exists. Each version below got four requests: none, the 2025 header, a made-up cookie, and Asha's real one. The Network tab opens on the made-up cookie:

1import { Suspense } from "react";2import { allStock } from "../../lib/db";3 4// proxy.ts already checked the session, so read the stock directly.5async function StockList() {6  const stock = await allStock();7  return (8    <ul>9      {stock.map((row) => (10        <li key={row.tea}>11          {row.tea}: {row.boxes} boxes12        </li>13      ))}14    </ul>15  );16}17 18export default function StockPage() {19  return (20    <main>21      <h1>Stock</h1>22      <Suspense fallback={<p>Loading…</p>}>23        <StockList />24      </Suspense>25    </main>26  );27}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/1j_b1xq_woyiy.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <!--&-->
    <main>
      <h1>Stock</h1>
      <!--$-->
      <ul>
        <li>Green tea<!-- -->: <!-- -->12<!-- --> boxes</li>
        <li>Mint tea<!-- -->: <!-- -->4<!-- --> boxes</li>
      </ul>
      <!--/$-->
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

The page that trusts proxy.ts reads allStock() directly, on line 6, and gave the made-up cookie every tea. Worse, the build prerendered it (○ /stock) with Cache-Control: s-maxage=31536000, so a shared cache in front of the app could keep the staff page for a year and hand it to anyone. The page that checks calls getStock() on line 5, which verifies the cookie's signature itself, with the same readSession as in proxy.ts, and answered Only staff can see the stock. Asha's real cookie still got the list.

1import "server-only";2import { cookies } from "next/headers";3import { readSession } from "./session";4import { allStock } from "./db";5 6export async function getStock() {7  const session = readSession((await cookies()).get("session")?.value);8  if (!session) return null;9  return allStock();10}11 

Line 7 reads the session from the cookie with readSession, which checks the signature. Line 8 returns nothing without a valid one. Every page, Route Handler and Server Action that reads the stock goes through here, so a skipped proxy.ts, a matcher that misses a path, or a forged cookie all end at the same null.

Reading a security advisory

A security advisory is a public warning: this package, these versions, this flaw, this fix. GitHub keeps them in its advisory database, each with a GHSA id; many also get a CVE id, from a shared list of known flaws. Each row is one part of GHSA-f82v-jwr5-mffw:

The severity comes from CVSS, a shared way to score flaws from 0 to 10. 9.1 is critical. The advisory also gives the score's reasons as a short code, its vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:N. Each row is one part of it:

You don't have to read advisories one by one. npm audit compares your lockfile with the advisory database. This is what it printed on October 30, 2026 for a project whose lockfile pins next@15.2.2:

1$ npm audit2# npm audit report3 4next  9.3.4-canary.0 - 16.3.0-preview.105Severity: critical6…7Authorization Bypass in Next.js Middleware - https://github.com/advisories/GHSA-f82v-jwr5-mffw8…9Next.js has a Middleware / Proxy bypass in App Router applications via segment-prefetch routes - https://github.com/advisories/GHSA-267c-6grr-h53f10…11fix available via `npm audit fix --force`12Will install next@15.5.28, which is outside the stated dependency range13node_modules/next

Line 4 names the package and the versions that have at least one of its advisories; line 5 gives the worst severity among them. Line 7 is the 2025 advisory, and line 9 the 2026 one; the full list for 15.2.2 is much longer, because many fixes came after it. Line 11 offers a fix, and line 12 warns that it's outside the stated dependency range: the project pins exactly 15.2.2, so the fix changes package.json. Read the release notes before you let --force do that.

And to hear about the next one before anyone uses it:

• Dependabot alerts. GitHub can watch your repository's lockfile and tell you when an advisory matches a version in it, and open a pull request with the upgrade.
• Watch the package. On a package's GitHub repository, Watch, then Custom, then Security alerts sends you its advisories as they're published.
• Stay on a supported version. Next.js's support policy says which major versions still get security fixes: on October 30, 2026, 16.x and, until January 31, 2027, 15.x.

Checking the tea shop after an advisory

When an advisory names a package you use, work through the same steps every time. Type a version into the playground to try the first two:

1. Find your version. npm ls next prints the one installed from your lockfile, not the range in package.json.
2. Compare it with the ranges. In range means open. Outside every range, check that you're on a line the advisory covers at all.
3. Check your setup. The hosting, and whether the affected feature makes a security decision in your app.
4. Upgrade, or use the workaround today. At least your line's fixed release, better the newest release of a supported major, deployed with your lockfile. If your line has no fixed release, like 11.x, move to a supported major, and strip the header in front of Next.js until you have.
5. Prove it. Send the attack yourself, as the recordings here sent the header, and check that the answer changed.
6. Ask what else would have stopped it. A check next to the data turns the next flaw like this into a non-event.

Common mix-ups

• "Next.js 16 still has the bug, because proxy.ts is the same file." No. The recorded 16.4.3 answered 307 to the header for proxy.ts and for middleware.ts.
• "Every Next.js app was open." No. Only affected versions on their own server, whose only check was in middleware. Vercel, Netlify, Cloudflare Workers and static exports were not.
• "The fix was to block the header." No. 15.2.3 dropped it unless it carried the server's secret id, and 15.2.4 stopped reading it altogether.
• "A check in proxy.ts is enough once you've upgraded." No. A made-up cookie passed the shop's optimistic check, and a 2026 advisory found another way past proxy. Check next to the data.
• "Critical means someone already attacked me." No. Severity says how bad it would be; whether you're exposed depends on your version, your hosting and where your checks are.
• "npm audit fix --force is always safe." No. It can move outside your version range, which may be a bigger upgrade than you meant.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

export const run = withTaggedErrors(async function runWithTaggedErrors(params) {
  const runtime = await getRuntimeContext(params)
  const subreq = params.request.headers[`x-middleware-subrequest`]
  const subrequests = typeof subreq === 'string' ? subreq.split(':') : []

  const MAX_RECURSION_DEPTH = 5
  const depth = subrequests.reduce(
    (acc, curr) => (curr === params.name ? acc + 1 : acc),
    0
  )

  if (depth >= MAX_RECURSION_DEPTH) {
    return {
      waitUntil: Promise.resolve(),
      response: new runtime.context.Response(null, {
        headers: {
          'x-middleware-next': '1',
        },
      }),
    }
  }

import { NextResponse, type NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  if (!request.cookies.has("session")) {
    return NextResponse.redirect(new URL("/sign-in", request.url));
  }
  return NextResponse.next();
}

export const config = { matcher: "/stock/:path*" };

import { Suspense } from "react";
import { allStock } from "../../lib/db";

// proxy.ts already checked the session, so read the stock directly.
async function StockList() {
  const stock = await allStock();
  return (
    <ul>
      {stock.map((row) => (
        <li key={row.tea}>
          {row.tea}: {row.boxes} boxes
        </li>
      ))}
    </ul>
  );
}

export default function StockPage() {
  return (
    <main>
      <h1>Stock</h1>
      <Suspense fallback={<p>Loading…</p>}>
        <StockList />
      </Suspense>
    </main>
  );
}

import { Suspense } from "react";
import { getStock } from "../../lib/stock";

async function StockList() {
  const stock = await getStock();
  if (!stock) return <p>Only staff can see the stock.</p>;
  return (
    <ul>
      {stock.map((row) => (
        <li key={row.tea}>
          {row.tea}: {row.boxes} boxes
        </li>
      ))}
    </ul>
  );
}

export default function StockPage() {
  return (
    <main>
      <h1>Stock</h1>
      <Suspense fallback={<p>Checking your session…</p>}>
        <StockList />
      </Suspense>
    </main>
  );
}

Check your understanding

For each question, ask who could send the header, what Next.js did with it, and which check was left.

Key takeaways

• Next.js marked middleware's own requests with x-middleware-subrequest, and skipped middleware when the header said so. Nothing checked that Next.js had added it.
• Affected: 11.1.4 up to 15.2.2, in ranges per line, on your own server. Fixed in 15.2.3, 14.2.25, 13.5.9 and 12.3.5, and in no 11.x release; Vercel, Netlify, Cloudflare Workers and static exports were never open.
• 15.2.3 dropped the header unless it carried the server's random id; 15.2.4 stopped reading it. Next.js 16.4.3 answers it with the proxy's own redirect.
• A header is text anyone can write. Never let one decide who gets in.
• Keep proxy.ts as a quick first check, and check again next to the data, where every way in passes.
• Read advisories by range, patched version, severity and workaround; let npm audit and Dependabot do the watching.

Coming next: MDX content, the first lesson on content, background work and AI. It writes pages in Markdown with React components inside.