feat(hot): require a secret on the endpoint, with hot.token

`hot.cors` is answered by `Origin`, and that is its weakness: a browser omits
`Origin` and the whole `Sec-Fetch-*` family when the destination is not
potentially trustworthy — plain `http` to anything but `localhost`, which
`host: "0.0.0.0"` gives you. webpack-dev-server shipped two fixes built on
those headers and both were bypassed exactly that way, CVE-2026-6402 and then
CVE-2026-14620. A token asks the browser to volunteer nothing.

`createHot` mints one per run, `injectHotClient` hands it to the client as
another entry-query option, and both wires check it with `timingSafeEqual`
before anything else — so a caller without one is told nothing about which
origins the endpoint would have allowed. A transport of your own is given it
too. Driven end to end:

  SSE, token: true       no token 403   wrong 403   right 200
  WS, default            no token 403   wrong 403   right CONNECTED
  WS, token: false       no token CONNECTED

The two transports default as they did for `cors`: `true` for the WebSocket,
which is unreleased so nothing is connecting to it that would not be handed
one, and `false` for Server-Sent Events, where requiring one would refuse every
client already connecting.

Two things the implementation had to account for, both found by the browser
tests rather than by reasoning:

`inject: false` turns the requirement off. The token reaches the browser
through the entry this middleware adds, so with nothing injected there is no
way to hand one over and requiring it would refuse a correctly wired client.

The client needed the option after all. The first attempt folded the token into
the `path` query on the assumption that the client uses that verbatim — true
for an injected client, useless for a hand-wired entry, which has no `path`
parameter and would not know what a bare `token=` meant. It is a client option
like the others now, and `hot.client.token` accepts it in node for a client
pointed at another endpoint, which keeps the two name sets identical — a test
asserts that and caught the asymmetry.

What it does not protect, said in the README rather than left implied: the
client reads the token from its entry query, so it is a string in the bundle.
Anything that can already read the bundle cross-origin reads the token with it,
and over plain `http` to a non-localhost address nothing stops that unless the
server sends `Cross-Origin-Resource-Policy`. This hardens every case where the
bundle is not readable, and is defence in depth where it is.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UjuMAuk9o6UazjHzcAQCTA

Author: alexander-akait

.changeset/hot-token.md

@@ -0,0 +1,37 @@
+---
+"webpack-dev-middleware": minor
+---
+
+Added `hot.token`: a secret the injected client carries and the hot endpoint
+requires, so reaching the stream takes something a page has to have been given
+rather than a header the browser may or may not send.
+
+`hot.cors` is answered by `Origin`, and that is its weakness. A browser omits
+`Origin` and the whole `Sec-Fetch-*` family when the destination is not
+potentially trustworthy — plain `http` to anything but `localhost`, which
+`host: "0.0.0.0"` gives you. webpack-dev-server shipped two fixes built on
+those headers and both were bypassed exactly that way, CVE-2026-6402 and then
+CVE-2026-14620. A token asks the browser to volunteer nothing.
+
+Off by default on both transports, and `true` in the next major release. A
+token only reaches the browser on the entry the middleware adds, and `inject`
+being on does not mean an entry was added: it is skipped when every entry point
+already pulls the client in, when `hot.transport` is a function, and for a
+non-web target. Requiring one by default would turn each of those into a `403`
+on every client. Set `token: true` to turn it on, and if you do so where no
+client was injected the middleware warns rather than leaving you with an
+unexplained refusal.
+
+With the client injected, that is all it takes: it is handed the token and puts
+it on its connection url. `hot.inject: false` turns the requirement off — the
+token travels in the entry the middleware adds, so with nothing injected there
+is no way to hand one over. A configuration that lists the client entry itself
+is built before the middleware exists and cannot carry a minted token, so give
+it a fixed one both sides know, or read the minted one from `instance.token`.
+
+What it does not protect: the client reads the token from its entry query, so
+it is a string in the bundle. Anything that can already read the bundle
+cross-origin reads the token with it, and over plain `http` to a non-localhost
+address nothing stops that unless your server sends
+`Cross-Origin-Resource-Policy`. This hardens every case where the bundle is not
+readable, and is defence in depth in the case where it is.

