@syncular/server-hono 0.0.6-125 → 0.0.6-135

package/src/console/gateway.ts

@@ -4,20 +4,19 @@ import { cors } from 'hono/cors';
 import type { UpgradeWebSocket } from 'hono/ws';
 import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
 import { z } from 'zod';
+import {
+  closeUnauthenticatedSocket,
+  parseBearerToken,
+  parseWebSocketAuthToken,
+} from './live-auth';
 import type {
   ConsoleApiKey,
   ConsoleApiKeyBulkRevokeResponse,
   ConsoleApiKeyCreateResponse,
-  ConsoleClearEventsResult,
   ConsoleClient,
   ConsoleCommitListItem,
-  ConsoleCompactResult,
-  ConsoleEvictResult,
   ConsoleOperationEvent,
   ConsolePaginatedResponse,
-  ConsolePruneEventsResult,
-  ConsolePrunePreview,
-  ConsolePruneResult,
   ConsoleRequestEvent,
   ConsoleTimelineItem,
   LatencyPercentiles,
@@ -155,6 +154,11 @@ const GatewaySingleInstanceQuerySchema = GatewayInstanceFilterSchema;
 const GatewaySingleInstancePartitionQuerySchema =
   ConsolePartitionQuerySchema.extend(GatewayInstanceFilterSchema.shape);
 
+type GatewayInstanceFilterQuery = {
+  instanceId?: string;
+  instanceIds?: string;
+};
+
 const GatewayApiKeyStatusSchema = z.enum(['active', 'revoked', 'expiring']);
 
 const GatewayApiKeysQuerySchema = ConsolePaginationQuerySchema.extend({
@@ -416,84 +420,58 @@ function parseLocalNumericId(value: string): number | null {
   return parsed;
 }
 
-function resolveEventTarget(args: {
-  id: string;
+function noInstancesSelectedResponse(): {
+  ok: false;
+  status: 400;
+  error: 'NO_INSTANCES_SELECTED';
+  message: string;
+} {
+  return {
+    ok: false,
+    status: 400,
+    error: 'NO_INSTANCES_SELECTED',
+    message: 'No enabled instances matched the provided instance filter.',
+  };
+}
+
+function resolveSingleSelectedInstance(args: {
   instances: ConsoleGatewayInstance[];
-  query: { instanceId?: string; instanceIds?: string };
+  query: GatewayInstanceFilterQuery;
+  onMultiple: { error: string; message: string };
 }):
-  | { ok: true; instance: ConsoleGatewayInstance; localEventId: number }
-  | { ok: false; status: 400 | 404; error: string; message?: string } {
-  const federated = parseFederatedNumericId(args.id);
-  if (federated) {
-    const instance = findInstanceById({
-      instances: args.instances,
-      instanceId: federated.instanceId,
-    });
-    if (!instance) {
-      return {
-        ok: false,
-        status: 404,
-        error: 'NOT_FOUND',
-        message: 'Instance not found',
-      };
-    }
-    return { ok: true, instance, localEventId: federated.localId };
-  }
-
-  const localEventId = parseLocalNumericId(args.id);
-  if (localEventId === null) {
-    return {
-      ok: false,
-      status: 400,
-      error: 'INVALID_FEDERATED_ID',
-      message:
-        'Expected either "<instanceId>:<eventId>" or "<eventId>" with an explicit instance filter.',
-    };
-  }
-
-  const selectedInstances = selectInstances({
-    instances: args.instances,
-    query: args.query,
-  });
+  | { ok: true; instance: ConsoleGatewayInstance }
+  | { ok: false; status: 400; error: string; message: string } {
+  const selectedInstances = selectInstances(args);
   if (selectedInstances.length === 0) {
-    return {
-      ok: false,
-      status: 400,
-      error: 'NO_INSTANCES_SELECTED',
-      message: 'No enabled instances matched the provided instance filter.',
-    };
+    return noInstancesSelectedResponse();
   }
   if (selectedInstances.length > 1) {
     return {
       ok: false,
       status: 400,
-      error: 'AMBIGUOUS_EVENT_ID',
-      message:
-        'Local event IDs are ambiguous across multiple instances. Use "<instanceId>:<eventId>" or select one instance.',
+      error: args.onMultiple.error,
+      message: args.onMultiple.message,
     };
   }
 
   const instance = selectedInstances[0];
   if (!instance) {
-    return {
-      ok: false,
-      status: 400,
-      error: 'NO_INSTANCES_SELECTED',
-      message: 'No enabled instances matched the provided instance filter.',
-    };
+    return noInstancesSelectedResponse();
   }
-
-  return { ok: true, instance, localEventId };
+  return { ok: true, instance };
 }
 
-function resolveCommitTarget(args: {
-  seq: string;
+function resolveFederatedOrLocalNumericTarget(args: {
+  id: string;
   instances: ConsoleGatewayInstance[];
-  query: { instanceId?: string; instanceIds?: string };
+  query: GatewayInstanceFilterQuery;
+  invalidMessage: string;
+  ambiguousError: string;
+  ambiguousMessage: string;
 }):
-  | { ok: true; instance: ConsoleGatewayInstance; localCommitSeq: number }
+  | { ok: true; instance: ConsoleGatewayInstance; localId: number }
   | { ok: false; status: 400 | 404; error: string; message?: string } {
-  const federated = parseFederatedNumericId(args.seq);
+  const federated = parseFederatedNumericId(args.id);
   if (federated) {
     const instance = findInstanceById({
       instances: args.instances,
@@ -507,92 +485,96 @@ function resolveCommitTarget(args: {
         message: 'Instance not found',
       };
     }
-    return { ok: true, instance, localCommitSeq: federated.localId };
+    return { ok: true, instance, localId: federated.localId };
   }
 
-  const localCommitSeq = parseLocalNumericId(args.seq);
-  if (localCommitSeq === null) {
+  const localId = parseLocalNumericId(args.id);
+  if (localId === null) {
     return {
       ok: false,
       status: 400,
       error: 'INVALID_FEDERATED_ID',
-      message:
-        'Expected either "<instanceId>:<commitSeq>" or "<commitSeq>" with an explicit instance filter.',
+      message: args.invalidMessage,
     };
   }
 
-  const selectedInstances = selectInstances({
+  const selection = resolveSingleSelectedInstance({
     instances: args.instances,
     query: args.query,
+    onMultiple: {
+      error: args.ambiguousError,
+      message: args.ambiguousMessage,
+    },
   });
-  if (selectedInstances.length === 0) {
-    return {
-      ok: false,
-      status: 400,
-      error: 'NO_INSTANCES_SELECTED',
-      message: 'No enabled instances matched the provided instance filter.',
-    };
-  }
-  if (selectedInstances.length > 1) {
-    return {
-      ok: false,
-      status: 400,
-      error: 'AMBIGUOUS_COMMIT_ID',
-      message:
-        'Local commit IDs are ambiguous across multiple instances. Use "<instanceId>:<commitSeq>" or select one instance.',
-    };
-  }
+  if (!selection.ok) return selection;
 
-  const instance = selectedInstances[0];
-  if (!instance) {
-    return {
-      ok: false,
-      status: 400,
-      error: 'NO_INSTANCES_SELECTED',
-      message: 'No enabled instances matched the provided instance filter.',
-    };
-  }
+  return { ok: true, instance: selection.instance, localId };
+}
+
+function resolveEventTarget(args: {
+  id: string;
+  instances: ConsoleGatewayInstance[];
+  query: GatewayInstanceFilterQuery;
+}):
+  | { ok: true; instance: ConsoleGatewayInstance; localEventId: number }
+  | { ok: false; status: 400 | 404; error: string; message?: string } {
+  const resolved = resolveFederatedOrLocalNumericTarget({
+    id: args.id,
+    instances: args.instances,
+    query: args.query,
+    invalidMessage:
+      'Expected either "<instanceId>:<eventId>" or "<eventId>" with an explicit instance filter.',
+    ambiguousError: 'AMBIGUOUS_EVENT_ID',
+    ambiguousMessage:
+      'Local event IDs are ambiguous across multiple instances. Use "<instanceId>:<eventId>" or select one instance.',
+  });
+  if (!resolved.ok) return resolved;
+  return {
+    ok: true,
+    instance: resolved.instance,
+    localEventId: resolved.localId,
+  };
+}
 
-  return { ok: true, instance, localCommitSeq };
+function resolveCommitTarget(args: {
+  seq: string;
+  instances: ConsoleGatewayInstance[];
+  query: GatewayInstanceFilterQuery;
+}):
+  | { ok: true; instance: ConsoleGatewayInstance; localCommitSeq: number }
+  | { ok: false; status: 400 | 404; error: string; message?: string } {
+  const resolved = resolveFederatedOrLocalNumericTarget({
+    id: args.seq,
+    instances: args.instances,
+    query: args.query,
+    invalidMessage:
+      'Expected either "<instanceId>:<commitSeq>" or "<commitSeq>" with an explicit instance filter.',
+    ambiguousError: 'AMBIGUOUS_COMMIT_ID',
+    ambiguousMessage:
+      'Local commit IDs are ambiguous across multiple instances. Use "<instanceId>:<commitSeq>" or select one instance.',
+  });
+  if (!resolved.ok) return resolved;
+  return {
+    ok: true,
+    instance: resolved.instance,
+    localCommitSeq: resolved.localId,
+  };
 }
 
 function resolveSingleInstanceTarget(args: {
   instances: ConsoleGatewayInstance[];
-  query: { instanceId?: string; instanceIds?: string };
+  query: GatewayInstanceFilterQuery;
 }):
   | { ok: true; instance: ConsoleGatewayInstance }
   | { ok: false; status: 400; error: string; message: string } {
-  const selectedInstances = selectInstances(args);
-  if (selectedInstances.length === 0) {
-    return {
-      ok: false,
-      status: 400,
-      error: 'NO_INSTANCES_SELECTED',
-      message: 'No enabled instances matched the provided instance filter.',
-    };
-  }
-
-  if (selectedInstances.length > 1) {
-    return {
-      ok: false,
-      status: 400,
+  return resolveSingleSelectedInstance({
+    ...args,
+    onMultiple: {
       error: 'INSTANCE_REQUIRED',
       message:
         'This endpoint requires exactly one target instance. Provide `instanceId` or a single-value `instanceIds` filter.',
-    };
-  }
-
-  const instance = selectedInstances[0];
-  if (!instance) {
-    return {
-      ok: false,
-      status: 400,
-      error: 'NO_INSTANCES_SELECTED',
-      message: 'No enabled instances matched the provided instance filter.',
-    };
-  }
-
-  return { ok: true, instance };
+    },
+  });
 }
 
 function minNullable(values: Array<number | null>): number | null {
@@ -728,17 +710,6 @@ function resolveForwardAuthorization(args: {
   return null;
 }
 
-function parseBearerToken(
-  authHeader: string | null | undefined
-): string | null {
-  const value = authHeader?.trim();
-  if (!value?.startsWith('Bearer ')) {
-    return null;
-  }
-  const token = value.slice(7).trim();
-  return token.length > 0 ? token : null;
-}
-
 async function fetchDownstreamJson<T>(args: {
   c: Context;
   instance: ConsoleGatewayInstance;
@@ -1079,6 +1050,222 @@ export function createConsoleGatewayRoutes(
     })
   );
 
+  const withGatewayAuth = async (
+    c: Context,
+    callback: () => Promise<Response>
+  ): Promise<Response> => {
+    const auth = await options.authenticate(c);
+    if (!auth) {
+      return unauthorizedResponse(c);
+    }
+    return callback();
+  };
+
+  const proxySingleInstanceJsonRequest = async <T>(args: {
+    c: Context;
+    query: { instanceId?: string; instanceIds?: string };
+    method: 'GET' | 'POST' | 'DELETE';
+    path: string;
+    responseSchema: z.ZodType<T>;
+    body?: unknown;
+  }): Promise<Response> => {
+    const target = resolveSingleInstanceTarget({
+      instances,
+      query: args.query,
+    });
+    if (!target.ok) {
+      return args.c.json(
+        {
+          error: target.error,
+          message: target.message,
+        },
+        target.status
+      );
+    }
+
+    const forwardQuery = sanitizeForwardQueryParams(
+      new URL(args.c.req.url).searchParams
+    );
+    const result = await forwardDownstreamJsonRequest<T>({
+      c: args.c,
+      instance: target.instance,
+      method: args.method,
+      path: args.path,
+      query: forwardQuery,
+      ...(args.body === undefined ? {} : { body: args.body }),
+      responseSchema: args.responseSchema,
+      fetchImpl,
+    });
+
+    if (!result.ok) {
+      return jsonResponse(result.body, result.status);
+    }
+
+    return jsonResponse(result.data, result.status);
+  };
+
+  const selectTargetInstances = (
+    c: Context,
+    query: GatewayInstanceFilterQuery
+  ):
+    | { ok: true; selectedInstances: ConsoleGatewayInstance[] }
+    | { ok: false; response: Response } => {
+    const selectedInstances = selectInstances({ instances, query });
+    if (selectedInstances.length > 0) {
+      return { ok: true, selectedInstances };
+    }
+
+    const noInstanceError = noInstancesSelectedResponse();
+    return {
+      ok: false,
+      response: c.json(
+        {
+          error: noInstanceError.error,
+          message: noInstanceError.message,
+        },
+        noInstanceError.status
+      ),
+    };
+  };
+
+  const fetchFromSelectedInstances = async <T>(args: {
+    c: Context;
+    selectedInstances: ConsoleGatewayInstance[];
+    path: string;
+    query: URLSearchParams;
+    schema: z.ZodType<T>;
+  }): Promise<
+    | {
+        ok: true;
+        successfulResults: Array<{
+          instance: ConsoleGatewayInstance;
+          data: T;
+        }>;
+        failedInstances: GatewayFailure[];
+      }
+    | { ok: false; response: Response }
+  > => {
+    const results = await Promise.all(
+      args.selectedInstances.map((instance) =>
+        fetchDownstreamJson({
+          c: args.c,
+          instance,
+          path: args.path,
+          query: args.query,
+          schema: args.schema,
+          fetchImpl,
+        })
+      )
+    );
+
+    const failedInstances = results
+      .filter(
+        (result): result is { ok: false; failure: GatewayFailure } => !result.ok
+      )
+      .map((result) => result.failure);
+    const successfulResults = results
+      .map((result, index) => ({
+        result,
+        instance: args.selectedInstances[index],
+      }))
+      .filter(
+        (
+          entry
+        ): entry is {
+          result: { ok: true; data: T };
+          instance: ConsoleGatewayInstance;
+        } => Boolean(entry.instance) && entry.result.ok
+      )
+      .map((entry) => ({
+        instance: entry.instance,
+        data: entry.result.data,
+      }));
+
+    if (successfulResults.length === 0) {
+      return {
+        ok: false,
+        response: allInstancesFailedResponse(args.c, failedInstances),
+      };
+    }
+
+    return {
+      ok: true,
+      successfulResults,
+      failedInstances,
+    };
+  };
+
+  const fetchPagedFromSelectedInstances = async <T>(args: {
+    c: Context;
+    selectedInstances: ConsoleGatewayInstance[];
+    path: string;
+    query: URLSearchParams;
+    targetCount: number;
+    schema: z.ZodType<ConsolePaginatedResponse<T>>;
+  }): Promise<
+    | {
+        ok: true;
+        successfulResults: Array<{
+          instance: ConsoleGatewayInstance;
+          items: T[];
+          total: number;
+        }>;
+        failedInstances: GatewayFailure[];
+      }
+    | { ok: false; response: Response }
+  > => {
+    const results = await Promise.all(
+      args.selectedInstances.map((instance) =>
+        fetchDownstreamPaged({
+          c: args.c,
+          instance,
+          path: args.path,
+          query: args.query,
+          targetCount: args.targetCount,
+          schema: args.schema,
+          fetchImpl,
+        })
+      )
+    );
+
+    const failedInstances = results
+      .filter(
+        (result): result is { ok: false; failure: GatewayFailure } => !result.ok
+      )
+      .map((result) => result.failure);
+    const successfulResults = results
+      .map((result, index) => ({
+        result,
+        instance: args.selectedInstances[index],
+      }))
+      .filter(
+        (
+          entry
+        ): entry is {
+          result: { ok: true; items: T[]; total: number };
+          instance: ConsoleGatewayInstance;
+        } => Boolean(entry.instance) && entry.result.ok
+      )
+      .map((entry) => ({
+        instance: entry.instance,
+        items: entry.result.items,
+        total: entry.result.total,
+      }));
+
+    if (successfulResults.length === 0) {
+      return {
+        ok: false,
+        response: allInstancesFailedResponse(args.c, failedInstances),
+      };
+    }
+
+    return {
+      ok: true,
+      successfulResults,
+      failedInstances,
+    };
+  };
+
   routes.get(
     '/instances',
     describeRoute({
@@ -1104,18 +1291,15 @@ export function createConsoleGatewayRoutes(
       },
     }),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      return c.json({
-        items: instances.map((instance) => ({
-          instanceId: instance.instanceId,
-          label: instance.label ?? instance.instanceId,
-          baseUrl: instance.baseUrl,
-          enabled: instance.enabled ?? true,
-        })),
+      return withGatewayAuth(c, async () => {
+        return c.json({
+          items: instances.map((instance) => ({
+            instanceId: instance.instanceId,
+            label: instance.label ?? instance.instanceId,
+            baseUrl: instance.baseUrl,
+            enabled: instance.enabled ?? true,
+          })),
+        });
       });
     }
   );
@@ -1146,46 +1330,36 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayInstanceFilterSchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
+        const items = await Promise.all(
+          selection.selectedInstances.map((instance) =>
+            checkDownstreamInstanceHealth({
+              c,
+              instance,
+              fetchImpl,
+            })
+          )
         );
-      }
-
-      const items = await Promise.all(
-        selectedInstances.map((instance) =>
-          checkDownstreamInstanceHealth({
-            c,
-            instance,
-            fetchImpl,
-          })
-        )
-      );
 
-      const failedInstances = items
-        .filter((item) => !item.healthy)
-        .map((item) => ({
-          instanceId: item.instanceId,
-          reason: item.reason ?? 'Health probe failed',
-          ...(item.status !== undefined ? { status: item.status } : {}),
-        }));
-
-      return c.json({
-        items,
-        partial: failedInstances.length > 0,
-        failedInstances,
+        const failedInstances = items
+          .filter((item) => !item.healthy)
+          .map((item) => ({
+            instanceId: item.instanceId,
+            reason: item.reason ?? 'Health probe failed',
+            ...(item.status !== undefined ? { status: item.status } : {}),
+          }));
+
+        return c.json({
+          items,
+          partial: failedInstances.length > 0,
+          failedInstances,
+        });
       });
     }
   );
@@ -1209,41 +1383,16 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest({
-        c,
-        instance: target.instance,
-        method: 'GET',
-        path: '/handlers',
-        query: forwardQuery,
-        responseSchema: GatewayHandlersResponseSchema,
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest({
+          c,
+          query,
+          method: 'GET',
+          path: '/handlers',
+          responseSchema: GatewayHandlersResponseSchema,
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1266,41 +1415,16 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest<ConsolePrunePreview>({
-        c,
-        instance: target.instance,
-        method: 'POST',
-        path: '/prune/preview',
-        query: forwardQuery,
-        responseSchema: ConsolePrunePreviewSchema,
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest({
+          c,
+          query,
+          method: 'POST',
+          path: '/prune/preview',
+          responseSchema: ConsolePrunePreviewSchema,
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1323,41 +1447,16 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest<ConsolePruneResult>({
-        c,
-        instance: target.instance,
-        method: 'POST',
-        path: '/prune',
-        query: forwardQuery,
-        responseSchema: ConsolePruneResultSchema,
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest({
+          c,
+          query,
+          method: 'POST',
+          path: '/prune',
+          responseSchema: ConsolePruneResultSchema,
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1380,41 +1479,16 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest<ConsoleCompactResult>({
-        c,
-        instance: target.instance,
-        method: 'POST',
-        path: '/compact',
-        query: forwardQuery,
-        responseSchema: ConsoleCompactResultSchema,
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest({
+          c,
+          query,
+          method: 'POST',
+          path: '/compact',
+          responseSchema: ConsoleCompactResultSchema,
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1438,43 +1512,18 @@ export function createConsoleGatewayRoutes(
     zValidator('query', GatewaySingleInstanceQuerySchema),
     zValidator('json', GatewayNotifyDataChangeRequestSchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const body = c.req.valid('json');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest({
-        c,
-        instance: target.instance,
-        method: 'POST',
-        path: '/notify-data-change',
-        query: forwardQuery,
-        body,
-        responseSchema: GatewayNotifyDataChangeResponseSchema,
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const body = c.req.valid('json');
+        return proxySingleInstanceJsonRequest({
+          c,
+          query,
+          method: 'POST',
+          path: '/notify-data-change',
+          body,
+          responseSchema: GatewayNotifyDataChangeResponseSchema,
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1498,42 +1547,17 @@ export function createConsoleGatewayRoutes(
     zValidator('param', GatewayClientPathParamSchema),
     zValidator('query', GatewaySingleInstancePartitionQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const { id } = c.req.valid('param');
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest<ConsoleEvictResult>({
-        c,
-        instance: target.instance,
-        method: 'DELETE',
-        path: `/clients/${encodeURIComponent(id)}`,
-        query: forwardQuery,
-        responseSchema: ConsoleEvictResultSchema,
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const { id } = c.req.valid('param');
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest({
+          c,
+          query,
+          method: 'DELETE',
+          path: `/clients/${encodeURIComponent(id)}`,
+          responseSchema: ConsoleEvictResultSchema,
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1556,42 +1580,16 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result =
-        await forwardDownstreamJsonRequest<ConsoleClearEventsResult>({
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest({
           c,
-          instance: target.instance,
+          query,
           method: 'DELETE',
           path: '/events',
-          query: forwardQuery,
           responseSchema: ConsoleClearEventsResultSchema,
-          fetchImpl,
         });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
+      });
     }
   );
 
@@ -1614,42 +1612,16 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result =
-        await forwardDownstreamJsonRequest<ConsolePruneEventsResult>({
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest({
           c,
-          instance: target.instance,
+          query,
           method: 'POST',
           path: '/events/prune',
-          query: forwardQuery,
           responseSchema: ConsolePruneEventsResultSchema,
-          fetchImpl,
         });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
+      });
     }
   );
 
@@ -1674,43 +1646,18 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayApiKeysQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest<
-        ConsolePaginatedResponse<ConsoleApiKey>
-      >({
-        c,
-        instance: target.instance,
-        method: 'GET',
-        path: '/api-keys',
-        query: forwardQuery,
-        responseSchema: ConsolePaginatedResponseSchema(ConsoleApiKeySchema),
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest<
+          ConsolePaginatedResponse<ConsoleApiKey>
+        >({
+          c,
+          query,
+          method: 'GET',
+          path: '/api-keys',
+          responseSchema: ConsolePaginatedResponseSchema(ConsoleApiKeySchema),
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1734,44 +1681,18 @@ export function createConsoleGatewayRoutes(
     zValidator('query', GatewaySingleInstanceQuerySchema),
     zValidator('json', ConsoleApiKeyCreateRequestSchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const body = c.req.valid('json');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result =
-        await forwardDownstreamJsonRequest<ConsoleApiKeyCreateResponse>({
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const body = c.req.valid('json');
+        return proxySingleInstanceJsonRequest<ConsoleApiKeyCreateResponse>({
           c,
-          instance: target.instance,
+          query,
           method: 'POST',
           path: '/api-keys',
-          query: forwardQuery,
           body,
           responseSchema: ConsoleApiKeyCreateResponseSchema,
-          fetchImpl,
         });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
+      });
     }
   );
 
@@ -1795,42 +1716,17 @@ export function createConsoleGatewayRoutes(
     zValidator('param', GatewayApiKeyPathParamSchema),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const { id } = c.req.valid('param');
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest<ConsoleApiKey>({
-        c,
-        instance: target.instance,
-        method: 'GET',
-        path: `/api-keys/${encodeURIComponent(id)}`,
-        query: forwardQuery,
-        responseSchema: ConsoleApiKeySchema,
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const { id } = c.req.valid('param');
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest<ConsoleApiKey>({
+          c,
+          query,
+          method: 'GET',
+          path: `/api-keys/${encodeURIComponent(id)}`,
+          responseSchema: ConsoleApiKeySchema,
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1854,42 +1750,17 @@ export function createConsoleGatewayRoutes(
     zValidator('param', GatewayApiKeyPathParamSchema),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const { id } = c.req.valid('param');
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await forwardDownstreamJsonRequest<{ revoked: boolean }>({
-        c,
-        instance: target.instance,
-        method: 'DELETE',
-        path: `/api-keys/${encodeURIComponent(id)}`,
-        query: forwardQuery,
-        responseSchema: ConsoleApiKeyRevokeResponseSchema,
-        fetchImpl,
+      return withGatewayAuth(c, async () => {
+        const { id } = c.req.valid('param');
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest<{ revoked: boolean }>({
+          c,
+          query,
+          method: 'DELETE',
+          path: `/api-keys/${encodeURIComponent(id)}`,
+          responseSchema: ConsoleApiKeyRevokeResponseSchema,
+        });
       });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
     }
   );
 
@@ -1913,44 +1784,18 @@ export function createConsoleGatewayRoutes(
     zValidator('query', GatewaySingleInstanceQuerySchema),
     zValidator('json', ConsoleApiKeyBulkRevokeRequestSchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const body = c.req.valid('json');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result =
-        await forwardDownstreamJsonRequest<ConsoleApiKeyBulkRevokeResponse>({
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const body = c.req.valid('json');
+        return proxySingleInstanceJsonRequest<ConsoleApiKeyBulkRevokeResponse>({
           c,
-          instance: target.instance,
+          query,
           method: 'POST',
           path: '/api-keys/bulk-revoke',
-          query: forwardQuery,
           body,
           responseSchema: ConsoleApiKeyBulkRevokeResponseSchema,
-          fetchImpl,
         });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
+      });
     }
   );
 
@@ -1974,43 +1819,17 @@ export function createConsoleGatewayRoutes(
     zValidator('param', GatewayApiKeyPathParamSchema),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const { id } = c.req.valid('param');
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result =
-        await forwardDownstreamJsonRequest<ConsoleApiKeyCreateResponse>({
+      return withGatewayAuth(c, async () => {
+        const { id } = c.req.valid('param');
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest<ConsoleApiKeyCreateResponse>({
           c,
-          instance: target.instance,
+          query,
           method: 'POST',
           path: `/api-keys/${encodeURIComponent(id)}/rotate/stage`,
-          query: forwardQuery,
           responseSchema: ConsoleApiKeyCreateResponseSchema,
-          fetchImpl,
         });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
+      });
     }
   );
 
@@ -2034,43 +1853,17 @@ export function createConsoleGatewayRoutes(
     zValidator('param', GatewayApiKeyPathParamSchema),
     zValidator('query', GatewaySingleInstanceQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const { id } = c.req.valid('param');
-      const query = c.req.valid('query');
-      const target = resolveSingleInstanceTarget({ instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            message: target.message,
-          },
-          target.status
-        );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result =
-        await forwardDownstreamJsonRequest<ConsoleApiKeyCreateResponse>({
+      return withGatewayAuth(c, async () => {
+        const { id } = c.req.valid('param');
+        const query = c.req.valid('query');
+        return proxySingleInstanceJsonRequest<ConsoleApiKeyCreateResponse>({
           c,
-          instance: target.instance,
+          query,
           method: 'POST',
           path: `/api-keys/${encodeURIComponent(id)}/rotate`,
-          query: forwardQuery,
           responseSchema: ConsoleApiKeyCreateResponseSchema,
-          fetchImpl,
         });
-
-      if (!result.ok) {
-        return jsonResponse(result.body, result.status);
-      }
-
-      return jsonResponse(result.data, result.status);
+      });
     }
   );
 
@@ -2092,96 +1885,65 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayStatsQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-
-      const results = await Promise.all(
-        selectedInstances.map((instance) =>
-          fetchDownstreamJson({
-            c,
-            instance,
-            path: '/stats',
-            query: forwardQuery,
-            schema: SyncStatsSchema,
-            fetchImpl,
-          })
-        )
-      );
-
-      const failedInstances = results
-        .filter(
-          (result): result is { ok: false; failure: GatewayFailure } =>
-            !result.ok
-        )
-        .map((result) => result.failure);
-      const successfulResults = results.filter(
-        (result): result is { ok: true; data: SyncStats } => result.ok
-      );
-
-      if (successfulResults.length === 0) {
-        return allInstancesFailedResponse(c, failedInstances);
-      }
+        const fetched = await fetchFromSelectedInstances<SyncStats>({
+          c,
+          selectedInstances: selection.selectedInstances,
+          path: '/stats',
+          query: forwardQuery,
+          schema: SyncStatsSchema,
+        });
+        if (!fetched.ok) {
+          return fetched.response;
+        }
 
-      const statsByInstance = new Map<string, SyncStats>();
-      for (let i = 0; i < selectedInstances.length; i++) {
-        const result = results[i];
-        if (!result || !result.ok) continue;
-        const instance = selectedInstances[i];
-        if (!instance) continue;
-        statsByInstance.set(instance.instanceId, result.data);
-      }
+        const statsByInstance = new Map<string, SyncStats>();
+        for (const result of fetched.successfulResults) {
+          statsByInstance.set(result.instance.instanceId, result.data);
+        }
 
-      const statsValues = Array.from(statsByInstance.values());
-      const sum = (selector: (stats: SyncStats) => number): number =>
-        statsValues.reduce((acc, stats) => acc + selector(stats), 0);
+        const statsValues = Array.from(statsByInstance.values());
+        const sum = (selector: (stats: SyncStats) => number): number =>
+          statsValues.reduce((acc, stats) => acc + selector(stats), 0);
 
-      const minCommitSeqByInstance: Record<string, number> = {};
-      const maxCommitSeqByInstance: Record<string, number> = {};
-      for (const [instanceId, stats] of statsByInstance.entries()) {
-        minCommitSeqByInstance[instanceId] = stats.minCommitSeq;
-        maxCommitSeqByInstance[instanceId] = stats.maxCommitSeq;
-      }
+        const minCommitSeqByInstance: Record<string, number> = {};
+        const maxCommitSeqByInstance: Record<string, number> = {};
+        for (const [instanceId, stats] of statsByInstance.entries()) {
+          minCommitSeqByInstance[instanceId] = stats.minCommitSeq;
+          maxCommitSeqByInstance[instanceId] = stats.maxCommitSeq;
+        }
 
-      return c.json({
-        commitCount: sum((stats) => stats.commitCount),
-        changeCount: sum((stats) => stats.changeCount),
-        minCommitSeq: Math.min(
-          ...statsValues.map((stats) => stats.minCommitSeq)
-        ),
-        maxCommitSeq: Math.max(
-          ...statsValues.map((stats) => stats.maxCommitSeq)
-        ),
-        clientCount: sum((stats) => stats.clientCount),
-        activeClientCount: sum((stats) => stats.activeClientCount),
-        minActiveClientCursor: minNullable(
-          statsValues.map((stats) => stats.minActiveClientCursor)
-        ),
-        maxActiveClientCursor: maxNullable(
-          statsValues.map((stats) => stats.maxActiveClientCursor)
-        ),
-        minCommitSeqByInstance,
-        maxCommitSeqByInstance,
-        partial: failedInstances.length > 0,
-        failedInstances,
+        return c.json({
+          commitCount: sum((stats) => stats.commitCount),
+          changeCount: sum((stats) => stats.changeCount),
+          minCommitSeq: Math.min(
+            ...statsValues.map((stats) => stats.minCommitSeq)
+          ),
+          maxCommitSeq: Math.max(
+            ...statsValues.map((stats) => stats.maxCommitSeq)
+          ),
+          clientCount: sum((stats) => stats.clientCount),
+          activeClientCount: sum((stats) => stats.activeClientCount),
+          minActiveClientCursor: minNullable(
+            statsValues.map((stats) => stats.minActiveClientCursor)
+          ),
+          maxActiveClientCursor: maxNullable(
+            statsValues.map((stats) => stats.maxActiveClientCursor)
+          ),
+          minCommitSeqByInstance,
+          maxCommitSeqByInstance,
+          partial: fetched.failedInstances.length > 0,
+          failedInstances: fetched.failedInstances,
+        });
       });
     }
   );
@@ -2204,64 +1966,37 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayTimeseriesQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-
-      const results = await Promise.all(
-        selectedInstances.map((instance) =>
-          fetchDownstreamJson({
+        const fetched =
+          await fetchFromSelectedInstances<TimeseriesStatsResponse>({
             c,
-            instance,
+            selectedInstances: selection.selectedInstances,
             path: '/stats/timeseries',
             query: forwardQuery,
             schema: TimeseriesStatsResponseSchema,
-            fetchImpl,
-          })
-        )
-      );
-
-      const failedInstances = results
-        .filter(
-          (result): result is { ok: false; failure: GatewayFailure } =>
-            !result.ok
-        )
-        .map((result) => result.failure);
-      const successfulResults = results.filter(
-        (result): result is { ok: true; data: TimeseriesStatsResponse } =>
-          result.ok
-      );
-
-      if (successfulResults.length === 0) {
-        return allInstancesFailedResponse(c, failedInstances);
-      }
+          });
+        if (!fetched.ok) {
+          return fetched.response;
+        }
 
-      return c.json({
-        buckets: mergeTimeseriesBuckets(
-          successfulResults.map((result) => result.data)
-        ),
-        interval: query.interval,
-        range: query.range,
-        partial: failedInstances.length > 0,
-        failedInstances,
+        return c.json({
+          buckets: mergeTimeseriesBuckets(
+            fetched.successfulResults.map((result) => result.data)
+          ),
+          interval: query.interval,
+          range: query.range,
+          partial: fetched.failedInstances.length > 0,
+          failedInstances: fetched.failedInstances,
+        });
       });
     }
   );
@@ -2284,66 +2019,38 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayLatencyQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-
-      const results = await Promise.all(
-        selectedInstances.map((instance) =>
-          fetchDownstreamJson({
-            c,
-            instance,
-            path: '/stats/latency',
-            query: forwardQuery,
-            schema: LatencyStatsResponseSchema,
-            fetchImpl,
-          })
-        )
-      );
-
-      const failedInstances = results
-        .filter(
-          (result): result is { ok: false; failure: GatewayFailure } =>
-            !result.ok
-        )
-        .map((result) => result.failure);
-      const successfulResults = results.filter(
-        (result): result is { ok: true; data: LatencyStatsResponse } =>
-          result.ok
-      );
-
-      if (successfulResults.length === 0) {
-        return allInstancesFailedResponse(c, failedInstances);
-      }
+        const fetched = await fetchFromSelectedInstances<LatencyStatsResponse>({
+          c,
+          selectedInstances: selection.selectedInstances,
+          path: '/stats/latency',
+          query: forwardQuery,
+          schema: LatencyStatsResponseSchema,
+        });
+        if (!fetched.ok) {
+          return fetched.response;
+        }
 
-      return c.json({
-        push: averagePercentiles(
-          successfulResults.map((result) => result.data.push)
-        ),
-        pull: averagePercentiles(
-          successfulResults.map((result) => result.data.pull)
-        ),
-        range: query.range,
-        partial: failedInstances.length > 0,
-        failedInstances,
+        return c.json({
+          push: averagePercentiles(
+            fetched.successfulResults.map((result) => result.data.push)
+          ),
+          pull: averagePercentiles(
+            fetched.successfulResults.map((result) => result.data.pull)
+          ),
+          range: query.range,
+          partial: fetched.failedInstances.length > 0,
+          failedInstances: fetched.failedInstances,
+        });
       });
     }
   );
@@ -2368,95 +2075,62 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayPaginatedQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
+        const targetCount = query.offset + query.limit;
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const targetCount = query.offset + query.limit;
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      forwardQuery.delete('limit');
-      forwardQuery.delete('offset');
-      const pageSchema = ConsolePaginatedResponseSchema(
-        ConsoleCommitListItemSchema
-      );
-
-      const results = await Promise.all(
-        selectedInstances.map((instance) =>
-          fetchDownstreamPaged({
+        forwardQuery.delete('limit');
+        forwardQuery.delete('offset');
+        const pageSchema = ConsolePaginatedResponseSchema(
+          ConsoleCommitListItemSchema
+        );
+        const fetched =
+          await fetchPagedFromSelectedInstances<ConsoleCommitListItem>({
             c,
-            instance,
+            selectedInstances: selection.selectedInstances,
             path: '/commits',
             query: forwardQuery,
             targetCount,
             schema: pageSchema,
-            fetchImpl,
-          })
-        )
-      );
-
-      const failedInstances = results
-        .filter(
-          (result): result is { ok: false; failure: GatewayFailure } =>
-            !result.ok
-        )
-        .map((result) => result.failure);
-      const successful = results
-        .map((result, index) => ({
-          result,
-          instance: selectedInstances[index],
-        }))
-        .filter(
-          (
-            entry
-          ): entry is {
-            result: { ok: true; items: ConsoleCommitListItem[]; total: number };
-            instance: ConsoleGatewayInstance;
-          } => Boolean(entry.instance) && entry.result.ok
-        );
-
-      if (successful.length === 0) {
-        return allInstancesFailedResponse(c, failedInstances);
-      }
+          });
+        if (!fetched.ok) {
+          return fetched.response;
+        }
 
-      const merged = successful
-        .flatMap(({ result, instance }) =>
-          result.items.map((commit) => ({
-            ...commit,
-            instanceId: instance.instanceId,
-            federatedCommitId: `${instance.instanceId}:${commit.commitSeq}`,
-          }))
-        )
-        .sort((a, b) => {
-          const byTime = compareIsoDesc(a.createdAt, b.createdAt);
-          if (byTime !== 0) return byTime;
-          const byInstance = a.instanceId.localeCompare(b.instanceId);
-          if (byInstance !== 0) return byInstance;
-          return b.commitSeq - a.commitSeq;
+        const merged = fetched.successfulResults
+          .flatMap(({ items, instance }) =>
+            items.map((commit) => ({
+              ...commit,
+              instanceId: instance.instanceId,
+              federatedCommitId: `${instance.instanceId}:${commit.commitSeq}`,
+            }))
+          )
+          .sort((a, b) => {
+            const byTime = compareIsoDesc(a.createdAt, b.createdAt);
+            if (byTime !== 0) return byTime;
+            const byInstance = a.instanceId.localeCompare(b.instanceId);
+            if (byInstance !== 0) return byInstance;
+            return b.commitSeq - a.commitSeq;
+          });
+
+        return c.json({
+          items: merged.slice(query.offset, query.offset + query.limit),
+          total: fetched.successfulResults.reduce(
+            (acc, entry) => acc + entry.total,
+            0
+          ),
+          offset: query.offset,
+          limit: query.limit,
+          partial: fetched.failedInstances.length > 0,
+          failedInstances: fetched.failedInstances,
         });
-
-      return c.json({
-        items: merged.slice(query.offset, query.offset + query.limit),
-        total: successful.reduce((acc, entry) => acc + entry.result.total, 0),
-        offset: query.offset,
-        limit: query.limit,
-        partial: failedInstances.length > 0,
-        failedInstances,
       });
     }
   );
@@ -2483,54 +2157,51 @@ export function createConsoleGatewayRoutes(
       ConsolePartitionQuerySchema.extend(GatewayInstanceFilterSchema.shape)
     ),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const { seq } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const target = resolveCommitTarget({ seq, instances, query });
+        if (!target.ok) {
+          return c.json(
+            {
+              error: target.error,
+              ...(target.message ? { message: target.message } : {}),
+            },
+            target.status
+          );
+        }
 
-      const { seq } = c.req.valid('param');
-      const query = c.req.valid('query');
-      const target = resolveCommitTarget({ seq, instances, query });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            ...(target.message ? { message: target.message } : {}),
-          },
-          target.status
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await fetchDownstreamJson({
-        c,
-        instance: target.instance,
-        path: `/commits/${target.localCommitSeq}`,
-        query: forwardQuery,
-        schema: ConsoleCommitDetailSchema,
-        fetchImpl,
-      });
+        const result = await fetchDownstreamJson({
+          c,
+          instance: target.instance,
+          path: `/commits/${target.localCommitSeq}`,
+          query: forwardQuery,
+          schema: ConsoleCommitDetailSchema,
+          fetchImpl,
+        });
 
-      if (!result.ok) {
-        if (result.failure.status === 404) {
-          return c.json({ error: 'NOT_FOUND' }, 404);
+        if (!result.ok) {
+          if (result.failure.status === 404) {
+            return c.json({ error: 'NOT_FOUND' }, 404);
+          }
+          return c.json(
+            {
+              error: 'DOWNSTREAM_UNAVAILABLE',
+              failedInstances: [result.failure],
+            },
+            502
+          );
         }
-        return c.json(
-          {
-            error: 'DOWNSTREAM_UNAVAILABLE',
-            failedInstances: [result.failure],
-          },
-          502
-        );
-      }
 
-      return c.json({
-        ...result.data,
-        instanceId: target.instance.instanceId,
-        federatedCommitId: `${target.instance.instanceId}:${result.data.commitSeq}`,
-        localCommitSeq: result.data.commitSeq,
+        return c.json({
+          ...result.data,
+          instanceId: target.instance.instanceId,
+          federatedCommitId: `${target.instance.instanceId}:${result.data.commitSeq}`,
+          localCommitSeq: result.data.commitSeq,
+        });
       });
     }
   );
@@ -2555,93 +2226,59 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayPaginatedQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
-
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
-        );
-      }
-
-      const targetCount = query.offset + query.limit;
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      forwardQuery.delete('limit');
-      forwardQuery.delete('offset');
-      const pageSchema = ConsolePaginatedResponseSchema(ConsoleClientSchema);
-
-      const results = await Promise.all(
-        selectedInstances.map((instance) =>
-          fetchDownstreamPaged({
-            c,
-            instance,
-            path: '/clients',
-            query: forwardQuery,
-            targetCount,
-            schema: pageSchema,
-            fetchImpl,
-          })
-        )
-      );
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const failedInstances = results
-        .filter(
-          (result): result is { ok: false; failure: GatewayFailure } =>
-            !result.ok
-        )
-        .map((result) => result.failure);
-      const successful = results
-        .map((result, index) => ({
-          result,
-          instance: selectedInstances[index],
-        }))
-        .filter(
-          (
-            entry
-          ): entry is {
-            result: { ok: true; items: ConsoleClient[]; total: number };
-            instance: ConsoleGatewayInstance;
-          } => Boolean(entry.instance) && entry.result.ok
+        const targetCount = query.offset + query.limit;
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-
-      if (successful.length === 0) {
-        return allInstancesFailedResponse(c, failedInstances);
-      }
-
-      const merged = successful
-        .flatMap(({ result, instance }) =>
-          result.items.map((client) => ({
-            ...client,
-            instanceId: instance.instanceId,
-            federatedClientId: `${instance.instanceId}:${client.clientId}`,
-          }))
-        )
-        .sort((a, b) => {
-          const byTime = compareIsoDesc(a.updatedAt, b.updatedAt);
-          if (byTime !== 0) return byTime;
-          const byInstance = a.instanceId.localeCompare(b.instanceId);
-          if (byInstance !== 0) return byInstance;
-          return a.clientId.localeCompare(b.clientId);
+        forwardQuery.delete('limit');
+        forwardQuery.delete('offset');
+        const pageSchema = ConsolePaginatedResponseSchema(ConsoleClientSchema);
+        const fetched = await fetchPagedFromSelectedInstances<ConsoleClient>({
+          c,
+          selectedInstances: selection.selectedInstances,
+          path: '/clients',
+          query: forwardQuery,
+          targetCount,
+          schema: pageSchema,
         });
+        if (!fetched.ok) {
+          return fetched.response;
+        }
 
-      return c.json({
-        items: merged.slice(query.offset, query.offset + query.limit),
-        total: successful.reduce((acc, entry) => acc + entry.result.total, 0),
-        offset: query.offset,
-        limit: query.limit,
-        partial: failedInstances.length > 0,
-        failedInstances,
+        const merged = fetched.successfulResults
+          .flatMap(({ items, instance }) =>
+            items.map((client) => ({
+              ...client,
+              instanceId: instance.instanceId,
+              federatedClientId: `${instance.instanceId}:${client.clientId}`,
+            }))
+          )
+          .sort((a, b) => {
+            const byTime = compareIsoDesc(a.updatedAt, b.updatedAt);
+            if (byTime !== 0) return byTime;
+            const byInstance = a.instanceId.localeCompare(b.instanceId);
+            if (byInstance !== 0) return byInstance;
+            return a.clientId.localeCompare(b.clientId);
+          });
+
+        return c.json({
+          items: merged.slice(query.offset, query.offset + query.limit),
+          total: fetched.successfulResults.reduce(
+            (acc, entry) => acc + entry.total,
+            0
+          ),
+          offset: query.offset,
+          limit: query.limit,
+          partial: fetched.failedInstances.length > 0,
+          failedInstances: fetched.failedInstances,
+        });
       });
     }
   );
@@ -2666,110 +2303,79 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayTimelineQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
+        const targetCount = query.offset + query.limit;
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const targetCount = query.offset + query.limit;
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      forwardQuery.delete('limit');
-      forwardQuery.delete('offset');
-      const pageSchema = ConsolePaginatedResponseSchema(
-        ConsoleTimelineItemSchema
-      );
-
-      const results = await Promise.all(
-        selectedInstances.map((instance) =>
-          fetchDownstreamPaged({
+        forwardQuery.delete('limit');
+        forwardQuery.delete('offset');
+        const pageSchema = ConsolePaginatedResponseSchema(
+          ConsoleTimelineItemSchema
+        );
+        const fetched =
+          await fetchPagedFromSelectedInstances<ConsoleTimelineItem>({
             c,
-            instance,
+            selectedInstances: selection.selectedInstances,
             path: '/timeline',
             query: forwardQuery,
             targetCount,
             schema: pageSchema,
-            fetchImpl,
-          })
-        )
-      );
-
-      const failedInstances = results
-        .filter(
-          (result): result is { ok: false; failure: GatewayFailure } =>
-            !result.ok
-        )
-        .map((result) => result.failure);
-      const successful = results
-        .map((result, index) => ({
-          result,
-          instance: selectedInstances[index],
-        }))
-        .filter(
-          (
-            entry
-          ): entry is {
-            result: { ok: true; items: ConsoleTimelineItem[]; total: number };
-            instance: ConsoleGatewayInstance;
-          } => Boolean(entry.instance) && entry.result.ok
-        );
-
-      if (successful.length === 0) {
-        return allInstancesFailedResponse(c, failedInstances);
-      }
+          });
+        if (!fetched.ok) {
+          return fetched.response;
+        }
 
-      const merged = successful
-        .flatMap(({ result, instance }) =>
-          result.items.map((item) => {
-            const localCommitSeq =
-              item.type === 'commit' ? (item.commit?.commitSeq ?? null) : null;
-            const localEventId =
-              item.type === 'event' ? (item.event?.eventId ?? null) : null;
-            const localIdSegment =
-              item.type === 'commit'
-                ? String(localCommitSeq ?? 'unknown')
-                : String(localEventId ?? 'unknown');
-
-            return {
-              ...item,
-              instanceId: instance.instanceId,
-              federatedTimelineId: `${instance.instanceId}:${item.type}:${localIdSegment}`,
-              localCommitSeq,
-              localEventId,
-            };
-          })
-        )
-        .sort((a, b) => {
-          const byTime = compareIsoDesc(a.timestamp, b.timestamp);
-          if (byTime !== 0) return byTime;
-          const byInstance = a.instanceId.localeCompare(b.instanceId);
-          if (byInstance !== 0) return byInstance;
-          const aLocalId = a.localCommitSeq ?? a.localEventId ?? 0;
-          const bLocalId = b.localCommitSeq ?? b.localEventId ?? 0;
-          return bLocalId - aLocalId;
+        const merged = fetched.successfulResults
+          .flatMap(({ items, instance }) =>
+            items.map((item) => {
+              const localCommitSeq =
+                item.type === 'commit'
+                  ? (item.commit?.commitSeq ?? null)
+                  : null;
+              const localEventId =
+                item.type === 'event' ? (item.event?.eventId ?? null) : null;
+              const localIdSegment =
+                item.type === 'commit'
+                  ? String(localCommitSeq ?? 'unknown')
+                  : String(localEventId ?? 'unknown');
+
+              return {
+                ...item,
+                instanceId: instance.instanceId,
+                federatedTimelineId: `${instance.instanceId}:${item.type}:${localIdSegment}`,
+                localCommitSeq,
+                localEventId,
+              };
+            })
+          )
+          .sort((a, b) => {
+            const byTime = compareIsoDesc(a.timestamp, b.timestamp);
+            if (byTime !== 0) return byTime;
+            const byInstance = a.instanceId.localeCompare(b.instanceId);
+            if (byInstance !== 0) return byInstance;
+            const aLocalId = a.localCommitSeq ?? a.localEventId ?? 0;
+            const bLocalId = b.localCommitSeq ?? b.localEventId ?? 0;
+            return bLocalId - aLocalId;
+          });
+
+        return c.json({
+          items: merged.slice(query.offset, query.offset + query.limit),
+          total: fetched.successfulResults.reduce(
+            (acc, entry) => acc + entry.total,
+            0
+          ),
+          offset: query.offset,
+          limit: query.limit,
+          partial: fetched.failedInstances.length > 0,
+          failedInstances: fetched.failedInstances,
         });
-
-      return c.json({
-        items: merged.slice(query.offset, query.offset + query.limit),
-        total: successful.reduce((acc, entry) => acc + entry.result.total, 0),
-        offset: query.offset,
-        limit: query.limit,
-        partial: failedInstances.length > 0,
-        failedInstances,
       });
     }
   );
@@ -2794,96 +2400,63 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayOperationsQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
+        const targetCount = query.offset + query.limit;
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const targetCount = query.offset + query.limit;
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      forwardQuery.delete('limit');
-      forwardQuery.delete('offset');
-      const pageSchema = ConsolePaginatedResponseSchema(
-        ConsoleOperationEventSchema
-      );
-
-      const results = await Promise.all(
-        selectedInstances.map((instance) =>
-          fetchDownstreamPaged({
+        forwardQuery.delete('limit');
+        forwardQuery.delete('offset');
+        const pageSchema = ConsolePaginatedResponseSchema(
+          ConsoleOperationEventSchema
+        );
+        const fetched =
+          await fetchPagedFromSelectedInstances<ConsoleOperationEvent>({
             c,
-            instance,
+            selectedInstances: selection.selectedInstances,
             path: '/operations',
             query: forwardQuery,
             targetCount,
             schema: pageSchema,
-            fetchImpl,
-          })
-        )
-      );
-
-      const failedInstances = results
-        .filter(
-          (result): result is { ok: false; failure: GatewayFailure } =>
-            !result.ok
-        )
-        .map((result) => result.failure);
-      const successful = results
-        .map((result, index) => ({
-          result,
-          instance: selectedInstances[index],
-        }))
-        .filter(
-          (
-            entry
-          ): entry is {
-            result: { ok: true; items: ConsoleOperationEvent[]; total: number };
-            instance: ConsoleGatewayInstance;
-          } => Boolean(entry.instance) && entry.result.ok
-        );
-
-      if (successful.length === 0) {
-        return allInstancesFailedResponse(c, failedInstances);
-      }
+          });
+        if (!fetched.ok) {
+          return fetched.response;
+        }
 
-      const merged = successful
-        .flatMap(({ result, instance }) =>
-          result.items.map((operation) => ({
-            ...operation,
-            instanceId: instance.instanceId,
-            federatedOperationId: `${instance.instanceId}:${operation.operationId}`,
-            localOperationId: operation.operationId,
-          }))
-        )
-        .sort((a, b) => {
-          const byTime = compareIsoDesc(a.createdAt, b.createdAt);
-          if (byTime !== 0) return byTime;
-          const byInstance = a.instanceId.localeCompare(b.instanceId);
-          if (byInstance !== 0) return byInstance;
-          return b.localOperationId - a.localOperationId;
+        const merged = fetched.successfulResults
+          .flatMap(({ items, instance }) =>
+            items.map((operation) => ({
+              ...operation,
+              instanceId: instance.instanceId,
+              federatedOperationId: `${instance.instanceId}:${operation.operationId}`,
+              localOperationId: operation.operationId,
+            }))
+          )
+          .sort((a, b) => {
+            const byTime = compareIsoDesc(a.createdAt, b.createdAt);
+            if (byTime !== 0) return byTime;
+            const byInstance = a.instanceId.localeCompare(b.instanceId);
+            if (byInstance !== 0) return byInstance;
+            return b.localOperationId - a.localOperationId;
+          });
+
+        return c.json({
+          items: merged.slice(query.offset, query.offset + query.limit),
+          total: fetched.successfulResults.reduce(
+            (acc, entry) => acc + entry.total,
+            0
+          ),
+          offset: query.offset,
+          limit: query.limit,
+          partial: fetched.failedInstances.length > 0,
+          failedInstances: fetched.failedInstances,
         });
-
-      return c.json({
-        items: merged.slice(query.offset, query.offset + query.limit),
-        total: successful.reduce((acc, entry) => acc + entry.result.total, 0),
-        offset: query.offset,
-        limit: query.limit,
-        partial: failedInstances.length > 0,
-        failedInstances,
       });
     }
   );
@@ -2908,96 +2481,63 @@ export function createConsoleGatewayRoutes(
     }),
     zValidator('query', GatewayEventsQuerySchema),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const query = c.req.valid('query');
+        const selection = selectTargetInstances(c, query);
+        if (!selection.ok) {
+          return selection.response;
+        }
 
-      const query = c.req.valid('query');
-      const selectedInstances = selectInstances({ instances, query });
-      if (selectedInstances.length === 0) {
-        return c.json(
-          {
-            error: 'NO_INSTANCES_SELECTED',
-            message:
-              'No enabled instances matched the provided instance filter.',
-          },
-          400
+        const targetCount = query.offset + query.limit;
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const targetCount = query.offset + query.limit;
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      forwardQuery.delete('limit');
-      forwardQuery.delete('offset');
-      const pageSchema = ConsolePaginatedResponseSchema(
-        ConsoleRequestEventSchema
-      );
-
-      const results = await Promise.all(
-        selectedInstances.map((instance) =>
-          fetchDownstreamPaged({
+        forwardQuery.delete('limit');
+        forwardQuery.delete('offset');
+        const pageSchema = ConsolePaginatedResponseSchema(
+          ConsoleRequestEventSchema
+        );
+        const fetched =
+          await fetchPagedFromSelectedInstances<ConsoleRequestEvent>({
             c,
-            instance,
+            selectedInstances: selection.selectedInstances,
             path: '/events',
             query: forwardQuery,
             targetCount,
             schema: pageSchema,
-            fetchImpl,
-          })
-        )
-      );
-
-      const failedInstances = results
-        .filter(
-          (result): result is { ok: false; failure: GatewayFailure } =>
-            !result.ok
-        )
-        .map((result) => result.failure);
-      const successful = results
-        .map((result, index) => ({
-          result,
-          instance: selectedInstances[index],
-        }))
-        .filter(
-          (
-            entry
-          ): entry is {
-            result: { ok: true; items: ConsoleRequestEvent[]; total: number };
-            instance: ConsoleGatewayInstance;
-          } => Boolean(entry.instance) && entry.result.ok
-        );
-
-      if (successful.length === 0) {
-        return allInstancesFailedResponse(c, failedInstances);
-      }
+          });
+        if (!fetched.ok) {
+          return fetched.response;
+        }
 
-      const merged = successful
-        .flatMap(({ result, instance }) =>
-          result.items.map((event) => ({
-            ...event,
-            instanceId: instance.instanceId,
-            federatedEventId: `${instance.instanceId}:${event.eventId}`,
-            localEventId: event.eventId,
-          }))
-        )
-        .sort((a, b) => {
-          const byTime = compareIsoDesc(a.createdAt, b.createdAt);
-          if (byTime !== 0) return byTime;
-          const byInstance = a.instanceId.localeCompare(b.instanceId);
-          if (byInstance !== 0) return byInstance;
-          return b.localEventId - a.localEventId;
+        const merged = fetched.successfulResults
+          .flatMap(({ items, instance }) =>
+            items.map((event) => ({
+              ...event,
+              instanceId: instance.instanceId,
+              federatedEventId: `${instance.instanceId}:${event.eventId}`,
+              localEventId: event.eventId,
+            }))
+          )
+          .sort((a, b) => {
+            const byTime = compareIsoDesc(a.createdAt, b.createdAt);
+            if (byTime !== 0) return byTime;
+            const byInstance = a.instanceId.localeCompare(b.instanceId);
+            if (byInstance !== 0) return byInstance;
+            return b.localEventId - a.localEventId;
+          });
+
+        return c.json({
+          items: merged.slice(query.offset, query.offset + query.limit),
+          total: fetched.successfulResults.reduce(
+            (acc, entry) => acc + entry.total,
+            0
+          ),
+          offset: query.offset,
+          limit: query.limit,
+          partial: fetched.failedInstances.length > 0,
+          failedInstances: fetched.failedInstances,
         });
-
-      return c.json({
-        items: merged.slice(query.offset, query.offset + query.limit),
-        total: successful.reduce((acc, entry) => acc + entry.result.total, 0),
-        offset: query.offset,
-        limit: query.limit,
-        partial: failedInstances.length > 0,
-        failedInstances,
       });
     }
   );
@@ -3024,6 +2564,7 @@ export function createConsoleGatewayRoutes(
         heartbeatInterval: ReturnType<typeof setInterval> | null;
         authTimeout: ReturnType<typeof setTimeout> | null;
         isAuthenticated: boolean;
+        startAuthenticatedSession: ((token: string | null) => void) | null;
       }
     >();
 
@@ -3066,17 +2607,6 @@ export function createConsoleGatewayRoutes(
           return options.authenticate(authContext);
         };
 
-        const closeUnauthenticated = (ws: WebSocketLike) => {
-          try {
-            ws.send(
-              JSON.stringify({ type: 'error', message: 'UNAUTHENTICATED' })
-            );
-          } catch {
-            // no-op
-          }
-          ws.close(4001, 'Unauthenticated');
-        };
-
         const cleanup = (ws: WebSocketLike) => {
           const state = liveState.get(ws);
           if (!state) return;
@@ -3115,11 +2645,15 @@ export function createConsoleGatewayRoutes(
               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);
 
@@ -3248,6 +2782,7 @@ export function createConsoleGatewayRoutes(
               }, heartbeatIntervalMs);
               state.heartbeatInterval = heartbeatInterval;
             };
+            state.startAuthenticatedSession = startAuthenticatedSession;
 
             if (initialAuth) {
               startAuthenticatedSession(
@@ -3261,7 +2796,7 @@ export function createConsoleGatewayRoutes(
               if (!current || current.isAuthenticated) {
                 return;
               }
-              closeUnauthenticated(ws);
+              closeUnauthenticatedSocket(ws);
               cleanup(ws);
             }, 5_000);
           },
@@ -3272,30 +2807,15 @@ export function createConsoleGatewayRoutes(
             }
 
             if (typeof event.data !== 'string') {
-              closeUnauthenticated(ws);
+              closeUnauthenticatedSocket(ws);
               cleanup(ws);
               return;
             }
 
-            let token = '';
-            try {
-              const parsed = JSON.parse(event.data) as {
-                type?: unknown;
-                token?: unknown;
-              };
-              if (
-                parsed.type === 'auth' &&
-                typeof parsed.token === 'string' &&
-                parsed.token.trim().length > 0
-              ) {
-                token = parsed.token;
-              }
-            } catch {
-              // Invalid auth message will be handled below.
-            }
+            const token = parseWebSocketAuthToken(event.data);
 
             if (!token) {
-              closeUnauthenticated(ws);
+              closeUnauthenticatedSocket(ws);
               cleanup(ws);
               return;
             }
@@ -3306,131 +2826,11 @@ export function createConsoleGatewayRoutes(
               return;
             }
             if (!auth) {
-              closeUnauthenticated(ws);
+              closeUnauthenticatedSocket(ws);
               cleanup(ws);
               return;
             }
-
-            current.isAuthenticated = true;
-            if (current.authTimeout) {
-              clearTimeout(current.authTimeout);
-              current.authTimeout = null;
-            }
-
-            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 upstreamToken = token.trim();
-              const downstreamToken =
-                instance.token?.trim() ||
-                (upstreamToken.length > 0 ? upstreamToken : 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;
-                }
-                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 liveEvent = {
-                    ...payload,
-                    data: payloadData,
-                    instanceId: instance.instanceId,
-                    timestamp:
-                      typeof payload.timestamp === 'string'
-                        ? payload.timestamp
-                        : new Date().toISOString(),
-                  };
-                  ws.send(JSON.stringify(liveEvent));
-                } catch {
-                  // Ignore malformed downstream events
-                }
-              };
-
-              downstreamSocket.onerror = () => {
-                try {
-                  ws.send(
-                    JSON.stringify({
-                      type: 'instance_error',
-                      instanceId: instance.instanceId,
-                      timestamp: new Date().toISOString(),
-                    })
-                  );
-                } catch {
-                  // ignore send errors
-                }
-              };
-
-              current.downstreamSockets.push(downstreamSocket);
-            }
-
-            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);
-              }
-            }, heartbeatIntervalMs);
-            current.heartbeatInterval = heartbeatInterval;
+            current.startAuthenticatedSession?.(token);
           },
           onClose(_event, ws) {
             cleanup(ws);
@@ -3465,58 +2865,55 @@ export function createConsoleGatewayRoutes(
       ConsolePartitionQuerySchema.extend(GatewayInstanceFilterSchema.shape)
     ),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const { id } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const target = resolveEventTarget({
+          id,
+          instances,
+          query,
+        });
+        if (!target.ok) {
+          return c.json(
+            {
+              error: target.error,
+              ...(target.message ? { message: target.message } : {}),
+            },
+            target.status
+          );
+        }
 
-      const { id } = c.req.valid('param');
-      const query = c.req.valid('query');
-      const target = resolveEventTarget({
-        id,
-        instances,
-        query,
-      });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            ...(target.message ? { message: target.message } : {}),
-          },
-          target.status
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await fetchDownstreamJson({
-        c,
-        instance: target.instance,
-        path: `/events/${target.localEventId}`,
-        query: forwardQuery,
-        schema: ConsoleRequestEventSchema,
-        fetchImpl,
-      });
+        const result = await fetchDownstreamJson({
+          c,
+          instance: target.instance,
+          path: `/events/${target.localEventId}`,
+          query: forwardQuery,
+          schema: ConsoleRequestEventSchema,
+          fetchImpl,
+        });
 
-      if (!result.ok) {
-        if (result.failure.status === 404) {
-          return c.json({ error: 'NOT_FOUND' }, 404);
+        if (!result.ok) {
+          if (result.failure.status === 404) {
+            return c.json({ error: 'NOT_FOUND' }, 404);
+          }
+          return c.json(
+            {
+              error: 'DOWNSTREAM_UNAVAILABLE',
+              failedInstances: [result.failure],
+            },
+            502
+          );
         }
-        return c.json(
-          {
-            error: 'DOWNSTREAM_UNAVAILABLE',
-            failedInstances: [result.failure],
-          },
-          502
-        );
-      }
 
-      return c.json({
-        ...result.data,
-        instanceId: target.instance.instanceId,
-        federatedEventId: `${target.instance.instanceId}:${result.data.eventId}`,
-        localEventId: result.data.eventId,
+        return c.json({
+          ...result.data,
+          instanceId: target.instance.instanceId,
+          federatedEventId: `${target.instance.instanceId}:${result.data.eventId}`,
+          localEventId: result.data.eventId,
+        });
       });
     }
   );
@@ -3543,58 +2940,55 @@ export function createConsoleGatewayRoutes(
       ConsolePartitionQuerySchema.extend(GatewayInstanceFilterSchema.shape)
     ),
     async (c) => {
-      const auth = await options.authenticate(c);
-      if (!auth) {
-        return unauthorizedResponse(c);
-      }
+      return withGatewayAuth(c, async () => {
+        const { id } = c.req.valid('param');
+        const query = c.req.valid('query');
+        const target = resolveEventTarget({
+          id,
+          instances,
+          query,
+        });
+        if (!target.ok) {
+          return c.json(
+            {
+              error: target.error,
+              ...(target.message ? { message: target.message } : {}),
+            },
+            target.status
+          );
+        }
 
-      const { id } = c.req.valid('param');
-      const query = c.req.valid('query');
-      const target = resolveEventTarget({
-        id,
-        instances,
-        query,
-      });
-      if (!target.ok) {
-        return c.json(
-          {
-            error: target.error,
-            ...(target.message ? { message: target.message } : {}),
-          },
-          target.status
+        const forwardQuery = sanitizeForwardQueryParams(
+          new URL(c.req.url).searchParams
         );
-      }
-
-      const forwardQuery = sanitizeForwardQueryParams(
-        new URL(c.req.url).searchParams
-      );
-      const result = await fetchDownstreamJson({
-        c,
-        instance: target.instance,
-        path: `/events/${target.localEventId}/payload`,
-        query: forwardQuery,
-        schema: ConsoleRequestPayloadSchema,
-        fetchImpl,
-      });
+        const result = await fetchDownstreamJson({
+          c,
+          instance: target.instance,
+          path: `/events/${target.localEventId}/payload`,
+          query: forwardQuery,
+          schema: ConsoleRequestPayloadSchema,
+          fetchImpl,
+        });
 
-      if (!result.ok) {
-        if (result.failure.status === 404) {
-          return c.json({ error: 'NOT_FOUND' }, 404);
+        if (!result.ok) {
+          if (result.failure.status === 404) {
+            return c.json({ error: 'NOT_FOUND' }, 404);
+          }
+          return c.json(
+            {
+              error: 'DOWNSTREAM_UNAVAILABLE',
+              failedInstances: [result.failure],
+            },
+            502
+          );
         }
-        return c.json(
-          {
-            error: 'DOWNSTREAM_UNAVAILABLE',
-            failedInstances: [result.failure],
-          },
-          502
-        );
-      }
 
-      return c.json({
-        ...result.data,
-        instanceId: target.instance.instanceId,
-        federatedEventId: `${target.instance.instanceId}:${target.localEventId}`,
-        localEventId: target.localEventId,
+        return c.json({
+          ...result.data,
+          instanceId: target.instance.instanceId,
+          federatedEventId: `${target.instance.instanceId}:${target.localEventId}`,
+          localEventId: target.localEventId,
+        });
       });
     }
   );