@lowdefy/server-dev 6.0.0 → 7.0.0

package/src/routes/normalizeMcpProtocolVersionHeader.test.mjs

@@ -0,0 +1,62 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+
+import normalizeMcpProtocolVersionHeader from './normalizeMcpProtocolVersionHeader.js';
+
+function createApp() {
+  const app = new Hono();
+  app.post('/api/mcp', (c) => {
+    normalizeMcpProtocolVersionHeader({ request: c.req.raw });
+    return c.json({ protocolVersion: c.req.header('mcp-protocol-version') ?? null });
+  });
+  return app;
+}
+
+async function send(headerValue) {
+  const headers = new Headers();
+  if (headerValue !== undefined) {
+    headers.set('mcp-protocol-version', headerValue);
+  }
+  const res = await createApp().request('/api/mcp', { method: 'POST', headers });
+  return (await res.json()).protocolVersion;
+}
+
+test('collapses a repeated protocol version to the single version it names', async () => {
+  expect(await send('2025-11-25, 2025-11-25')).toEqual('2025-11-25');
+});
+
+test('collapses the value the Fetch Headers constructor builds from both header spellings', async () => {
+  const headers = new Headers({
+    'mcp-protocol-version': '2025-11-25',
+    'MCP-Protocol-Version': '2025-11-25',
+  });
+  const res = await createApp().request('/api/mcp', { method: 'POST', headers });
+  expect((await res.json()).protocolVersion).toEqual('2025-11-25');
+});
+
+test('leaves a single protocol version untouched', async () => {
+  expect(await send('2025-06-18')).toEqual('2025-06-18');
+});
+
+test('leaves a header naming two different versions for the transport to refuse', async () => {
+  expect(await send('2025-11-25, 2025-06-18')).toEqual('2025-11-25, 2025-06-18');
+});
+
+test('leaves an absent header absent', async () => {
+  expect(await send(undefined)).toEqual(null);
+});

package/src/routes/reload.js

@@ -20,6 +20,21 @@ import chokidar from 'chokidar';
 import { streamSSE } from 'hono/streaming';
 
 import { registerTab, unregisterTab } from '../../lib/docs/tabChannel.js';
+import readRecordingCookie from '../../lib/server/recording/readRecordingCookie.js';
+
+// A verified recording cookie means the dev server's own headless browser
+// opened the tab: a journey run ({ source }), or a headless
+// tool ('off'). A developer's tab carries none.
+function tabOrigin(cookieHeader) {
+  const recording = readRecordingCookie(cookieHeader);
+  if (recording === null) {
+    return { source: 'dev', automated: false };
+  }
+  if (recording === 'off') {
+    return { source: 'headless', automated: true };
+  }
+  return { source: recording.source, automated: true };
+}
 
 // SSE endpoint — notifies the client when build/reload is written so it can
 // mutate the SWR cache and refetch config. Also doubles as the transport for
