svelte-adapter-uws 0.4.11 → 0.4.12

package/README.md

@@ -36,6 +36,7 @@ I've been loving Svelte and SvelteKit for a long time. I always wanted to expand
 **WebSocket deep dive**
 - [WebSocket handler (`hooks.ws`)](#websocket-handler-hooksws)
 - [Authentication](#authentication)
+- [Refreshing session cookies on WebSocket connect](#refreshing-session-cookies-on-websocket-connect)
 - [Platform API (`event.platform`)](#platform-api-eventplatform)
 - [Client store API](#client-store-api)
 - [Seeding initial state](#seeding-initial-state)
@@ -726,8 +727,10 @@ export async function upgrade({ cookies }) {
   if (!user) return false; // -> 401, expired or invalid session
 
   // Attach user data to the socket - available via ws.getUserData()
-  // To also set response headers on the 101 (e.g. refresh session cookie):
-  // return upgradeResponse({ userId: user.id }, { 'set-cookie': '...' });
+  // To refresh the session cookie on connect, use the `authenticate` hook
+  // (see "Refreshing session cookies on WebSocket connect" below).
+  // `upgradeResponse()` with custom non-cookie headers is also supported:
+  // return upgradeResponse({ userId: user.id }, { 'x-session-version': '2' });
   return { userId: user.id, name: user.name, role: user.role };
 }
 
@@ -797,6 +800,72 @@ The WebSocket upgrade is an HTTP request. The browser treats it like any other r
 | Server hook | `hooks.server.js` `handle()` | Yes |
 | **WebSocket upgrade** | **`hooks.ws.js` `upgrade()`** | **Yes** |
 
+### Refreshing session cookies on WebSocket connect
+
+For short-lived sessions you often want to rotate the session cookie every time a client connects. The obvious approach -- attaching `Set-Cookie` to the 101 Switching Protocols response via `upgradeResponse()` -- is RFC-compliant but **is silently rejected by Cloudflare Tunnel, Cloudflare's proxy, and some other strict edge proxies**. The symptom is that the WebSocket `open` handler fires server-side, then the connection closes with code 1006 (`Received TCP FIN before WebSocket close frame`) before any frames are exchanged. The adapter emits a build-time warning when it detects this pattern.
+
+The adapter ships a first-class solution: the optional `authenticate` hook runs as a normal HTTP POST **before** the WebSocket upgrade. `Set-Cookie` rides on a standard 2xx response, which every proxy handles correctly; the browser then attaches the refreshed cookie to the upgrade request that follows.
+
+**Step 1: add an `authenticate` export to `hooks.ws.js`**
+
+```js
+// src/hooks.ws.js
+import { getSession, renewSession } from '$lib/server/auth.js';
+
+// Runs as POST /__ws/auth, before the WebSocket upgrade.
+// cookies.set() becomes Set-Cookie on a standard 204 response.
+export async function authenticate({ cookies }) {
+  const session = await getSession(cookies.get('session'));
+  if (!session) return false; // -> 401, client does not open the WebSocket
+
+  const renewed = await renewSession(session);
+  cookies.set('session', renewed.token, {
+    path: '/',
+    httpOnly: true,
+    secure: true,
+    sameSite: 'lax',
+    maxAge: 60 * 60 * 24 * 7
+  });
+}
+
+// Your existing upgrade() hook stays unchanged - it reads the now-fresh cookie.
+export async function upgrade({ cookies }) {
+  const session = await getSession(cookies.session);
+  if (!session) return false;
+  return { userId: session.userId, role: session.role };
+}
+```
+
+The `authenticate` event exposes the SvelteKit event shape you already know: `{ request, headers, cookies, url, remoteAddress, getClientAddress, platform }`. Return values:
+
+- `undefined` / nothing - success, responds `204 No Content` with any `Set-Cookie` headers from `cookies.set()` (recommended).
+- `false` - responds `401 Unauthorized`. The client does not open the WebSocket.
+- A full `Response` - used as-is; any `cookies.set()` calls are merged in.
+
+**Step 2: opt in from the client**
+
+```js
+import { connect } from 'svelte-adapter-uws/client';
+
+// Hit /__ws/auth before every WebSocket connect (including reconnects)
+connect({ auth: true });
+
+// Or point at a custom path (e.g. behind a Cloudflare Access rule)
+connect({ auth: '/api/ws-auth' });
+```
+
+With `auth: true` the client stores runs `fetch('/__ws/auth', { method: 'POST', credentials: 'include' })` before every `new WebSocket(...)` call, including after automatic reconnects. Concurrent connect attempts share a single in-flight preflight. A `4xx` response is treated as terminal (the user is not authenticated); `5xx` and network errors fall back to the normal reconnect backoff.
+
+**Configuration**
+
+- The default auth path is `/__ws/auth`. Override with `adapter({ websocket: { authPath: '/api/ws-auth' } })`.
+- The hook is only mounted when `authenticate` is exported from `hooks.ws` -- no runtime cost when unused.
+- Dev mode (Vite plugin) mirrors the production route on the same path.
+
+**Why not put `Set-Cookie` on the 101?**
+
+Cloudflare's HTTP/2 WebSocket bridging rewrites 101 responses, and `Set-Cookie` on the 101 trips the edge into tearing the connection down. This is undocumented Cloudflare behavior, but reproducible on every tunnel and proxy connector. The `authenticate` hook sidesteps it entirely by using a standard HTTP response.
+
 ---
 
 ## Platform API (`event.platform`)

package/client.d.ts

@@ -40,6 +40,46 @@ export interface ConnectOptions {
 	 * @default false
 	 */
 	debug?: boolean;
+
+	/**
+	 * Run a pre-WebSocket HTTP preflight against the adapter's `authenticate`
+	 * endpoint before opening the socket. Required only when your server's
+	 * `hooks.ws` exports an `authenticate` hook that refreshes session cookies.
+	 *
+	 * - `true` (recommended) - use the default path `/__ws/auth`
+	 * - `string` - use a custom path, e.g. `'/api/ws/auth'`
+	 * - `false` / omit - disabled, no preflight (default)
+	 *
+	 * The preflight is a `fetch(authPath, { method: 'POST', credentials: 'include' })`
+	 * that runs before every connect (including reconnects) so rotated session
+	 * cookies are picked up. Concurrent connect attempts share a single in-flight
+	 * request. On a non-2xx response, the connection is not opened and the status
+	 * store transitions to `'closed'` with a permanent rejection.
+	 *
+	 * This exists because `Set-Cookie` on a 101 Switching Protocols response is
+	 * silently dropped by Cloudflare Tunnel and some other strict edge proxies,
+	 * which closes the WebSocket with code 1006 before any frames are exchanged.
+	 * Refreshing cookies via a normal HTTP response works behind every proxy.
+	 *
+	 * @default false
+	 *
+	 * @example
+	 * ```ts
+	 * // src/hooks.ws.ts
+	 * export function authenticate({ cookies }) {
+	 *   const session = validateSession(cookies.get('session'));
+	 *   if (!session) return false;
+	 *   cookies.set('session', renewSession(session), {
+	 *     httpOnly: true, secure: true, sameSite: 'lax', path: '/'
+	 *   });
+	 * }
+	 *
+	 * // src/routes/+layout.svelte
+	 * import { connect } from 'svelte-adapter-uws/client';
+	 * connect({ auth: true });
+	 * ```
+	 */
+	auth?: boolean | string;
 }
 
 /**

package/client.js

@@ -509,9 +509,15 @@ function createConnection(options) {
 		reconnectInterval = 3000,
 		maxReconnectInterval = 30000,
 		maxReconnectAttempts = Infinity,
-		debug = false
+		debug = false,
+		auth = false
 	} = options;
 
+	// Resolve the auth preflight path. `auth: true` -> default '/__ws/auth',
+	// `auth: '/custom'` -> use the provided path, `auth: false` (default) -> disabled.
+	/** @type {string | null} */
+	const authPath = auth === true ? '/__ws/auth' : (typeof auth === 'string' && auth) ? auth : null;
+
 	/** @type {WebSocket | null} */
 	let ws = null;
 
@@ -520,6 +526,9 @@ function createConnection(options) {
 	/** @type {ReturnType<typeof setInterval> | null} */
 	let activityTimer = null;
 
+	/** @type {Promise<boolean> | null} deduped in-flight auth preflight */
+	let authInFlight = null;
+
 	let attempt = 0;
 	let intentionallyClosed = false;
 	// Set when the server permanently rejects us (terminal close code) or when
@@ -570,12 +579,99 @@ function createConnection(options) {
 		return `${protocol}//${window.location.host}${path}`;
 	}
 
+	/**
+	 * Build the HTTP URL for the auth preflight. Mirrors getUrl() but emits
+	 * http/https instead of ws/wss so same-origin cookies flow correctly.
+	 * Returns null in SSR or when auth is disabled.
+	 */
+	function getAuthUrl() {
+		if (!authPath) return null;
+		if (url) {
+			try {
+				const wsUrl = new URL(url);
+				const httpScheme = wsUrl.protocol === 'wss:' ? 'https:' : 'http:';
+				return httpScheme + '//' + wsUrl.host + authPath;
+			} catch {
+				return null;
+			}
+		}
+		if (typeof window === 'undefined') return null;
+		return window.location.origin + authPath;
+	}
+
+	/**
+	 * Run the auth preflight. Returns one of:
+	 *  - `'ok'` - request accepted (2xx). Open the socket.
+	 *  - `'unauthorized'` - server rejected with 4xx. Terminal: the user is
+	 *    not authenticated and retrying won't help without new credentials.
+	 *  - `'transient'` - 5xx or network error. Fall back to normal reconnect
+	 *    backoff so the preflight retries alongside the socket.
+	 *
+	 * Deduped: concurrent doConnect() calls share a single in-flight fetch.
+	 *
+	 * @returns {Promise<'ok' | 'unauthorized' | 'transient'>}
+	 */
+	function runAuth() {
+		if (!authPath) return Promise.resolve('ok');
+		if (authInFlight) return authInFlight;
+		const target = getAuthUrl();
+		if (!target) return Promise.resolve('ok');
+
+		authInFlight = (async () => {
+			try {
+				const resp = await fetch(target, {
+					method: 'POST',
+					credentials: 'include',
+					headers: { 'x-requested-with': 'svelte-adapter-uws' }
+				});
+				if (debug) console.log('[ws] auth preflight status=%d', resp.status);
+				if (resp.ok) return 'ok';
+				if (resp.status >= 400 && resp.status < 500) return 'unauthorized';
+				return 'transient';
+			} catch (err) {
+				if (debug) console.warn('[ws] auth preflight network error:', err);
+				return 'transient';
+			} finally {
+				authInFlight = null;
+			}
+		})();
+		return authInFlight;
+	}
+
 	function doConnect() {
 		if (!url && typeof window === 'undefined') return;
 		if (ws && (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)) return;
 
 		statusStore.set('connecting');
 
+		if (authPath) {
+			runAuth().then((outcome) => {
+				if (intentionallyClosed || terminalClosed) return;
+				if (outcome === 'unauthorized') {
+					// Server rejected the request with a 4xx. The user is not
+					// authenticated and retrying won't help until they log in.
+					if (debug) console.warn('[ws] auth preflight rejected (4xx), not opening WebSocket');
+					statusStore.set('closed');
+					terminalClosed = true;
+					permaClosedStore.set(true);
+					return;
+				}
+				if (outcome === 'transient') {
+					// Network error or 5xx. Retry via the normal backoff loop so
+					// the preflight automatically re-runs on the next attempt.
+					if (debug) console.warn('[ws] auth preflight transient failure, scheduling reconnect');
+					statusStore.set('closed');
+					scheduleReconnect();
+					return;
+				}
+				openSocket();
+			});
+			return;
+		}
+		openSocket();
+	}
+
+	function openSocket() {
 		try {
 			ws = new WebSocket(getUrl());
 		} catch {

package/files/cookies.js

@@ -23,3 +23,119 @@ export function parseCookies(cookieHeader) {
 	}
 	return cookies;
 }
+
+const COOKIE_NAME_INVALID = /[\s"(),/:;<=>?@[\\\]{}\u0000-\u001f\u007f]/;
+const COOKIE_VALUE_INVALID = /[,;\s\u0000-\u001f\u007f]/;
+const VALID_SAMESITE = new Set(['strict', 'lax', 'none']);
+
+/**
+ * @typedef {object} CookieSerializeOptions
+ * @property {string} [path]
+ * @property {string} [domain]
+ * @property {Date} [expires]
+ * @property {number} [maxAge] - seconds
+ * @property {boolean} [httpOnly]
+ * @property {boolean} [secure]
+ * @property {boolean} [partitioned]
+ * @property {'strict' | 'lax' | 'none' | boolean} [sameSite]
+ * @property {boolean} [encode] - default true; pass false to skip URI encoding
+ */
+
+/**
+ * Serialize a cookie name/value/options triple into a Set-Cookie header string.
+ * Mirrors the cookie semantics SvelteKit applies via its cookies.set() API so
+ * users writing an authenticate hook get the same behavior as in +server.js.
+ *
+ * @param {string} name
+ * @param {string} value
+ * @param {CookieSerializeOptions} [options]
+ * @returns {string}
+ */
+export function serializeCookie(name, value, options = {}) {
+	if (typeof name !== 'string' || name.length === 0 || COOKIE_NAME_INVALID.test(name)) {
+		throw new Error(`Invalid cookie name: '${name}'`);
+	}
+	const encoded = options.encode === false ? value : encodeURIComponent(value);
+	if (COOKIE_VALUE_INVALID.test(encoded)) {
+		throw new Error(`Invalid cookie value for '${name}'`);
+	}
+	let out = name + '=' + encoded;
+	if (options.domain !== undefined) out += '; Domain=' + options.domain;
+	if (options.path !== undefined) out += '; Path=' + options.path;
+	if (options.expires !== undefined) out += '; Expires=' + options.expires.toUTCString();
+	if (options.maxAge !== undefined) {
+		if (!Number.isFinite(options.maxAge)) {
+			throw new Error(`Invalid Max-Age for cookie '${name}': ${options.maxAge}`);
+		}
+		out += '; Max-Age=' + Math.floor(options.maxAge);
+	}
+	if (options.httpOnly) out += '; HttpOnly';
+	if (options.secure) out += '; Secure';
+	if (options.partitioned) out += '; Partitioned';
+	if (options.sameSite !== undefined) {
+		const raw = options.sameSite === true ? 'strict' : options.sameSite === false ? 'lax' : options.sameSite;
+		const normalized = String(raw).toLowerCase();
+		if (!VALID_SAMESITE.has(normalized)) {
+			throw new Error(`Invalid SameSite for cookie '${name}': ${options.sameSite}`);
+		}
+		out += '; SameSite=' + normalized[0].toUpperCase() + normalized.slice(1);
+	}
+	return out;
+}
+
+/**
+ * Create a SvelteKit-like cookies API for use in the authenticate hook.
+ * Reads from the incoming request's Cookie header and accumulates Set-Cookie
+ * strings that the caller writes onto the response.
+ *
+ * @param {string} [cookieHeader] - raw Cookie header from the request
+ */
+export function createCookies(cookieHeader) {
+	const parsed = parseCookies(cookieHeader);
+	/** @type {Map<string, string>} keyed by name + path + domain so repeated set() with the same scope overwrites */
+	const outgoing = new Map();
+
+	function key(name, path, domain) {
+		return name + '\0' + (path || '') + '\0' + (domain || '');
+	}
+
+	const api = {
+		/** @param {string} name */
+		get(name) {
+			return parsed[name];
+		},
+		/** @returns {Record<string, string>} */
+		getAll() {
+			return { ...parsed };
+		},
+		/**
+		 * @param {string} name
+		 * @param {string} value
+		 * @param {CookieSerializeOptions} [options]
+		 */
+		set(name, value, options = {}) {
+			outgoing.set(key(name, options.path, options.domain), serializeCookie(name, value, options));
+			parsed[name] = value;
+		},
+		/**
+		 * @param {string} name
+		 * @param {Pick<CookieSerializeOptions, 'path' | 'domain'>} [options]
+		 */
+		delete(name, options = {}) {
+			api.set(name, '', {
+				...options,
+				expires: new Date(0),
+				maxAge: 0
+			});
+			delete parsed[name];
+		},
+		/**
+		 * Drain accumulated Set-Cookie headers. Called by the adapter, not the user.
+		 * @returns {string[]}
+		 */
+		_serialize() {
+			return [...outgoing.values()];
+		}
+	};
+	return api;
+}

package/files/handler.js

@@ -11,7 +11,7 @@ import { Server } from 'SERVER';
 import { manifest, prerendered, base } from 'MANIFEST';
 import { env } from 'ENV';
 import * as wsModule from 'WS_HANDLER';
-import { parseCookies } from './cookies.js';
+import { parseCookies, createCookies } from './cookies.js';
 import { mimeLookup, parse_as_bytes, parse_origin } from './utils.js';
 
 /* global ENV_PREFIX */
@@ -19,6 +19,7 @@ import { mimeLookup, parse_as_bytes, parse_origin } from './utils.js';
 /* global WS_ENABLED */
 /* global WS_PATH */
 /* global WS_OPTIONS */
+/* global WS_AUTH_PATH */
 /* global HEALTH_CHECK_PATH */
 
 class PayloadTooLargeError extends Error {
@@ -1332,7 +1333,7 @@ function handleRequest(res, req) {
 // WS_ENABLED is set by the adapter at build time - no inference from exports needed
 if (WS_ENABLED) {
 	// Warn about unrecognized exports - catches typos like "mesage" or "opn"
-	const knownWsExports = new Set(['open', 'message', 'upgrade', 'close', 'drain', 'subscribe', 'unsubscribe']);
+	const knownWsExports = new Set(['open', 'message', 'upgrade', 'close', 'drain', 'subscribe', 'unsubscribe', 'authenticate']);
 	for (const name of Object.keys(wsModule)) {
 		if (!knownWsExports.has(name)) {
 			console.warn(
@@ -1342,6 +1343,30 @@ if (WS_ENABLED) {
 		}
 	}
 
+	// One-shot runtime warning when a user upgrade handler attaches Set-Cookie
+	// to the 101 Switching Protocols response. Cloudflare Tunnel and some other
+	// strict edge proxies silently close WebSocket connections with 1006 when
+	// the 101 carries Set-Cookie. The `authenticate` hook refreshes cookies
+	// over a normal HTTP response and works behind every proxy.
+	let warnedSetCookieOnUpgrade = false;
+	/** @param {Record<string, string | string[]> | null | undefined} responseHeaders */
+	function maybeWarnSetCookieOnUpgrade(responseHeaders) {
+		if (warnedSetCookieOnUpgrade || !responseHeaders) return;
+		for (const k of Object.keys(responseHeaders)) {
+			if (k.toLowerCase() === 'set-cookie') {
+				warnedSetCookieOnUpgrade = true;
+				console.warn(
+					'[adapter-uws] Set-Cookie on the 101 upgrade response is rejected by ' +
+					'Cloudflare Tunnel and some other edge proxies (WebSocket opens, then ' +
+					'closes with 1006 TCP FIN). Migrate to the `authenticate` hook to ' +
+					'refresh session cookies over a normal HTTP response: ' +
+					'export function authenticate({ cookies }) { cookies.set(...); }'
+				);
+				return;
+			}
+		}
+	}
+
 	const wsOptions = WS_OPTIONS;
 	const allowedOrigins = wsOptions.allowedOrigins || 'same-origin';
 
@@ -1403,6 +1428,127 @@ if (WS_ENABLED) {
 		}
 	}, 60000).unref();
 
+	// -- Authenticate endpoint (pre-upgrade HTTP hook) ---------------------
+	// Optional `authenticate` export in hooks.ws.ts runs as a normal HTTP POST
+	// so session cookies can be refreshed via a standard Set-Cookie on a 200
+	// response. This works behind Cloudflare Tunnel and other strict edge
+	// proxies that silently drop WebSocket connections whose 101 response
+	// carries Set-Cookie. The client store POSTs here before opening the WS
+	// when `connect({ auth: true })` is used.
+	if (typeof wsModule.authenticate === 'function') {
+		const authPath = WS_AUTH_PATH;
+		// Body size cap for the authenticate endpoint. Most requests have no
+		// body at all -- the hook reads cookies from the Cookie header. Cap at
+		// a small value to make malicious payloads cheap to reject.
+		const AUTH_BODY_LIMIT = 64 * 1024;
+
+		app.post(authPath, (res, req) => {
+			/** @type {Record<string, string>} */
+			const authHeaders = {};
+			req.forEach((k, v) => { authHeaders[k] = v; });
+			const method = 'POST';
+			const url = req.getUrl() + (req.getQuery() ? '?' + req.getQuery() : '');
+			const clientIp = resolveClientIp(textDecoder.decode(res.getRemoteAddressAsText()), authHeaders);
+
+			const state = acquireState();
+			res.onAborted(() => { state.aborted = true; });
+
+			const contentLength = parseInt(authHeaders['content-length'], 10);
+			if (!isNaN(contentLength) && contentLength > AUTH_BODY_LIMIT) {
+				send413(res);
+				releaseState(state);
+				return;
+			}
+
+			const body = readBody(res, AUTH_BODY_LIMIT, state, isNaN(contentLength) ? -1 : contentLength);
+
+			const base_origin = origin || get_origin(authHeaders);
+			const request = new Request(base_origin + url, {
+				method,
+				headers: authHeaders,
+				body,
+				// @ts-expect-error
+				duplex: 'half'
+			});
+
+			const cookies = createCookies(authHeaders['cookie']);
+
+			const event = {
+				request,
+				headers: authHeaders,
+				cookies,
+				url,
+				remoteAddress: clientIp,
+				getClientAddress: () => clientIp,
+				platform
+			};
+
+			Promise.resolve()
+				.then(() => wsModule.authenticate(event))
+				.then(async (result) => {
+					if (state.aborted) return;
+
+					if (result === false) {
+						res.cork(() => {
+							res.writeStatus('401 Unauthorized');
+							res.writeHeader('content-type', 'text/plain');
+							res.end('Unauthorized');
+						});
+						return;
+					}
+
+					if (result instanceof Response) {
+						// User returned a full Response -- honour it, but merge any
+						// cookies set via cookies.set() so both APIs work together.
+						const buf = result.body ? Buffer.from(await result.arrayBuffer()) : null;
+						if (state.aborted) return;
+						res.cork(() => {
+							res.writeStatus(String(result.status));
+							for (const [hk, hv] of result.headers) {
+								if (hk === 'set-cookie' || hk === 'content-length') continue;
+								res.writeHeader(hk, hv);
+							}
+							for (const c of result.headers.getSetCookie()) res.writeHeader('set-cookie', c);
+							for (const c of cookies._serialize()) res.writeHeader('set-cookie', c);
+							if (buf) res.end(buf);
+							else res.end();
+						});
+						return;
+					}
+
+					// Implicit success: 204 No Content with any Set-Cookie headers
+					res.cork(() => {
+						res.writeStatus('204 No Content');
+						for (const c of cookies._serialize()) res.writeHeader('set-cookie', c);
+						res.endWithoutBody(0);
+					});
+				})
+				.catch((err) => {
+					if (state.aborted) return;
+					if (err instanceof PayloadTooLargeError) {
+						send413(res);
+						return;
+					}
+					console.error('[adapter-uws] authenticate error:', err);
+					if (!state.aborted) send500(res);
+				})
+				.finally(() => { releaseState(state); });
+		});
+
+		// Reject non-POST verbs on the auth path so GET/HEAD do not fall through
+		// to the SSR catch-all (which would try to render a SvelteKit route).
+		app.any(authPath, (res) => {
+			res.cork(() => {
+				res.writeStatus('405 Method Not Allowed');
+				res.writeHeader('allow', 'POST');
+				res.writeHeader('content-type', 'text/plain');
+				res.end('Method Not Allowed');
+			});
+		});
+
+		console.log(`WebSocket auth endpoint registered at ${authPath}`);
+	}
+
 	app.ws(WS_PATH, {
 		// Handle HTTP -> WebSocket upgrade with user-provided auth
 		upgrade: (res, req, context) => {
@@ -1582,6 +1728,7 @@ if (WS_ENABLED) {
 					const ud = userData || {};
 					if (!ud.remoteAddress) ud.remoteAddress = clientIp;
 					if (responseHeaders) {
+						maybeWarnSetCookieOnUpgrade(responseHeaders);
 						for (const [hk, hv] of Object.entries(responseHeaders)) {
 							if (Array.isArray(hv)) {
 								for (const v of hv) res.writeHeader(hk, v);

package/index.d.ts

@@ -127,6 +127,20 @@ export interface WebSocketOptions {
 	 */
 	path?: string;
 
+	/**
+	 * URL path for the `authenticate` preflight endpoint.
+	 *
+	 * The adapter auto-mounts a `POST` endpoint here when your `hooks.ws` file
+	 * exports an `authenticate` function. The client store hits it before
+	 * opening a WebSocket when `connect({ auth: true })` is used.
+	 *
+	 * Must differ from `path`. Change this only if the default collides with
+	 * your routing or if Cloudflare Access requires a non-`__`-prefixed path.
+	 *
+	 * @default '/__ws/auth'
+	 */
+	authPath?: string;
+
 	/**
 	 * Max message size in bytes. Connections sending larger messages are closed.
 	 * @default 16384 (16 KB)
@@ -201,6 +215,36 @@ export interface WebSocketOptions {
 
 // -- User's WebSocket handler module exports ---------------------------------
 
+/**
+ * Options accepted by `authenticateCookies.set()` and `.delete()`. Matches the
+ * shape SvelteKit uses for `cookies.set()`.
+ */
+export interface CookieSerializeOptions {
+	path?: string;
+	domain?: string;
+	expires?: Date;
+	/** In seconds. */
+	maxAge?: number;
+	httpOnly?: boolean;
+	secure?: boolean;
+	partitioned?: boolean;
+	sameSite?: 'strict' | 'lax' | 'none' | boolean;
+	/** Defaults to `true`. Set to `false` to skip URI-encoding the value. */
+	encode?: boolean;
+}
+
+/**
+ * SvelteKit-like cookies API available inside the `authenticate` hook.
+ * Mutations via `.set()` and `.delete()` become `Set-Cookie` headers on the
+ * HTTP response returned from the endpoint.
+ */
+export interface AuthenticateCookies {
+	get(name: string): string | undefined;
+	getAll(): Record<string, string>;
+	set(name: string, value: string, options?: CookieSerializeOptions): void;
+	delete(name: string, options?: Pick<CookieSerializeOptions, 'path' | 'domain'>): void;
+}
+
 /**
  * Context passed to the `upgrade` handler.
  */
@@ -215,6 +259,31 @@ export interface UpgradeContext {
 	remoteAddress: string;
 }
 
+/**
+ * Context passed to the optional `authenticate` handler.
+ *
+ * `authenticate` runs as a normal HTTP POST before the WebSocket upgrade, so
+ * any `Set-Cookie` headers from `cookies.set()` ride on a standard response
+ * and work behind every proxy (unlike `Set-Cookie` on the 101 upgrade, which
+ * Cloudflare Tunnel and some other strict edge proxies silently drop).
+ */
+export interface AuthenticateContext {
+	/** The incoming request (standard `Request` object, with body). */
+	request: Request;
+	/** Request headers (all lowercase keys). */
+	headers: Record<string, string>;
+	/** SvelteKit-like cookies API. Mutations become Set-Cookie on the response. */
+	cookies: AuthenticateCookies;
+	/** The request URL path, including query string if present. */
+	url: string;
+	/** Remote IP address (honoring `ADDRESS_HEADER` / `XFF_DEPTH`). */
+	remoteAddress: string;
+	/** Shorthand for returning `remoteAddress`. Matches the SvelteKit event shape. */
+	getClientAddress: () => string;
+	/** The platform API (publish, send, topic helpers, etc.). */
+	platform: Platform;
+}
+
 /**
  * Context passed to `open` and `drain` handlers.
  */
@@ -294,6 +363,41 @@ export interface SubscribeContext {
  * ```
  */
 export interface WebSocketHandler<UserData = unknown> {
+	/**
+	 * Optional HTTP preflight that runs before the WebSocket upgrade.
+	 *
+	 * Recommended for any flow that needs to refresh a session cookie on WS
+	 * connect. Returning cookies from this hook goes out via a standard HTTP
+	 * response, which works behind every proxy. Setting `Set-Cookie` on the
+	 * 101 upgrade response (via `upgradeResponse()`) is silently dropped by
+	 * Cloudflare Tunnel and some other strict edge proxies.
+	 *
+	 * Triggered by the client store via `connect({ auth: true })`, which
+	 * POSTs to `/__ws/auth` (configurable via `websocket.authPath`) before
+	 * opening every WebSocket - including after reconnects.
+	 *
+	 * Return values:
+	 * - `undefined` / `void` - success, responds 204 with any cookies set via `cookies.set()`.
+	 * - `false` - respond 401 Unauthorized.
+	 * - `Response` - use the returned response directly; any `cookies.set()` calls are merged in.
+	 *
+	 * May be async.
+	 *
+	 * @example
+	 * ```js
+	 * export function authenticate({ cookies }) {
+	 *   const session = validateSessionToken(cookies.get('session'));
+	 *   if (!session) return false;
+	 *   cookies.set('session', renewSession(session), {
+	 *     httpOnly: true, secure: true, sameSite: 'lax', path: '/', maxAge: 60 * 60 * 24 * 7
+	 *   });
+	 * }
+	 * ```
+	 */
+	authenticate?: (ctx: AuthenticateContext) =>
+		| Response | false | void
+		| Promise<Response | false | void>;
+
 	/**
 	 * Called during the HTTP upgrade handshake.
 	 *
@@ -538,19 +642,25 @@ export interface TopicHelper {
 
 /**
  * Wrap upgrade hook return value to include response headers on the 101
- * Switching Protocols response (e.g. `Set-Cookie` for session refresh).
+ * Switching Protocols response.
  *
- * @example
+ * **Warning (Cloudflare):** attaching `Set-Cookie` to the 101 response is
+ * rejected by Cloudflare Tunnel and some other strict edge proxies. The
+ * WebSocket opens, then closes with code 1006 before any frames are exchanged.
+ * For session-cookie refresh use the `authenticate` hook instead, which
+ * refreshes cookies over a normal HTTP response and works behind every proxy.
+ *
+ * This helper remains supported for non-cookie response headers and for
+ * deployments that do not sit behind strict proxies.
+ *
+ * @example Custom non-cookie headers (safe):
  * ```js
  * import { upgradeResponse } from 'svelte-adapter-uws';
  *
  * export function upgrade({ cookies }) {
  *   const session = validateSession(cookies.session_id);
  *   if (!session) return false;
- *   return upgradeResponse(
- *     { userId: session.userId },
- *     { 'set-cookie': refreshSessionCookie(session) }
- *   );
+ *   return upgradeResponse({ userId: session.userId }, { 'x-session-version': '2' });
  * }
  * ```
  */

package/index.js

@@ -12,6 +12,47 @@ const files = fileURLToPath(new URL('./files', import.meta.url).href);
 // by handler.js for ALL messages regardless of user handler.
 const DEFAULT_WS_HANDLER = '// Built-in: subscribe/unsubscribe handled by the runtime\n';
 
+/**
+ * Scan a bundled WS handler for `upgradeResponse(..., { 'set-cookie': ... })`
+ * usage. Emits a loud warning at build time because Cloudflare Tunnel and some
+ * other strict edge proxies silently drop WebSocket connections whose 101
+ * response carries Set-Cookie -- symptom is 1006 TCP FIN immediately after
+ * open fires server-side. The recommended fix is the `authenticate` hook.
+ *
+ * @param {string} source
+ * @returns {boolean}
+ */
+function detectSetCookieOnUpgrade(source) {
+	// Scan each upgradeResponse( call for a 'set-cookie' / "Set-Cookie" literal
+	// inside its arguments. Works against bundler output (esbuild/rollup/Vite),
+	// which preserves these as literals even after minification rewrites the
+	// surrounding identifiers.
+	const re = /upgradeResponse\s*\(/gi;
+	let match;
+	while ((match = re.exec(source)) !== null) {
+		// Walk forward matching parens to find the end of the call
+		let depth = 1;
+		let i = match.index + match[0].length;
+		let inStr = '';
+		let esc = false;
+		for (; i < source.length && depth > 0; i++) {
+			const c = source[i];
+			if (esc) { esc = false; continue; }
+			if (inStr) {
+				if (c === '\\') esc = true;
+				else if (c === inStr) inStr = '';
+				continue;
+			}
+			if (c === '"' || c === "'" || c === '`') { inStr = c; continue; }
+			if (c === '(') depth++;
+			else if (c === ')') depth--;
+		}
+		const args = source.slice(match.index + match[0].length, i - 1);
+		if (/['"`]\s*set-cookie\s*['"`]/i.test(args)) return true;
+	}
+	return false;
+}
+
 /** @type {import('./index.js').default} */
 export default function (opts = {}) {
 	const { out = 'build', precompress = true, envPrefix = '', healthCheckPath = '/healthz' } = opts;
@@ -227,6 +268,18 @@ export default function (opts = {}) {
 					`Use '/${wsPath}' instead.`
 				);
 			}
+			const wsAuthPath = websocket?.authPath ?? '/__ws/auth';
+			if (wsAuthPath[0] !== '/') {
+				throw new Error(
+					`websocket.authPath must start with '/' - got '${wsAuthPath}'. ` +
+					`Use '/${wsAuthPath}' instead.`
+				);
+			}
+			if (wsAuthPath === wsPath) {
+				throw new Error(
+					`websocket.authPath ('${wsAuthPath}') must differ from websocket.path ('${wsPath}').`
+				);
+			}
 			const wsOpts = {
 				maxPayloadLength: websocket?.maxPayloadLength ?? 16 * 1024,
 				idleTimeout: websocket?.idleTimeout ?? 120,
@@ -239,6 +292,38 @@ export default function (opts = {}) {
 				upgradeRateLimitWindow: websocket?.upgradeRateLimitWindow ?? 10
 			};
 
+			// Scan the bundled WS handler for `upgradeResponse(..., { 'set-cookie': ... })`
+			// and warn loudly. Cloudflare Tunnel and some other strict edge proxies
+			// silently close WebSocket connections whose 101 response carries
+			// Set-Cookie (1006 TCP FIN immediately after the server-side open fires).
+			if (websocket && existsSync(`${tmp}/ws-handler.js`)) {
+				try {
+					const handlerSrc = readFileSync(`${tmp}/ws-handler.js`, 'utf8');
+					if (detectSetCookieOnUpgrade(handlerSrc)) {
+						builder.log.warn(
+							'[adapter-uws] Your upgrade() hook attaches Set-Cookie to the 101 response ' +
+							'via upgradeResponse(). This fails silently behind Cloudflare Tunnel, ' +
+							"Cloudflare's proxy, and some other strict edge proxies: the WebSocket " +
+							'opens, then closes with code 1006 before any frames are exchanged.\n' +
+							'\n' +
+							'Migrate to the `authenticate` hook to refresh session cookies over a ' +
+							'normal HTTP response that works behind every proxy:\n' +
+							'\n' +
+							'  export function authenticate({ cookies }) {\n' +
+							"    const session = validateSession(cookies.get('session'));\n" +
+							'    if (!session) return false;\n' +
+							"    cookies.set('session', renewSession(session), { httpOnly: true, secure: true, sameSite: 'lax', path: '/' });\n" +
+							'  }\n' +
+							'\n' +
+							'Then opt in from the client: connect({ auth: true }).\n' +
+							'This warning is safe to ignore if you do not deploy behind Cloudflare.'
+						);
+					}
+				} catch {
+					// Scanner is best-effort; ignore IO errors
+				}
+			}
+
 			builder.copy(files, out, {
 				replace: {
 					ENV: './env.js',
@@ -252,6 +337,7 @@ export default function (opts = {}) {
 					WS_ENABLED: JSON.stringify(!!websocket),
 					WS_PATH: JSON.stringify(wsPath),
 					WS_OPTIONS: JSON.stringify(wsOpts),
+					WS_AUTH_PATH: JSON.stringify(wsAuthPath),
 					HEALTH_CHECK_PATH: JSON.stringify(healthCheckPath)
 				}
 			});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-adapter-uws",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "SvelteKit adapter for uWebSockets.js - high-performance C++ HTTP server with built-in WebSocket support",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/vite.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
-import { parseCookies } from './files/cookies.js';
+import { parseCookies, createCookies } from './files/cookies.js';
 
 /**
  * Safely quote a string for JSON embedding. Throws on invalid characters
@@ -27,11 +27,12 @@ function esc(s) {
  * Uses the same subscribe/unsubscribe/publish protocol as the production
  * uWS handler, so the client store works identically in dev and prod.
  *
- * @param {{ path?: string, handler?: string }} [options]
+ * @param {{ path?: string, handler?: string, authPath?: string }} [options]
  * @returns {import('vite').Plugin}
  */
 export default function uws(options = {}) {
 	const wsPath = options.path || '/ws';
+	const wsAuthPath = options.authPath || '/__ws/auth';
 
 	/** @type {import('ws').WebSocketServer | undefined} */
 	let wss;
@@ -45,7 +46,7 @@ export default function uws(options = {}) {
 	/** @type {Map<import('ws').WebSocket, object>} */
 	const wsWrappers = new Map();
 
-	/** @type {{ upgrade?: Function, open?: Function, message?: Function, close?: Function, drain?: Function, subscribe?: Function }} */
+	/** @type {{ upgrade?: Function, open?: Function, message?: Function, close?: Function, drain?: Function, subscribe?: Function, unsubscribe?: Function, authenticate?: Function }} */
 	let userHandlers = {};
 
 	/**
@@ -209,7 +210,8 @@ export default function uws(options = {}) {
 			close: mod.close,
 			drain: mod.drain,
 			subscribe: mod.subscribe,
-			unsubscribe: mod.unsubscribe
+			unsubscribe: mod.unsubscribe,
+			authenticate: mod.authenticate
 		};
 	}
 
@@ -324,6 +326,110 @@ export default function uws(options = {}) {
 				})();
 			}
 
+			// /__ws/auth middleware: runs the user's `authenticate` hook as a normal
+			// HTTP POST so session cookies are refreshed via a standard Set-Cookie
+			// on a 200-series response. Mirrors the production handler in dev.
+			server.middlewares.use(wsAuthPath, async (req, res, next) => {
+				await handlerReady;
+				if (!userHandlers.authenticate) { next(); return; }
+				if (req.method !== 'POST') {
+					res.statusCode = 405;
+					res.setHeader('allow', 'POST');
+					res.setHeader('content-type', 'text/plain');
+					res.end('Method Not Allowed');
+					return;
+				}
+
+				/** @type {Record<string, string>} */
+				const headers = {};
+				for (const [k, v] of Object.entries(req.headers)) {
+					if (typeof v === 'string') headers[k] = v;
+					else if (Array.isArray(v)) headers[k] = v.join(', ');
+				}
+
+				// Read body (capped at 64 KB; the hook rarely needs it).
+				const AUTH_BODY_LIMIT = 64 * 1024;
+				/** @type {Buffer[]} */
+				const chunks = [];
+				let total = 0;
+				let oversized = false;
+				for await (const chunk of req) {
+					total += chunk.length;
+					if (total > AUTH_BODY_LIMIT) { oversized = true; break; }
+					chunks.push(chunk);
+				}
+				if (oversized) {
+					res.statusCode = 413;
+					res.setHeader('content-type', 'text/plain');
+					res.end('Content Too Large');
+					return;
+				}
+				const bodyBuf = Buffer.concat(chunks);
+
+				const origin = 'http://' + (headers['host'] || 'localhost');
+				const url = req.url || wsAuthPath;
+				const request = new Request(origin + url, {
+					method: 'POST',
+					headers,
+					body: bodyBuf.length > 0 ? bodyBuf : undefined,
+					// @ts-expect-error
+					duplex: 'half'
+				});
+
+				const cookies = createCookies(headers['cookie']);
+				const clientIp = req.socket?.remoteAddress || '';
+				const event = {
+					request,
+					headers,
+					cookies,
+					url,
+					remoteAddress: clientIp,
+					getClientAddress: () => clientIp,
+					platform
+				};
+
+				try {
+					const result = await Promise.resolve(userHandlers.authenticate(event));
+
+					if (result === false) {
+						res.statusCode = 401;
+						res.setHeader('content-type', 'text/plain');
+						res.end('Unauthorized');
+						return;
+					}
+
+					if (result instanceof Response) {
+						res.statusCode = result.status;
+						for (const [hk, hv] of result.headers) {
+							if (hk === 'set-cookie' || hk === 'content-length') continue;
+							res.setHeader(hk, hv);
+						}
+						const outCookies = [
+							...result.headers.getSetCookie(),
+							...cookies._serialize()
+						];
+						if (outCookies.length > 0) res.setHeader('set-cookie', outCookies);
+						if (result.body) {
+							const buf = Buffer.from(await result.arrayBuffer());
+							res.end(buf);
+						} else {
+							res.end();
+						}
+						return;
+					}
+
+					res.statusCode = 204;
+					const outCookies = cookies._serialize();
+					if (outCookies.length > 0) res.setHeader('set-cookie', outCookies);
+					res.end();
+				} catch (err) {
+					console.error('[adapter-uws] authenticate error:', err);
+					res.statusCode = 500;
+					res.setHeader('content-type', 'text/plain');
+					res.end('Internal Server Error');
+				}
+			});
+
 			server.httpServer?.on('upgrade', async (req, socket, head) => {
 				const { pathname } = new URL(req.url || '', 'http://localhost');
 				if (pathname !== wsPath) return;
@@ -370,7 +476,19 @@ export default function uws(options = {}) {
 						if (result && result.__upgradeResponse === true) {
 							userData = result.userData || {};
 							if (result.headers && Object.keys(result.headers).length > 0) {
-								console.warn('[adapter-uws] upgrade() returned response headers — these are only applied in production (uWS). The ws library used in dev does not support custom 101 headers.');
+								const hasSetCookie = Object.keys(result.headers).some(
+									(k) => k.toLowerCase() === 'set-cookie'
+								);
+								if (hasSetCookie) {
+									console.warn(
+										'[adapter-uws] upgradeResponse() attaches Set-Cookie to the 101 response. ' +
+										'This fails silently behind Cloudflare Tunnel and some other strict edge proxies ' +
+										'(WebSocket opens, then closes with 1006). Use the `authenticate` hook to ' +
+										'refresh session cookies over a normal HTTP response.'
+									);
+								} else {
+									console.warn('[adapter-uws] upgrade() returned response headers. These are only applied in production (uWS); the ws library used in dev does not support custom 101 headers.');
+								}
 							}
 						} else {
 							userData = result || {};