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

package/dist/console/routes.js

@@ -21,7 +21,7 @@ import { cors } from 'hono/cors';
 import { describeRoute, resolver, validator as zValidator } from 'hono-openapi';
 import { sql } from 'kysely';
 import { z } from 'zod';
-import { ApiKeyTypeSchema, ConsoleApiKeyBulkRevokeRequestSchema, ConsoleApiKeyBulkRevokeResponseSchema, ConsoleApiKeyCreateRequestSchema, ConsoleApiKeyCreateResponseSchema, ConsoleApiKeyRevokeResponseSchema, ConsoleApiKeySchema, ConsoleClearEventsResultSchema, ConsoleClientSchema, ConsoleCommitDetailSchema, ConsoleCommitListItemSchema, ConsoleCompactResultSchema, ConsoleEvictResultSchema, ConsoleHandlerSchema, ConsoleOperationEventSchema, ConsoleOperationsQuerySchema, ConsolePaginatedResponseSchema, ConsolePaginationQuerySchema, ConsolePartitionedPaginationQuerySchema, ConsolePartitionQuerySchema, ConsolePruneEventsResultSchema, ConsolePrunePreviewSchema, ConsolePruneResultSchema, ConsoleRequestEventSchema, ConsoleRequestPayloadSchema, ConsoleTimelineItemSchema, ConsoleTimelineQuerySchema, LatencyQuerySchema, LatencyStatsResponseSchema, SyncStatsSchema, TimeseriesQuerySchema, TimeseriesStatsResponseSchema, } from './schemas.js';
+import { ApiKeyTypeSchema, ConsoleApiKeyBulkRevokeRequestSchema, ConsoleApiKeyBulkRevokeResponseSchema, ConsoleApiKeyCreateRequestSchema, ConsoleApiKeyCreateResponseSchema, ConsoleApiKeyRevokeResponseSchema, ConsoleApiKeySchema, ConsoleBlobDeleteResponseSchema, ConsoleBlobListQuerySchema, ConsoleBlobListResponseSchema, ConsoleClearEventsResultSchema, ConsoleClientSchema, ConsoleCommitDetailSchema, ConsoleCommitListItemSchema, ConsoleCompactResultSchema, ConsoleEvictResultSchema, ConsoleHandlerSchema, ConsoleOperationEventSchema, ConsoleOperationsQuerySchema, ConsolePaginatedResponseSchema, ConsolePaginationQuerySchema, ConsolePartitionedPaginationQuerySchema, ConsolePartitionQuerySchema, ConsolePruneEventsResultSchema, ConsolePrunePreviewSchema, ConsolePruneResultSchema, ConsoleRequestEventSchema, ConsoleRequestPayloadSchema, ConsoleTimelineItemSchema, ConsoleTimelineQuerySchema, LatencyQuerySchema, LatencyStatsResponseSchema, SyncStatsSchema, TimeseriesQuerySchema, TimeseriesStatsResponseSchema, } from './schemas.js';
 /**
  * Create a simple console event emitter for broadcasting live events.
  */
@@ -262,23 +262,54 @@ const apiKeysQuerySchema = ConsolePaginationQuerySchema.extend({
 const handlersResponseSchema = z.object({
     items: z.array(ConsoleHandlerSchema),
 });
+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, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallback;
+    }
+    if (value < 0) {
+        return fallback;
+    }
+    return Math.floor(value);
+}
 export function createConsoleRoutes(options) {
     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);
+    });
     const db = options.db;
     const metricsAggregationMode = options.metrics?.aggregationMode ?? 'auto';
     const rawFallbackMaxEvents = Math.max(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
     const corsOrigins = options.corsOrigins ?? [
         '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',
@@ -290,8 +321,30 @@ export function createConsoleRoutes(options) {
             'Tracestate',
         ],
         exposeHeaders: ['X-Total-Count'],
-        credentials: true,
+        credentials: !allowWildcardCors,
     }));
+    const ensureConsoleSchemaReady = async (c) => {
+        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) => {
         const auth = await options.authenticate(c);
@@ -377,6 +430,161 @@ export function createConsoleRoutes(options) {
         resultPayload: parseJsonValue(row.result_payload),
         createdAt: row.created_at ?? '',
     });