.cspell.json

@@ -43,7 +43,8 @@
     "expressjs",
     "wildcarded",
     "jshttp",
-    "realpath"
+    "realpath",
+    "Rsbuild"
   ],
   "ignorePaths": [
     "CHANGELOG.md",

README.md

@@ -337,6 +337,7 @@ The object form accepts these options:
 |       **[`server`](#hotserver)**       |                            `object`                             |    `undefined`     | HTTP server the `'ws'` transport answers upgrades on.                                   |
 |     **[`progress`](#hotprogress)**     |                            `boolean`                            |      `false`       | Publish compilation progress events to the clients.                                     |
 |         **[`cors`](#hotcors)**         | `boolean \| string \| string[] \| RegExp \| function \| object` |     see below      | Which origins may reach the endpoint from a page on another one, over either transport. |
+|        **[`token`](#hottoken)**        |                       `boolean \| string`                       |     see below      | A secret the injected client carries and the endpoint requires, over either transport.  |
 |       **[`inject`](#hotinject)**       |                            `boolean`                            |       `true`       | Add the client entry and `HotModuleReplacementPlugin`.                                  |
 | **[`statsOptions`](#hotstatsoptions)** |                            `object`                             |    `undefined`     | Deprecated — do not use; see [`stats`](#stats).                                         |
 
@@ -537,6 +538,62 @@ A **function** [transport](#hottransport) of your own is handed the option as it
 >
 > This is about who may reach the endpoint, and nothing else. It does not decide who may reach the **assets** the middleware serves, which is your server's to answer — with a `Cross-Origin-Resource-Policy` response header, or with whatever your framework's own CORS middleware does.
 
+#### `hot.token`
+
+Type: `Boolean | String`
+Default: `false`
+
+A secret the injected client carries and the endpoint requires. Reaching the stream then takes something a page has to have been **given**, rather than a header a browser may or may not send.
+
+[`cors`](#hotcors) is answered by `Origin`, and that is the weakness: a browser omits `Origin` and the whole `Sec-Fetch-*` family when the destination is not [potentially trustworthy](https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy) — plain `http` to anything but `localhost`, which is what `host: '0.0.0.0'` gives you. webpack-dev-server shipped two fixes built on those headers and both were bypassed exactly that way ([CVE-2026-6402](https://github.com/advisories/GHSA-79cf-xcqc-c78w), then [CVE-2026-14620](https://github.com/advisories/GHSA-f5vj-f2hx-8m93)). A token asks the browser to volunteer nothing.
+
+**Off by default, on both transports**, and `true` in the next major release. A token only reaches the browser on the entry this middleware adds, and `inject` being on does not mean an entry was added — it is skipped when every entry point already pulls the client in, when [`hot.transport`](#hottransport) is a function, and for a non-web target. Requiring one by default would turn each of those into a `403` on every client.
+
+Turn it on, which is all the normal setup needs — the client is injected, so it is handed the token and uses it:
+
+```js
+app.use(middleware(compiler, { hot: { token: true } }));
+```
+
+If you turn it on where no client was injected, the middleware says so rather than leaving you with an unexplained `403`:
+
+```
+[webpack-dev-middleware] 'hot.token' requires a token on the endpoint, but no
+client entry was added to hand one over, so every client will be refused.
+```
+
+> [!IMPORTANT]
+>
+> **What a token does not protect.** The client reads it from its entry query, so it is a string in the bundle. Anything that can already read your bundle cross-origin can read the token out of it — and over plain `http` to a non-`localhost` address, nothing stops that unless your server sends `Cross-Origin-Resource-Policy`. The token hardens every case where the bundle is not readable; where it is, your source has already gone and the stream is the smaller loss. Closing that needs the response header and a `Host` allowlist, which are [your server's](#security) to set.
+
+**Wiring the client yourself.** The token travels in the entry this middleware adds, so `hot.inject: false` turns the requirement off — there would be no way to hand one over, and requiring it would refuse a client you wired correctly.
+
+A configuration that already lists the client as an entry is the other half of that: it is built before the middleware exists, so it cannot carry a token minted per run. Give it one of your own instead, which both sides can know in advance:
+
+```js
+const token = "a-secret-of-my-own";
+
+// webpack.config.js
+entry: [`webpack-dev-middleware/client?token=${token}`, "./src/index.js"];
+
+// and the middleware
+app.use(middleware(compiler, { hot: { transport: "ws", token } }));
+```
+
+Or read the minted one off the instance, for a client you serve yourself:
+
+```js
+const instance = middleware(compiler, {
+  hot: { transport: "ws", token: true },
+});
+
+app.get("/my-client-config.json", (_req, res) => {
+  res.json({ token: instance.token });
+});
+```
+
+`false` requires none, which is the default.
+
 #### `hot.inject`
 
 Type: `Boolean`

client-src/index.js

@@ -14,6 +14,7 @@ import { log, setLogLevel } from "./utils/log.js";
 import reloadPage from "./utils/reload.js";
 import sendMessage from "./utils/send-message.js";
 import stripAnsi from "./utils/strip-ansi.js";
+import withToken from "./utils/with-token.js";
 
 /** @typedef {import("./utils/log.js").LogLevel} LogLevel */
 
@@ -45,6 +46,7 @@ import stripAnsi from "./utils/strip-ansi.js";
  * @property {string} urlPrefix prefix of the page-url parameters that turn `hot` and `liveReload` off for one page
  * @property {LogLevel} logging logger level
  * @property {string} name limit updates to this compilation name
+ * @property {string} token the secret the endpoint requires, when it requires one, put on the connection url — empty when it requires none
  * @property {boolean} autoConnect connect immediately when the entry runs
  * @property {number=} reconnect how many times to reconnect before giving up, unset to use the transport's default
  * @property {boolean | "circular" | "linear"} progress show an indicator while a rebuild is in progress — `true` and `"circular"` a small badge, `"linear"` a thin bar across the top of the viewport
@@ -62,6 +64,10 @@ const options = {
   urlPrefix: "webpack-dev-middleware",
   logging: "info",
   name: "",
+  // The secret the endpoint requires, when it requires one. Put on the url
+  // rather than sent as a header: neither `EventSource` nor `WebSocket` lets a
+  // page set one.
+  token: "",
   autoConnect: true,
   progress: true,
 };
@@ -172,6 +178,7 @@ function setOverrides(overrides) {
   // Where the page connects, which may be an absolute url rather than a path
   // when the endpoint is on another origin.
   if (overrides.path) options.path = overrides.path;
+  if (overrides.token) options.token = overrides.token;
   if (overrides.timeout) {
     const timeout = Number(overrides.timeout);
 
@@ -274,19 +281,23 @@ function getClient() {
 function createClientSocket() {
   const isEventSource = options.transport !== "ws";
 
-  return createSocket(getClient(), /** @type {string} */ (options.path), {
-    clientOptions: { timeout: options.timeout },
-    // Server-Sent Events are retried for as long as the page is open, at the
-    // steady interval its watchdog already uses: a dev server is expected to
-    // come back, and a tab left open over a restart has to find it again.
-    retries: isEventSource ? Infinity : options.reconnect,
-    retryDelay: isEventSource
-      ? () => /** @type {number} */ (options.timeout)
-      : undefined,
-    onDisconnect: () => {
-      sendMessage("Close");
+  return createSocket(
+    getClient(),
+    withToken(/** @type {string} */ (options.path), options.token),
+    {
+      clientOptions: { timeout: options.timeout },
+      // Server-Sent Events are retried for as long as the page is open, at the
+      // steady interval its watchdog already uses: a dev server is expected to
+      // come back, and a tab left open over a restart has to find it again.
+      retries: isEventSource ? Infinity : options.reconnect,
+      retryDelay: isEventSource
+        ? () => /** @type {number} */ (options.timeout)
+        : undefined,
+      onDisconnect: () => {
+        sendMessage("Close");
+      },
     },
-  });
+  );
 }
 
 const WRAPPER_KEY = "__wdmEventSourceWrapper";

client-src/utils/with-token.js

@@ -0,0 +1,35 @@
+/**
+ * Put the token on an endpoint url.
+ *
+ * On the url because neither `EventSource` nor `WebSocket` lets a page set a
+ * request header, so there is nowhere else to put it.
+ *
+ * Set rather than appended: a path that already carries a `token` would end up
+ * with two, and the endpoint reads the first — so the one passed here would be
+ * the one ignored. Taken apart by hand rather than through `URL`, which would
+ * need a base and would turn a relative path into an absolute one; this keeps
+ * whatever shape it was given, absolute url, rooted path or relative.
+ * @param {string} path the endpoint, which may already carry a query, a fragment, or both
+ * @param {string | undefined} token the token, when the endpoint requires one
+ * @returns {string} the endpoint to connect to
+ */
+export default function withToken(path, token) {
+  if (!token) {
+    return path;
+  }
+
+  const hashAt = path.indexOf("#");
+  const hash = hashAt === -1 ? "" : path.slice(hashAt);
+  const withoutHash = hashAt === -1 ? path : path.slice(0, hashAt);
+  const queryAt = withoutHash.indexOf("?");
+  const before = queryAt === -1 ? withoutHash : withoutHash.slice(0, queryAt);
+  const query = new URLSearchParams(
+    queryAt === -1 ? "" : withoutHash.slice(queryAt + 1),
+  );
+
+  query.set("token", token);
+
+  // Before the fragment, where a query belongs — appending would have put the
+  // token inside it.
+  return `${before}?${query}${hash}`;
+}

src/hot.js

@@ -51,6 +51,7 @@
  * @property {StatsOptions=} statsOptions deprecated, removed in the next major release — webpack stats options used when serializing compilation results
  * @property {boolean=} progress publish compilation progress events to the clients
  * @property {CorsOption=} cors which origins may reach the endpoint from a page on another one; the local ones by default
+ * @property {(boolean | string)=} token a secret the injected client carries and the endpoint requires; `true` mints one per run, a string uses that one, `false` requires none. Defaults to `false` on both transports; `true` in the next major release
  * @property {boolean=} inject add the hot client entry and `HotModuleReplacementPlugin` to the compilation (default `true`); turn it off to wire them yourself
  * @property {HotClientOptions=} client options handed to the browser runtime through its entry query
  */
@@ -128,7 +129,7 @@
  * built-in two are made of whatever this returns.
  * @template {EXPECTED_ANY} [TClient=StreamClient]
  * @callback ClientStreamFactory
- * @param {{ path: string, heartbeat: number, cors: CorsOption | undefined }} options the endpoint's path and heartbeat interval, and the origins it is meant to allow
+ * @param {{ path: string, heartbeat: number, cors: CorsOption | undefined, token: string | false }} options the endpoint's path and heartbeat interval, the origins it is meant to allow, and the token it should require
  * @param {Logger} logger logger
  * @returns {ClientStream<TClient>} client stream
  */
@@ -141,7 +142,13 @@
 // module paths and source frames a failed build reports. Both transports
 // honour it now, each the only way it can be honoured on that wire: the event
 // stream withholds the grant, and an upgrade is refused.
-const { HOT_DEFAULT_CORS_SSE, applyCors, resolveCors } = require("./utils.js");
+const {
+  HOT_DEFAULT_CORS_SSE,
+  applyCors,
+  isTokenValid,
+  resolveCors,
+  resolveToken,
+} = require("./utils.js");
 
 const HOT_DEFAULT_PATH = "/__webpack_hmr";
 const HOT_DEFAULT_HEARTBEAT = 10 * 1000;
@@ -241,9 +248,10 @@ function checkClientStream(stream) {
  * @param {number} heartbeat heartbeat interval in milliseconds
  * @param {Logger} logger logger
  * @param {CorsOption=} cors which origins may read the stream, the local ones by default
+ * @param {(string | false)=} token the token the endpoint requires, or false for none
  * @returns {EventStream} event stream
  */
-function createEventStream(heartbeat, logger, cors) {
+function createEventStream(heartbeat, logger, cors, token = false) {
   const corsGrant = resolveCors(cors ?? HOT_DEFAULT_CORS_SSE);
   let clientId = 0;
   /** @type {Map<number, ServerResponse>} */
@@ -317,6 +325,17 @@ function createEventStream(heartbeat, logger, cors) {
         return;
       }
 
+      // Before the stream, and without the CORS grant: a caller that does not
+      // carry the token is told nothing about who may read this endpoint.
+      if (!isTokenValid(token, req)) {
+        logger.warn(
+          `A request to "${req.url}" was refused: it carried no valid 'token'. The injected client is given one; a client of your own has to pass it, or set 'hot.token' to a value it can use.`,
+        );
+        res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+        res.end("Forbidden");
+        return;
+      }
+
       /** @type {Record<string, string>} */
       const headers = {
         "Content-Type": "text/event-stream;charset=utf-8",
@@ -601,6 +620,7 @@ function publishBundles(bundles, previousBundles, eventStream) {
  * @typedef {object} HotInstance
  * @property {string} path path the endpoint is served at
  * @property {("sse" | "ws" | ClientStreamFactory<EXPECTED_ANY>)} transport how events reach the clients
+ * @property {string | false} token the secret the endpoint requires, or false when it requires none; the injected client is given it
  * @property {(server: HttpServer) => void} attach answer WebSocket upgrades on this server, a no-op for Server-Sent Events
  * @property {(req: IncomingMessage, socket: Duplex, head: Buffer) => boolean} handleUpgrade answer one WebSocket upgrade, for a caller that owns the server's `upgrade` event and wants to decide each one; returns false when the request is not the endpoint's, or the transport does not answer upgrades
  * @property {(fn: (client: EXPECTED_ANY, req: IncomingMessage) => void) => void} onConnect called with each client once it has joined, and the request it joined with, before anything is published to it
@@ -622,6 +642,13 @@ function createHot(compiler, userOptions, statsOption) {
   const transport = options.transport || HOT_DEFAULT_TRANSPORT;
   const { cors } = options;
   const { statsOptions } = options;
+  // `inject: false` turns it off: the token reaches the browser through the
+  // entry this middleware adds, so with nothing injected there is no way to
+  // hand one over, and requiring it would refuse a client the developer wired
+  // correctly. Off by default either way — see `HOT_DEFAULT_TOKEN`.
+  const token = resolveToken(
+    options.inject === false ? (options.token ?? false) : options.token,
+  );
   const logger = compiler.getInfrastructureLogger("webpack-dev-middleware");
 
   // TODO in the next major release remove `statsOptions` and this warning
@@ -638,7 +665,7 @@ function createHot(compiler, userOptions, statsOption) {
 
   if (typeof transport === "function") {
     eventStream = checkClientStream(
-      transport({ heartbeat, path, cors }, logger),
+      transport({ heartbeat, path, cors, token }, logger),
     );
     transportName = "a custom transport";
   } else if (transport === "ws") {
@@ -648,10 +675,13 @@ function createHot(compiler, userOptions, statsOption) {
 
     const createWebSocketStream = require("./servers/WebSocketServer.js");
 
-    eventStream = createWebSocketStream({ heartbeat, path, cors }, logger);
+    eventStream = createWebSocketStream(
+      { heartbeat, path, cors, token },
+      logger,
+    );
     transportName = "a WebSocket";
   } else {
-    eventStream = createEventStream(heartbeat, logger, cors);
+    eventStream = createEventStream(heartbeat, logger, cors, token);
     transportName = "Server-Sent Events";
   }
 
@@ -778,6 +808,7 @@ function createHot(compiler, userOptions, statsOption) {
   return {
     path,
     transport,
+    token,
     attach(server) {
       if (closed || !eventStream.attach) {
         return;