@syncular/server-hono 0.0.4-25 → 0.0.6-100

package/src/console/routes.ts

@@ -16,11 +16,7 @@
  */
 
 import { logSyncEvent } from '@syncular/core';
-import type {
-  ServerSyncDialect,
-  ServerTableHandler,
-  SyncCoreDb,
-} from '@syncular/server';
+import type { SqlFamily, SyncCoreDb, SyncServerAuth } from '@syncular/server';
 import {
   compactChanges,
   computePruneWatermarkCommitSeq,
@@ -31,11 +27,9 @@ import {
 import type { Context } from 'hono';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
-import type { UpgradeWebSocket } from 'hono/ws';
 import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
 import { type Generated, type Kysely, type Selectable, sql } from 'kysely';
 import { z } from 'zod';
-import type { WebSocketConnectionManager } from '../ws';
 import {
   type ApiKeyType,
   ApiKeyTypeSchema,
@@ -48,6 +42,9 @@ import {
   ConsoleApiKeyCreateResponseSchema,
   ConsoleApiKeyRevokeResponseSchema,
   ConsoleApiKeySchema,
+  ConsoleBlobDeleteResponseSchema,
+  ConsoleBlobListQuerySchema,
+  ConsoleBlobListResponseSchema,
   type ConsoleChange,
   type ConsoleClearEventsResult,
   ConsoleClearEventsResultSchema,
@@ -97,36 +94,12 @@ import {
   type TimeseriesStatsResponse,
   TimeseriesStatsResponseSchema,
 } from './schemas';
-
-export interface ConsoleAuthResult {
-  /** Identifier for the console user (for audit logging). */
-  consoleUserId?: string;
-}
-
-/**
- * Listener for console live events (SSE streaming).
- */
-export type ConsoleEventListener = (event: LiveEvent) => void;
-
-/**
- * Console event emitter for broadcasting live events.
- */
-export interface ConsoleEventEmitter {
-  /** Add a listener for live events */
-  addListener(listener: ConsoleEventListener): void;
-  /** Remove a listener */
-  removeListener(listener: ConsoleEventListener): void;
-  /** Emit an event to all listeners */
-  emit(event: LiveEvent): void;
-  /**
-   * Replay recent events, optionally constrained by timestamp, partition, and max count.
-   */
-  replay(options?: {
-    since?: string;
-    limit?: number;
-    partitionId?: string;
-  }): LiveEvent[];
-}
+import type {
+  ConsoleAuthResult,
+  ConsoleEventEmitter,
+  ConsoleEventListener,
+  CreateConsoleRoutesOptions,
+} from './types';
 
 /**
  * Create a simple console event emitter for broadcasting live events.
@@ -193,73 +166,6 @@ export function createConsoleEventEmitter(options?: {
   };
 }
 
-export interface CreateConsoleRoutesOptions<
-  DB extends SyncCoreDb = SyncCoreDb,
-> {
-  db: Kysely<DB>;
-  dialect: ServerSyncDialect;
-  handlers: ServerTableHandler<DB>[];
-  /**
-   * Authentication function for console requests.
-   * Return null to reject the request.
-   */
-  authenticate: (c: Context) => Promise<ConsoleAuthResult | null>;
-  /**
-   * CORS origins to allow. Defaults to ['http://localhost:5173', 'https://console.sync.dev'].
-   * Set to '*' to allow all origins (not recommended for production).
-   */
-  corsOrigins?: string[] | '*';
-  /**
-   * Compaction options (required for /compact endpoint).
-   */
-  compact?: {
-    fullHistoryHours?: number;
-  };
-  /**
-   * Pruning options.
-   */
-  prune?: {
-    activeWindowMs?: number;
-    fallbackMaxAgeMs?: number;
-    keepNewestCommits?: number;
-  };
-  /**
-   * Event emitter for live console events.
-   * If provided along with websocket config, enables the /events/live WebSocket endpoint.
-   */
-  eventEmitter?: ConsoleEventEmitter;
-  /**
-   * Shared sync WebSocket connection manager.
-   * When provided, `/clients` includes realtime connection state per client.
-   */
-  wsConnectionManager?: WebSocketConnectionManager;
-  /**
-   * WebSocket configuration for live events streaming.
-   */
-  websocket?: {
-    enabled?: boolean;
-    /**
-     * Runtime-provided WebSocket upgrader (e.g. from `hono/bun`'s `createBunWebSocket()`).
-     */
-    upgradeWebSocket?: UpgradeWebSocket;
-    /**
-     * Heartbeat interval in milliseconds. Default: 30000
-     */
-    heartbeatIntervalMs?: number;
-  };
-  /**
-   * Metrics query strategy for timeseries/latency endpoints.
-   * - raw: in-memory processing from raw event rows
-   * - aggregated: DB-level aggregation where supported (raw fallback for unsupported paths)
-   * - auto: use raw for small windows, aggregated for larger windows
-   */
-  metrics?: {
-    aggregationMode?: 'auto' | 'raw' | 'aggregated';
-    /** Max events for using raw mode when aggregationMode is 'auto'. */
-    rawFallbackMaxEvents?: number;
-  };
-}
-
 function coerceNumber(value: unknown): number | null {
   if (value === null || value === undefined) return null;
   if (typeof value === 'number') return Number.isFinite(value) ? value : null;
@@ -485,11 +391,45 @@ const handlersResponseSchema = z.object({
   items: z.array(ConsoleHandlerSchema),
 });
 
-export function createConsoleRoutes<DB extends SyncCoreDb>(
-  options: CreateConsoleRoutesOptions<DB>
-): Hono {
+const DEFAULT_REQUEST_EVENTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_REQUEST_EVENTS_MAX_ROWS = 10_000;
+const DEFAULT_OPERATION_EVENTS_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const DEFAULT_OPERATION_EVENTS_MAX_ROWS = 5_000;
+const DEFAULT_AUTO_EVENTS_PRUNE_INTERVAL_MS = 5 * 60 * 1000;
+
+function readNonNegativeInteger(
+  value: number | undefined,
+  fallback: number
+): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return fallback;
+  }
+  if (value < 0) {
+    return fallback;
+  }
+  return Math.floor(value);
+}
+
+export function createConsoleRoutes<
+  DB extends SyncCoreDb,
+  Auth extends SyncServerAuth,
+  F extends SqlFamily = SqlFamily,
+>(options: CreateConsoleRoutesOptions<DB, Auth, F>): Hono {
   const routes = new Hono();
 
+  routes.onError((error, context) => {
+    const message =
+      error instanceof Error ? error.message : 'Unknown console error';
+    console.error('[console] route error', error);
+    return context.json(
+      {
+        error: 'CONSOLE_ROUTE_ERROR',
+        message,
+      },
+      500
+    );
+  });
+
   interface SyncRequestEventsTable {
     event_id: number;
     partition_id: string;
@@ -568,11 +508,36 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
     1,
     options.metrics?.rawFallbackMaxEvents ?? 5000
   );
-
-  // Ensure console schema exists (creates sync_request_events table if needed)
-  // Run asynchronously - will be ready before first request typically
-  options.dialect.ensureConsoleSchema?.(options.db).catch((err) => {
+  const requestEventsMaxAgeMs = readNonNegativeInteger(
+    options.maintenance?.requestEventsMaxAgeMs,
+    DEFAULT_REQUEST_EVENTS_MAX_AGE_MS
+  );
+  const requestEventsMaxRows = readNonNegativeInteger(
+    options.maintenance?.requestEventsMaxRows,
+    DEFAULT_REQUEST_EVENTS_MAX_ROWS
+  );
+  const operationEventsMaxAgeMs = readNonNegativeInteger(
+    options.maintenance?.operationEventsMaxAgeMs,
+    DEFAULT_OPERATION_EVENTS_MAX_AGE_MS
+  );
+  const operationEventsMaxRows = readNonNegativeInteger(
+    options.maintenance?.operationEventsMaxRows,
+    DEFAULT_OPERATION_EVENTS_MAX_ROWS
+  );
+  const autoEventsPruneIntervalMs = readNonNegativeInteger(
+    options.maintenance?.autoPruneIntervalMs,
+    DEFAULT_AUTO_EVENTS_PRUNE_INTERVAL_MS
+  );
+  let lastEventsPruneRunAt = 0;
+
+  // Ensure console schema exists before handlers query console tables.
+  const consoleSchemaReadyPromise = (
+    options.consoleSchemaReady ??
+    options.dialect.ensureConsoleSchema?.(options.db) ??
+    Promise.resolve()
+  ).catch((err) => {
     console.error('[console] Failed to ensure console schema:', err);
+    throw err;
   });
 
   // CORS configuration
@@ -580,18 +545,53 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
     'http://localhost:5173',
     'https://console.sync.dev',
   ];
+  const allowWildcardCors = corsOrigins === '*';
 
   routes.use(
     '*',
     cors({
-      origin: corsOrigins === '*' ? '*' : corsOrigins,
+      origin: allowWildcardCors ? '*' : corsOrigins,
       allowMethods: ['GET', 'POST', 'DELETE', 'OPTIONS'],
-      allowHeaders: ['Content-Type', 'Authorization'],
+      allowHeaders: [
+        'Content-Type',
+        'Authorization',
+        'X-Syncular-Transport-Path',
+        'Baggage',
+        'Sentry-Trace',
+        'Traceparent',
+        'Tracestate',
+      ],
       exposeHeaders: ['X-Total-Count'],
-      credentials: true,
+      credentials: !allowWildcardCors,
     })
   );
 
+  const ensureConsoleSchemaReady = async (
+    c: Context
+  ): Promise<Response | null> => {
+    try {
+      await consoleSchemaReadyPromise;
+      return null;
+    } catch {
+      return c.json({ error: 'CONSOLE_SCHEMA_UNAVAILABLE' }, 503);
+    }
+  };
+
+  routes.use('*', async (c, next) => {
+    const readyError = await ensureConsoleSchemaReady(c);
+    if (readyError) {
+      return readyError;
+    }
+    await next();
+  });
+
+  routes.use('*', async (c, next) => {
+    if (c.req.method !== 'OPTIONS') {
+      triggerAutomaticEventsPrune();
+    }
+    await next();
+  });
+
   // Auth middleware
   const requireAuth = async (c: Context): Promise<ConsoleAuthResult | null> => {
     const auth = await options.authenticate(c);
@@ -687,6 +687,202 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
     createdAt: row.created_at ?? '',
   });
 
+  type PruneEventsRunResult = {
+    requestEventsDeleted: number;
+    operationEventsDeleted: number;
+    payloadSnapshotsDeleted: number;
+    totalDeleted: number;
+  };
+
+  const deleteUnreferencedPayloadSnapshots = async (): Promise<number> => {
+    const result = await db
+      .deleteFrom('sync_request_payloads')
+      .where(
+        'payload_ref',
+        'not in',
+        db
+          .selectFrom('sync_request_events')
+          .select('payload_ref')
+          .where('payload_ref', 'is not', null)
+      )
+      .executeTakeFirst();
+    return Number(result?.numDeletedRows ?? 0);
+  };
+
+  const pruneRequestEventsByAge = async (): Promise<number> => {
+    if (requestEventsMaxAgeMs <= 0) {
+      return 0;
+    }
+
+    const cutoffDate = new Date(Date.now() - requestEventsMaxAgeMs);
+    const result = await db
+      .deleteFrom('sync_request_events')
+      .where('created_at', '<', cutoffDate.toISOString())
+      .executeTakeFirst();
+
+    return Number(result?.numDeletedRows ?? 0);
+  };
+
+  const pruneRequestEventsByCount = async (): Promise<number> => {
+    if (requestEventsMaxRows <= 0) {
+      return 0;
+    }
+
+    const countRow = await db
+      .selectFrom('sync_request_events')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+
+    const total = coerceNumber(countRow?.total) ?? 0;
+    if (total <= requestEventsMaxRows) {
+      return 0;
+    }
+
+    const cutoffRow = await db
+      .selectFrom('sync_request_events')
+      .select(['event_id'])
+      .orderBy('event_id', 'desc')
+      .offset(requestEventsMaxRows)
+      .limit(1)
+      .executeTakeFirst();
+
+    const cutoffEventId = coerceNumber(cutoffRow?.event_id);
+    if (cutoffEventId === null) {
+      return 0;
+    }
+
+    const result = await db
+      .deleteFrom('sync_request_events')
+      .where('event_id', '<=', cutoffEventId)
+      .executeTakeFirst();
+    return Number(result?.numDeletedRows ?? 0);
+  };
+
+  const pruneOperationEventsByAge = async (): Promise<number> => {
+    if (operationEventsMaxAgeMs <= 0) {
+      return 0;
+    }
+
+    const cutoffDate = new Date(Date.now() - operationEventsMaxAgeMs);
+    const result = await db
+      .deleteFrom('sync_operation_events')
+      .where('created_at', '<', cutoffDate.toISOString())
+      .executeTakeFirst();
+    return Number(result?.numDeletedRows ?? 0);
+  };
+
+  const pruneOperationEventsByCount = async (): Promise<number> => {
+    if (operationEventsMaxRows <= 0) {
+      return 0;
+    }
+
+    const countRow = await db
+      .selectFrom('sync_operation_events')
+      .select(({ fn }) => fn.countAll().as('total'))
+      .executeTakeFirst();
+    const total = coerceNumber(countRow?.total) ?? 0;
+    if (total <= operationEventsMaxRows) {
+      return 0;
+    }
+
+    const cutoffRow = await db
+      .selectFrom('sync_operation_events')
+      .select(['operation_id'])
+      .orderBy('operation_id', 'desc')
+      .offset(operationEventsMaxRows)
+      .limit(1)
+      .executeTakeFirst();
+
+    const cutoffOperationId = coerceNumber(cutoffRow?.operation_id);
+    if (cutoffOperationId === null) {
+      return 0;
+    }
+
+    const result = await db
+      .deleteFrom('sync_operation_events')
+      .where('operation_id', '<=', cutoffOperationId)
+      .executeTakeFirst();
+    return Number(result?.numDeletedRows ?? 0);
+  };
+
+  const pruneConsoleEvents = async (): Promise<PruneEventsRunResult> => {
+    const requestEventsDeletedByAge = await pruneRequestEventsByAge();
+    const requestEventsDeletedByCount = await pruneRequestEventsByCount();
+    const requestEventsDeleted =
+      requestEventsDeletedByAge + requestEventsDeletedByCount;
+
+    const operationEventsDeletedByAge = await pruneOperationEventsByAge();
+    const operationEventsDeletedByCount = await pruneOperationEventsByCount();
+    const operationEventsDeleted =
+      operationEventsDeletedByAge + operationEventsDeletedByCount;
+
+    const payloadSnapshotsDeleted = await deleteUnreferencedPayloadSnapshots();
+    const totalDeleted = requestEventsDeleted + operationEventsDeleted;
+
+    return {
+      requestEventsDeleted,
+      operationEventsDeleted,
+      payloadSnapshotsDeleted,
+      totalDeleted,
+    };
+  };
+
+  let eventsPrunePromise: Promise<PruneEventsRunResult> | null = null;
+
+  const runEventsPrune = async (): Promise<PruneEventsRunResult> => {
+    if (eventsPrunePromise) {
+      return eventsPrunePromise;
+    }
+
+    let pending: Promise<PruneEventsRunResult>;
+    pending = pruneConsoleEvents()
+      .then((result) => {
+        lastEventsPruneRunAt = Date.now();
+        return result;
+      })
+      .finally(() => {
+        if (eventsPrunePromise === pending) {
+          eventsPrunePromise = null;
+        }
+      });
+
+    eventsPrunePromise = pending;
+    return pending;
+  };
+
+  const triggerAutomaticEventsPrune = (): void => {
+    if (autoEventsPruneIntervalMs <= 0) {
+      return;
+    }
+    if (eventsPrunePromise) {
+      return;
+    }
+    if (Date.now() - lastEventsPruneRunAt < autoEventsPruneIntervalMs) {
+      return;
+    }
+
+    void runEventsPrune()
+      .then((result) => {
+        if (result.totalDeleted <= 0 && result.payloadSnapshotsDeleted <= 0) {
+          return;
+        }
+
+        logSyncEvent({
+          event: 'console.prune_events_auto',
+          deletedCount: result.totalDeleted,
+          requestEventsDeleted: result.requestEventsDeleted,
+          operationEventsDeleted: result.operationEventsDeleted,
+          payloadDeletedCount: result.payloadSnapshotsDeleted,
+        });
+      })
+      .catch((error) => {
+        logSyncEvent({
+          event: 'console.prune_events_auto_failed',
+          error: error instanceof Error ? error.message : String(error),
+        });
+      });
+  };
+
   const recordOperationEvent = async (event: {
     operationType: ConsoleOperationType;
     consoleUserId?: string;
@@ -875,7 +1071,7 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
           ? sql`and partition_id = ${partitionId}`
           : sql``;
 
-        if (options.dialect.name === 'sqlite') {
+        if (options.dialect.family === 'sqlite') {
           const bucketFormat = intervalToSqliteBucketFormat(interval);
           const rowsResult = await sql<{
             bucket: unknown;
@@ -1019,7 +1215,7 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
       const startIso = startTime.toISOString();
       const useRawMetrics = await shouldUseRawMetrics(startIso, partitionId);
 
-      if (!useRawMetrics && options.dialect.name !== 'sqlite') {
+      if (!useRawMetrics && options.dialect.family !== 'sqlite') {
         const partitionFilter = partitionId
           ? sql`and partition_id = ${partitionId}`
           : sql``;
@@ -2288,16 +2484,40 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
     const wsState = new WeakMap<
       WebSocketLike,
       {
-        listener: ConsoleEventListener;
-        heartbeatInterval: ReturnType<typeof setInterval>;
+        listener: ConsoleEventListener | null;
+        heartbeatInterval: ReturnType<typeof setInterval> | null;
+        authTimeout: ReturnType<typeof setTimeout> | null;
+        isAuthenticated: boolean;
       }
     >();
 
+    const closeUnauthenticated = (ws: WebSocketLike) => {
+      try {
+        ws.send(JSON.stringify({ type: 'error', message: 'UNAUTHENTICATED' }));
+      } catch {
+        // ignore send errors
+      }
+      ws.close(4001, 'Unauthenticated');
+    };
+
+    const cleanup = (ws: WebSocketLike) => {
+      const state = wsState.get(ws);
+      if (!state) return;
+      if (state.listener) {
+        emitter.removeListener(state.listener);
+      }
+      if (state.heartbeatInterval) {
+        clearInterval(state.heartbeatInterval);
+      }
+      if (state.authTimeout) {
+        clearTimeout(state.authTimeout);
+      }
+      wsState.delete(ws);
+    };
+
     routes.get(
       '/events/live',
       upgradeWebSocket(async (c) => {
-        // Auth check via query param (WebSocket doesn't support headers easily)
-        const token = c.req.query('token');
         const authHeader = c.req.header('Authorization');
         const partitionId = c.req.query('partitionId')?.trim() || undefined;
         const replaySince = c.req.query('since');
@@ -2312,25 +2532,173 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
           req: {
             header: (name: string) =>
               name === 'Authorization' ? authHeader : undefined,
-            query: (name: string) => (name === 'token' ? token : undefined),
+            query: () => undefined,
           },
-        } as Context;
+        } as unknown as Context;
 
-        const auth = await options.authenticate(mockContext);
+        const initialAuth = await options.authenticate(mockContext);
+
+        const authenticateWithBearer = async (token: string) => {
+          const trimmedToken = token.trim();
+          if (!trimmedToken) return null;
+          const authContext = {
+            req: {
+              header: (name: string) =>
+                name === 'Authorization' ? `Bearer ${trimmedToken}` : undefined,
+              query: () => undefined,
+            },
+          } as unknown as Context;
+          return options.authenticate(authContext);
+        };
 
         return {
           onOpen(_event, ws) {
-            if (!auth) {
+            const state = {
+              listener: null,
+              heartbeatInterval: null,
+              authTimeout: null,
+              isAuthenticated: false,
+            } as {
+              listener: ConsoleEventListener | null;
+              heartbeatInterval: ReturnType<typeof setInterval> | null;
+              authTimeout: ReturnType<typeof setTimeout> | null;
+              isAuthenticated: boolean;
+            };
+            wsState.set(ws, state);
+
+            const startAuthenticatedSession = () => {
+              if (state.isAuthenticated) return;
+              state.isAuthenticated = true;
+              if (state.authTimeout) {
+                clearTimeout(state.authTimeout);
+                state.authTimeout = null;
+              }
+
+              const listener: ConsoleEventListener = (event) => {
+                if (partitionId) {
+                  const eventPartitionId = event.data.partitionId;
+                  if (
+                    typeof eventPartitionId !== 'string' ||
+                    eventPartitionId !== partitionId
+                  ) {
+                    return;
+                  }
+                }
+                try {
+                  ws.send(JSON.stringify(event));
+                } catch {
+                  // Connection closed
+                }
+              };
+
+              emitter.addListener(listener);
+              state.listener = listener;
+
               ws.send(
-                JSON.stringify({ type: 'error', message: 'UNAUTHENTICATED' })
+                JSON.stringify({
+                  type: 'connected',
+                  timestamp: new Date().toISOString(),
+                })
               );
-              ws.close(4001, 'Unauthenticated');
+
+              const replayEvents = emitter.replay({
+                since: replaySince,
+                limit: replayLimit,
+                partitionId,
+              });
+              for (const replayEvent of replayEvents) {
+                try {
+                  ws.send(JSON.stringify(replayEvent));
+                } catch {
+                  // Connection closed
+                  break;
+                }
+              }
+
+              const heartbeatInterval = setInterval(() => {
+                try {
+                  ws.send(
+                    JSON.stringify({
+                      type: 'heartbeat',
+                      timestamp: new Date().toISOString(),
+                    })
+                  );
+                } catch {
+                  clearInterval(heartbeatInterval);
+                }
+              }, heartbeatIntervalMs);
+              state.heartbeatInterval = heartbeatInterval;
+            };
+
+            if (initialAuth) {
+              startAuthenticatedSession();
+              return;
+            }
+
+            state.authTimeout = setTimeout(() => {
+              const current = wsState.get(ws);
+              if (!current || current.isAuthenticated) {
+                return;
+              }
+              closeUnauthenticated(ws);
+              cleanup(ws);
+            }, 5_000);
+          },
+          async onMessage(event, ws) {
+            const state = wsState.get(ws);
+            if (!state || state.isAuthenticated) {
+              return;
+            }
+
+            if (typeof event.data !== 'string') {
+              closeUnauthenticated(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 {
+              // Ignore parse errors and close as unauthenticated below.
+            }
+
+            if (!token) {
+              closeUnauthenticated(ws);
+              cleanup(ws);
+              return;
+            }
+
+            const auth = await authenticateWithBearer(token);
+            const currentState = wsState.get(ws);
+            if (!currentState || currentState.isAuthenticated) {
+              return;
+            }
+            if (!auth) {
+              closeUnauthenticated(ws);
+              cleanup(ws);
               return;
             }
 
-            const listener: ConsoleEventListener = (event) => {
+            currentState.isAuthenticated = true;
+            if (currentState.authTimeout) {
+              clearTimeout(currentState.authTimeout);
+              currentState.authTimeout = null;
+            }
+
+            const listener: ConsoleEventListener = (liveEvent) => {
               if (partitionId) {
-                const eventPartitionId = event.data.partitionId;
+                const eventPartitionId = liveEvent.data.partitionId;
                 if (
                   typeof eventPartitionId !== 'string' ||
                   eventPartitionId !== partitionId
@@ -2339,15 +2707,15 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
                 }
               }
               try {
-                ws.send(JSON.stringify(event));
+                ws.send(JSON.stringify(liveEvent));
               } catch {
                 // Connection closed
               }
             };
 
             emitter.addListener(listener);
+            currentState.listener = listener;
 
-            // Send connected message
             ws.send(
               JSON.stringify({
                 type: 'connected',
@@ -2369,7 +2737,6 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
               }
             }
 
-            // Start heartbeat
             const heartbeatInterval = setInterval(() => {
               try {
                 ws.send(
@@ -2382,22 +2749,13 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
                 clearInterval(heartbeatInterval);
               }
             }, heartbeatIntervalMs);
-
-            wsState.set(ws, { listener, heartbeatInterval });
+            currentState.heartbeatInterval = heartbeatInterval;
           },
           onClose(_event, ws) {
-            const state = wsState.get(ws);
-            if (!state) return;
-            emitter.removeListener(state.listener);
-            clearInterval(state.heartbeatInterval);
-            wsState.delete(ws);
+            cleanup(ws);
           },
           onError(_event, ws) {
-            const state = wsState.get(ws);
-            if (!state) return;
-            emitter.removeListener(state.listener);
-            clearInterval(state.heartbeatInterval);
-            wsState.delete(ws);
+            cleanup(ws);
           },
         };
       })
@@ -2605,11 +2963,13 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
       const res = await db.deleteFrom('sync_request_events').executeTakeFirst();
 
       const deletedCount = Number(res?.numDeletedRows ?? 0);
+      const payloadDeletedCount = await deleteUnreferencedPayloadSnapshots();
 
       logSyncEvent({
         event: 'console.clear_events',
         consoleUserId: auth.consoleUserId,
         deletedCount,
+        payloadDeletedCount,
       });
 
       const result: ConsoleClearEventsResult = { deletedCount };
@@ -2647,53 +3007,16 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
       const auth = await requireAuth(c);
       if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
 
-      // Prune events older than 7 days or keep max 10000 events
-      const cutoffDate = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
-
-      // Delete by date first
-      const resByDate = await db
-        .deleteFrom('sync_request_events')
-        .where('created_at', '<', cutoffDate.toISOString())
-        .executeTakeFirst();
-
-      let deletedCount = Number(resByDate?.numDeletedRows ?? 0);
-
-      // Then delete oldest if we still have more than 10000 events
-      const countRow = await db
-        .selectFrom('sync_request_events')
-        .select(({ fn }) => fn.countAll().as('total'))
-        .executeTakeFirst();
-
-      const total = coerceNumber(countRow?.total) ?? 0;
-      const maxEvents = 10000;
-
-      if (total > maxEvents) {
-        // Find event_id cutoff to keep only newest maxEvents
-        const cutoffRow = await db
-          .selectFrom('sync_request_events')
-          .select(['event_id'])
-          .orderBy('event_id', 'desc')
-          .offset(maxEvents)
-          .limit(1)
-          .executeTakeFirst();
-
-        if (cutoffRow) {
-          const cutoffEventId = coerceNumber(cutoffRow.event_id);
-          if (cutoffEventId !== null) {
-            const resByCount = await db
-              .deleteFrom('sync_request_events')
-              .where('event_id', '<=', cutoffEventId)
-              .executeTakeFirst();
-
-            deletedCount += Number(resByCount?.numDeletedRows ?? 0);
-          }
-        }
-      }
+      const pruneResult = await runEventsPrune();
+      const deletedCount = pruneResult.totalDeleted;
 
       logSyncEvent({
         event: 'console.prune_events',
         consoleUserId: auth.consoleUserId,
         deletedCount,
+        requestEventsDeleted: pruneResult.requestEventsDeleted,
+        operationEventsDeleted: pruneResult.operationEventsDeleted,
+        payloadDeletedCount: pruneResult.payloadSnapshotsDeleted,
       });
 
       const result: ConsolePruneEventsResult = { deletedCount };
@@ -3407,6 +3730,157 @@ export function createConsoleRoutes<DB extends SyncCoreDb>(
     }
   );
 
+  // -----------------------------------------------------------------------
+  // Storage endpoints
+  // -----------------------------------------------------------------------
+  const bucket = options.blobBucket;
+
+  routes.get(
+    '/storage',
+    describeRoute({
+      tags: ['console'],
+      summary: 'List storage items',
+      responses: {
+        200: {
+          description: 'Paginated list of storage items',
+          content: {
+            'application/json': {
+              schema: resolver(ConsoleBlobListResponseSchema),
+            },
+          },
+        },
+        401: {
+          description: 'Unauthenticated',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+      },
+    }),
+    zValidator('query', ConsoleBlobListQuerySchema),
+    async (c) => {
+      const auth = await requireAuth(c);
+      if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
+
+      if (!bucket) {
+        return c.json({ error: 'BLOB_STORAGE_NOT_CONFIGURED' }, 501);
+      }
+
+      const { prefix, cursor, limit } = c.req.valid('query');
+      const listed = await bucket.list({
+        prefix: prefix || undefined,
+        cursor: cursor || undefined,
+        limit,
+      });
+
+      return c.json(
+        {
+          items: listed.objects.map((obj) => ({
+            key: obj.key,
+            size: obj.size,
+            uploaded: obj.uploaded.toISOString(),
+            httpMetadata: obj.httpMetadata?.contentType
+              ? { contentType: obj.httpMetadata.contentType }
+              : undefined,
+          })),
+          truncated: listed.truncated,
+          cursor: listed.cursor ?? null,
+        },
+        200
+      );
+    }
+  );
+
+  routes.get(
+    '/storage/:key{.+}/download',
+    describeRoute({
+      tags: ['console'],
+      summary: 'Download a storage item',
+      responses: {
+        200: { description: 'Storage item contents' },
+        401: {
+          description: 'Unauthenticated',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+        404: {
+          description: 'Blob not found',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+      },
+    }),
+    async (c) => {
+      const auth = await requireAuth(c);
+      if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
+
+      if (!bucket) {
+        return c.json({ error: 'BLOB_STORAGE_NOT_CONFIGURED' }, 501);
+      }
+
+      const key = decodeURIComponent(c.req.param('key'));
+      const object = await bucket.get(key);
+      if (!object) {
+        return c.json({ error: 'BLOB_NOT_FOUND' }, 404);
+      }
+
+      const headers = new Headers();
+      headers.set('Content-Length', String(object.size));
+      headers.set(
+        'Content-Type',
+        object.httpMetadata?.contentType ?? 'application/octet-stream'
+      );
+      const filename = key.split('/').pop() || key;
+      headers.set(
+        'Content-Disposition',
+        `attachment; filename="${filename.replace(/"/g, '\\"')}"`
+      );
+
+      return new Response(object.body as ReadableStream, {
+        status: 200,
+        headers,
+      });
+    }
+  );
+
+  routes.delete(
+    '/storage/:key{.+}',
+    describeRoute({
+      tags: ['console'],
+      summary: 'Delete a storage item',
+      responses: {
+        200: {
+          description: 'Storage item deleted',
+          content: {
+            'application/json': {
+              schema: resolver(ConsoleBlobDeleteResponseSchema),
+            },
+          },
+        },
+        401: {
+          description: 'Unauthenticated',
+          content: {
+            'application/json': { schema: resolver(ErrorResponseSchema) },
+          },
+        },
+      },
+    }),
+    async (c) => {
+      const auth = await requireAuth(c);
+      if (!auth) return c.json({ error: 'UNAUTHENTICATED' }, 401);
+
+      if (!bucket) {
+        return c.json({ error: 'BLOB_STORAGE_NOT_CONFIGURED' }, 501);
+      }
+
+      const key = decodeURIComponent(c.req.param('key'));
+      await bucket.delete(key);
+      return c.json({ deleted: true }, 200);
+    }
+  );
+
   return routes;
 }
 
@@ -3444,29 +3918,19 @@ async function hashApiKey(secretKey: string): Promise<string> {
 export function createTokenAuthenticator(
   token?: string
 ): (c: Context) => Promise<ConsoleAuthResult | null> {
-  const expectedToken = token ?? process.env.SYNC_CONSOLE_TOKEN;
+  const expectedToken = (token ?? process.env.SYNC_CONSOLE_TOKEN)?.trim() ?? '';
 
   return async (c: Context) => {
-    if (!expectedToken) {
-      // No token configured, allow all requests (not recommended for production)
-      return { consoleUserId: 'anonymous' };
-    }
+    if (!expectedToken) return null;
 
-    // Check Authorization header
-    const authHeader = c.req.header('Authorization');
+    const authHeader = c.req.header('Authorization')?.trim();
     if (authHeader?.startsWith('Bearer ')) {
-      const bearerToken = authHeader.slice(7);
+      const bearerToken = authHeader.slice(7).trim();
       if (bearerToken === expectedToken) {
         return { consoleUserId: 'token' };
       }
     }
 
-    // Check query parameter
-    const queryToken = c.req.query('token');
-    if (queryToken === expectedToken) {
-      return { consoleUserId: 'token' };
-    }
-
     return null;
   };
 }