+    const deleteUnreferencedPayloadSnapshots = async () => {
+        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 () => {
+        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 () => {
+        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 () => {
+        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 () => {
+        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 () => {
+        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 = null;
+    const runEventsPrune = async () => {
+        if (eventsPrunePromise) {
+            return eventsPrunePromise;
+        }
+        let pending;
+        pending = pruneConsoleEvents()
+            .then((result) => {
+            lastEventsPruneRunAt = Date.now();
+            return result;
+        })
+            .finally(() => {
+            if (eventsPrunePromise === pending) {
+                eventsPrunePromise = null;
+            }
+        });
+        eventsPrunePromise = pending;
+        return pending;
+    };
+    const triggerAutomaticEventsPrune = () => {
+        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) => {
         await db
             .insertInto('sync_operation_events')
@@ -523,7 +731,7 @@ export function createConsoleRoutes(options) {
             const partitionFilter = partitionId
                 ? sql `and partition_id = ${partitionId}`
                 : sql ``;
-            if (options.dialect.name === 'sqlite') {
+            if (options.dialect.family === 'sqlite') {
                 const bucketFormat = intervalToSqliteBucketFormat(interval);
                 const rowsResult = await sql `
             select
@@ -638,7 +846,7 @@ export function createConsoleRoutes(options) {
         const startTime = new Date(Date.now() - rangeMs);
         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 ``;
@@ -1631,9 +1839,31 @@ export function createConsoleRoutes(options) {
         const upgradeWebSocket = options.websocket.upgradeWebSocket;
         const heartbeatIntervalMs = options.websocket.heartbeatIntervalMs ?? 30000;
         const wsState = new WeakMap();
+        const closeUnauthenticated = (ws) => {
+            try {
+                ws.send(JSON.stringify({ type: 'error', message: 'UNAUTHENTICATED' }));
+            }
+            catch {
+                // ignore send errors
+            }
+            ws.close(4001, 'Unauthenticated');
+        };
+        const cleanup = (ws) => {
+            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');
@@ -1647,34 +1877,159 @@ export function createConsoleRoutes(options) {
             const mockContext = {
                 req: {
                     header: (name) => name === 'Authorization' ? authHeader : undefined,
-                    query: (name) => (name === 'token' ? token : undefined),
+                    query: () => undefined,
                 },
             };
-            const auth = await options.authenticate(mockContext);
+            const initialAuth = await options.authenticate(mockContext);
+            const authenticateWithBearer = async (token) => {
+                const trimmedToken = token.trim();
+                if (!trimmedToken)
+                    return null;
+                const authContext = {
+                    req: {
+                        header: (name) => name === 'Authorization' ? `Bearer ${trimmedToken}` : undefined,
+                        query: () => undefined,
+                    },
+                };
+                return options.authenticate(authContext);
+            };
             return {
                 onOpen(_event, ws) {
+                    const state = {
+                        listener: null,
+                        heartbeatInterval: null,
+                        authTimeout: null,
+                        isAuthenticated: false,
+                    };
+                    wsState.set(ws, state);
+                    const startAuthenticatedSession = () => {
+                        if (state.isAuthenticated)
+                            return;
+                        state.isAuthenticated = true;
+                        if (state.authTimeout) {
+                            clearTimeout(state.authTimeout);
+                            state.authTimeout = null;
+                        }
+                        const listener = (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: 'connected',
+                            timestamp: new Date().toISOString(),
+                        }));
+                        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);
+                        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) {
-                        ws.send(JSON.stringify({ type: 'error', message: 'UNAUTHENTICATED' }));
-                        ws.close(4001, 'Unauthenticated');
+                        closeUnauthenticated(ws);
+                        cleanup(ws);
                         return;
                     }
-                    const listener = (event) => {
+                    currentState.isAuthenticated = true;
+                    if (currentState.authTimeout) {
+                        clearTimeout(currentState.authTimeout);
+                        currentState.authTimeout = null;
+                    }
+                    const listener = (liveEvent) => {
                         if (partitionId) {
-                            const eventPartitionId = event.data.partitionId;
+                            const eventPartitionId = liveEvent.data.partitionId;
                             if (typeof eventPartitionId !== 'string' ||
                                 eventPartitionId !== partitionId) {
                                 return;
                             }
                         }
                         try {
-                            ws.send(JSON.stringify(event));
+                            ws.send(JSON.stringify(liveEvent));
                         }
                         catch {
                             // Connection closed
                         }
                     };
                     emitter.addListener(listener);
-                    // Send connected message
+                    currentState.listener = listener;
                     ws.send(JSON.stringify({
                         type: 'connected',
                         timestamp: new Date().toISOString(),
@@ -1693,7 +2048,6 @@ export function createConsoleRoutes(options) {
                             break;
                         }
                     }
-                    // Start heartbeat
                     const heartbeatInterval = setInterval(() => {
                         try {
                             ws.send(JSON.stringify({
@@ -1705,23 +2059,13 @@ export function createConsoleRoutes(options) {
                             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);
                 },
             };
         }));
@@ -1886,10 +2230,12 @@ export function createConsoleRoutes(options) {
             return c.json({ error: 'UNAUTHENTICATED' }, 401);
         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 = { deletedCount };
         return c.json(result, 200);
@@ -1920,45 +2266,15 @@ export function createConsoleRoutes(options) {
         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 = { deletedCount };
         return c.json(result, 200);
@@ -2549,6 +2865,125 @@ export function createConsoleRoutes(options) {
         };
         return c.json(response, 200);
     });
+    // -----------------------------------------------------------------------
+    // 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, {
+            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;
 }
 // ===========================================================================
@@ -2577,25 +3012,17 @@ async function hashApiKey(secretKey) {
  * The token can be set via SYNC_CONSOLE_TOKEN env var or passed directly.
  */
 export function createTokenAuthenticator(token) {
-    const expectedToken = token ?? process.env.SYNC_CONSOLE_TOKEN;
+    const expectedToken = (token ?? process.env.SYNC_CONSOLE_TOKEN)?.trim() ?? '';
     return async (c) => {
-        if (!expectedToken) {
-            // No token configured, allow all requests (not recommended for production)
-            return { consoleUserId: 'anonymous' };
-        }
-        // Check Authorization header
-        const authHeader = c.req.header('Authorization');
+        if (!expectedToken)
+            return null;
+        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;
     };
 }