@syncular/server-hono 0.0.6-158 → 0.0.6-165

package/src/console/gateway.ts

@@ -2,13 +2,14 @@ import type { Context } from 'hono';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 import type { UpgradeWebSocket } from 'hono/ws';
-import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
+import { resolver, validator as zValidator } from 'hono-openapi';
 import { z } from 'zod';
 import {
   closeUnauthenticatedSocket,
   parseBearerToken,
   parseWebSocketAuthToken,
 } from './live-auth';
+import { describeConsoleGatewayRoute } from './route-descriptor';
 import type {
   ConsoleApiKey,
   ConsoleApiKeyBulkRevokeResponse,
@@ -87,6 +88,10 @@ export interface CreateConsoleGatewayRoutesOptions {
     upgradeWebSocket?: UpgradeWebSocket;
     heartbeatIntervalMs?: number;
     createWebSocket?: (url: string) => ConsoleGatewayDownstreamSocket;
+    maxMessageBytes?: number;
+    maxMessagesPerWindow?: number;
+    messageRateWindowMs?: number;
+    allowedOrigins?: string[] | '*';
   };
 }
 
@@ -1268,8 +1273,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/instances',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'List configured downstream console instances',
       responses: {
         200: {
@@ -1306,8 +1310,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/instances/health',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'Probe downstream console health by instance',
       responses: {
         200: {
@@ -1366,8 +1369,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/handlers',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'List handlers for a single target instance (requires instance selection)',
       responses: {
@@ -1398,8 +1400,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/prune/preview',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Preview prune on a single target instance (requires instance selection)',
       responses: {
@@ -1430,8 +1431,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/prune',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Trigger prune on a single target instance (requires instance selection)',
       responses: {
@@ -1462,8 +1462,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/compact',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Trigger compaction on a single target instance (requires instance selection)',
       responses: {
@@ -1494,8 +1493,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/notify-data-change',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Notify data change on a single target instance (requires instance selection)',
       responses: {
@@ -1529,8 +1527,7 @@ export function createConsoleGatewayRoutes(
 
   routes.delete(
     '/clients/:id',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Evict client on a single target instance (requires instance selection)',
       responses: {
@@ -1563,8 +1560,7 @@ export function createConsoleGatewayRoutes(
 
   routes.delete(
     '/events',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Clear request events on a single target instance (requires instance selection)',
       responses: {
@@ -1595,8 +1591,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/events/prune',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Prune request events on a single target instance (requires instance selection)',
       responses: {
@@ -1627,8 +1622,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/api-keys',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'List API keys for a single target instance (requires instance selection)',
       responses: {
@@ -1663,8 +1657,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/api-keys',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Create API key on a single target instance (requires instance selection)',
       responses: {
@@ -1698,8 +1691,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/api-keys/:id',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Get API key from a single target instance (requires instance selection)',
       responses: {
@@ -1732,8 +1724,7 @@ export function createConsoleGatewayRoutes(
 
   routes.delete(
     '/api-keys/:id',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Revoke API key on a single target instance (requires instance selection)',
       responses: {
@@ -1766,8 +1757,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/api-keys/bulk-revoke',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Bulk revoke API keys on a single target instance (requires instance selection)',
       responses: {
@@ -1801,8 +1791,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/api-keys/:id/rotate/stage',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Stage-rotate API key on a single target instance (requires instance selection)',
       responses: {
@@ -1835,8 +1824,7 @@ export function createConsoleGatewayRoutes(
 
   routes.post(
     '/api-keys/:id/rotate',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary:
         'Rotate API key on a single target instance (requires instance selection)',
       responses: {
@@ -1869,8 +1857,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/stats',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'Get merged sync stats across instances',
       responses: {
         200: {
@@ -1950,8 +1937,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/stats/timeseries',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'Get merged time-series stats across instances',
       responses: {
         200: {
@@ -2003,8 +1989,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/stats/latency',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'Get merged latency stats across instances',
       responses: {
         200: {
@@ -2057,8 +2042,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/commits',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'List merged commits across instances',
       responses: {
         200: {
@@ -2137,8 +2121,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/commits/:seq',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'Get merged commit detail by federated id',
       responses: {
         200: {
@@ -2208,8 +2191,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/clients',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'List merged clients across instances',
       responses: {
         200: {
@@ -2285,8 +2267,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/timeline',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'List merged timeline items across instances',
       responses: {
         200: {
@@ -2382,8 +2363,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/operations',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'List merged operation events across instances',
       responses: {
         200: {
@@ -2463,8 +2443,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/events',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'List merged request events across instances',
       responses: {
         200: {
@@ -2548,6 +2527,9 @@ export function createConsoleGatewayRoutes(
   ) {
     const upgradeWebSocket = options.websocket.upgradeWebSocket;
     const heartbeatIntervalMs = options.websocket.heartbeatIntervalMs ?? 30000;
+    const maxMessageBytes = options.websocket.maxMessageBytes ?? 1024 * 1024;
+    const maxMessagesPerWindow = options.websocket.maxMessagesPerWindow ?? 120;
+    const messageRateWindowMs = options.websocket.messageRateWindowMs ?? 10000;
     const createDownstreamSocket =
       options.websocket.createWebSocket ??
       ((url: string): ConsoleGatewayDownstreamSocket => new WebSocket(url));
@@ -2565,288 +2547,320 @@ export function createConsoleGatewayRoutes(
         authTimeout: ReturnType<typeof setTimeout> | null;
         isAuthenticated: boolean;
         startAuthenticatedSession: ((token: string | null) => void) | null;
+        messageRateWindowStart: number;
+        messageRateWindowCount: number;
       }
     >();
 
-    routes.get(
-      '/events/live',
-      upgradeWebSocket(async (c) => {
-        const initialAuth = await options.authenticate(c);
-        const partitionId = c.req.query('partitionId')?.trim() || undefined;
-        const replaySince = c.req.query('since')?.trim() || undefined;
-        const replayLimitRaw = c.req.query('replayLimit');
-        const replayLimitNumber = replayLimitRaw
-          ? Number.parseInt(replayLimitRaw, 10)
-          : Number.NaN;
-        const replayLimit = Number.isFinite(replayLimitNumber)
-          ? Math.max(1, Math.min(500, replayLimitNumber))
-          : 100;
-
-        const selectedInstances = selectInstances({
-          instances,
-          query: {
-            instanceId: c.req.query('instanceId') ?? undefined,
-            instanceIds: c.req.query('instanceIds') ?? undefined,
+    const liveEventsWebSocketRoute = upgradeWebSocket(async (c) => {
+      const initialAuth = await options.authenticate(c);
+      const partitionId = c.req.query('partitionId')?.trim() || undefined;
+      const replaySince = c.req.query('since')?.trim() || undefined;
+      const replayLimitRaw = c.req.query('replayLimit');
+      const replayLimitNumber = replayLimitRaw
+        ? Number.parseInt(replayLimitRaw, 10)
+        : Number.NaN;
+      const replayLimit = Number.isFinite(replayLimitNumber)
+        ? Math.max(1, Math.min(500, replayLimitNumber))
+        : 100;
+
+      const selectedInstances = selectInstances({
+        instances,
+        query: {
+          instanceId: c.req.query('instanceId') ?? undefined,
+          instanceIds: c.req.query('instanceIds') ?? undefined,
+        },
+      });
+
+      const authenticateWithBearer = async (
+        token: string
+      ): Promise<ConsoleAuthResult | null> => {
+        const trimmedToken = token.trim();
+        if (!trimmedToken) {
+          return null;
+        }
+        const authContext = {
+          req: {
+            header: (name: string) =>
+              name === 'Authorization' ? `Bearer ${trimmedToken}` : undefined,
+            query: () => undefined,
           },
-        });
+        } as unknown as Context;
+        return options.authenticate(authContext);
+      };
 
-        const authenticateWithBearer = async (
-          token: string
-        ): Promise<ConsoleAuthResult | null> => {
-          const trimmedToken = token.trim();
-          if (!trimmedToken) {
-            return null;
+      const cleanup = (ws: WebSocketLike) => {
+        const state = liveState.get(ws);
+        if (!state) return;
+        if (state.heartbeatInterval) {
+          clearInterval(state.heartbeatInterval);
+        }
+        if (state.authTimeout) {
+          clearTimeout(state.authTimeout);
+        }
+        for (const downstream of state.downstreamSockets) {
+          try {
+            downstream.close();
+          } catch {
+            // no-op
           }
-          const authContext = {
-            req: {
-              header: (name: string) =>
-                name === 'Authorization' ? `Bearer ${trimmedToken}` : undefined,
-              query: () => undefined,
-            },
-          } as unknown as Context;
-          return options.authenticate(authContext);
-        };
+        }
+        liveState.delete(ws);
+      };
 
-        const cleanup = (ws: WebSocketLike) => {
-          const state = liveState.get(ws);
-          if (!state) return;
-          if (state.heartbeatInterval) {
-            clearInterval(state.heartbeatInterval);
-          }
-          if (state.authTimeout) {
-            clearTimeout(state.authTimeout);
-          }
-          for (const downstream of state.downstreamSockets) {
-            try {
-              downstream.close();
-            } catch {
-              // no-op
-            }
+      return {
+        onOpen(_event, ws) {
+          if (selectedInstances.length === 0) {
+            ws.send(
+              JSON.stringify({
+                type: 'error',
+                message:
+                  'No enabled instances matched the provided instance filter.',
+              })
+            );
+            ws.close(4004, 'No instances selected');
+            return;
           }
-          liveState.delete(ws);
-        };
-
-        return {
-          onOpen(_event, ws) {
-            if (selectedInstances.length === 0) {
-              ws.send(
-                JSON.stringify({
-                  type: 'error',
-                  message:
-                    'No enabled instances matched the provided instance filter.',
-                })
-              );
-              ws.close(4004, 'No instances selected');
+
+          const state: {
+            downstreamSockets: ConsoleGatewayDownstreamSocket[];
+            heartbeatInterval: ReturnType<typeof setInterval> | null;
+            authTimeout: ReturnType<typeof setTimeout> | null;
+            isAuthenticated: boolean;
+            startAuthenticatedSession: ((token: string | null) => void) | null;
+            messageRateWindowStart: number;
+            messageRateWindowCount: number;
+          } = {
+            downstreamSockets: [],
+            heartbeatInterval: null,
+            authTimeout: null,
+            isAuthenticated: false,
+            startAuthenticatedSession: null,
+            messageRateWindowStart: Date.now(),
+            messageRateWindowCount: 0,
+          };
+          liveState.set(ws, state);
+
+          const startAuthenticatedSession = (
+            upstreamBearerToken: string | null
+          ) => {
+            if (state.isAuthenticated) {
               return;
             }
+            state.isAuthenticated = true;
+            if (state.authTimeout) {
+              clearTimeout(state.authTimeout);
+              state.authTimeout = null;
+            }
 
-            const state: {
-              downstreamSockets: ConsoleGatewayDownstreamSocket[];
-              heartbeatInterval: ReturnType<typeof setInterval> | null;
-              authTimeout: ReturnType<typeof setTimeout> | null;
-              isAuthenticated: boolean;
-              startAuthenticatedSession:
-                | ((token: string | null) => void)
-                | null;
-            } = {
-              downstreamSockets: [],
-              heartbeatInterval: null,
-              authTimeout: null,
-              isAuthenticated: false,
-              startAuthenticatedSession: null,
-            };
-            liveState.set(ws, state);
-
-            const startAuthenticatedSession = (
-              upstreamBearerToken: string | null
-            ) => {
-              if (state.isAuthenticated) {
-                return;
+            for (const instance of selectedInstances) {
+              const downstreamQuery = new URLSearchParams();
+              if (partitionId) {
+                downstreamQuery.set('partitionId', partitionId);
               }
-              state.isAuthenticated = true;
-              if (state.authTimeout) {
-                clearTimeout(state.authTimeout);
-                state.authTimeout = null;
+              if (replaySince) {
+                downstreamQuery.set('since', replaySince);
               }
-
-              for (const instance of selectedInstances) {
-                const downstreamQuery = new URLSearchParams();
-                if (partitionId) {
-                  downstreamQuery.set('partitionId', partitionId);
-                }
-                if (replaySince) {
-                  downstreamQuery.set('since', replaySince);
-                }
-                downstreamQuery.set('replayLimit', String(replayLimit));
-
-                const downstreamUrl = buildConsoleEndpointUrl({
-                  instance,
-                  requestUrl: c.req.url,
-                  path: '/events/live',
-                  query: downstreamQuery,
-                });
-
-                const downstreamSocket = createDownstreamSocket(downstreamUrl);
-                const downstreamToken =
-                  instance.token?.trim() ?? upstreamBearerToken?.trim() ?? null;
-                if (downstreamToken && downstreamSocket.send) {
-                  downstreamSocket.onopen = () => {
-                    try {
-                      downstreamSocket.send?.(
-                        JSON.stringify({
-                          type: 'auth',
-                          token: downstreamToken,
-                        })
-                      );
-                    } catch {
-                      // no-op
-                    }
-                  };
-                }
-
-                downstreamSocket.onmessage = (message: MessageEvent) => {
-                  if (typeof message.data !== 'string') {
-                    return;
-                  }
+              downstreamQuery.set('replayLimit', String(replayLimit));
+
+              const downstreamUrl = buildConsoleEndpointUrl({
+                instance,
+                requestUrl: c.req.url,
+                path: '/events/live',
+                query: downstreamQuery,
+              });
+
+              const downstreamSocket = createDownstreamSocket(downstreamUrl);
+              const downstreamToken =
+                instance.token?.trim() ?? upstreamBearerToken?.trim() ?? null;
+              if (downstreamToken && downstreamSocket.send) {
+                downstreamSocket.onopen = () => {
                   try {
-                    const payload = JSON.parse(message.data) as Record<
-                      string,
-                      unknown
-                    >;
-                    if (
-                      typeof payload.type === 'string' &&
-                      (payload.type === 'connected' ||
-                        payload.type === 'heartbeat')
-                    ) {
-                      return;
-                    }
-
-                    const payloadData =
-                      payload.data &&
-                      typeof payload.data === 'object' &&
-                      !Array.isArray(payload.data)
-                        ? { ...payload.data, instanceId: instance.instanceId }
-                        : { instanceId: instance.instanceId };
-
-                    const event = {
-                      ...payload,
-                      data: payloadData,
-                      instanceId: instance.instanceId,
-                      timestamp:
-                        typeof payload.timestamp === 'string'
-                          ? payload.timestamp
-                          : new Date().toISOString(),
-                    };
-                    ws.send(JSON.stringify(event));
-                  } catch {
-                    // Ignore malformed downstream events
-                  }
-                };
-
-                downstreamSocket.onerror = () => {
-                  try {
-                    ws.send(
+                    downstreamSocket.send?.(
                       JSON.stringify({
-                        type: 'instance_error',
-                        instanceId: instance.instanceId,
-                        timestamp: new Date().toISOString(),
+                        type: 'auth',
+                        token: downstreamToken,
                       })
                     );
                   } catch {
-                    // ignore send errors
+                    // no-op
                   }
                 };
-
-                state.downstreamSockets.push(downstreamSocket);
               }
 
-              ws.send(
-                JSON.stringify({
-                  type: 'connected',
-                  timestamp: new Date().toISOString(),
-                  instanceCount: selectedInstances.length,
-                })
-              );
+              downstreamSocket.onmessage = (message: MessageEvent) => {
+                if (typeof message.data !== 'string') {
+                  return;
+                }
+                try {
+                  const payload = JSON.parse(message.data) as Record<
+                    string,
+                    unknown
+                  >;
+                  if (
+                    typeof payload.type === 'string' &&
+                    (payload.type === 'connected' ||
+                      payload.type === 'heartbeat')
+                  ) {
+                    return;
+                  }
+
+                  const payloadData =
+                    payload.data &&
+                    typeof payload.data === 'object' &&
+                    !Array.isArray(payload.data)
+                      ? { ...payload.data, instanceId: instance.instanceId }
+                      : { instanceId: instance.instanceId };
+
+                  const event = {
+                    ...payload,
+                    data: payloadData,
+                    instanceId: instance.instanceId,
+                    timestamp:
+                      typeof payload.timestamp === 'string'
+                        ? payload.timestamp
+                        : new Date().toISOString(),
+                  };
+                  ws.send(JSON.stringify(event));
+                } catch {
+                  // Ignore malformed downstream events
+                }
+              };
 
-              const heartbeatInterval = setInterval(() => {
+              downstreamSocket.onerror = () => {
                 try {
                   ws.send(
                     JSON.stringify({
-                      type: 'heartbeat',
+                      type: 'instance_error',
+                      instanceId: instance.instanceId,
                       timestamp: new Date().toISOString(),
                     })
                   );
                 } catch {
-                  clearInterval(heartbeatInterval);
+                  // ignore send errors
                 }
-              }, heartbeatIntervalMs);
-              state.heartbeatInterval = heartbeatInterval;
-            };
-            state.startAuthenticatedSession = startAuthenticatedSession;
-
-            if (initialAuth) {
-              startAuthenticatedSession(
-                parseBearerToken(c.req.header('Authorization'))
-              );
-              return;
+              };
+
+              state.downstreamSockets.push(downstreamSocket);
             }
 
-            state.authTimeout = setTimeout(() => {
-              const current = liveState.get(ws);
-              if (!current || current.isAuthenticated) {
-                return;
+            ws.send(
+              JSON.stringify({
+                type: 'connected',
+                timestamp: new Date().toISOString(),
+                instanceCount: selectedInstances.length,
+              })
+            );
+
+            const heartbeatInterval = setInterval(() => {
+              try {
+                ws.send(
+                  JSON.stringify({
+                    type: 'heartbeat',
+                    timestamp: new Date().toISOString(),
+                  })
+                );
+              } catch {
+                clearInterval(heartbeatInterval);
               }
-              closeUnauthenticatedSocket(ws);
-              cleanup(ws);
-            }, 5_000);
-          },
-          async onMessage(event, ws) {
-            const state = liveState.get(ws);
-            if (!state || state.isAuthenticated) {
-              return;
-            }
+            }, heartbeatIntervalMs);
+            state.heartbeatInterval = heartbeatInterval;
+          };
+          state.startAuthenticatedSession = startAuthenticatedSession;
+
+          if (initialAuth) {
+            startAuthenticatedSession(
+              parseBearerToken(c.req.header('Authorization'))
+            );
+            return;
+          }
 
-            if (typeof event.data !== 'string') {
-              closeUnauthenticatedSocket(ws);
-              cleanup(ws);
+          state.authTimeout = setTimeout(() => {
+            const current = liveState.get(ws);
+            if (!current || current.isAuthenticated) {
               return;
             }
+            closeUnauthenticatedSocket(ws);
+            cleanup(ws);
+          }, 5_000);
+        },
+        async onMessage(event, ws) {
+          const state = liveState.get(ws);
+          if (!state) {
+            return;
+          }
 
-            const token = parseWebSocketAuthToken(event.data);
+          const messageBytes = measureWebSocketMessageBytes(event.data);
+          if (messageBytes > maxMessageBytes) {
+            ws.close(1009, 'message too large');
+            cleanup(ws);
+            return;
+          }
 
-            if (!token) {
-              closeUnauthenticatedSocket(ws);
-              cleanup(ws);
-              return;
+          if (maxMessagesPerWindow > 0 && messageRateWindowMs > 0) {
+            const nowMs = Date.now();
+            if (nowMs - state.messageRateWindowStart >= messageRateWindowMs) {
+              state.messageRateWindowStart = nowMs;
+              state.messageRateWindowCount = 0;
             }
-
-            const auth = await authenticateWithBearer(token);
-            const current = liveState.get(ws);
-            if (!current || current.isAuthenticated) {
-              return;
-            }
-            if (!auth) {
-              closeUnauthenticatedSocket(ws);
+            state.messageRateWindowCount += 1;
+            if (state.messageRateWindowCount > maxMessagesPerWindow) {
+              ws.close(1008, 'message rate exceeded');
               cleanup(ws);
               return;
             }
-            current.startAuthenticatedSession?.(token);
-          },
-          onClose(_event, ws) {
+          }
+
+          if (state.isAuthenticated) {
+            return;
+          }
+
+          if (typeof event.data !== 'string') {
+            closeUnauthenticatedSocket(ws);
             cleanup(ws);
-          },
-          onError(_event, ws) {
+            return;
+          }
+
+          const token = parseWebSocketAuthToken(event.data);
+
+          if (!token) {
+            closeUnauthenticatedSocket(ws);
             cleanup(ws);
-          },
-        };
-      })
-    );
+            return;
+          }
+
+          const auth = await authenticateWithBearer(token);
+          const current = liveState.get(ws);
+          if (!current || current.isAuthenticated) {
+            return;
+          }
+          if (!auth) {
+            closeUnauthenticatedSocket(ws);
+            cleanup(ws);
+            return;
+          }
+          current.startAuthenticatedSession?.(token);
+        },
+        onClose(_event, ws) {
+          cleanup(ws);
+        },
+        onError(_event, ws) {
+          cleanup(ws);
+        },
+      };
+    });
+
+    routes.get('/events/live', async (c, next) => {
+      if (!isWebSocketOriginAllowed(c, options.websocket?.allowedOrigins)) {
+        return c.json({ error: 'FORBIDDEN_ORIGIN' }, 403);
+      }
+      return liveEventsWebSocketRoute(c, next);
+    });
   }
 
   routes.get(
     '/events/:id',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'Get merged event detail by federated id',
       responses: {
         200: {
@@ -2920,8 +2934,7 @@ export function createConsoleGatewayRoutes(
 
   routes.get(
     '/events/:id/payload',
-    describeRoute({
-      tags: ['console-gateway'],
+    describeConsoleGatewayRoute({
       summary: 'Get merged event payload by federated id',
       responses: {
         200: {
@@ -2995,3 +3008,37 @@ export function createConsoleGatewayRoutes(
 
   return routes;
 }
+
+function isWebSocketOriginAllowed(
+  c: Context,
+  allowedOrigins?: string[] | '*'
+): boolean {
+  if (!allowedOrigins) return true;
+  if (allowedOrigins === '*') return true;
+
+  const origin = c.req.header('origin');
+  if (!origin) return false;
+
+  try {
+    const normalizedOrigin = new URL(origin).origin;
+    return allowedOrigins.includes(normalizedOrigin);
+  } catch {
+    return false;
+  }
+}
+
+function measureWebSocketMessageBytes(data: unknown): number {
+  if (typeof data === 'string') {
+    return new TextEncoder().encode(data).byteLength;
+  }
+  if (data instanceof ArrayBuffer) {
+    return data.byteLength;
+  }
+  if (ArrayBuffer.isView(data)) {
+    return data.byteLength;
+  }
+  if (typeof Blob !== 'undefined' && data instanceof Blob) {
+    return data.size;
+  }
+  return new TextEncoder().encode(String(data)).byteLength;
+}