@@ -46,6 +61,7 @@ async function reloadHandler(c) {
     registerTab({
       id: tabId,
       send: (event, data) => stream.writeSSE({ event, data: JSON.stringify(data) }),
+      ...tabOrigin(c.req.header('cookie')),
     });
 
     let open = true;

package/src/routes/request.js

@@ -14,7 +14,7 @@
   limitations under the License.
 */
 
-import { callRequest, redactErrorResponse } from '@lowdefy/api';
+import { callRequest, parseRequestBody, redactErrorResponse } from '@lowdefy/api';
 import { serializer } from '@lowdefy/helpers';
 
 import buildPageIfNeeded from '../../lib/server/jitPageBuilder.js';
@@ -23,7 +23,9 @@ import { getMock } from '../../lib/docs/devMockRegistry.js';
 
 async function requestHandler(c) {
   if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+    // A wrong-method request is client-caused: answer 405 rather than raising a
+    // fault that would be logged at error level and answered with a 500.
+    return c.json({ error: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
   const segments = getPathSegments(c, '/api/request/');
@@ -32,7 +34,7 @@ async function requestHandler(c) {
   }
   const requestId = segments[segments.length - 1];
   const pageId = segments.slice(0, -1).join('/');
-  const { actionId, blockId, payload } = await c.req.json();
+  const { actionId, blockId, payload } = parseRequestBody({ text: await c.req.text() });
 
   // Dev-only agent tooling: once a state checkpoint has been loaded
   // (lib/docs/loadState.js), its recorded request/response pairs live in
@@ -55,7 +57,7 @@ async function requestHandler(c) {
 
   // Page artifacts (including pages/{pageId}/requests/{requestId}.json) are
   // built JIT by GET /api/page/* and thrown away on every page invalidation
-  // (lowdefyBuildWatcher / moduleBuildWatcher). A client that already holds
+  // (lowdefyBuildWatcher). A client that already holds
   // the page config keeps firing requests across that window — and a request
   // that arrived before the page was rebuilt failed with
   // `Request "x" does not exist.` Run the same idempotent build the page route

package/src/routes/request.test.mjs

@@ -20,6 +20,7 @@ import { jest } from '@jest/globals';
 const mockCallRequest = jest.fn();
 jest.unstable_mockModule('@lowdefy/api', () => ({
   callRequest: mockCallRequest,
+  parseRequestBody: ({ text }) => JSON.parse(text),
   redactErrorResponse: jest.fn((context, error) => ({ error: error.message })),
 }));
 
@@ -115,10 +116,13 @@ test('requestHandler replays a dev mock without building or calling the request'
   expect(mockCallRequest).not.toHaveBeenCalled();
 });
 
-test('requestHandler rejects non-POST methods', async () => {
-  const app = createApp();
-  app.onError((err, c) => c.json({ error: err.message }, 500));
-  const res = await app.request('/api/request/dashboard/get_rows');
-  expect(res.status).toEqual(500);
+// A GET to the request route is client-caused, so it must answer 405 rather
+// than throwing into the error handler and being logged as a fault with a 500.
+test('requestHandler returns 405 without building or calling the request for a non-POST method', async () => {
+  const res = await createApp().request('/api/request/dashboard/get_rows');
+
+  expect(res.status).toEqual(405);
+  expect(await res.json()).toEqual({ error: 'Method not allowed.' });
   expect(mockBuildPageIfNeeded).not.toHaveBeenCalled();
+  expect(mockCallRequest).not.toHaveBeenCalled();
 });

package/src/routes/requestBody.test.mjs

@@ -0,0 +1,159 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { fileURLToPath } from 'node:url';
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+import { isSameOriginRequest, parseRequestBody } from '@lowdefy/api';
+
+// usage.js reads package.json from the working directory as it loads, and a suite that
+// ran earlier in the same jest worker may have left the working directory in a temporary
+// fixture directory.
+process.chdir(fileURLToPath(new URL('../..', import.meta.url)));
+
+const mockGetEndpointConfig = jest.fn().mockRejectedValue(new Error('not found'));
+const mockRunWebhookEndpoint = jest.fn();
+jest.unstable_mockModule('@lowdefy/api', () => ({
+  acceptDetachedEndpoint: jest.fn(),
+  callAgent: jest.fn(),
+  callEndpoint: jest.fn(),
+  callRequest: jest.fn(),
+  getEndpointConfig: mockGetEndpointConfig,
+  logClientError: jest.fn(),
+  isSameOriginRequest,
+  parseRequestBody,
+  redactErrorResponse: jest.fn(),
+  runWebhookEndpoint: mockRunWebhookEndpoint,
+}));
+jest.unstable_mockModule('../../lib/server/jitPageBuilder.js', () => ({ default: jest.fn() }));
+jest.unstable_mockModule('../../lib/docs/devMockRegistry.js', () => ({
+  getMock: jest.fn(),
+  loadMocks: jest.fn(),
+}));
+jest.unstable_mockModule('../../lib/docs/loadState.js', () => ({ default: jest.fn() }));
+jest.unstable_mockModule('../../lib/docs/snapshotState.js', () => ({ default: jest.fn() }));
+
+const { default: createErrorHandler } = await import('../middleware/errorHandler.js');
+const routes = {
+  '/api/agent/*': (await import('./agent.js')).default,
+  '/api/client-error': (await import('./clientError.js')).default,
+  '/api/detached/*': (await import('./detached.js')).default,
+  '/api/dev-inspect': (await import('./devInspect.js')).default,
+  '/api/dev-inspect/*': (await import('./devInspect.js')).default,
+  '/api/endpoints/*': (await import('./endpoints.js')).default,
+  '/api/request/*': (await import('./request.js')).default,
+  '/api/usage': (await import('./usage.js')).default,
+  '/lowdefy-docs/state-checkpoints/load': (await import('./docs/loadState.js')).default,
+  '/lowdefy-docs/state-checkpoints/snapshot': (await import('./docs/snapshotState.js')).default,
+  '/lowdefy-feedback': (await import('./feedback.js')).default,
+};
+
+const logger = { debug: jest.fn(), error: jest.fn(), info: jest.fn(), warn: jest.fn() };
+
+function createApp() {
+  const app = new Hono();
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', { logger, handleError: jest.fn() });
+    await next();
+  });
+  Object.entries(routes).forEach(([path, handler]) => app.all(path, handler));
+  app.onError(createErrorHandler({ logger }));
+  return app;
+}
+
+const originalCronSecret = process.env.CRON_SECRET;
+beforeAll(() => {
+  process.env.CRON_SECRET = 'secret';
+});
+afterAll(() => {
+  if (originalCronSecret === undefined) {
+    delete process.env.CRON_SECRET;
+  } else {
+    process.env.CRON_SECRET = originalCronSecret;
+  }
+});
+
+const sameOrigin = { host: 'localhost', origin: 'http://localhost' };
+const notJson = JSON.stringify({ name: 'UserError', message: 'Request body is not valid JSON.' });
+
+// Paths outside /api/ get the error handler's plain-text answer.
+test.each([
+  ['/api/endpoints/save', {}, notJson],
+  ['/api/request/orders/load', {}, notJson],
+  ['/api/agent/orders/assistant', {}, notJson],
+  ['/api/detached/save', { authorization: 'Bearer secret' }, notJson],
+  ['/api/usage', {}, notJson],
+  ['/api/client-error', sameOrigin, notJson],
+  ['/api/dev-inspect', sameOrigin, notJson],
+  ['/api/dev-inspect/page', sameOrigin, notJson],
+  ['/lowdefy-docs/state-checkpoints/load', {}, 'Bad Request'],
+  ['/lowdefy-docs/state-checkpoints/snapshot', {}, 'Bad Request'],
+  ['/lowdefy-feedback', sameOrigin, 'Bad Request'],
+])(
+  'POST %s with a body that is not JSON answers 400 and logs a warning',
+  async (path, headers, text) => {
+    const res = await createApp().request(path, { method: 'POST', body: 'nope', headers });
+    expect(res.status).toBe(400);
+    expect(await res.text()).toBe(text);
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.error).not.toHaveBeenCalled();
+  }
+);
+
+test('POST /api/endpoints with a null body answers 400', async () => {
+  const res = await createApp().request('/api/endpoints/save', { method: 'POST', body: 'null' });
+  expect(res.status).toBe(400);
+  expect(await res.json()).toEqual({
+    name: 'UserError',
+    message: 'Request body must be a JSON object.',
+  });
+});
+
+test('POST /api/endpoints to a webhook endpoint passes the body text exactly as sent as rawBody', async () => {
+  mockGetEndpointConfig.mockResolvedValueOnce({ webhook: { verify: {} } });
+  mockRunWebhookEndpoint.mockResolvedValue({ status: 200, body: { ok: true } });
+  const body = '{ "zeta": 1,  "alpha": "caf\\u00e9", "beta": "café" }';
+  const res = await createApp().request('/api/endpoints/signed_hook?t=1', {
+    method: 'POST',
+    body,
+    headers: { 'x-hub-signature-256': 'sha256=abc' },
+  });
+  expect(res.status).toBe(200);
+  expect(mockRunWebhookEndpoint).toHaveBeenCalledWith(expect.anything(), {
+    endpointId: 'signed_hook',
+    rawBody: body,
+    query: { t: '1' },
+    headers: expect.objectContaining({ 'x-hub-signature-256': 'sha256=abc' }),
+  });
+});
+
+test.each([
+  [200, { received: true }],
+  [401, { error: { code: 'unauthorized', message: 'Webhook verification failed.' } }],
+  [404, { error: 'not_found', id: 'ticket-1' }],
+  [500, { error: { code: 'internal_error', message: 'Webhook failed.' } }],
+])(
+  'POST /api/endpoints to a webhook endpoint answers status %s with its body',
+  async (status, body) => {
+    mockGetEndpointConfig.mockResolvedValueOnce({ webhook: true });
+    mockRunWebhookEndpoint.mockResolvedValue({ status, body });
+    const res = await createApp().request('/api/endpoints/hook', { method: 'POST', body: '{}' });
+    expect(res.status).toBe(status);
+    expect(await res.json()).toEqual(body);
+  }
+);

package/src/routes/usage.js

@@ -17,14 +17,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { parseRequestBody } from '@lowdefy/api';
+
 const packageJson = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
 
 async function usageHandler(c) {
   if (c.req.method !== 'POST') {
-    throw new Error('Only POST requests are supported.');
+    // A wrong-method request is client-caused: answer 405 rather than raising a
+    // fault that would be logged at error level and answered with a 500.
+    return c.json({ error: 'Method not allowed.' }, 405);
   }
   const context = c.get('lowdefyContext');
-  const { user, machine } = await c.req.json();
+  const { user, machine } = parseRequestBody({ text: await c.req.text() });
   const host = c.req.header('host');
   context.logger.info({ event: 'log_usage', user, machine });
 

package/src/routes/user.js

@@ -0,0 +1,27 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// The resolved caller for the client - the same resolveAuthentication output
+// the first page load embeds. The base session carries neither roles (read
+// live from the active member row) nor the merged attributes bag, so the
+// client re-syncs from here (UpdateSession) after a session change such as
+// SetActiveOrganization.
+async function userHandler(c) {
+  const context = c.get('lowdefyContext');
+  return c.json({ user: context.user ?? null });
+}
+
+export default userHandler;

package/src/routes/websocket.js

@@ -14,19 +14,40 @@
   limitations under the License.
 */
 
-import { setPendingWebSocketContext } from '../websocket/devWebSocket.js';
+import { isWebSocketOriginAllowed } from '@lowdefy/api';
+import { type } from '@lowdefy/helpers';
+
+import getStrategies from '../../lib/server/auth/getStrategies.js';
+import isRebindingSafeHost from '../middleware/isRebindingSafeHost.js';
 
 // In dev, Vite owns the HTTP server, so websocket upgrades can't flow through
-// @hono/node-server. The Vite plugin (see vite.config.js) fetches this route
-// with the upgrade request's headers to run the full middleware chain (auth
-// session, apiContext), and this handler hands the built context back to the
-// upgrade handler through a pending-context exchange keyed by request id.
+// @hono/node-server. The upgrade handler (src/websocket/devWebSocket.js) runs
+// this route with the upgrade request's headers so the full middleware chain
+// (auth session, apiContext) builds the request context, and passes a
+// websocketUpgrade object in the Hono env; this handler puts the context and
+// auth strategies on it. A plain HTTP request to this route carries no such object.
 function websocketHandler(c) {
-  const rid = c.req.header('x-lowdefy-websocket-rid');
-  if (!rid) {
+  const websocketUpgrade = c.env?.websocketUpgrade;
+  if (type.isNone(websocketUpgrade)) {
     return c.json({ message: 'WebSocket upgrade required.' }, 400);
   }
-  setPendingWebSocketContext(rid, c.get('lowdefyContext'));
+  // Vite's host check guards HTTP requests against DNS rebinding, but upgrades
+  // reach this route through a plugin's upgrade listener, past that check - and
+  // a rebound page's Origin matches its Host. So the Host must be one no DNS
+  // answer can rebind, as Vite requires of every HTTP request.
+  if (!isRebindingSafeHost({ host: c.req.header('host') })) {
+    return c.json({ error: 'Forbidden' }, 403);
+  }
+  const context = c.get('lowdefyContext');
+  // Upgrades are accepted from the app's own pages and from clients that send
+  // no Origin; isWebSocketOriginAllowed holds the rule and logs a refusal.
+  if (!isWebSocketOriginAllowed({ context, getHeader: (name) => c.req.header(name) })) {
+    return c.json({ error: 'Forbidden' }, 403);
+  }
+  websocketUpgrade.context = context;
+  // The connection resolves its caller again while the socket is open, with
+  // the upgrade's headers and the strategies of the current build.
+  websocketUpgrade.strategies = getStrategies({ logger: context.logger });
   return c.json({ ok: true });
 }
 

package/src/routes/websocket.test.mjs

@@ -0,0 +1,65 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Hono } from 'hono';
+import { jest } from '@jest/globals';
+
+const mockStrategies = [];
+jest.unstable_mockModule('../../lib/server/auth/getStrategies.js', () => ({
+  default: () => mockStrategies,
+}));
+
+const { default: websocketHandler } = await import('./websocket.js');
+
+// The dev upgrade listener (src/websocket/devWebSocket.js) runs this route
+// through the app and opens the websocket only on a 200 that carries the
+// context - so a refusal here is a refused upgrade.
+async function upgrade({ headers }) {
+  const app = new Hono().basePath('/app');
+  app.use('*', async (c, next) => {
+    c.set('lowdefyContext', { config: {}, logger: { warn: () => {} }, rid: 'request' });
+    await next();
+  });
+  app.get('/api/websocket', websocketHandler);
+  const websocketUpgrade = { context: null, strategies: null };
+  const res = await app.request('/app/api/websocket', { headers }, { websocketUpgrade });
+  return {
+    status: res.status,
+    context: websocketUpgrade.context,
+    strategies: websocketUpgrade.strategies,
+  };
+}
+
+test.each([
+  ['the dev app page opens it', { host: 'localhost:4100', origin: 'http://localhost:4100' }],
+  ['a client sends no origin', { host: 'localhost:4100' }],
+])('the dev websocket route opens the upgrade when %s', async (_, headers) => {
+  expect(await upgrade({ headers })).toEqual({
+    status: 200,
+    context: expect.any(Object),
+    strategies: mockStrategies,
+  });
+});
+
+test.each([
+  ['the origin is another site', { host: 'localhost:4100', origin: 'https://other.test' }],
+  [
+    'a rebound domain names itself in both host and origin',
+    { host: 'rebound.test:4100', origin: 'http://rebound.test:4100' },
+  ],
+])('the dev websocket route refuses the upgrade when %s', async (_, headers) => {
+  expect(await upgrade({ headers })).toEqual({ status: 403, context: null, strategies: null });
+});

package/src/routes/wellKnownFallback.js

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// RFC 8615 well-known URIs are machine-facing: a path this deployment does not
+// serve must answer 404, never the app's HTML shell. Serving 200 HTML breaks
+// clients that probe discovery documents - an MCP client's OAuth probe, for
+// example, fails with "Failed to parse JSON" instead of learning there is no
+// auth to discover. Mounted after the real discovery documents, before the
+// page catch-all.
+function wellKnownFallbackHandler(c) {
+  return c.json(
+    { name: 'NotFoundError', message: `No well-known document at ${c.req.path}.` },
+    404
+  );
+}
+
+export default wellKnownFallbackHandler;

package/src/routes/wellKnownFallback.test.mjs

@@ -0,0 +1,32 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { jest } from '@jest/globals';
+
+import wellKnownFallbackHandler from './wellKnownFallback.js';
+
+test('an unserved well-known path answers 404 JSON, never the app shell', () => {
+  const json = jest.fn((data, status) => ({ data, status }));
+  const result = wellKnownFallbackHandler({
+    req: { path: '/.well-known/oauth-protected-resource' },
+    json,
+  });
+  expect(result.status).toBe(404);
+  expect(result.data).toEqual({
+    name: 'NotFoundError',
+    message: 'No well-known document at /.well-known/oauth-protected-resource.',
+  });
+});

package/src/websocket/devWebSocket.js

@@ -14,54 +14,69 @@
   limitations under the License.
 */
 
-import { randomUUID } from 'node:crypto';
+import { STATUS_CODES } from 'node:http';
 import { createChannelRegistry, createWebSocketConnection } from '@lowdefy/api';
+import { type } from '@lowdefy/helpers';
 
-import app from '../app.js';
+import createLogger from '../../lib/server/log/createLogger.js';
+
+const logger = createLogger();
 
 // One registry per dev server process, shared by all websocket connections.
 const registry = createChannelRegistry();
 
-// Contexts built by the /api/websocket route (full middleware chain) are
-// handed to the upgrade handler through this exchange, keyed by request id.
-const pendingContexts = new Map();
-
-function setPendingWebSocketContext(rid, context) {
-  pendingContexts.set(rid, context);
-}
-
-function takePendingWebSocketContext(rid) {
-  const context = pendingContexts.get(rid);
-  pendingContexts.delete(rid);
-  return context;
-}
-
-// Called by the Vite plugin on an HTTP upgrade for /api/websocket. Runs the
-// dev Hono app for the upgrade request (auth session + apiContext), then
-// completes the websocket handshake and wires the connection to the registry.
-async function handleWebSocketUpgrade({ request, socket, head, wss }) {
-  const rid = randomUUID();
+// Called by the Vite plugin (see vite.config.js) on an HTTP upgrade for
+// /api/websocket, with the dev Hono app. Runs the app for the upgrade request
+// (auth session + apiContext) and receives the request context through the
+// websocketUpgrade object in the Hono env, then completes the websocket
+// handshake and wires the connection to the registry. The context travels
+// with the request, not through state shared between modules, so the upgrade
+// works however Vite has re-evaluated the app's modules after a rebuild.
+async function handleWebSocketUpgrade({ app, request, socket, head, wss }) {
   const headers = new Headers();
   Object.entries(request.headers).forEach(([key, value]) => {
     if (value) {
       headers.set(key, Array.isArray(value) ? value[0] : value);
     }
   });
-  headers.set('x-lowdefy-websocket-rid', rid);
 
   const url = `http://${request.headers.host ?? 'localhost'}${request.url}`;
-  const response = await app.fetch(new Request(url, { headers }));
-  const context = takePendingWebSocketContext(rid);
+  const websocketUpgrade = { context: null, strategies: null };
+  const response = await app.fetch(new Request(url, { headers }), { websocketUpgrade });
+
+  if (response.status !== 200) {
+    const body = await response.text();
+    logger.warn(
+      { event: 'ws_upgrade_refused', status: response.status },
+      `WebSocket upgrade refused: ${request.url} answered ${response.status}. ${body}`
+    );
+    socket.end(
+      `HTTP/1.1 ${response.status} ${STATUS_CODES[response.status]}\r\nConnection: close\r\n\r\n`
+    );
+    return;
+  }
 
-  if (!context || response.status !== 200) {
+  // A 200 without a context means the request reached another handler than
+  // the websocket route (a route or middleware answered first).
+  const { context, strategies } = websocketUpgrade;
+  if (type.isNone(context)) {
+    logger.warn(
+      { event: 'ws_upgrade_refused', status: response.status },
+      `WebSocket upgrade refused: ${request.url} answered ${response.status} without a request context; the websocket route did not run.`
+    );
     socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n');
     return;
   }
 
   wss.handleUpgrade(request, socket, head, (ws) => {
+    // The upgrade's headers stay with the connection: its caller is resolved
+    // from them again while the socket is open.
     const connection = createWebSocketConnection(context, {
+      closeSocket: ({ code, reason }) => ws.close(code, reason),
+      headers,
       registry,
       send: (message) => ws.send(message),
+      strategies,
     });
     ws.on('message', (data) => {
       connection.handleMessage(data.toString());
@@ -75,4 +90,4 @@ async function handleWebSocketUpgrade({ request, socket, head, wss }) {
   });
 }
 
-export { handleWebSocketUpgrade, setPendingWebSocketContext };
+export { handleWebSocketUpgrade };