@rebasepro/server-postgres 0.17.3-canary.gdd23447 → 0.18.0

package/src/websocket.ts

@@ -1,855 +0,0 @@
-import { RealtimeService } from "./services/realtimeService";
-import { PostgresBackendDriver, effectiveSqlRole } from "./PostgresBackendDriver";
-import type { DataDriver, DeleteProps, FetchCollectionProps, FetchOneProps, SaveProps, TableMetadata, BranchInfo, AuthAdapter } from "@rebasepro/types";
-import { ANONYMOUS_USER_ID, isSQLAdmin, isSchemaAdmin, resolveClientListLimit, ListLimitError } from "@rebasepro/types";
-import type { User } from "@rebasepro/types";
-
-import { WebSocketServer, WebSocket } from "ws";
-import { Server } from "http";
-import { inspect } from "util";
-import { extractUserFromToken, AccessTokenPayload, safeCompare, resolveRequireAuth, assertWriteRequestValid, ApiError } from "@rebasepro/server";
-import { logger } from "@rebasepro/server";
-
-/** Minimal subset of RebaseAuthConfig used by the WebSocket layer. */
-interface WsAuthConfig {
-    requireAuth?: boolean;
-    jwtSecret?: string;
-    /**
-     * Same static server-to-server secret the HTTP middleware accepts. Without
-     * it here, a service key authenticates over HTTP but not over the socket —
-     * so any SDK client using one (scripts, cron, server-to-server) connects,
-     * fails realtime auth with "jwt malformed", and silently gets no events.
-     */
-    serviceKey?: string;
-}
-
-/**
- * Normalized user identity for WebSocket sessions.
- */
-interface WsUserIdentity {
-    uid: string;
-    roles: string[];
-    isAdmin: boolean;
-}
-
-interface ClientSession {
-    ws: WebSocket;
-    user?: WsUserIdentity;
-    authenticated: boolean;
-    /** Sliding window message counter for rate limiting */
-    messageCount: number;
-    messageWindowStart: number;
-    /** The same window, counted separately for channel frames. */
-    channelMessageCount: number;
-    channelWindowStart: number;
-}
-
-
-/** Maximum messages per client per window */
-const WS_RATE_LIMIT = 2000;
-/** Rate limit window in milliseconds (60 seconds) */
-const WS_RATE_WINDOW_MS = 60_000;
-
-/**
- * Channel frames get their own budget, because they are a different workload.
- *
- * 2000/minute is 33/second, which is generous for queries and subscriptions and
- * an order of magnitude below what the documented channel idiom asks for: the
- * capacity note in `docs/backend/realtime.md` uses 60 fps cursor movement as
- * its worked example, and the presence idiom re-`track()`s on every move, so
- * one client sustaining that sends ~120 frames/second — 7200 a minute. Sharing
- * one counter meant the cursor stream ate the query budget and then froze for
- * the rest of the window.
- *
- * The number is sized to that documented workload and nothing more; it is not
- * a considered product limit (see `docs/channel-authorization.md`).
- */
-const WS_CHANNEL_RATE_LIMIT = 7200;
-
-/** Frames counted against the channel budget rather than the general one. */
-const CHANNEL_MESSAGE_TYPES = new Set([
-    "join_channel",
-    "leave_channel",
-    "broadcast",
-    "presence_track",
-    "presence_untrack",
-    "presence_state",
-    "channel_history"
-]);
-
-/**
- * WebSocket message types that require an admin session.
- *
- * Exported so the test can READ it. It used to be private, and the test that
- * exists to make "a privileged verb added without a role check" impossible held
- * a hand-typed copy of the same nine strings — so it agreed with itself, and
- * `FETCH_APPLICATION_ROLES` was added to neither. That verb runs
- * `SELECT DISTINCT unnest(roles)` over the users table through `executeSql`,
- * which is the owner connection and not subject to RLS, so any authenticated
- * non-admin could enumerate every role in the project — and any anonymous
- * socket could, on a deployment with `requireAuth: false`.
- *
- * The list is no longer the whole guarantee. `PUBLIC_TYPES` below is its
- * counterpart, and a test asserts that every `case` this file handles appears
- * in exactly one of the two — so a verb added to neither fails rather than
- * defaulting to reachable.
- */
-export const ADMIN_ONLY_TYPES = new Set([
-    "EXECUTE_SQL",
-    "FETCH_DATABASES",
-    "FETCH_ROLES",
-    "FETCH_APPLICATION_ROLES",
-    "FETCH_UNMAPPED_TABLES",
-    "FETCH_TABLE_METADATA",
-    "FETCH_CURRENT_DATABASE",
-    "CREATE_BRANCH",
-    "DELETE_BRANCH",
-    "LIST_BRANCHES"
-]);
-
-/**
- * Message types deliberately reachable by a non-admin session.
- *
- * Data operations, gated per row by RLS and per request by the same write
- * checks the REST layer applies — not by this list. It exists so that "which
- * bucket is this verb in" is a question with an answer for every verb, and
- * adding one without answering it is a test failure.
- */
-export const PUBLIC_TYPES = new Set([
-    "FETCH_COLLECTION",
-    "FETCH_ONE",
-    "COUNT",
-    "SAVE",
-    "DELETE",
-    "CHECK_UNIQUE_FIELD"
-]);
-
-/**
- * Recursively extract the deepest error message from an error's cause chain (e.g., Drizzle wrapping a PG error).
- */
-function extractErrorMessage(error: unknown): string {
-    if (!error) return "Unknown error";
-    if (error instanceof Error) {
-        if ("cause" in error && error.cause) {
-            return extractErrorMessage(error.cause);
-        }
-        return error.message;
-    }
-    if (typeof error === "object" && "message" in error && typeof (error as { message: unknown }).message === "string") {
-        return (error as { message: string }).message;
-    }
-    return String(error);
-}
-
-/**
- * Check if the current session belongs to an admin user.
- */
-function isAdminSession(session: ClientSession | undefined): boolean {
-    if (!session?.user) return false;
-    // Fast path: new adapter-aware sessions set isAdmin directly
-    if (session.user.isAdmin) return true;
-    if (!session.user.roles) return false;
-    return session.user.roles.some((r) => r === "admin");
-}
-
-export function createPostgresWebSocket(
-    server: Server,
-    realtimeService: RealtimeService,
-    driver: PostgresBackendDriver,
-    authConfig?: WsAuthConfig,
-    authAdapter?: AuthAdapter
-) {
-    // Session map scoped to this factory invocation — prevents stale sessions
-    // leaking across hot reloads or multiple factory calls.
-    const clientSessions = new Map<string, ClientSession>();
-
-    const isProduction = process.env.NODE_ENV === "production";
-    /** Debug logger that is suppressed in production to prevent PII/data leaks */
-    const wsDebug = (...args: unknown[]) => { if (!isProduction) console.debug(...args); };
-    const wss = new WebSocketServer({ server });
-
-    // Handle errors on the WSS so that EADDRINUSE from the underlying HTTP
-    // server doesn't surface as an unhandled 'error' event and crash the
-    // process.  The dev-mode `listenWithPortRetry` utility handles retry
-    // logic on the HTTP server side — we just need the WSS not to throw.
-    wss.on("error", (err: NodeJS.ErrnoException) => {
-        if (err.code === "EADDRINUSE") {
-            // Silently absorbed — listenWithPortRetry will retry the next port
-            return;
-        }
-        logger.error("❌ [WebSocket Server] Error", { error: err });
-    });
-
-    // The same predicate the HTTP data routes use, from the same function —
-    // this socket is the other enforcement point for one product decision, and
-    // while it computed the answer itself it computed a different one. See
-    // `resolveRequireAuth` for what its local copy got wrong and why a `false`
-    // here grants access rather than skipping a check.
-    const requireAuth = !!authAdapter || resolveRequireAuth(authConfig as never);
-
-    if (requireAuth && !authAdapter && !authConfig?.jwtSecret && !authConfig?.serviceKey) {
-        logger.warn(
-            "🔐 [WebSocket Server] Authentication is required but no adapter, jwtSecret or " +
-            "serviceKey is configured — no client can complete AUTH, so every realtime " +
-            "message will be refused with UNAUTHORIZED."
-        );
-    }
-
-    wss.on("connection", (ws) => {
-        const clientId = `client_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
-        wsDebug(`WebSocket client connected: ${clientId}`);
-
-        // Initialize client session
-        clientSessions.set(clientId, { ws,
-authenticated: !requireAuth,
-messageCount: 0,
-messageWindowStart: Date.now(),
-channelMessageCount: 0,
-channelWindowStart: Date.now() });
-        realtimeService.addClient(clientId, ws);
-
-        ws.on("close", () => {
-            wsDebug(`WebSocket client disconnected: ${clientId}`);
-            clientSessions.delete(clientId);
-        });
-
-        // Route all messages through RealtimeService for unified handling
-        ws.on("message", async (message) => {
-            let requestId: string | undefined;
-            try {
-                const {
-                    type,
-                    payload,
-                    requestId: reqId
-                } = JSON.parse(message.toString());
-                requestId = reqId; // Capture requestId for use in catch block
-
-                wsDebug(`[WS] ${clientId} → ${type}`, requestId ? `(${requestId})` : "");
-
-                // Handle authentication first
-                // Helper: send a canonical error frame
-                const sendError = (errType: "ERROR" | "AUTH_ERROR", code: string, msg: string) => {
-                    ws.send(JSON.stringify({
-                        type: errType,
-                        requestId,
-                        payload: { error: { message: msg,
-code } }
-                    }));
-                };
-
-                if (type === "AUTHENTICATE") {
-                    const { token } = payload || {};
-                    if (!token) {
-                        sendError("AUTH_ERROR", "INVALID_INPUT", "Token is required");
-                        return;
-                    }
-
-                    // Use the auth adapter when available (custom auth, Clerk, etc.)
-                    // Fall back to JWT extraction otherwise.
-                    let verifiedUser: WsUserIdentity | null = null;
-
-                    if (authAdapter) {
-                        try {
-                            const adapterUser = authAdapter.verifyToken
-                                ? await authAdapter.verifyToken(token)
-                                : await authAdapter.verifyRequest(new Request("http://localhost/_ws_auth", {
-                                    headers: { Authorization: `Bearer ${token}` }
-                                }));
-
-                            if (adapterUser) {
-                                verifiedUser = {
-                                    uid: adapterUser.uid,
-                                    roles: adapterUser.roles,
-                                    isAdmin: adapterUser.isAdmin
-                                };
-                            }
-                        } catch {
-                            // Adapter threw — treat as invalid token
-                        }
-                    } else if (authConfig?.serviceKey && safeCompare(token, authConfig.serviceKey)) {
-                        // Service key: a static secret, not a JWT. Checked
-                        // before verification, mirroring the HTTP middleware —
-                        // verifying it as a JWT can only ever fail.
-                        verifiedUser = { uid: "service", roles: ["admin"], isAdmin: true };
-                    } else {
-                        // Standard JWT path
-                        const jwtPayload = await extractUserFromToken(token);
-                        if (jwtPayload) {
-                            verifiedUser = {
-                                uid: jwtPayload.uid,
-                                roles: jwtPayload.roles ?? [],
-                                isAdmin: (jwtPayload.roles ?? []).some((r: string) => r === "admin")
-                            };
-                        }
-                    }
-
-                    if (verifiedUser) {
-                        const session = clientSessions.get(clientId);
-                        if (session) {
-                            session.user = verifiedUser;
-                            session.authenticated = true;
-                        }
-                        wsDebug(`[WS] replying AUTH_SUCCESS for requestId ${requestId}`);
-                        ws.send(JSON.stringify({
-                            type: "AUTH_SUCCESS",
-                            requestId,
-                            payload: { uid: verifiedUser.uid,
-roles: verifiedUser.roles }
-                        }));
-                        wsDebug(`🔐 [WebSocket Server] Client ${clientId} authenticated as ${verifiedUser.uid}`);
-                    } else {
-                        wsDebug(`[WS] replying AUTH_ERROR for requestId ${requestId} (invalid token)`);
-                        sendError("AUTH_ERROR", "INVALID_TOKEN", "Invalid or expired token");
-                    }
-                    return;
-                }
-
-                // Check authentication for protected operations
-                if (requireAuth) {
-                    const session = clientSessions.get(clientId);
-                    if (!session?.authenticated) {
-                        sendError("ERROR", "UNAUTHORIZED", "Authentication required");
-                        return;
-                    }
-                }
-
-                // Rate limiting: reject if client exceeds message limit.
-                // Channel frames are counted against their own budget — see
-                // WS_CHANNEL_RATE_LIMIT for why one shared counter starved them.
-                {
-                    const session = clientSessions.get(clientId);
-                    if (session) {
-                        const now = Date.now();
-                        const isChannelFrame = CHANNEL_MESSAGE_TYPES.has(type);
-                        if (isChannelFrame) {
-                            if (now - session.channelWindowStart > WS_RATE_WINDOW_MS) {
-                                session.channelMessageCount = 0;
-                                session.channelWindowStart = now;
-                            }
-                            session.channelMessageCount++;
-                            if (session.channelMessageCount > WS_CHANNEL_RATE_LIMIT) {
-                                sendError("ERROR", "RATE_LIMITED", "Too many channel messages. Please slow down.");
-                                return;
-                            }
-                        } else {
-                            if (now - session.messageWindowStart > WS_RATE_WINDOW_MS) {
-                                session.messageCount = 0;
-                                session.messageWindowStart = now;
-                            }
-                            session.messageCount++;
-                            if (session.messageCount > WS_RATE_LIMIT) {
-                                sendError("ERROR", "RATE_LIMITED", "Too many requests. Please slow down.");
-                                return;
-                            }
-                        }
-                    }
-                }
-
-                // Admin-only operations require admin role
-                if (ADMIN_ONLY_TYPES.has(type)) {
-                    const session = clientSessions.get(clientId);
-                    if (!isAdminSession(session)) {
-                        sendError("ERROR", "FORBIDDEN", "Admin access required for this operation");
-                        return;
-                    }
-                }
-
-                /**
-                 * Apply the REST layer's write checks to a socket payload.
-                 *
-                 * Silent when the path names no registered collection: the
-                 * driver decides what a path means, and refusing here would
-                 * turn "unknown collection" into a validation error.
-                 */
-                const assertWriteRequest = (path: string | undefined, values: unknown): void => {
-                    if (!path || !values || typeof values !== "object") return;
-                    const collection = driver.registry?.getCollectionByPath(path);
-                    if (!collection) return;
-                    assertWriteRequestValid(values as Record<string, unknown>, collection);
-                };
-
-                // Helper to get correctly scoped delegate for the current request
-                const getScopedDelegate = async (): Promise<DataDriver> => {
-                    const session = clientSessions.get(clientId);
-                    // Check if the driver supports RLS-scoped delegates
-                    if (typeof driver.withAuth === "function") {
-                        try {
-                            const userForAuth: User = session?.user
-                                ? {
-                                    uid: session.user.uid,
-                                    displayName: null,
-                                    email: null,
-                                    photoURL: null,
-                                    providerId: "websocket",
-                                    isAnonymous: false,
-                                    roles: session.user.roles ?? []
-                                }
-                                : {
-                                    uid: ANONYMOUS_USER_ID,
-                                    displayName: null,
-                                    email: null,
-                                    photoURL: null,
-                                    providerId: "websocket",
-                                    isAnonymous: true,
-                                    roles: ["anon"]
-                                };
-                            return await driver.withAuth(userForAuth);
-                        } catch (e) {
-                            logger.error("Failed to create RLS scoped delegate for WS request", { error: e });
-                            throw new Error("Internal authentication error");
-                        }
-                    }
-                    return driver;
-                };
-
-                switch (type) {
-                    case "FETCH_COLLECTION": {
-                        wsDebug("📋 [WebSocket Server] Processing FETCH_COLLECTION request");
-                        const request: FetchCollectionProps = payload;
-                        const delegate = await getScopedDelegate();
-                        // Bound the client-supplied limit with the SAME guarantee
-                        // the REST ingress and `subscribe_collection` apply
-                        // (`resolveClientListLimit`). Without it an absent limit
-                        // reached the driver as `undefined`, which emits no LIMIT
-                        // clause — one socket frame streamed the whole table, on
-                        // the one transport that skipped the ceiling every other
-                        // read path enforces.
-                        const rows = await delegate.fetchCollection({
-                            ...request,
-                            limit: resolveClientListLimit(request.limit, {
-                                vectorSearch: !!request.vectorSearch
-                            })
-                        });
-                        wsDebug("📋 [WebSocket Server] FETCH_COLLECTION result - rows count:", rows.length);
-                        const response = {
-                            type: "FETCH_COLLECTION_SUCCESS",
-                            payload: { rows },
-                            requestId
-                        };
-                        wsDebug("📋 [WebSocket Server] Sending FETCH_COLLECTION_SUCCESS response");
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "FETCH_ONE": {
-                        wsDebug("📄 [WebSocket Server] Processing FETCH_ENTITY request");
-                        const request: FetchOneProps = payload;
-                        const delegate = await getScopedDelegate();
-                        const row = await delegate.fetchOne(request);
-                        wsDebug("📄 [WebSocket Server] FETCH_ENTITY result:", row);
-                        const response = {
-                            type: "FETCH_ONE_SUCCESS",
-                            payload: { row: row ?? null },
-                            requestId
-                        };
-                        wsDebug("📄 [WebSocket Server] Sending FETCH_ENTITY_SUCCESS response");
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "SAVE": {
-                        wsDebug("💾 [WebSocket Server] Processing SAVE_ENTITY request");
-                        const request: SaveProps = payload;
-                        wsDebug("💾 [WebSocket Server] Saving row with request:", inspect(request, { depth: null,
-colors: true }));
-                        // The same two checks the REST write routes run, on the
-                        // same input, at the same point. This socket is the
-                        // other request boundary — the comment on `requireAuth`
-                        // above says so — and it used to hand the client's
-                        // payload straight to the driver, so a value the HTTP
-                        // API answers 400 for was written when it arrived here.
-                        //
-                        // The collection comes from the registry by path, never
-                        // from `request.collection`: that field is client-
-                        // supplied, and reading the rules out of it would let
-                        // the caller choose which rules to be checked against.
-                        assertWriteRequest(request.path, request.values as Record<string, unknown>);
-                        const delegate = await getScopedDelegate();
-                        const row = await delegate.save(request);
-                        wsDebug("💾 [WebSocket Server] SAVE_ENTITY result:", inspect(row, { depth: null,
-colors: true }));
-                        const response = {
-                            type: "SAVE_SUCCESS",
-                            payload: { row },
-                            requestId
-                        };
-                        wsDebug("💾 [WebSocket Server] Sending SAVE_ENTITY_SUCCESS response");
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "DELETE": {
-                        wsDebug("🗑️ [WebSocket Server] Processing DELETE_ENTITY request");
-                        const request: DeleteProps = payload;
-                        wsDebug("🗑️ [WebSocket Server] Deleting row:", request.row);
-                        const delegate = await getScopedDelegate();
-                        await delegate.delete(request);
-                        wsDebug("🗑️ [WebSocket Server] DELETE_ENTITY completed successfully");
-                        const response = {
-                            type: "DELETE_SUCCESS",
-                            payload: { success: true },
-                            requestId
-                        };
-                        wsDebug("🗑️ [WebSocket Server] Sending DELETE_ENTITY_SUCCESS response");
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "CHECK_UNIQUE_FIELD": {
-                        wsDebug("🔍 [WebSocket Server] Processing CHECK_UNIQUE_FIELD request");
-                        const {
-                            path,
-                            name,
-                            value,
-                            id,
-                            collection
-                        } = payload;
-                        const delegate = await getScopedDelegate();
-                        const isUnique = await delegate.checkUniqueField(path, name, value, id, collection);
-                        wsDebug("🔍 [WebSocket Server] CHECK_UNIQUE_FIELD result:", isUnique);
-                        const response = {
-                            type: "CHECK_UNIQUE_FIELD_SUCCESS",
-                            payload: { isUnique },
-                            requestId
-                        };
-                        wsDebug("🔍 [WebSocket Server] Sending CHECK_UNIQUE_FIELD_SUCCESS response");
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-
-                    case "COUNT": {
-                        // Deliberately NOT routed through `resolveClientListLimit`:
-                        // this answers with a scalar, and the driver drops `limit`
-                        // on the way to `SELECT count(*)`. Clamping here could only
-                        // ever make `total` describe fewer rows than the collection
-                        // holds — the page size is the caller's business, the total
-                        // is not.
-                        const request: FetchCollectionProps = payload;
-                        const delegate = await getScopedDelegate();
-                        const count = await delegate.count!(request);
-                        const response = {
-                            type: "COUNT_SUCCESS",
-                            payload: { count },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "EXECUTE_SQL": {
-                        const { sql, options } = payload;
-                        try {
-                            const delegate = await getScopedDelegate();
-                            const admin = delegate.admin;
-                            if (!isSQLAdmin(admin)) {
-                                sendError("ERROR", "NOT_SUPPORTED", "SQL execution is not available for this driver.");
-                                break;
-                            }
-                            const result = await admin.executeSql(sql, options);
-                            if (process.env.NODE_ENV !== "production") {
-                                wsDebug(`⚡ [WebSocket Server] SQL executed. Returned ${Array.isArray(result) ? result.length : "non-array"} rows.`);
-                            }
-                            const auditSession = clientSessions.get(clientId);
-                            // Through `logger`, not `console.log`: this line is
-                            // emitted in production, and a bare console call
-                            // has no severity, no timestamp, no JSON envelope
-                            // and no LOG_LEVEL gate, so it lands in Cloud
-                            // Logging as unstructured text the queries written
-                            // for every other line cannot match.
-                            //
-                            // The bound values are counted, never written — the
-                            // statement is the audit signal, the parameters are
-                            // whatever row the operator was touching. (stdout is
-                            // not an audit sink either; a real trail belongs in
-                            // a table with an actor and a retention policy.)
-                            logger.info("[SQL Audit] WebSocket SQL execution", {
-                                sql: typeof sql === "string" ? sql.substring(0, 500) : String(sql),
-                                database: options?.database,
-                                role: options?.role,
-                                // The role the statement asked for is above;
-                                // this is the one it ran as. They used to be
-                                // assumed identical, so an execution that fell
-                                // back to the owner was audited under the role
-                                // it had failed to assume. That fallback is now
-                                // an error everywhere except the documented
-                                // `DISABLE_DB_ROLE_SWITCHING` opt-out — which is
-                                // precisely the case this line still has to
-                                // report honestly.
-                                effectiveRole: effectiveSqlRole(options?.role),
-                                paramCount: Array.isArray(options?.params) ? options.params.length : 0,
-                                resultRows: Array.isArray(result) ? result.length : "unknown",
-                                uid: auditSession?.user?.uid ?? "unknown",
-                                roles: auditSession?.user?.roles ?? [],
-                                isAdmin: auditSession?.user?.isAdmin ?? false,
-                                requestId
-                            });
-                            const response = {
-                                type: "EXECUTE_SQL_SUCCESS",
-                                payload: { result },
-                                requestId
-                            };
-                            ws.send(JSON.stringify(response));
-                        } catch (sqlError: unknown) {
-                            // This is a query execution error (e.g., syntax error, permission denied).
-                            // We return it cleanly to the client without logging a server stack trace.
-                            const errMsg = extractErrorMessage(sqlError);
-                            sendError("ERROR", "SQL_ERROR", errMsg);
-                        }
-                    }
-                        break;
-
-                    case "FETCH_DATABASES": {
-                        wsDebug("📚 [WebSocket Server] Processing FETCH_DATABASES request");
-                        const delegate = await getScopedDelegate();
-                        const admin = delegate.admin;
-                        let databases: string[] = [];
-                        if (isSQLAdmin(admin) && admin.fetchAvailableDatabases) {
-                            databases = await admin.fetchAvailableDatabases();
-                        }
-                        wsDebug(`📚 [WebSocket Server] Fetched ${databases.length} databases.`);
-                        const response = {
-                            type: "FETCH_DATABASES_SUCCESS",
-                            payload: { databases },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "FETCH_ROLES": {
-                        wsDebug("👤 [WebSocket Server] Processing FETCH_ROLES request");
-                        const delegate = await getScopedDelegate();
-                        const admin = delegate.admin;
-                        let roles: string[] = [];
-                        if (isSQLAdmin(admin) && admin.fetchAvailableRoles) {
-                            roles = await admin.fetchAvailableRoles();
-                        }
-                        wsDebug(`👤 [WebSocket Server] Fetched ${roles.length} roles.`);
-                        const response = {
-                            type: "FETCH_ROLES_SUCCESS",
-                            payload: { roles },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "FETCH_APPLICATION_ROLES": {
-                        wsDebug("👤 [WebSocket Server] Processing FETCH_APPLICATION_ROLES request");
-                        const delegate = await getScopedDelegate();
-                        const admin = delegate.admin;
-                        let roles: string[] = [];
-                        if (isSQLAdmin(admin) && admin.fetchApplicationRoles) {
-                            roles = await admin.fetchApplicationRoles();
-                        }
-                        wsDebug(`👤 [WebSocket Server] Fetched ${roles.length} application roles.`);
-                        const response = {
-                            type: "FETCH_APPLICATION_ROLES_SUCCESS",
-                            payload: { roles },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "FETCH_CURRENT_DATABASE": {
-                        wsDebug("📚 [WebSocket Server] Processing FETCH_CURRENT_DATABASE request");
-                        const delegate = await getScopedDelegate();
-                        const admin = delegate.admin;
-                        let database: string | undefined = undefined;
-                        if (isSQLAdmin(admin) && admin.fetchCurrentDatabase) {
-                            database = await admin.fetchCurrentDatabase();
-                        }
-                        const response = {
-                            type: "FETCH_CURRENT_DATABASE_SUCCESS",
-                            payload: { database },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "FETCH_UNMAPPED_TABLES": {
-                        wsDebug("📋 [WebSocket Server] Processing FETCH_UNMAPPED_TABLES request");
-                        const delegate = await getScopedDelegate();
-                        const admin = delegate.admin;
-                        let tables: string[] = [];
-                        if (isSchemaAdmin(admin) && admin.fetchUnmappedTables) {
-                            tables = await admin.fetchUnmappedTables(payload?.mappedPaths);
-                        }
-                        wsDebug(`📋 [WebSocket Server] Fetched ${tables.length} unmapped tables.`);
-                        const response = {
-                            type: "FETCH_UNMAPPED_TABLES_SUCCESS",
-                            payload: { tables },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "FETCH_TABLE_METADATA": {
-                        wsDebug("📋 [WebSocket Server] Processing FETCH_TABLE_METADATA request");
-                        const { tableName } = payload;
-                        const delegate = await getScopedDelegate();
-                        const admin = delegate.admin;
-                        let metadata: TableMetadata | undefined;
-                        if (isSchemaAdmin(admin) && admin.fetchTableMetadata) {
-                            metadata = await admin.fetchTableMetadata(tableName) as TableMetadata;
-                        }
-                        wsDebug(`📋 [WebSocket Server] Fetched metadata for table '${tableName}'. (${metadata?.columns?.length ?? 0} columns)`);
-                        const response = {
-                            type: "FETCH_TABLE_METADATA_SUCCESS",
-                            payload: { metadata },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "CREATE_BRANCH": {
-                        wsDebug("🌿 [WebSocket Server] Processing CREATE_BRANCH request");
-                        const { name, options } = payload;
-                        const delegate = await getScopedDelegate();
-                        if (!delegate.admin?.createBranch) {
-                            sendError("ERROR", "NOT_SUPPORTED", "Database branching is not available. Configure adminConnectionString.");
-                            break;
-                        }
-                        const branch: BranchInfo = await delegate.admin.createBranch(name, options);
-                        wsDebug(`🌿 [WebSocket Server] Branch created: ${branch.name}`);
-                        const response = {
-                            type: "CREATE_BRANCH_SUCCESS",
-                            payload: { branch },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "DELETE_BRANCH": {
-                        wsDebug("🗑️ [WebSocket Server] Processing DELETE_BRANCH request");
-                        const { name: branchName } = payload;
-                        const delegate = await getScopedDelegate();
-                        if (!delegate.admin?.deleteBranch) {
-                            sendError("ERROR", "NOT_SUPPORTED", "Database branching is not available.");
-                            break;
-                        }
-                        await delegate.admin.deleteBranch(branchName);
-                        wsDebug(`🗑️ [WebSocket Server] Branch deleted: ${branchName}`);
-                        const response = {
-                            type: "DELETE_BRANCH_SUCCESS",
-                            payload: { success: true },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    case "LIST_BRANCHES": {
-                        wsDebug("🌿 [WebSocket Server] Processing LIST_BRANCHES request");
-                        const delegate = await getScopedDelegate();
-                        let branches: BranchInfo[] = [];
-                        if (delegate.admin?.listBranches) {
-                            branches = await delegate.admin.listBranches();
-                        }
-                        wsDebug(`🌿 [WebSocket Server] Listed ${branches.length} branches.`);
-                        const response = {
-                            type: "LIST_BRANCHES_SUCCESS",
-                            payload: { branches },
-                            requestId
-                        };
-                        ws.send(JSON.stringify(response));
-                    }
-                        break;
-
-                    // Route subscription messages, broadcast channels, and presence to RealtimeService
-                    case "subscribe_collection":
-                    case "subscribe_one":
-                    case "unsubscribe":
-                    case "join_channel":
-                    case "leave_channel":
-                    case "broadcast":
-                    case "presence_track":
-                    case "presence_untrack":
-                    case "presence_state":
-                    case "channel_history": {
-                        wsDebug("🔄 [WebSocket Server] Routing realtime message to RealtimeService:", type);
-                        // Attach auth context from the WS session so RLS-aware refetches work
-                        const session = clientSessions.get(clientId);
-                        const authContext = session?.user
-                            ? { uid: session.user.uid,
-roles: session.user.roles ?? [] }
-                            : { uid: ANONYMOUS_USER_ID,
-roles: ["anon"] };
-                        // Let RealtimeService handle these messages
-                        await realtimeService.handleClientMessage(clientId, {
-                            type,
-                            payload,
-                            subscriptionId: payload?.subscriptionId
-                        }, authContext);
-                        break;
-                    }
-
-                    default:
-                        logger.error("❌ [WebSocket Server] Unknown message type", { detail: type });
-                }
-            } catch (error: unknown) {
-                // A refused `limit` is the caller's mistake, not a server fault.
-                // Left to the generic branch below it answers INTERNAL_ERROR
-                // with the message suppressed in production — so the one thing
-                // that would tell the caller what to send instead is exactly
-                // what gets dropped. Answered here the way
-                // `subscribe_collection` already answers it: INVALID_LIMIT,
-                // message intact. The text names the ceiling and nothing else.
-                if (error instanceof ListLimitError) {
-                    logger.warn(`[WebSocket Server] Refused a list read: ${error.message}`);
-                    ws.send(JSON.stringify({
-                        type: "ERROR",
-                        requestId,
-                        payload: { error: { message: error.message,
-code: "INVALID_LIMIT" } }
-                    }));
-                    return;
-                }
-                // A refused write is the caller's mistake, and its message is
-                // the only thing that says what to send instead — the same
-                // reasoning as `ListLimitError` above. Left to the generic
-                // branch it becomes INTERNAL_ERROR with the text dropped in
-                // production, so the socket would refuse the write and decline
-                // to say why.
-                if (error instanceof ApiError || (error as Error)?.name === "ApiError") {
-                    const apiError = error as ApiError;
-                    logger.warn(`[WebSocket Server] Refused a write: ${apiError.message}`);
-                    ws.send(JSON.stringify({
-                        type: "ERROR",
-                        requestId,
-                        payload: { error: { message: apiError.message,
-code: apiError.code } }
-                    }));
-                    return;
-                }
-                logger.error("💥 [WebSocket Server] Error handling message", { error: error });
-                if (error instanceof Error) {
-                    logger.error("Stack trace", { detail: error.stack });
-                }
-                // Unwrap the cause chain: a Drizzle failure reports itself as
-                // "Failed query: <sql> params:", which tells the user nothing and
-                // echoes the statement back at them. The reason is in the cause.
-                const errorMessage = process.env.NODE_ENV === "production"
-                    ? "An unexpected error occurred"
-                    : extractErrorMessage(error);
-                const errorResponse = {
-                    type: "ERROR",
-                    requestId,
-                    payload: {
-                        error: {
-                            message: errorMessage,
-                            code: "INTERNAL_ERROR"
-                        }
-                    }
-                };
-                ws.send(JSON.stringify(errorResponse));
-            }
-        });
-    });
-}