up

Author: pi0

docs/1.guide/7.proxy.md

@@ -30,6 +30,34 @@ Every incoming peer opens a matching upstream connection. Text and binary messag
 > [!TIP]
 > Messages sent by the client before the upstream connection is ready are buffered and flushed as soon as the upstream is open.
 
+> [!CAUTION]
+> **The default proxy is an open relay.** It accepts every incoming connection and forwards it to the configured upstream without any authorization check. Always combine it with an [`upgrade` hook](#authentication) when the upstream is not itself publicly accessible — otherwise anyone who can reach the proxy can reach the upstream.
+
+## Authentication
+
+`createWebSocketProxy()` returns a plain hooks object, so you can spread it and override individual hooks. Authenticate the upgrade request before proxying by wrapping the proxy's `upgrade` hook:
+
+```ts
+import { createWebSocketProxy } from "crossws";
+
+const proxyHooks = createWebSocketProxy("wss://backend.example.com");
+
+const hooks = {
+  ...proxyHooks,
+  async upgrade(req) {
+    const token = req.headers.get("authorization");
+    if (!(await isValidToken(token))) {
+      return new Response("Unauthorized", { status: 401 });
+    }
+    // Delegate to the proxy's own `upgrade` so subprotocol echoing still works.
+    return proxyHooks.upgrade?.(req);
+  },
+};
+```
+
+> [!NOTE]
+> The WHATWG `WebSocket` constructor cannot forward cookies, `Authorization`, or `Origin` to the upstream, so upstream identity checks relying on those headers will silently fail. Authenticate at the proxy, or pass a custom `WebSocket` client and use the [`headers` option](#forwarding-headers) to propagate identity.
+
 ## Dynamic target
 
 Pass a function to resolve the upstream URL from the incoming [`Peer`](/guide/peer) — useful for routing based on request URL, headers, or authenticated context.
@@ -47,6 +75,9 @@ const hooks = createWebSocketProxy({
 });
 ```
 
+> [!WARNING]
+> **SSRF risk.** A dynamic `target` resolver is a trust boundary. Never interpolate untrusted input (query strings, headers, path segments a client controls) directly into the returned URL — a naive resolver turns the proxy into an SSRF primitive that can dial `ws://127.0.0.1`, `ws://169.254.169.254`, or any reachable internal service. Always resolve against a hard-coded allowlist of hosts you control.
+
 ## Subprotocol negotiation
 
 By default, the proxy forwards the client's `sec-websocket-protocol` header to the upstream and echoes the first requested subprotocol back in the upgrade response so the client handshake succeeds. Disable this if you want to negotiate subprotocols yourself:
@@ -75,35 +106,51 @@ const hooks = createWebSocketProxy({
 });
 ```
 
-## Combining with custom hooks
+### Unix domain sockets
 
-`createWebSocketProxy()` returns a plain hooks object, so you can spread it and override individual hooks — for example, to authenticate the upgrade request before proxying:
+The proxy does not enforce any scheme allowlist — whatever the configured `WebSocket` constructor accepts is accepted. For example, the [`ws`](https://github.com/websockets/ws) package supports Unix domain sockets via its `ws+unix:` scheme:
 
 ```ts
+import { WebSocket } from "ws";
 import { createWebSocketProxy } from "crossws";
 
-const proxyHooks = createWebSocketProxy("wss://backend.example.com");
+const hooks = createWebSocketProxy({
+  target: "ws+unix:/var/run/backend.sock:/chat",
+  WebSocket: WebSocket as unknown as typeof globalThis.WebSocket,
+});
+```
 
-const hooks = {
-  ...proxyHooks,
-  upgrade(req) {
-    if (!req.headers.get("authorization")) {
-      return new Response("Unauthorized", { status: 401 });
-    }
-    return proxyHooks.upgrade?.(req);
-  },
-};
+## Forwarding headers
+
+Passing a `headers` option attaches extra headers to the upstream handshake. This is the usual way to forward identity (`cookie`, `authorization`, `origin`) or inject a shared secret to the upstream.
+
+```ts
+import { WebSocket } from "ws";
+import { createWebSocketProxy } from "crossws";
+
+const hooks = createWebSocketProxy({
+  target: "wss://backend.example.com",
+  WebSocket: WebSocket as unknown as typeof globalThis.WebSocket,
+  headers: (peer) => ({
+    cookie: peer.request.headers.get("cookie") ?? "",
+    "x-forwarded-for": peer.remoteAddress ?? "",
+  }),
+});
 ```
 
+> [!IMPORTANT]
+> The WHATWG global `WebSocket` constructor does **not** accept custom headers. `headers` is only honored when a `WebSocket` constructor that takes a third options argument is passed via the [`WebSocket` option](#custom-websocket-constructor) — e.g. [`ws`](https://github.com/websockets/ws) or [`undici`](https://undici.nodejs.org). With the global constructor the option is silently ignored.
+
 ## API
 
 ### `createWebSocketProxy(target)`
 
 Accepts either a target URL (`string` or `URL`), a resolver function, or an options object:
 
-- **`target`** — `string | URL | (peer: Peer) => string | URL`. The upstream WebSocket URL, or a function that resolves it per peer.
-- **`forwardProtocol`** — `boolean` (default `true`). When enabled, the client's `sec-websocket-protocol` header is forwarded to the upstream and echoed back in the upgrade response.
-- **`maxBufferSize`** — `number` (default `1048576`, i.e. 1 MiB). Maximum number of bytes buffered per peer while the upstream is still connecting. When exceeded, the peer is closed with code `1009` (Message Too Big). Set to `0` to disable.
+- **`target`** — `string | URL | (peer: Peer) => string | URL`. The upstream WebSocket URL, or a function that resolves it per peer. The proxy does not enforce a scheme allowlist; any URL the configured `WebSocket` constructor accepts (including `ws+unix:` with `ws`) works. See the [SSRF warning](#dynamic-target) before using a dynamic resolver.
+- **`forwardProtocol`** — `boolean` (default `true`). When enabled, the client's `sec-websocket-protocol` header is forwarded to the upstream and echoed back in the upgrade response. Values that are not valid RFC 7230 tokens are dropped.
+- **`headers`** — `HeadersInit | (peer: Peer) => HeadersInit`. Extra headers to send on the upstream handshake. Only honored when a custom `WebSocket` constructor that accepts a third options argument is supplied — the WHATWG global ignores it.
+- **`maxBufferSize`** — `number` (default `1048576`, i.e. 1 MiB). Maximum number of bytes buffered per peer while the upstream is still connecting. String frames are accounted at their UTF-8 worst case (3 bytes per UTF-16 code unit) to avoid undercounting multi-byte content. When exceeded, the peer is closed with code `1009` (Message Too Big). Set to `0` to disable.
 - **`connectTimeout`** — `number` (default `10000`). Milliseconds to wait for the upstream WebSocket handshake to complete. If exceeded, the peer is closed with code `1011`. Set to `0` to disable.
 - **`WebSocket`** — `typeof WebSocket` (default `globalThis.WebSocket`). Custom `WebSocket` constructor used to dial the upstream. Falls back to the global when omitted; throws at setup time if neither is available.
 

src/proxy.ts

@@ -8,6 +8,11 @@ const DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024;
 // 10 seconds — aligns with common reverse-proxy defaults (nginx, haproxy).
 const DEFAULT_CONNECT_TIMEOUT = 10_000;
 
+// RFC 7230 `token` grammar — the on-wire form of a WebSocket subprotocol
+// per RFC 6455 §4.1. Used to validate values we echo back in the upgrade
+// response so client-controlled input can't coerce unexpected header content.
+const TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
 export interface WebSocketProxyOptions {
   /**
    * Target WebSocket URL to proxy to (`ws://` or `wss://`).
@@ -51,6 +56,34 @@ export interface WebSocketProxyOptions {
    * @default globalThis.WebSocket
    */
   WebSocket?: typeof WebSocket;
+
+  /**
+   * Extra headers to send on the upstream handshake. Can be a static
+   * object or a resolver called per peer.
+   *
+   * Useful to forward identity from the incoming request (`cookie`,
+   * `authorization`, `origin`), or to inject a shared secret the
+   * upstream expects.
+   *
+   * > [!NOTE]
+   * > The WHATWG global `WebSocket` constructor does not accept custom
+   * > headers — this option is only honored by `WebSocket` constructors
+   * > that take a third options argument (e.g. `ws`, `undici`). Pass
+   * > one via the {@link WebSocket} option to use it.
+   *
+   * @example
+   * ```ts
+   * createWebSocketProxy({
+   *   target: "wss://backend.example.com",
+   *   WebSocket: WsFromNodeWs,
+   *   headers: (peer) => ({
+   *     cookie: peer.request.headers.get("cookie") ?? "",
+   *     "x-forwarded-for": peer.remoteAddress ?? "",
+   *   }),
+   * });
+   * ```
+   */
+  headers?: HeadersInit | ((peer: Peer) => HeadersInit | undefined | void);
 }
 
 /**
@@ -92,15 +125,42 @@ export function createWebSocketProxy(
       // Accept the first requested subprotocol so the upgrade handshake
       // echoes a value the client expects. Upstream must support it too.
       const accepted = reqProtocol.split(",")[0]!.trim();
+      // Defense-in-depth: only echo RFC 7230 tokens. The Fetch `Headers`
+      // API already rejects CRLF, but restricting to the subprotocol
+      // grammar ensures no other client-controlled bytes can land in a
+      // response header — even under buggy or custom header writers.
+      if (!TOKEN_RE.test(accepted)) {
+        return;
+      }
       return { headers: { "sec-websocket-protocol": accepted } };
     },
 
     open(peer) {
-      const url = _resolveTarget(options.target, peer);
-      const protocols = _resolveProtocols(peer, options.forwardProtocol);
-
-      const ws = new WebSocketCtor(url, protocols);
-      ws.binaryType = "arraybuffer";
+      let ws: WebSocket;
+      try {
+        const url = _resolveTarget(options.target, peer);
+        const protocols = _resolveProtocols(peer, options.forwardProtocol);
+        const wsOptions = _resolveWsOptions(options.headers, peer);
+        // The WHATWG WebSocket constructor only takes (url, protocols);
+        // additional arguments are ignored. Custom clients like `ws` and
+        // `undici` accept a third options object where `headers` is
+        // honored — so always pass it when the user configured headers.
+        ws = wsOptions
+          ? new (WebSocketCtor as unknown as new (
+              url: URL,
+              protocols: string[] | undefined,
+              opts: { headers: HeadersInit },
+            ) => WebSocket)(url, protocols, wsOptions)
+          : new WebSocketCtor(url, protocols);
+        ws.binaryType = "arraybuffer";
+      } catch {
+        // Bad target URL, disallowed scheme, invalid subprotocol token,
+        // or a throwing custom resolver — close the peer with a
+        // generic internal-error code rather than letting the exception
+        // escape the hook.
+        _safeClose(peer, 1011, "Upstream setup failed");
+        return;
+      }
 
       const state: UpstreamState = {
         ws,
@@ -165,7 +225,13 @@ export function createWebSocketProxy(
         }
         return;
       }
-      const size = typeof raw === "string" ? raw.length : raw.byteLength;
+      // Strings become UTF-8 on the wire: a UTF-16 code unit encodes to
+      // at most 3 UTF-8 bytes (surrogate pairs use 4 bytes spread across
+      // 2 code units, so the per-unit worst case still bounds at 3).
+      // Use the upper bound to keep the check O(1) while guaranteeing
+      // the buffered payload can't exceed the configured limit on the
+      // wire, even for multi-byte content.
+      const size = typeof raw === "string" ? raw.length * 3 : raw.byteLength;
       const limit = options.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE;
       if (limit > 0 && state.bufferSize + size > limit) {
         _cleanupState(upstreams, peer.id, state);
@@ -247,6 +313,16 @@ function _resolveTarget(
   return raw instanceof URL ? raw : new URL(raw);
 }
 
+function _resolveWsOptions(
+  headers: WebSocketProxyOptions["headers"],
+  peer: Peer,
+): { headers: HeadersInit } | undefined {
+  if (!headers) return;
+  const resolved = typeof headers === "function" ? headers(peer) : headers;
+  if (!resolved) return;
+  return { headers: resolved };
+}
+
 function _resolveProtocols(
   peer: Peer,
   forwardProtocol: boolean | undefined,

test/proxy.test.ts

@@ -237,14 +237,137 @@ describe("createWebSocketProxy", () => {
       ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent));
     });
     // Upstream has a 100ms upgrade delay, so these messages queue in the
-    // proxy's buffer before the upstream connection opens.
-    await ws.send("aaaaa"); // 5 bytes — fills the limit exactly
-    await ws.send("bbbbb"); // 5 more bytes — exceeds
+    // proxy's buffer before the upstream connection opens. The proxy
+    // accounts strings at their UTF-8 worst case (3 bytes per code unit)
+    // so any non-empty frame exceeds the 5-byte limit configured above.
+    await ws.send("aaaaa");
     const event = await closed;
     expect(event.code).toBe(1009);
   });
 });
 
+describe("createWebSocketProxy unit hooks", () => {
+  test("echoes valid subprotocol tokens in upgrade response", () => {
+    const hooks = createWebSocketProxy("ws://localhost/");
+    const req = new Request("http://localhost/", {
+      headers: { "sec-websocket-protocol": "chat" },
+    });
+    const result = hooks.upgrade?.(req);
+    expect(result).toMatchObject({
+      headers: { "sec-websocket-protocol": "chat" },
+    });
+  });
+
+  test("drops subprotocol values that are not RFC 7230 tokens", () => {
+    // Defense-in-depth: even if a buggy runtime lets a client smuggle a
+    // non-token character into the header, the proxy must not echo it
+    // into the upgrade response.
+    const hooks = createWebSocketProxy("ws://localhost/");
+    for (const bad of ["a/b", "has space", "semi;colon", "ctl\u0001"]) {
+      const req = new Request("http://localhost/", {
+        headers: { "sec-websocket-protocol": bad },
+      });
+      expect(hooks.upgrade?.(req)).toBeUndefined();
+    }
+  });
+
+  test("passes headers option through to custom WebSocket constructor", () => {
+    const calls: Array<{
+      url: unknown;
+      protocols: unknown;
+      options: unknown;
+    }> = [];
+    class StubWS extends EventTarget {
+      binaryType = "arraybuffer";
+      readyState = 0;
+      constructor(url: unknown, protocols: unknown, options?: unknown) {
+        super();
+        calls.push({ url, protocols, options });
+      }
+      send(): void {}
+      close(): void {}
+    }
+    const hooks = createWebSocketProxy({
+      target: "ws://upstream.invalid/",
+      WebSocket: StubWS as unknown as typeof WebSocket,
+      connectTimeout: 0,
+      headers: (peer) => ({
+        cookie: peer.request?.headers.get("cookie") ?? "",
+        "x-trace": "t1",
+      }),
+    });
+    const peer = {
+      id: "p-headers",
+      request: new Request("http://localhost/", {
+        headers: { cookie: "sid=abc" },
+      }),
+      close() {},
+      send() {},
+    };
+    hooks.open?.(peer as never);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.options).toEqual({
+      headers: { cookie: "sid=abc", "x-trace": "t1" },
+    });
+  });
+
+  test("closes peer with 1011 when WebSocket constructor rejects the target", async () => {
+    // The WHATWG `WebSocket` constructor throws `SyntaxError` for any
+    // scheme other than `ws:`/`wss:`. The open hook must catch that
+    // and close the peer instead of letting the exception escape.
+    const badAdapter = nodeAdapter({
+      hooks: createWebSocketProxy({
+        target: () => new URL("http://localhost:1/"),
+      }),
+    });
+    const server = createServer((_req, res) => res.end("ok"));
+    server.on("upgrade", badAdapter.handleUpgrade);
+    const port = await getRandomPort("localhost");
+    await new Promise<void>((resolve) => server.listen(port, resolve));
+    await waitForPort(port);
+    try {
+      const ws = await wsConnect(`ws://localhost:${port}/`);
+      const event = await new Promise<CloseEvent>((resolve) => {
+        ws.ws.addEventListener("close", (e) => resolve(e as CloseEvent));
+      });
+      expect(event.code).toBe(1011);
+    } finally {
+      server.closeAllConnections?.();
+      server.close();
+    }
+  });
+
+  test("passes ws+unix targets through to a custom WebSocket client", () => {
+    // No built-in scheme validation: anything the custom constructor
+    // accepts (e.g. the `ws+unix:` syntax supported by `ws`) works.
+    const calls: unknown[] = [];
+    class StubWS extends EventTarget {
+      binaryType = "arraybuffer";
+      readyState = 0;
+      constructor(url: unknown) {
+        super();
+        calls.push(url);
+      }
+      send(): void {}
+      close(): void {}
+    }
+    const hooks = createWebSocketProxy({
+      target: "ws+unix:/tmp/sock:/",
+      WebSocket: StubWS as unknown as typeof WebSocket,
+      connectTimeout: 0,
+    });
+    const peer = {
+      id: "p-unix",
+      request: new Request("http://localhost/"),
+      close() {},
+      send() {},
+    };
+    hooks.open?.(peer as never);
+    expect(calls).toHaveLength(1);
+    expect(String(calls[0])).toContain("ws+unix:");
+  });
+});
+
 describe("createWebSocketProxy internals", () => {
   test("_normalizeOutgoingCode allows 1000 and 3000-4999 range", () => {
     // state.ws is a client-side WebSocket; WHATWG forbids anything else.