@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/requests/service/websocket.service.js

@@ -0,0 +1,2222 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject, Container } from 'inversify';
+import { Server as SocketIOServer } from 'socket.io';
+import { createAdapter } from '@socket.io/redis-adapter';
+import { createClient } from 'redis';
+import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { LoggerService } from '../../monitoring/logger/services/logger.service.js';
+import { AppConfigurationService } from '../../config/services/app-configuration.backend.service.js';
+import { RedisService } from '../../databases/services/redis.service.js';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
+import { ErrorCustomMessageReference, ErrorType, ExecutionContext_ExecutionType, ResourcePrimaryScope, CoreResourceOperation, ARRAY_RESPONSE_OPERATIONS, DataMode, ResourcesConfigOperationsDtosBuilderUtils, ResourceOperationsUtils, WildoHeaderKeys, ResourceOperationVariantType, isWildoBackendError, } from '@wildo-ai/saas-models';
+import { ExecutionContextCreatorBackendService, } from '../../runtime/services/execution-context-creator.backend.service.js';
+import { AuthorizationsBackendService } from '../../security/authorizations/services/authorizations.backend.service.js';
+import { ResourcesRegistryBackendService } from '../../resources/services/resources-registry.backend.service.js';
+import { WS_ResourceSubscribePayloadSchema, WS_ResourceEditingPayloadSchema, WS_ResourceCustomEventPayloadSchema, NotificationDisplayTarget, ResourceAction, buildResourceRoomName, buildScopeRoomName, buildUserRoomName, buildOrganizationRoomName, buildOrganizationRoleRoomName, buildAppRoleRoomName, parseOrganizationRoomName, WebSocketRoomPrefix, CoreWebSocketEvent, WebSocketResourceDeliveryTarget, } from '@wildo-ai/saas-models';
+function subscriptionMatchesOrganization(subscription, organizationId) {
+    if (subscription.scopeId === organizationId) {
+        return true;
+    }
+    return Object.values(subscription.contextResourceIdentifiers ?? {}).includes(organizationId);
+}
+/**
+ * Default rate limits per event type
+ */
+const DEFAULT_RATE_LIMITS = {
+    // Resource subscription: 20 per 10 seconds (allow rapid page navigation)
+    [CoreWebSocketEvent.RESOURCE_SUBSCRIBE]: { maxEvents: 20, windowSeconds: 10 },
+    [CoreWebSocketEvent.RESOURCE_UNSUBSCRIBE]: { maxEvents: 20, windowSeconds: 10 },
+    // Editing events: 10 per minute (reasonable for form editing)
+    [CoreWebSocketEvent.RESOURCE_EDITING_START]: { maxEvents: 10, windowSeconds: 60 },
+    [CoreWebSocketEvent.RESOURCE_EDITING_END]: { maxEvents: 10, windowSeconds: 60 },
+    // Custom events: 30 per second (for real-time collaboration like cursor moves)
+    [CoreWebSocketEvent.RESOURCE_CUSTOM]: { maxEvents: 30, windowSeconds: 1 },
+    // Badge requests: 10 per second
+    [CoreWebSocketEvent.BADGE_GET]: { maxEvents: 10, windowSeconds: 1 },
+    [CoreWebSocketEvent.BADGE_GET_ALL]: { maxEvents: 5, windowSeconds: 1 },
+    // Auth/system events: 5 per minute
+    [CoreWebSocketEvent.AUTH_REFRESH]: { maxEvents: 5, windowSeconds: 60 },
+    [CoreWebSocketEvent.ORGANIZATION_SWITCH]: { maxEvents: 10, windowSeconds: 60 },
+    // Default for unlisted events: 100 per minute
+    'default': { maxEvents: 100, windowSeconds: 60 },
+};
+/**
+ * WebSocket Service
+ *
+ * Provides real-time communication for SaaS applications:
+ * - Multi-tenant socket management with identity-based rooms
+ * - Resource-centric rooms for collaboration (editing, locking, custom events)
+ * - Role-based message broadcasting
+ * - Redis adapter for horizontal scaling
+ * - JWT authentication reusing ExecutionContextCreatorBackendService
+ * - Authorization reusing AuthorizationsBackendService
+ */
+let WebSocketService = class WebSocketService {
+    logger;
+    configService;
+    errorBuilder;
+    redisService;
+    executionContextCreator;
+    authorizationsService;
+    resourcesRegistry;
+    container;
+    io = null;
+    userSockets = new Map(); // userId -> socketIds
+    rooms = new Map();
+    organizationSockets = new Map(); // orgId -> socketIds
+    // NEW: Track authenticated sockets and editing state
+    authenticatedSockets = new Map(); // socketId -> auth info
+    resourceEditingState = new Map(); // resource room -> editing userIds
+    resourceSubscriptionsBySocket = new Map();
+    logDebug;
+    constructor(logger, configService, errorBuilder, redisService, executionContextCreator, authorizationsService, resourcesRegistry, container) {
+        this.logger = logger;
+        this.configService = configService;
+        this.errorBuilder = errorBuilder;
+        this.redisService = redisService;
+        this.executionContextCreator = executionContextCreator;
+        this.authorizationsService = authorizationsService;
+        this.resourcesRegistry = resourcesRegistry;
+        this.container = container;
+        this.logDebug = this.logger.debugByType('WebSocketService');
+        this.logger.setDebugTypeLogging('WebSocketService', false);
+    }
+    /**
+     * Lazy getter for NotificationBadgeService to break circular dependency
+     * NotificationBadgeService depends on WebSocketService, so we resolve it lazily
+     */
+    getBadgeService() {
+        return this.container.get(SAAS_SERVICE_TYPES.NotificationBadgeService);
+    }
+    getSocketAuth(socket) {
+        return socket.auth;
+    }
+    hasOrganizationAccess(auth, organizationId) {
+        if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+            return false;
+        }
+        return auth.initiatorRoles.some((roleInfo) => roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS
+            && roleInfo.relatedResourceId === organizationId);
+    }
+    trackSocketResourceSubscription(socketId, subscription) {
+        const subscriptions = this.resourceSubscriptionsBySocket.get(socketId) ?? new Map();
+        subscriptions.set(subscription.roomName, subscription);
+        this.resourceSubscriptionsBySocket.set(socketId, subscriptions);
+    }
+    untrackSocketResourceSubscription(socketId, roomName) {
+        const subscriptions = this.resourceSubscriptionsBySocket.get(socketId);
+        if (!subscriptions) {
+            return;
+        }
+        subscriptions.delete(roomName);
+        if (subscriptions.size === 0) {
+            this.resourceSubscriptionsBySocket.delete(socketId);
+        }
+    }
+    async revokeTrackedResourceSubscription(params) {
+        const { socket, auth, subscription, reason } = params;
+        await socket.leave(subscription.roomName);
+        if (subscription.resourceId && auth.initiatorIds?.userId) {
+            await this.trackEditingState(subscription.resourceType, subscription.resourceId, auth.initiatorIds.userId, 'end');
+            this.io?.to(subscription.roomName).emit(CoreWebSocketEvent.RESOURCE_EDITING_END, {
+                resourceType: subscription.resourceType,
+                resourceId: subscription.resourceId,
+                initiatorUserId: auth.initiatorIds.userId,
+                reason,
+                timestamp: new Date(),
+            });
+        }
+        this.untrackSocketResourceSubscription(socket.id, subscription.roomName);
+    }
+    async revalidateTrackedResourceSubscriptions(socket, auth) {
+        const subscriptions = Array.from(this.resourceSubscriptionsBySocket.get(socket.id)?.values() ?? []);
+        for (const subscription of subscriptions) {
+            try {
+                if (subscription.resourceId) {
+                    await this.verifyResourceAccess(socket, auth, subscription.resourceType, subscription.resourceId, subscription.contextResourceIdentifiers);
+                }
+                else if (subscription.scopeKey && subscription.scopeId) {
+                    await this.verifyScopeAccess(auth, subscription.scopeKey, subscription.scopeId, subscription.contextResourceIdentifiers);
+                }
+                else {
+                    throw new Error('Tracked resource subscription is missing routing identifiers');
+                }
+            }
+            catch {
+                await this.revokeTrackedResourceSubscription({
+                    socket,
+                    auth,
+                    subscription,
+                    reason: 'auth_refresh',
+                });
+            }
+        }
+    }
+    /**
+     * Initialize WebSocket server
+     *
+     * For platform services that don't serve frontends (e.g., crontabs-batches-manager),
+     * WebSocket initialization is skipped since they only receive internal backend requests.
+     */
+    async initialize(httpServer) {
+        const corsOrigins = this.getCorsOrigins();
+        // If no frontend URLs are configured, skip WebSocket initialization entirely
+        // This is expected for platform services that only receive backend-to-backend requests
+        // and don't need real-time WebSocket communication with browsers
+        if (corsOrigins.length === 0) {
+            this.logger.info('📝 No frontend URLs configured - skipping WebSocket initialization (platform/internal service mode)', {
+                availableEndpoints: Object.keys(this.configService.config?.runtime?.endPoints || {}),
+                note: 'This is expected for platform services that only receive backend-to-backend requests'
+            });
+            // Mark as "initialized" but in disabled mode - all public methods will safely no-op
+            this.io = null;
+            return;
+        }
+        const config = {
+            cors: {
+                origin: corsOrigins,
+                credentials: true
+            },
+            transports: ['websocket', 'polling'],
+            pingTimeout: 60000,
+            pingInterval: 25000,
+            maxHttpBufferSize: 1e6,
+            allowEIO3: true
+        };
+        this.io = new SocketIOServer(httpServer, config);
+        // Setup Redis adapter for horizontal scaling
+        await this.setupRedisAdapter();
+        // Setup authentication middleware (FACTORIZED with HTTP)
+        this.setupAuthentication();
+        // Setup rate limiting middleware (Redis-synchronized across pods)
+        this.setupRateLimiting();
+        // Setup connection handling (identity-based rooms)
+        this.setupConnectionHandling();
+        this.logDebug('WebSocket service initialized', {
+            cors: config.cors.origin,
+            transports: config.transports
+        });
+    }
+    // =====================================================
+    // PUBLIC MESSAGING METHODS
+    // =====================================================
+    /**
+     * Send message to specific user (with cross-pod support via Redis adapter)
+     */
+    async sendToUser(userId, message) {
+        if (!this.io) {
+            this.logger.warn('WebSocket not initialized');
+            return false;
+        }
+        const roomName = buildUserRoomName(userId);
+        this.io.to(roomName).emit(message.type, {
+            ...message,
+            timestamp: new Date(),
+        });
+        this.logDebug('Message sent to user', {
+            userId: userId.substring(0, 8) + '...',
+            messageType: message.type,
+        });
+        return true;
+    }
+    /**
+     * Send a direct notification to a specific user.
+     *
+     * This is a convenience method for sending user notifications that are not
+     * tied to resource operations (e.g., "Your export is ready", "Payment received").
+     *
+     * @param userId - The user ID to notify
+     * @param notification - Notification configuration
+     * @param notification.type - Notification level (info, success, warning, error)
+     * @param notification.identifier - i18n identifier for message lookup
+     * @param notification.message - Direct message (fallback if identifier not found)
+     * @param notification.title - Optional notification title
+     * @param notification.data - Additional context data
+     * @param notification.displayTarget - Where to display (toast, center, or both)
+     * @param notification.organizationId - Organization context (optional)
+     *
+     * @example
+     * // Notify user about export completion
+     * await webSocketService.notifyUser(userId, {
+     *   type: NotificationLevel.SUCCESS,
+     *   identifier: 'export.completed',
+     *   data: { fileName: 'report.pdf', downloadUrl: '/files/123' },
+     * });
+     *
+     * @example
+     * // Notify user with direct message
+     * await webSocketService.notifyUser(userId, {
+     *   type: NotificationLevel.INFO,
+     *   message: 'Your session will expire in 5 minutes',
+     *   displayTarget: NotificationDisplayTarget.TOAST,
+     * });
+     */
+    async notifyUser(userId, notification) {
+        const payload = {
+            notificationLevel: notification.type,
+            identifier: notification.identifier,
+            message: notification.message,
+            title: notification.title,
+            data: notification.data,
+            displayTarget: notification.displayTarget ?? NotificationDisplayTarget.BOTH,
+            organizationId: notification.organizationId,
+            timestamp: new Date(),
+        };
+        const wsMessage = {
+            type: CoreWebSocketEvent.USER_NOTIFICATION,
+            payload,
+            timestamp: new Date(),
+            userId,
+            organizationId: notification.organizationId,
+        };
+        return this.sendToUser(userId, wsMessage);
+    }
+    /**
+     * Send a direct notification to all users in an organization.
+     *
+     * @param organizationId - The organization ID
+     * @param notification - Notification configuration (same as notifyUser)
+     * @param excludeUsers - Optional list of user IDs to exclude
+     */
+    async notifyOrganization(organizationId, notification, excludeUsers) {
+        const payload = {
+            notificationLevel: notification.type,
+            identifier: notification.identifier,
+            message: notification.message,
+            title: notification.title,
+            data: notification.data,
+            displayTarget: notification.displayTarget ?? NotificationDisplayTarget.BOTH,
+            organizationId,
+            timestamp: new Date(),
+        };
+        const wsMessage = {
+            type: CoreWebSocketEvent.USER_NOTIFICATION,
+            payload,
+            timestamp: new Date(),
+            organizationId,
+        };
+        return this.sendToOrganization(organizationId, wsMessage, excludeUsers);
+    }
+    /**
+     * Send message to organization (with cross-pod support via Redis adapter)
+     */
+    async sendToOrganization(organizationId, message, excludeUsers) {
+        const roomName = buildOrganizationRoomName(organizationId);
+        const messageWithTimestamp = {
+            ...message,
+            timestamp: new Date(),
+            organizationId
+        };
+        if (!this.io) {
+            this.logger.warn('WebSocket not initialized');
+            return 0;
+        }
+        if (excludeUsers && excludeUsers.length > 0) {
+            // For cross-pod compatibility with Redis adapter:
+            // 1. Send to the org room (reaches all pods)
+            // 2. Exclude users by emitting to their user rooms with a "skip" flag
+            //
+            // Alternative approach: Use Socket.IO's except() which works with Redis adapter
+            const excludeRooms = excludeUsers.map(userId => buildUserRoomName(userId));
+            let broadcast = this.io.to(roomName);
+            for (const excludeRoom of excludeRooms) {
+                broadcast = broadcast.except(excludeRoom);
+            }
+            broadcast.emit(message.type, messageWithTimestamp);
+            this.logDebug('Message sent to organization with exclusions', {
+                organizationId: organizationId.substring(0, 8) + '...',
+                messageType: message.type,
+                excludedUsers: excludeUsers.length,
+            });
+            // Return approximate count (exact count not available with except())
+            return 1;
+        }
+        else {
+            this.io.to(roomName).emit(message.type, messageWithTimestamp);
+            this.logDebug('Message sent to organization', {
+                organizationId: organizationId.substring(0, 8) + '...',
+                messageType: message.type,
+            });
+            return 1;
+        }
+    }
+    /**
+     * Send message to users with specific role within an organization
+     */
+    async sendToRole(organizationId, role, message) {
+        const roomName = buildOrganizationRoleRoomName(organizationId, role);
+        const messageWithTimestamp = {
+            ...message,
+            timestamp: new Date(),
+            organizationId
+        };
+        if (!this.io) {
+            this.logger.warn('WebSocket not initialized');
+            return 0;
+        }
+        const sentCount = (await this.io.in(roomName).fetchSockets()).length;
+        this.io.to(roomName).emit(message.type, messageWithTimestamp);
+        this.logDebug('Message sent to role', {
+            organizationId: organizationId.substring(0, 8) + '...',
+            role,
+            messageType: message.type,
+            sentCount
+        });
+        return sentCount;
+    }
+    /**
+     * Send message to users with application-level role (admin dashboard users).
+     *
+     * Application-level roles are not scoped to an organization - they are global
+     * admin roles like super admins, support staff, billing admins, etc.
+     *
+     * Users with app-level roles join app role rooms (via buildAppRoleRoomName) on connection.
+     *
+     * @param role - The application-level role (e.g., 'admin', 'super_admin', 'support')
+     * @param message - The WebSocket message to send
+     * @returns Number of sockets the message was sent to
+     *
+     * @example
+     * // Notify all application administrators
+     * await webSocketService.sendToAppRole(CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN, {
+     *   type: CoreWebSocketEvent.USER_NOTIFICATION,
+     *   payload: { notificationLevel: NotificationLevel.WARNING, message: 'New user signup requires review' },
+     *   timestamp: new Date(),
+     * });
+     */
+    async sendToAppRole(role, message) {
+        const roomName = buildAppRoleRoomName(role);
+        const messageWithTimestamp = {
+            ...message,
+            timestamp: new Date(),
+        };
+        if (!this.io) {
+            this.logger.warn('WebSocket not initialized');
+            return 0;
+        }
+        const sentCount = (await this.io.in(roomName).fetchSockets()).length;
+        this.io.to(roomName).emit(message.type, messageWithTimestamp);
+        this.logDebug('Message sent to app role', {
+            role,
+            messageType: message.type,
+            sentCount
+        });
+        return sentCount;
+    }
+    /**
+     * Send a direct notification to users with a specific application-level role.
+     *
+     * Convenience method for sending admin notifications.
+     *
+     * @param role - The application-level role
+     * @param notification - Notification configuration
+     *
+     * @example
+     * // Notify support staff about a new ticket
+     * await webSocketService.notifyAppRole(CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN, {
+     *   type: NotificationLevel.INFO,
+     *   identifier: 'support.new_ticket',
+     *   data: { ticketId: '123', subject: 'Help needed' },
+     * });
+     */
+    async notifyAppRole(role, notification) {
+        const payload = {
+            notificationLevel: notification.type,
+            identifier: notification.identifier,
+            message: notification.message,
+            title: notification.title,
+            data: notification.data,
+            displayTarget: notification.displayTarget ?? NotificationDisplayTarget.BOTH,
+            timestamp: new Date(),
+        };
+        const wsMessage = {
+            type: CoreWebSocketEvent.USER_NOTIFICATION,
+            payload,
+            timestamp: new Date(),
+        };
+        return this.sendToAppRole(role, wsMessage);
+    }
+    /**
+     * Broadcast message to all connected users
+     */
+    async broadcast(message) {
+        if (!this.io) {
+            this.logger.warn('WebSocket not initialized');
+            return 0;
+        }
+        const messageWithTimestamp = {
+            ...message,
+            timestamp: new Date()
+        };
+        const sockets = await this.io.fetchSockets();
+        this.io.emit(message.type, messageWithTimestamp);
+        this.logDebug('Message broadcasted', {
+            messageType: message.type,
+            connectedSockets: sockets.length
+        });
+        return sockets.length;
+    }
+    // =====================================================
+    // RESOURCE ROOM PUBLIC METHODS (for NotificationDispatcher)
+    // =====================================================
+    /**
+     * Extract DataMode from a websocket payload.
+     * Defaults to RAW for websocket messages when no explicit data mode is present.
+     */
+    extractDataMode(payload) {
+        return ResourceOperationsUtils.extractDataMode(payload, undefined, DataMode.RAW);
+    }
+    /**
+     * Select the appropriate response DTO based on DataMode.
+     * Similar to controller-resource.backend.service.ts
+     */
+    selectResponseDto(operation, dataMode) {
+        if (!operation) {
+            return undefined;
+        }
+        return ResourcesConfigOperationsDtosBuilderUtils.selectResponseDto(operation, dataMode) || undefined;
+    }
+    /**
+     * Validate and transform websocket resource data before sending it.
+     * Similar to controller-resource.backend.service.ts sendResponse() method.
+     *
+     * This method validates resource data against the appropriate DTO and transforms dates.
+     * It is used for sync-grade replay payloads and for custom websocket events that
+     * choose to carry resource-shaped data.
+     *
+     * @param resourceData - The resource data to validate (if present in payload)
+     * @param resourceType - Resource type
+     * @param operationIdentifier - Operation identifier (optional)
+     * @param dataMode - Data mode (defaults to RAW)
+     * @returns Validated and transformed resource data, or false when validation cannot proceed
+     */
+    resolveOperationForWebSocketValidation(params) {
+        const desiredOperationIdentifier = params.validationTarget === 'canonical-read'
+            ? CoreResourceOperation.READ
+            : params.operationIdentifier ?? CoreResourceOperation.READ;
+        try {
+            const operationPath = this.resourcesRegistry.getOperationPathDefault(params.resourceType, desiredOperationIdentifier);
+            return this.resourcesRegistry.getOperationFromPath(operationPath);
+        }
+        catch (error) {
+            this.logger.warn('WebSocket resource data validation lookup failed', {
+                resourceType: params.resourceType,
+                operationIdentifier: params.operationIdentifier,
+                desiredOperationIdentifier,
+                dataMode: params.dataMode,
+                validationTarget: params.validationTarget,
+                error: error instanceof Error ? error.message : 'Unknown',
+            });
+            return null;
+        }
+    }
+    validateAndTransformResourceData(resourceData, resourceType, operationIdentifier, dataMode = DataMode.RAW, validationTarget = 'canonical-read') {
+        // If no resource data provided, signal the caller to emit metadata only.
+        if (!resourceData || typeof resourceData !== 'object') {
+            return { success: false };
+        }
+        const operation = this.resolveOperationForWebSocketValidation({
+            resourceType,
+            operationIdentifier,
+            dataMode,
+            validationTarget,
+        });
+        if (!operation) {
+            return { success: false };
+        }
+        // Select appropriate DTO based on DataMode
+        const selectedDto = this.selectResponseDto(operation, dataMode);
+        if (!selectedDto) {
+            return { success: false };
+        }
+        try {
+            // Transform dates from Date objects to ISO strings before validation
+            let transformedData = resourceData;
+            transformedData = ResourcesConfigOperationsDtosBuilderUtils.transformResponseDates(resourceData, selectedDto);
+            // Validate response against the selected DTO as a runtime safety net
+            // Handle array responses (LIST, CREATE_MANY, etc.)
+            const effectiveOperation = operation.resourceOperationLike || operation.operationIdentifier;
+            const isArrayOperation = ARRAY_RESPONSE_OPERATIONS.includes(effectiveOperation);
+            if (isArrayOperation && Array.isArray(transformedData)) {
+                // For array operations, validate each item individually
+                return {
+                    success: true,
+                    data: transformedData.map(item => selectedDto.parse(item)),
+                };
+            }
+            else {
+                // For single-item operations, validate directly
+                return {
+                    success: true,
+                    data: selectedDto.parse(transformedData),
+                };
+            }
+        }
+        catch (error) {
+            this.logger.warn('WebSocket resource data validation failed', {
+                resourceType,
+                operationIdentifier,
+                dataMode,
+                error: error instanceof Error ? error.message : 'Unknown',
+                resourceDataKeys: typeof resourceData === 'object' ? Object.keys(resourceData) : 'not-object'
+            });
+            return { success: false };
+        }
+    }
+    stripScopeNotificationReplayFields(payload) {
+        const { resourceData: _resourceData, fieldMeta: _fieldMeta, version: _version, dataMode: _dataMode, ...notificationPayload } = payload;
+        return notificationPayload;
+    }
+    validateAndTransformSyncReplayData(params) {
+        const dataMode = params.dataMode ?? DataMode.RAW;
+        if (!params.resourceData || typeof params.resourceData !== 'object') {
+            this.logger.warn('WebSocket sync replay payload is missing resource data', {
+                resourceType: params.resourceType,
+                dataMode,
+            });
+            return { success: false };
+        }
+        const readOperation = this.resolveOperationForWebSocketValidation({
+            resourceType: params.resourceType,
+            dataMode,
+            validationTarget: 'canonical-read',
+        });
+        if (!readOperation) {
+            return { success: false };
+        }
+        const selectedDto = this.selectResponseDto(readOperation, dataMode);
+        if (!selectedDto) {
+            this.logger.warn('WebSocket sync replay payload missing canonical READ DTO', {
+                resourceType: params.resourceType,
+                dataMode,
+            });
+            return { success: false };
+        }
+        try {
+            const transformedData = ResourcesConfigOperationsDtosBuilderUtils.transformResponseDates(params.resourceData, selectedDto);
+            return {
+                success: true,
+                data: selectedDto.parse(transformedData),
+            };
+        }
+        catch (error) {
+            this.logger.warn('WebSocket sync replay validation failed', {
+                resourceType: params.resourceType,
+                dataMode,
+                error: error instanceof Error ? error.message : 'Unknown',
+                resourceDataKeys: typeof params.resourceData === 'object' ? Object.keys(params.resourceData) : 'not-object',
+            });
+            return { success: false };
+        }
+    }
+    /**
+     * Emit to a specific resource room (path-independent)
+     * Called by NotificationDispatcherService after CRUD operations
+     *
+     * Resource-room sync payloads now validate replay-grade resource data when it
+     * is present in the payload.
+     *
+     * @param resourceType - Resource type
+     * @param resourceId - Resource ID
+     * @param event - WebSocket event name
+     * @param payload - Resource-room payload. Sync-grade update payloads carry authoritative
+     * `version` + `resourceData`; delete/state payloads intentionally do not.
+     *
+     * @example
+     * // Send notification-grade metadata only
+     * websocketService.emitToResourceRoom('users', 'userId123', CoreWebSocketEvent.RESOURCE_UPDATED, {
+     *   resourceType: 'users',
+     *   resourceId: 'userId123',
+     *   contextResourceIdentifiers: {},
+     *   action: ResourceAction.UPDATED,
+     *   operationIdentifier: CoreResourceOperation.UPDATE
+     * });
+     *
+     * @example
+     * // Send synchronization-grade replay data for RESOURCE_ROOM_SYNC
+     * websocketService.emitToResourceRoom('users', 'userId123', CoreWebSocketEvent.RESOURCE_UPDATED, {
+     *   resourceType: 'users',
+     *   resourceId: 'userId123',
+     *   contextResourceIdentifiers: {},
+     *   action: ResourceAction.UPDATED,
+     *   operationIdentifier: CoreResourceOperation.UPDATE,
+     *   resourceData: updatedUserObject, // Full resource object
+     *   dataMode: DataMode.RAW // or DataMode.SUMMARY, DataMode.CONTEXT
+     * });
+     */
+    emitToResourceRoom(resourceType, resourceId, event, payload) {
+        if (!this.io) {
+            this.logger.warn('WebSocket not initialized, cannot emit to resource room');
+            return false;
+        }
+        // Only sync-grade resource-room payloads are allowed to act like
+        // authoritative replay input for clients. Notification-grade room payloads
+        // still emit, but they do not go through the stricter canonical replay gate.
+        const shouldValidateSyncReplay = payload.deliveryTarget === WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC
+            && 'resourceData' in payload;
+        let payloadToEmit = payload;
+        let dataMode = DataMode.RAW;
+        if (shouldValidateSyncReplay) {
+            dataMode = this.extractDataMode({ dataMode: payload.dataMode });
+            const validation = this.validateAndTransformSyncReplayData({
+                resourceData: payload.resourceData,
+                resourceType,
+                dataMode,
+            });
+            if (!validation.success) {
+                this.logDebug('Skipped resource-room emit: sync replay payload failed canonical validation', {
+                    resourceType,
+                    resourceId,
+                    event,
+                    deliveryTarget: payload.deliveryTarget,
+                });
+                return false;
+            }
+            payloadToEmit = {
+                ...payload,
+                resourceData: validation.data,
+            };
+        }
+        const roomName = buildResourceRoomName(resourceType, resourceId);
+        this.io.to(roomName).emit(event, payloadToEmit);
+        this.logDebug('Emitted to resource room', {
+            roomName,
+            event,
+            dataMode: shouldValidateSyncReplay ? dataMode : undefined,
+            hasResourceData: shouldValidateSyncReplay,
+            deliveryTarget: payload.deliveryTarget,
+        });
+        return true;
+    }
+    /**
+     * Helper method to send resource data via WebSocket with automatic validation.
+     *
+     * This is a convenience method that prepares a payload with resource data and sends it
+     * to a resource room. Use this when you want to send authoritative resource objects via
+     * WebSocket.
+     *
+     * @param resourceType - Resource type
+     * @param resourceId - Resource ID
+     * @param event - WebSocket event name (e.g., CoreWebSocketEvent.RESOURCE_UPDATED)
+     * @param action - Resource action (ResourceAction.CREATED, UPDATED, DELETED)
+     * @param resourceData - The resource data object to send (will be validated and transformed)
+     * @param options - Optional configuration
+     * @param options.operationIdentifier - Operation identifier (e.g., CoreResourceOperation.UPDATE)
+     * @param options.dataMode - Data mode (defaults to RAW)
+     * @param options.contextResourceIdentifiers - Context resource identifiers
+     * @param options.affectedIds - Array of affected resource IDs
+     * @param options.initiatorUserId - User ID of the initiator
+     *
+     * @example
+     * // Send updated user resource
+     * await websocketService.sendResourceData(
+     *   'users',
+     *   'userId123',
+     *   CoreWebSocketEvent.RESOURCE_UPDATED,
+     *   ResourceAction.UPDATED,
+     *   updatedUserObject,
+     *   {
+     *     operationIdentifier: CoreResourceOperation.UPDATE,
+     *     dataMode: DataMode.RAW,
+     *     contextResourceIdentifiers: {},
+     *     initiatorUserId: 'currentUserId'
+     *   }
+     * );
+     *
+     * @example
+     * // Send created resource with summary data
+     * await websocketService.sendResourceData(
+     *   'todos',
+     *   'todoId456',
+     *   CoreWebSocketEvent.RESOURCE_UPDATED,
+     *   ResourceAction.CREATED,
+     *   newTodoObject,
+     *   {
+     *     operationIdentifier: CoreResourceOperation.CREATE,
+     *     dataMode: DataMode.SUMMARY, // Use summary for list refreshes
+     *     contextResourceIdentifiers: { organizationId: 'org123' },
+     *     initiatorUserId: 'currentUserId'
+     *   }
+     * );
+     */
+    sendResourceData(resourceType, resourceId, event, action, resourceData, options = {}) {
+        const { operationIdentifier, dataMode = DataMode.RAW, contextResourceIdentifiers = {}, affectedIds, initiatorUserId, version, } = options;
+        // Convert DataMode enum to string for schema compatibility
+        const effectiveDataMode = typeof dataMode === 'string'
+            ? ResourceOperationsUtils.normalizeDataModeString(dataMode) || DataMode.RAW
+            : dataMode || DataMode.RAW;
+        const dataModeString = ResourceOperationsUtils.dataModeToString(effectiveDataMode);
+        const resolvedVersion = version ?? (resourceData && typeof resourceData === 'object'
+            ? resourceData._version
+            : undefined);
+        if (action !== ResourceAction.DELETED && resolvedVersion == null) {
+            this.logger.warn('sendResourceData skipped sync payload without authoritative version', {
+                resourceType,
+                resourceId,
+                event,
+                action,
+            });
+            return;
+        }
+        const payload = action === ResourceAction.DELETED
+            ? {
+                deliveryTarget: WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC,
+                resourceType,
+                resourceId,
+                contextResourceIdentifiers,
+                action: ResourceAction.DELETED,
+                operationIdentifier: operationIdentifier ?? CoreResourceOperation.DELETE,
+                affectedIds,
+                initiatorUserId,
+                timestamp: new Date(),
+            }
+            : {
+                deliveryTarget: WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC,
+                resourceType,
+                resourceId,
+                contextResourceIdentifiers,
+                action,
+                operationIdentifier: operationIdentifier ?? CoreResourceOperation.UPDATE,
+                resourceData,
+                dataMode: dataModeString,
+                affectedIds,
+                initiatorUserId,
+                timestamp: new Date(),
+                version: resolvedVersion,
+            };
+        this.emitToResourceRoom(resourceType, resourceId, event, payload);
+    }
+    /**
+     * Emit to scope rooms (collections) for list refresh
+     * Called by NotificationDispatcherService after CRUD operations
+     *
+     * Scope-room payloads validate resource-shaped data when it is present in the
+     * payload, while still treating these emissions as notification-grade rather
+     * than replay-grade sync.
+     *
+     * @param resourceType - Resource type
+     * @param scopes - Array of scope rooms to emit to
+     * @param event - WebSocket event name
+     * @param payload - Payload with optional resourceData and dataMode
+     *
+     * @example
+     * // Send notification-grade metadata for list refresh
+     * websocketService.emitToScopeRooms('users', [{ scopeKey: 'organization', scopeId: 'org123' }],
+     *   CoreWebSocketEvent.RESOURCE_UPDATED, { ... });
+     *
+     * @example
+     * // Send optional summary data for list refresh
+     * websocketService.emitToScopeRooms('users', [{ scopeKey: 'organization', scopeId: 'org123' }],
+     *   CoreWebSocketEvent.RESOURCE_UPDATED, {
+     *     ...metadata,
+     *     resourceData: updatedUserObject,
+     *     dataMode: DataMode.SUMMARY // Use SUMMARY for list refreshes
+     *   });
+     */
+    emitToScopeRooms(resourceType, scopes, event, payload) {
+        if (!this.io)
+            return;
+        // Extract DataMode and validate resource data if present
+        const dataMode = this.extractDataMode({ dataMode: payload.dataMode });
+        let validatedPayload = { ...payload };
+        const resourceData = payload.resourceData;
+        // Scope-room payloads stay notification-grade. If DTO shaping fails, strip
+        // replay-like fields rather than emitting non-canonical bodies; list
+        // invalidation is still useful even when authoritative replay truth is not.
+        if (resourceData) {
+            const validation = this.validateAndTransformResourceData(resourceData, resourceType, undefined, dataMode, 'canonical-read');
+            if (validation.success) {
+                validatedPayload = {
+                    ...validatedPayload,
+                    resourceData: validation.data,
+                };
+            }
+            else {
+                validatedPayload = this.stripScopeNotificationReplayFields(validatedPayload);
+            }
+        }
+        for (const scope of scopes) {
+            const roomName = buildScopeRoomName(resourceType, scope.scopeKey, scope.scopeId);
+            this.io.to(roomName).emit(event, validatedPayload);
+        }
+        this.logDebug('Emitted to scope rooms', {
+            resourceType,
+            scopeCount: scopes.length,
+            event,
+            dataMode,
+            hasResourceData: !!resourceData,
+            deliveryTarget: payload.deliveryTarget,
+        });
+    }
+    /**
+     * Get all users currently editing a resource
+     */
+    async getResourceEditingUsers(resourceType, resourceId) {
+        const prefix = this.redisService.getAppPrefix();
+        const key = `${prefix}editing:${resourceType}:${resourceId}`;
+        const redisClient = this.redisService.getClient();
+        if (!redisClient) {
+            return Array.from(this.resourceEditingState.get(key) || []);
+        }
+        try {
+            const editing = await redisClient.hGetAll(key);
+            return Object.keys(editing);
+        }
+        catch {
+            return Array.from(this.resourceEditingState.get(key) || []);
+        }
+    }
+    // =====================================================
+    // ROOM MANAGEMENT
+    // =====================================================
+    /**
+     * Create custom room
+     */
+    async createRoom(roomName, organizationId, type = 'custom', metadata) {
+        const room = {
+            name: roomName,
+            organizationId,
+            type,
+            members: new Set(),
+            metadata
+        };
+        this.rooms.set(roomName, room);
+        this.logDebug('Room created', {
+            roomName,
+            organizationId: organizationId.substring(0, 8) + '...',
+            type,
+        });
+    }
+    /**
+     * Join user to room
+     */
+    async joinRoom(userId, roomName) {
+        const socketIds = this.userSockets.get(userId);
+        const room = this.rooms.get(roomName);
+        if (!socketIds || !room || !this.io) {
+            return false;
+        }
+        room.members.add(userId);
+        for (const socketId of socketIds) {
+            const socket = this.io.sockets.sockets.get(socketId);
+            if (socket) {
+                await socket.join(roomName);
+            }
+        }
+        this.logDebug('User joined room', { userId: userId.substring(0, 8) + '...', roomName });
+        return true;
+    }
+    /**
+     * Remove user from room
+     */
+    async leaveRoom(userId, roomName) {
+        const socketIds = this.userSockets.get(userId);
+        const room = this.rooms.get(roomName);
+        if (!socketIds || !room || !this.io) {
+            return false;
+        }
+        room.members.delete(userId);
+        for (const socketId of socketIds) {
+            const socket = this.io.sockets.sockets.get(socketId);
+            if (socket) {
+                await socket.leave(roomName);
+            }
+        }
+        this.logDebug('User left room', { userId: userId.substring(0, 8) + '...', roomName });
+        return true;
+    }
+    // =====================================================
+    // STATUS METHODS
+    // =====================================================
+    getConnectedUsersCount() {
+        return this.authenticatedSockets.size;
+    }
+    getOrganizationUsersCount(organizationId) {
+        const socketIds = this.organizationSockets.get(organizationId);
+        return socketIds ? socketIds.size : 0;
+    }
+    isUserConnected(userId) {
+        const socketIds = this.userSockets.get(userId);
+        return socketIds ? socketIds.size > 0 : false;
+    }
+    getRoomInfo(roomName) {
+        return this.rooms.get(roomName);
+    }
+    // =====================================================
+    // PRIVATE SETUP METHODS
+    // =====================================================
+    /**
+     * Get CORS origins from app-config runtime endpoints
+     */
+    getCorsOrigins() {
+        // Config must be initialized - this is ensured by the initialization order:
+        // 1. AppsUpdaterConfigService fetches config from apps-manager
+        // 2. Standard AppConfigurationService is initialized with that config
+        // 3. HTTP server starts, which initializes WebSocket
+        // If config is not initialized here, it's a programming error - fail fast
+        if (!this.configService.isInitialized()) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.APP_CONFIGURATION_NOT_INITIALIZED,
+                context: {
+                    message: 'Application configuration not initialized : use config before using the service',
+                    service: 'WebSocketService',
+                    operation: 'getCorsOrigins'
+                }
+            });
+        }
+        const config = this.configService.config;
+        const frontendServices = Object.keys(config.frontendServices ?? {});
+        return frontendServices.map((frontendServiceName) => {
+            const url = config.runtime?.endPoints?.[frontendServiceName]?.publicUrl;
+            if (!url) {
+                throw new Error(`Missing runtime.endPoints.${frontendServiceName}.publicUrl for declared frontend service "${frontendServiceName}". ` +
+                    'WebSocket CORS cannot be derived from an incomplete runtime topology.');
+            }
+            return url;
+        });
+    }
+    /**
+     * Setup Redis adapter for horizontal scaling across Kubernetes pods
+     */
+    async setupRedisAdapter() {
+        try {
+            if (!this.io) {
+                throw new Error('Socket.IO server not initialized');
+            }
+            // Check if config is initialized before accessing
+            if (!this.configService.isInitialized()) {
+                this.logger.warn('App config not initialized, using memory adapter (single instance only)');
+                return;
+            }
+            const appConfig = this.configService.config;
+            const appSecrets = this.configService.secrets;
+            if (!appConfig.database.redis) {
+                this.logger.warn('Redis not configured, using memory adapter (single instance only)');
+                return;
+            }
+            const redisHost = appConfig.database.redis.host;
+            const redisPort = appConfig.database.redis.port || 6379;
+            const redisPassword = appSecrets?.database?.redis?.password;
+            const redisUsername = appSecrets?.database?.redis?.username;
+            if (!redisHost || redisHost.includes('localhost')) {
+                this.logger.warn('Redis not properly configured for production, using memory adapter (single instance only)');
+                return;
+            }
+            // Build Redis client options (same pattern as RedisService)
+            // Include username for ACL authentication (required when using app-specific credentials)
+            const redisOptions = {
+                socket: {
+                    host: redisHost,
+                    port: redisPort,
+                    connectTimeout: 10000
+                },
+                username: redisUsername,
+                password: redisPassword,
+            };
+            const pubClient = createClient(redisOptions);
+            const subClient = pubClient.duplicate();
+            // CRITICAL: Attach error handlers BEFORE connect to prevent "missing 'error' handler" warnings
+            // These handlers prevent unhandled errors from crashing the process during Redis restarts
+            pubClient.on('error', (error) => {
+                this.logger.error('Socket.IO Redis pubClient error', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            });
+            subClient.on('error', (error) => {
+                this.logger.error('Socket.IO Redis subClient error', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            });
+            // Reconnection handlers for visibility
+            pubClient.on('reconnecting', () => {
+                this.logDebug('Socket.IO Redis pubClient reconnecting...');
+            });
+            subClient.on('reconnecting', () => {
+                this.logDebug('Socket.IO Redis subClient reconnecting...');
+            });
+            await Promise.all([
+                pubClient.connect(),
+                subClient.connect()
+            ]);
+            // SECURITY FIX: Use tenant-specific channel prefix for Socket.IO adapter
+            // This ensures each tenant's Socket.IO messages are isolated to their own channels
+            // ACL pattern &{username}#* will only allow access to channels with this prefix
+            const channelPrefix = redisUsername || 'default';
+            this.io.adapter(createAdapter(pubClient, subClient, { key: channelPrefix }));
+            this.logDebug('Socket.IO Redis adapter configured for horizontal scaling', {
+                redisHost,
+                redisPort,
+                channelPrefix,
+                scalingEnabled: true,
+                environment: process.env.APPLICATION_ENV || 'development'
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            this.logger.error('Failed to setup Redis adapter, falling back to memory adapter', {
+                error: errorMessage,
+            });
+            this.logger.warn('Using memory adapter - horizontal scaling will not work across pods');
+        }
+    }
+    /**
+     * Setup authentication middleware
+     * FACTORIZED: Uses ExecutionContextCreatorBackendService for JWT validation
+     */
+    setupAuthentication() {
+        if (!this.io)
+            return;
+        this.io.use(async (socket, next) => {
+            try {
+                const token = socket.handshake.auth.token ||
+                    socket.handshake.headers.authorization?.replace('Bearer ', '');
+                let authResult;
+                if (!token) {
+                    // No token = public connection (allowed but limited)
+                    authResult = this.executionContextCreator.getPublicSocketAuth();
+                    this.logDebug('Public socket connection (no token)');
+                }
+                else {
+                    authResult = await this.executionContextCreator.authenticateSocketConnection(token);
+                    // W7.3b: Capture consumable token from handshake auth or headers
+                    const consumableToken = socket.handshake.auth?.consumableToken
+                        || socket.handshake.headers?.[WildoHeaderKeys.CONSUMABLE_TOKEN];
+                    if (consumableToken && typeof consumableToken === 'string') {
+                        authResult.consumableTokenValue = consumableToken;
+                    }
+                    this.logDebug('Authenticated socket connection', {
+                        executionType: authResult.executionType,
+                        userId: authResult.initiatorIds?.userId?.substring(0, 8) + '...',
+                        rolesCount: authResult.initiatorRoles.length,
+                        hasConsumableToken: !!authResult.consumableTokenValue,
+                    });
+                }
+                socket.auth = authResult;
+                next();
+            }
+            catch (error) {
+                this.logger.warn('WebSocket authentication failed', {
+                    error: error instanceof Error ? error.message : 'Unknown error'
+                });
+                next(new Error('Authentication failed'));
+            }
+        });
+    }
+    /**
+     * Setup rate limiting middleware
+     * Uses Redis for cross-pod synchronization of rate limit counters
+     */
+    setupRateLimiting() {
+        if (!this.io)
+            return;
+        // Intercept all incoming events with rate limiting
+        this.io.use(async (socket, next) => {
+            // Override socket.on to wrap event handlers with rate limiting
+            const originalOn = socket.on.bind(socket);
+            socket.on = (event, handler) => {
+                // Skip internal Socket.IO events
+                if (event.startsWith('$') || ['connect', 'disconnect', 'error'].includes(event)) {
+                    return originalOn(event, handler);
+                }
+                // Wrap handler with rate limiting check
+                return originalOn(event, async (...args) => {
+                    const auth = socket.auth;
+                    const identifier = auth.initiatorIds?.userId || socket.id;
+                    const allowed = await this.checkRateLimit(identifier, event);
+                    if (!allowed) {
+                        // Rate limit exceeded - emit error and skip handler
+                        socket.emit(CoreWebSocketEvent.SYSTEM_ERROR, {
+                            code: 'RATE_LIMIT_EXCEEDED',
+                            message: `Too many ${event} requests. Please slow down.`,
+                            details: { event }
+                        });
+                        this.logDebug('Rate limit exceeded', {
+                            identifier: identifier.substring(0, 8),
+                            event
+                        });
+                        return;
+                    }
+                    // Call original handler
+                    handler(...args);
+                });
+            };
+            next();
+        });
+    }
+    /**
+     * Check rate limit for an event using Redis
+     * Returns true if allowed, false if rate limited
+     *
+     * Uses sliding window algorithm with Redis INCR and EXPIRE
+     */
+    async checkRateLimit(identifier, event) {
+        const config = DEFAULT_RATE_LIMITS[event] || DEFAULT_RATE_LIMITS['default'];
+        const redisClient = this.redisService.getClient();
+        // Fallback to in-memory if Redis unavailable (less accurate cross-pod)
+        if (!redisClient) {
+            return this.checkRateLimitInMemory(identifier, event, config);
+        }
+        try {
+            const prefix = this.redisService.getAppPrefix();
+            const key = `${prefix}ws:ratelimit:${identifier}:${event}`;
+            const windowKey = `${key}:${Math.floor(Date.now() / (config.windowSeconds * 1000))}`;
+            // Increment counter for current window
+            const count = await redisClient.incr(windowKey);
+            // Set expiry on first request in window
+            if (count === 1) {
+                await redisClient.expire(windowKey, config.windowSeconds + 1);
+            }
+            return count <= config.maxEvents;
+        }
+        catch (error) {
+            // On Redis error, allow the request (fail open)
+            this.logger.warn('Rate limit check failed, allowing request', {
+                identifier: identifier.substring(0, 8),
+                event,
+                error: error instanceof Error ? error.message : 'Unknown',
+            });
+            return true;
+        }
+    }
+    /**
+     * In-memory rate limiting fallback (single pod only)
+     */
+    inMemoryRateLimits = new Map();
+    checkRateLimitInMemory(identifier, event, config) {
+        const key = `${identifier}:${event}`;
+        const now = Date.now();
+        const entry = this.inMemoryRateLimits.get(key);
+        if (!entry || now >= entry.resetAt) {
+            // Start new window
+            this.inMemoryRateLimits.set(key, {
+                count: 1,
+                resetAt: now + (config.windowSeconds * 1000),
+            });
+            return true;
+        }
+        if (entry.count >= config.maxEvents) {
+            return false;
+        }
+        entry.count++;
+        return true;
+    }
+    /**
+     * Setup connection handling
+     * Joins user to identity-based rooms based on their roles and IDs
+     * Sets up resource room handlers for collaboration
+     */
+    setupConnectionHandling() {
+        if (!this.io)
+            return;
+        this.io.on('connection', (socket) => {
+            const auth = socket.auth;
+            // Track authenticated socket
+            this.authenticatedSockets.set(socket.id, auth);
+            // === IDENTITY-BASED ROOM ASSIGNMENT ===
+            if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+                // Public users only join public room
+                socket.join(WebSocketRoomPrefix.PUBLIC);
+                this.logDebug('Public socket connected', { socketId: socket.id });
+                // Still setup disconnect handler
+                socket.on('disconnect', () => {
+                    this.handleSocketDisconnection(socket.id, this.getSocketAuth(socket));
+                });
+                return;
+            }
+            // User: Join organization-based rooms from their roles
+            for (const roleInfo of auth.initiatorRoles) {
+                if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && roleInfo.relatedResourceId) {
+                    const orgId = roleInfo.relatedResourceId;
+                    // Organization room (receives all org-wide notifications)
+                    socket.join(buildOrganizationRoomName(orgId));
+                    // Track organization sockets
+                    if (!this.organizationSockets.has(orgId)) {
+                        this.organizationSockets.set(orgId, new Set());
+                    }
+                    this.organizationSockets.get(orgId).add(socket.id);
+                    // Role-specific rooms (for role-targeted notifications)
+                    for (const role of roleInfo.roles || []) {
+                        socket.join(buildOrganizationRoleRoomName(orgId, role));
+                    }
+                }
+                if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.APPLICATION && roleInfo.relatedResourceId) {
+                    // App-level role room (for app admins, super admins)
+                    for (const role of roleInfo.roles || []) {
+                        socket.join(buildAppRoleRoomName(role));
+                    }
+                }
+            }
+            // User-specific room (for direct messages, personal notifications)
+            if (auth.initiatorIds?.userId) {
+                socket.join(buildUserRoomName(auth.initiatorIds.userId));
+                // Track user sockets for multi-tab support
+                if (!this.userSockets.has(auth.initiatorIds.userId)) {
+                    this.userSockets.set(auth.initiatorIds.userId, new Set());
+                }
+                this.userSockets.get(auth.initiatorIds.userId).add(socket.id);
+            }
+            this.logDebug('Socket connected with identity rooms', {
+                socketId: socket.id,
+                executionType: auth.executionType,
+                userId: auth.initiatorIds?.userId?.substring(0, 8),
+                organizationRoles: auth.initiatorRoles.filter(r => r.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS).length
+            });
+            // === RESOURCE ROOM HANDLERS (for collaboration) ===
+            this.setupResourceRoomHandlers(socket);
+            // === BADGE HANDLERS ===
+            this.setupBadgeHandlers(socket);
+            // === SYSTEM EVENT HANDLERS ===
+            this.setupSystemEventHandlers(socket);
+            // === DISCONNECTION HANDLING ===
+            socket.on('disconnect', () => {
+                this.handleSocketDisconnection(socket.id, this.getSocketAuth(socket));
+            });
+        });
+    }
+    /**
+     * Setup handlers for resource-centric rooms (collaboration, editing locks, custom events)
+     * These rooms are path-independent - same resource = same room regardless of access path
+     */
+    setupResourceRoomHandlers(socket) {
+        // === SUBSCRIBE TO RESOURCE ROOM ===
+        socket.on(CoreWebSocketEvent.RESOURCE_SUBSCRIBE, async (rawPayload) => {
+            // Runtime validation using Zod schema
+            const parseResult = WS_ResourceSubscribePayloadSchema.safeParse(rawPayload);
+            if (!parseResult.success) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBED, {
+                    roomName: '',
+                    success: false,
+                    error: `Invalid payload: ${parseResult.error.issues[0]?.message || 'validation failed'}`
+                });
+                return;
+            }
+            const payload = parseResult.data;
+            const { resourceType, resourceId, scopeKey, scopeId, contextResourceIdentifiers } = payload;
+            // Validate contextResourceIdentifiers has at least one entry
+            if (!contextResourceIdentifiers || Object.keys(contextResourceIdentifiers).length === 0) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBED, {
+                    roomName: '',
+                    success: false,
+                    error: 'contextResourceIdentifiers is required for authorization'
+                });
+                return;
+            }
+            try {
+                const auth = this.getSocketAuth(socket);
+                // Verify READ access using full context (organization, parent resources, etc.)
+                if (resourceId) {
+                    await this.verifyResourceAccess(socket, auth, resourceType, resourceId, contextResourceIdentifiers);
+                }
+                else if (scopeKey && scopeId) {
+                    // For collection subscription, verify context access
+                    await this.verifyScopeAccess(auth, scopeKey, scopeId, contextResourceIdentifiers);
+                }
+                else {
+                    throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                        customMessageReference: ErrorCustomMessageReference.SERVICE_RESOURCE_VALIDATION_FAILED,
+                        context: { operation: 'resourceSubscribe', message: 'Either resourceId or (scopeKey + scopeId) required' },
+                    });
+                }
+                // Build room name
+                const roomName = resourceId
+                    ? buildResourceRoomName(resourceType, resourceId)
+                    : buildScopeRoomName(resourceType, scopeKey, scopeId);
+                socket.join(roomName);
+                this.trackSocketResourceSubscription(socket.id, {
+                    ...payload,
+                    roomName,
+                });
+                // Get current editing users for this resource (if subscribing to specific resource)
+                let editingUsers = [];
+                if (resourceId) {
+                    editingUsers = await this.getResourceEditingUsers(resourceType, resourceId);
+                }
+                socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBED, {
+                    roomName,
+                    success: true,
+                    editingUsers, // Include current editing users in subscription confirmation
+                });
+                this.logDebug('Socket subscribed to resource room', {
+                    socketId: socket.id,
+                    roomName,
+                    userId: auth.initiatorIds?.userId?.substring(0, 8),
+                    contextKeys: Object.keys(contextResourceIdentifiers),
+                    editingUsersCount: editingUsers.length
+                });
+            }
+            catch (error) {
+                const roomName = resourceId
+                    ? buildResourceRoomName(resourceType, resourceId)
+                    : buildScopeRoomName(resourceType, scopeKey || '', scopeId || '');
+                socket.emit(CoreWebSocketEvent.RESOURCE_SUBSCRIBED, {
+                    roomName,
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Access denied'
+                });
+            }
+        });
+        // === UNSUBSCRIBE FROM RESOURCE ROOM ===
+        socket.on(CoreWebSocketEvent.RESOURCE_UNSUBSCRIBE, (rawPayload) => {
+            // Runtime validation using Zod schema
+            const parseResult = WS_ResourceSubscribePayloadSchema.safeParse(rawPayload);
+            if (!parseResult.success) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_UNSUBSCRIBED, {
+                    roomName: '',
+                    success: false,
+                    error: `Invalid payload: ${parseResult.error.issues[0]?.message || 'validation failed'}`
+                });
+                return;
+            }
+            const payload = parseResult.data;
+            const { resourceType, resourceId, scopeKey, scopeId } = payload;
+            const roomName = resourceId
+                ? buildResourceRoomName(resourceType, resourceId)
+                : buildScopeRoomName(resourceType, scopeKey, scopeId);
+            socket.leave(roomName);
+            this.untrackSocketResourceSubscription(socket.id, roomName);
+            socket.emit(CoreWebSocketEvent.RESOURCE_UNSUBSCRIBED, { roomName, success: true });
+            this.logDebug('Socket unsubscribed from resource room', { socketId: socket.id, roomName });
+        });
+        // === START EDITING (LOCK) ===
+        socket.on(CoreWebSocketEvent.RESOURCE_EDITING_START, async (rawPayload) => {
+            // Runtime validation using Zod schema
+            const parseResult = WS_ResourceEditingPayloadSchema.safeParse(rawPayload);
+            if (!parseResult.success) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_ERROR, {
+                    resourceType: '',
+                    resourceId: '',
+                    success: false,
+                    error: `Invalid payload: ${parseResult.error.issues[0]?.message || 'validation failed'}`
+                });
+                return;
+            }
+            const payload = parseResult.data;
+            const { resourceType, resourceId, contextResourceIdentifiers } = payload;
+            const auth = this.getSocketAuth(socket);
+            const userId = auth.initiatorIds?.userId;
+            if (!userId) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_ERROR, {
+                    resourceType,
+                    resourceId,
+                    success: false,
+                    error: 'Authentication required for editing'
+                });
+                return;
+            }
+            // Validate contextResourceIdentifiers is provided
+            if (!contextResourceIdentifiers || Object.keys(contextResourceIdentifiers).length === 0) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_ERROR, {
+                    resourceType,
+                    resourceId,
+                    success: false,
+                    error: 'contextResourceIdentifiers is required for authorization'
+                });
+                return;
+            }
+            try {
+                // Verify user has WRITE access to edit this resource (using UPDATE operation)
+                await this.verifyResourceAccessForEdit(socket, auth, resourceType, resourceId, contextResourceIdentifiers);
+                const roomName = buildResourceRoomName(resourceType, resourceId);
+                // Track editing state in memory + Redis for cross-pod sync
+                await this.trackEditingState(resourceType, resourceId, userId, 'start');
+                // Broadcast to room (exclude sender) - don't include contextResourceIdentifiers in broadcast
+                const eventPayload = {
+                    resourceType,
+                    resourceId,
+                    initiatorUserId: userId,
+                    timestamp: new Date(),
+                };
+                socket.to(roomName).emit(CoreWebSocketEvent.RESOURCE_EDITING_START, eventPayload);
+                // Confirm to sender
+                socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_STARTED, { resourceType, resourceId, success: true });
+                this.logDebug('User started editing resource', {
+                    userId: userId.substring(0, 8),
+                    resourceType,
+                    resourceId: resourceId.substring(0, 8)
+                });
+            }
+            catch (error) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_EDITING_ERROR, {
+                    resourceType,
+                    resourceId,
+                    success: false,
+                    error: 'Access denied'
+                });
+            }
+        });
+        // === STOP EDITING (UNLOCK) ===
+        socket.on(CoreWebSocketEvent.RESOURCE_EDITING_END, async (rawPayload) => {
+            // Runtime validation using Zod schema
+            const parseResult = WS_ResourceEditingPayloadSchema.safeParse(rawPayload);
+            if (!parseResult.success) {
+                // Silent fail for editing end (not critical)
+                this.logDebug('Invalid editing end payload', {
+                    error: parseResult.error.issues[0]?.message
+                });
+                return;
+            }
+            const payload = parseResult.data;
+            const { resourceType, resourceId } = payload;
+            const auth = this.getSocketAuth(socket);
+            const userId = auth.initiatorIds?.userId;
+            if (!userId)
+                return;
+            const roomName = buildResourceRoomName(resourceType, resourceId);
+            // Clear editing state
+            await this.trackEditingState(resourceType, resourceId, userId, 'end');
+            // Broadcast to room (exclude sender)
+            const eventPayload = {
+                resourceType,
+                resourceId,
+                initiatorUserId: userId,
+                timestamp: new Date(),
+            };
+            socket.to(roomName).emit(CoreWebSocketEvent.RESOURCE_EDITING_END, eventPayload);
+            this.logDebug('User stopped editing resource', {
+                userId: userId.substring(0, 8),
+                resourceType,
+                resourceId: resourceId.substring(0, 8)
+            });
+        });
+        // === CUSTOM COLLABORATION EVENT ===
+        socket.on(CoreWebSocketEvent.RESOURCE_CUSTOM, async (rawPayload) => {
+            // Runtime validation using Zod schema
+            const parseResult = WS_ResourceCustomEventPayloadSchema.safeParse(rawPayload);
+            if (!parseResult.success) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_CUSTOM_ERROR, {
+                    eventName: '',
+                    error: `Invalid payload: ${parseResult.error.issues[0]?.message || 'validation failed'}`
+                });
+                return;
+            }
+            const payload = parseResult.data;
+            const { resourceType, resourceId, eventName, data, includeSelf, contextResourceIdentifiers } = payload;
+            const auth = this.getSocketAuth(socket);
+            const userId = auth.initiatorIds?.userId;
+            // Validate contextResourceIdentifiers is provided
+            if (!contextResourceIdentifiers || Object.keys(contextResourceIdentifiers).length === 0) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_CUSTOM_ERROR, { eventName, error: 'contextResourceIdentifiers is required' });
+                return;
+            }
+            try {
+                // Verify READ access (custom events require at least read access)
+                await this.verifyResourceAccess(socket, auth, resourceType, resourceId, contextResourceIdentifiers);
+                const roomName = buildResourceRoomName(resourceType, resourceId);
+                // Build outgoing event payload (don't include contextResourceIdentifiers in broadcast)
+                const eventPayload = {
+                    resourceType,
+                    resourceId,
+                    eventName,
+                    data,
+                    initiatorUserId: userId,
+                    timestamp: new Date(),
+                    // Include resourceData and dataMode if present in the incoming payload
+                    resourceData: payload.resourceData,
+                    dataMode: payload.dataMode,
+                };
+                // Validate and transform resource data if present
+                if (payload.resourceData) {
+                    const dataMode = this.extractDataMode(payload);
+                    const validation = this.validateAndTransformResourceData(payload.resourceData, resourceType, undefined, // Custom events don't have operationIdentifier
+                    dataMode, 'canonical-read');
+                    if (validation.success) {
+                        eventPayload.resourceData = validation.data;
+                    }
+                    else {
+                        delete eventPayload.resourceData;
+                        delete eventPayload.dataMode;
+                    }
+                }
+                // Broadcast to room (include or exclude sender based on flag)
+                if (includeSelf) {
+                    this.io.to(roomName).emit(CoreWebSocketEvent.RESOURCE_CUSTOM, eventPayload);
+                }
+                else {
+                    socket.to(roomName).emit(CoreWebSocketEvent.RESOURCE_CUSTOM, eventPayload);
+                }
+            }
+            catch (error) {
+                socket.emit(CoreWebSocketEvent.RESOURCE_CUSTOM_ERROR, { eventName, error: 'Access denied' });
+            }
+        });
+    }
+    /**
+     * Setup system event handlers (auth refresh, organization switch)
+     */
+    setupSystemEventHandlers(socket) {
+        // Token refresh handling
+        socket.on(CoreWebSocketEvent.AUTH_REFRESH, async (payload) => {
+            try {
+                const oldAuth = socket.auth;
+                const newAuth = await this.executionContextCreator.authenticateSocketConnection(payload.token);
+                // W7.3b: Carry forward consumable token across auth refreshes
+                if (oldAuth.consumableTokenValue) {
+                    newAuth.consumableTokenValue = oldAuth.consumableTokenValue;
+                }
+                socket.auth = newAuth;
+                this.authenticatedSockets.set(socket.id, newAuth);
+                // Re-assign identity rooms based on new auth
+                await this.reassignIdentityRooms(socket, oldAuth, newAuth);
+                await this.revalidateTrackedResourceSubscriptions(socket, newAuth);
+                socket.emit(CoreWebSocketEvent.SYSTEM_TOKEN_REFRESHED, { success: true });
+                this.logDebug('Socket auth refreshed and rooms reassigned', {
+                    socketId: socket.id,
+                    userId: newAuth.initiatorIds?.userId?.substring(0, 8),
+                    newRolesCount: newAuth.initiatorRoles.length
+                });
+            }
+            catch (error) {
+                socket.emit(CoreWebSocketEvent.SYSTEM_ERROR, {
+                    code: 'AUTH_REFRESH_FAILED',
+                    message: error instanceof Error ? error.message : 'Token refresh failed'
+                });
+            }
+        });
+        // Organization switch handling
+        socket.on(CoreWebSocketEvent.ORGANIZATION_SWITCH, async (payload) => {
+            const auth = this.getSocketAuth(socket);
+            if (!this.hasOrganizationAccess(auth, payload.organizationId)) {
+                socket.emit(CoreWebSocketEvent.SYSTEM_ERROR, {
+                    code: 'ORGANIZATION_SWITCH_FORBIDDEN',
+                    message: 'Access denied to the requested organization',
+                });
+                return;
+            }
+            // Leave old organization rooms if specified
+            if (payload.previousOrganizationId) {
+                socket.leave(buildOrganizationRoomName(payload.previousOrganizationId));
+                this.organizationSockets.get(payload.previousOrganizationId)?.delete(socket.id);
+                if (this.organizationSockets.get(payload.previousOrganizationId)?.size === 0) {
+                    this.organizationSockets.delete(payload.previousOrganizationId);
+                }
+                // Leave role rooms too
+                for (const roleInfo of auth.initiatorRoles) {
+                    if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS &&
+                        roleInfo.relatedResourceId === payload.previousOrganizationId) {
+                        for (const role of roleInfo.roles || []) {
+                            socket.leave(buildOrganizationRoleRoomName(payload.previousOrganizationId, role));
+                        }
+                    }
+                }
+                const trackedSubscriptions = Array.from(this.resourceSubscriptionsBySocket.get(socket.id)?.values() ?? []);
+                for (const subscription of trackedSubscriptions) {
+                    if (!subscriptionMatchesOrganization(subscription, payload.previousOrganizationId)) {
+                        continue;
+                    }
+                    await this.revokeTrackedResourceSubscription({
+                        socket,
+                        auth,
+                        subscription,
+                        reason: 'organization_switch',
+                    });
+                }
+            }
+            // Join new organization rooms
+            socket.join(buildOrganizationRoomName(payload.organizationId));
+            if (!this.organizationSockets.has(payload.organizationId)) {
+                this.organizationSockets.set(payload.organizationId, new Set());
+            }
+            this.organizationSockets.get(payload.organizationId).add(socket.id);
+            // Find roles for the new organization and join role rooms
+            for (const roleInfo of auth.initiatorRoles) {
+                if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS &&
+                    roleInfo.relatedResourceId === payload.organizationId) {
+                    for (const role of roleInfo.roles || []) {
+                        socket.join(buildOrganizationRoleRoomName(payload.organizationId, role));
+                    }
+                }
+            }
+            this.logDebug('Organization switched', {
+                socketId: socket.id,
+                previousOrganizationId: payload.previousOrganizationId?.substring(0, 8),
+                newOrganizationId: payload.organizationId.substring(0, 8)
+            });
+        });
+    }
+    /**
+     * Reassign identity-based rooms when auth is refreshed
+     * Handles role changes, organization membership changes, etc.
+     */
+    async reassignIdentityRooms(socket, oldAuth, newAuth) {
+        // === LEAVE OLD ROOMS ===
+        // Leave old user room if user ID changed (unlikely but possible)
+        if (oldAuth.initiatorIds?.userId && oldAuth.initiatorIds.userId !== newAuth.initiatorIds?.userId) {
+            socket.leave(buildUserRoomName(oldAuth.initiatorIds.userId));
+            // Update user sockets tracking
+            this.userSockets.get(oldAuth.initiatorIds.userId)?.delete(socket.id);
+        }
+        // Build sets of old and new organization rooms for comparison
+        const oldOrgRooms = new Set();
+        const oldRoleRooms = new Set();
+        for (const roleInfo of oldAuth.initiatorRoles) {
+            if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && roleInfo.relatedResourceId) {
+                oldOrgRooms.add(buildOrganizationRoomName(roleInfo.relatedResourceId));
+                for (const role of roleInfo.roles || []) {
+                    oldRoleRooms.add(buildOrganizationRoleRoomName(roleInfo.relatedResourceId, role));
+                }
+            }
+            if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.APPLICATION) {
+                for (const role of roleInfo.roles || []) {
+                    oldRoleRooms.add(buildAppRoleRoomName(role));
+                }
+            }
+        }
+        const newOrgRooms = new Set();
+        const newRoleRooms = new Set();
+        for (const roleInfo of newAuth.initiatorRoles) {
+            if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && roleInfo.relatedResourceId) {
+                newOrgRooms.add(buildOrganizationRoomName(roleInfo.relatedResourceId));
+                for (const role of roleInfo.roles || []) {
+                    newRoleRooms.add(buildOrganizationRoleRoomName(roleInfo.relatedResourceId, role));
+                }
+            }
+            if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.APPLICATION) {
+                for (const role of roleInfo.roles || []) {
+                    newRoleRooms.add(buildAppRoleRoomName(role));
+                }
+            }
+        }
+        // Leave org rooms that are no longer in new auth
+        for (const room of oldOrgRooms) {
+            if (!newOrgRooms.has(room)) {
+                socket.leave(room);
+                // Update organization sockets tracking
+                const orgId = parseOrganizationRoomName(room);
+                if (orgId) {
+                    this.organizationSockets.get(orgId)?.delete(socket.id);
+                }
+            }
+        }
+        // Leave role rooms that are no longer in new auth
+        for (const room of oldRoleRooms) {
+            if (!newRoleRooms.has(room)) {
+                socket.leave(room);
+            }
+        }
+        // Leave public room if was public but now authenticated
+        if (oldAuth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION &&
+            newAuth.executionType !== ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+            socket.leave(WebSocketRoomPrefix.PUBLIC);
+        }
+        // === JOIN NEW ROOMS ===
+        // Join new user room
+        if (newAuth.initiatorIds?.userId) {
+            socket.join(buildUserRoomName(newAuth.initiatorIds.userId));
+            if (!this.userSockets.has(newAuth.initiatorIds.userId)) {
+                this.userSockets.set(newAuth.initiatorIds.userId, new Set());
+            }
+            this.userSockets.get(newAuth.initiatorIds.userId).add(socket.id);
+        }
+        // Join new org rooms
+        for (const room of newOrgRooms) {
+            if (!oldOrgRooms.has(room)) {
+                socket.join(room);
+                const orgId = parseOrganizationRoomName(room);
+                if (orgId) {
+                    if (!this.organizationSockets.has(orgId)) {
+                        this.organizationSockets.set(orgId, new Set());
+                    }
+                    this.organizationSockets.get(orgId).add(socket.id);
+                }
+            }
+        }
+        // Join new role rooms
+        for (const room of newRoleRooms) {
+            if (!oldRoleRooms.has(room)) {
+                socket.join(room);
+            }
+        }
+        // Join public room if now public
+        if (newAuth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+            socket.join(WebSocketRoomPrefix.PUBLIC);
+        }
+    }
+    /**
+     * Setup badge handlers (badge:get, badge:get-all)
+     * Enables frontend useBadge and useUserBadges hooks
+     */
+    setupBadgeHandlers(socket) {
+        // badge:get - Get single badge count
+        socket.on(CoreWebSocketEvent.BADGE_GET, async (payload, callback) => {
+            if (!callback)
+                return;
+            try {
+                const auth = this.getSocketAuth(socket);
+                // Verify user has access to this scope
+                if (!this.verifyBadgeScopeAccess(auth, payload.scope, payload.scopeId)) {
+                    callback({ count: 0 });
+                    return;
+                }
+                // Build a minimal execution context for the badge service
+                const appReadOp = this.resourcesRegistry.getOperationFromPath(this.resourcesRegistry.getOperationPathDefault('APPLICATION', CoreResourceOperation.READ));
+                if (!appReadOp) {
+                    callback({ count: 0 });
+                    return;
+                }
+                const executionContext = await this.executionContextCreator.buildContextFromSocketAuth(auth, appReadOp, {});
+                const count = await this.getBadgeService().getBadgeCount(executionContext, payload.scope, payload.scopeId, payload.identifier);
+                callback({ count });
+            }
+            catch (error) {
+                this.logger.warn('Failed to get badge count', {
+                    error: error instanceof Error ? error.message : 'Unknown error'
+                });
+                callback({ count: 0 });
+            }
+        });
+        // badge:get-all - Get all badges for a scope
+        socket.on(CoreWebSocketEvent.BADGE_GET_ALL, async (payload, callback) => {
+            if (!callback)
+                return;
+            try {
+                const auth = this.getSocketAuth(socket);
+                // Verify user has access to this scope
+                if (!this.verifyBadgeScopeAccess(auth, payload.scope, payload.scopeId)) {
+                    callback([]);
+                    return;
+                }
+                // Build a minimal execution context for the badge service
+                const appReadOp = this.resourcesRegistry.getOperationFromPath(this.resourcesRegistry.getOperationPathDefault('APPLICATION', CoreResourceOperation.READ));
+                if (!appReadOp) {
+                    callback([]);
+                    return;
+                }
+                const executionContext = await this.executionContextCreator.buildContextFromSocketAuth(auth, appReadOp, {});
+                const badges = await this.getBadgeService().getAllBadges(executionContext, payload.scope, payload.scopeId);
+                callback(badges);
+            }
+            catch (error) {
+                this.logger.warn('Failed to get all badges', {
+                    error: error instanceof Error ? error.message : 'Unknown error'
+                });
+                callback([]);
+            }
+        });
+    }
+    /**
+     * Verify user has access to a badge scope
+     */
+    verifyBadgeScopeAccess(auth, scope, scopeId) {
+        // Public users cannot access badges
+        if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+            return false;
+        }
+        switch (scope) {
+            case ResourcePrimaryScope.USER_SELF:
+                // User can only access their own badges
+                return auth.initiatorIds?.userId === scopeId;
+            case ResourcePrimaryScope.ORGANIZATIONS:
+                // User must be member of the organization
+                return auth.initiatorRoles.some(r => r.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS &&
+                    r.relatedResourceId === scopeId);
+            case ResourcePrimaryScope.APPLICATION:
+                // Application-level badges - check if user has any app roles
+                return auth.initiatorRoles.some(r => r.relatedPrimaryScope === ResourcePrimaryScope.APPLICATION);
+            default:
+                return false;
+        }
+    }
+    // =====================================================
+    // AUTHORIZATION HELPERS (FACTORIZED with HTTP)
+    // =====================================================
+    /**
+     * Verify user has READ access to a specific resource
+     *
+     * REUSES: AuthorizationsBackendService.authorizeInController()
+     * This is the EXACT same method used by HTTP controllers
+     */
+    async verifyResourceAccess(socket, auth, resourceType, resourceId, contextResourceIdentifiers) {
+        if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+                context: { resourceType, resourceId, message: 'Public connections cannot access resources' },
+            });
+        }
+        await this.authorizeSocketResourceAgainstAnyVariant(auth, resourceType, resourceId, contextResourceIdentifiers, CoreResourceOperation.READ);
+    }
+    /**
+     * Verify user has WRITE access to edit a resource (for editing lock)
+     *
+     * REUSES: AuthorizationsBackendService.authorizeInController() with UPDATE operation
+     */
+    async verifyResourceAccessForEdit(socket, auth, resourceType, resourceId, contextResourceIdentifiers) {
+        if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+                context: { resourceType, resourceId, message: 'Public connections cannot edit resources' },
+            });
+        }
+        await this.authorizeSocketResourceAgainstAnyVariant(auth, resourceType, resourceId, contextResourceIdentifiers, CoreResourceOperation.UPDATE);
+    }
+    /**
+     * Verify user has access to a scope (for collection subscriptions)
+     *
+     * REUSES: Role-based check for organization scope, or AuthorizationsBackendService for parent resources
+     */
+    async verifyScopeAccess(auth, scopeKey, scopeId, contextResourceIdentifiers) {
+        if (auth.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+                context: { scopeKey, scopeId, message: 'Public connections cannot access scoped collections' },
+            });
+        }
+        const normalizedScopeKey = scopeKey.trim().toLowerCase();
+        // For organization scope, just check user has role in that org
+        if (normalizedScopeKey === 'org' || normalizedScopeKey === 'organization' || normalizedScopeKey === 'organizationid') {
+            const hasOrgAccess = auth.initiatorRoles.some(r => r.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS &&
+                r.relatedResourceId === scopeId);
+            if (!hasOrgAccess) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+                    context: { scopeId, scopeKey, message: 'No access to organization' },
+                });
+            }
+            return;
+        }
+        // For other scopes (e.g., todolist), verify READ access to the parent resource
+        const parentResourceType = this.mapScopeKeyToResourceType(scopeKey);
+        if (!parentResourceType) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+                context: { scopeId, scopeKey, message: 'Unknown or unmapped scope key' },
+            });
+        }
+        const scopeResourceId = contextResourceIdentifiers[`${scopeKey}Id`]
+            || contextResourceIdentifiers[`${normalizedScopeKey}Id`]
+            || contextResourceIdentifiers[scopeKey]
+            || contextResourceIdentifiers[normalizedScopeKey]
+            || scopeId;
+        await this.authorizeSocketResourceAgainstAnyVariant(auth, parentResourceType, scopeResourceId, contextResourceIdentifiers, CoreResourceOperation.READ, { scopeKey });
+    }
+    getSocketAuthorizationCandidateOperations(resourceType, coreOperation) {
+        const registry = this.resourcesRegistry.getResourcesRegistry();
+        const resourceConfiguration = registry.resourceConfigurations[resourceType];
+        if (!resourceConfiguration) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+                customMessageReference: ErrorCustomMessageReference.RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND,
+                context: { resourceType, operation: coreOperation },
+            });
+        }
+        return resourceConfiguration.operations.filter((operation) => (ResourceOperationsUtils.getCoreResourceOperationFromOperation(operation) === coreOperation
+            && !('isBulkOperation' in operation && operation.isBulkOperation === true)
+            && (operation.variantType === ResourceOperationVariantType.API_CALL
+                || operation.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK)
+            && 'initiatorInfos' in operation
+            && Array.isArray(operation.initiatorInfos)
+            && operation.initiatorInfos.length > 0));
+    }
+    async authorizeSocketResourceAgainstAnyVariant(auth, resourceType, resourceId, contextResourceIdentifiers, coreOperation, extraContext) {
+        const candidateOperations = this.getSocketAuthorizationCandidateOperations(resourceType, coreOperation);
+        let lastAuthorizationError;
+        for (const operation of candidateOperations) {
+            try {
+                const executionContext = await this.executionContextCreator.buildContextFromSocketAuth(auth, operation, contextResourceIdentifiers);
+                await this.authorizationsService.authorizeInController(resourceId, executionContext);
+                this.logDebug('Socket authorization succeeded with operation variant', {
+                    resourceType,
+                    resourceId,
+                    coreOperation,
+                    variantKey: operation.variantKey,
+                    isOperationDefault: operation.isOperationDefault,
+                    ...extraContext,
+                });
+                return;
+            }
+            catch (error) {
+                if (isWildoBackendError(error) && error.type === ErrorType.AUTHORIZATION) {
+                    lastAuthorizationError = error;
+                    continue;
+                }
+                throw error;
+            }
+        }
+        if (lastAuthorizationError) {
+            throw lastAuthorizationError;
+        }
+        throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+            customMessageReference: ErrorCustomMessageReference.RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND,
+            context: { resourceType, operation: coreOperation, ...extraContext },
+        });
+    }
+    /**
+     * Map scope key to parent resource type using the resources registry
+     *
+     * Scope keys follow the pattern: fieldIdentifier without 'Id' suffix
+     * E.g., 'todolist' → find resource with fieldIdentifier 'todolistId' → TODOLISTS
+     *
+     * Uses the registry's resource configurations to dynamically resolve
+     * without hardcoded mappings.
+     */
+    mapScopeKeyToResourceType(scopeKey) {
+        // Build the expected field identifier
+        const fieldIdentifierVariants = [
+            `${scopeKey}Id`, // todolist → todolistId
+            `${scopeKey.toLowerCase()}Id`, // TodoList → todolistid (case insensitive)
+        ];
+        // Search through all resource configurations
+        const registry = this.resourcesRegistry.getResourcesRegistry();
+        const resourceTypes = Object.keys(registry.resourceConfigurations);
+        for (const resourceType of resourceTypes) {
+            const config = registry.resourceConfigurations[resourceType];
+            const configFieldId = config.resourceFieldIdentifier?.toLowerCase();
+            for (const variant of fieldIdentifierVariants) {
+                if (configFieldId === variant.toLowerCase()) {
+                    return resourceType;
+                }
+            }
+        }
+        // Also check if scopeKey is itself a resource type (direct match)
+        if (registry.resourceConfigurations[scopeKey]) {
+            return scopeKey;
+        }
+        // Check for case-insensitive resource type match
+        const lowerScopeKey = scopeKey.toLowerCase();
+        for (const resourceType of resourceTypes) {
+            if (resourceType.toLowerCase() === lowerScopeKey) {
+                return resourceType;
+            }
+        }
+        this.logDebug('Could not map scope key to resource type', { scopeKey });
+        return null;
+    }
+    // =====================================================
+    // EDITING STATE TRACKING (Redis-backed for multi-pod)
+    // =====================================================
+    /**
+     * Track editing state in Redis for cross-pod synchronization
+     */
+    async trackEditingState(resourceType, resourceId, userId, action) {
+        const prefix = this.redisService.getAppPrefix();
+        const key = `${prefix}editing:${resourceType}:${resourceId}`;
+        const redisClient = this.redisService.getClient();
+        if (!redisClient) {
+            // Fallback to in-memory if Redis unavailable
+            if (action === 'start') {
+                if (!this.resourceEditingState.has(key)) {
+                    this.resourceEditingState.set(key, new Set());
+                }
+                this.resourceEditingState.get(key).add(userId);
+            }
+            else {
+                this.resourceEditingState.get(key)?.delete(userId);
+            }
+            return;
+        }
+        try {
+            if (action === 'start') {
+                await redisClient.hSet(key, userId, new Date().toISOString());
+                await redisClient.expire(key, 3600); // 1 hour TTL (cleanup stale locks)
+            }
+            else {
+                await redisClient.hDel(key, userId);
+            }
+        }
+        catch (error) {
+            this.logger.warn('Failed to track editing state in Redis', {
+                error: error instanceof Error ? error.message : 'Unknown',
+                resourceType,
+                resourceId: resourceId.substring(0, 8)
+            });
+        }
+    }
+    /**
+     * Cleanup editing states when user disconnects
+     * Cleans both in-memory state AND Redis for immediate consistency across pods
+     *
+     * CROSS-POD SUPPORT: Uses Redis SCAN to find all editing keys across all pods
+     * where this user is editing, ensuring complete cleanup.
+     */
+    async cleanupEditingStatesForUser(userId) {
+        if (!userId)
+            return;
+        const redisClient = this.redisService.getClient();
+        // Cleanup in-memory state on this pod
+        for (const [key, users] of this.resourceEditingState.entries()) {
+            if (users.has(userId)) {
+                users.delete(userId);
+            }
+        }
+        // Cross-pod cleanup: SCAN Redis for all editing:* keys where this user is editing
+        if (redisClient) {
+            try {
+                await this.cleanupUserEditingStatesFromRedis(redisClient, userId);
+            }
+            catch (error) {
+                this.logger.warn('Failed to cleanup Redis editing states on disconnect', {
+                    userId: userId.substring(0, 8),
+                    error: error instanceof Error ? error.message : 'Unknown',
+                });
+            }
+        }
+    }
+    /**
+     * SCAN Redis for all editing:* keys and remove the user from each
+     * Also broadcasts editing:end to affected resource rooms
+     *
+     * Key format: {appPrefix}editing:{resourceType}:{resourceId}
+     * Example: "wildo-ai-app_local:editing:users:user456"
+     */
+    async cleanupUserEditingStatesFromRedis(redisClient, userId) {
+        if (!redisClient)
+            return;
+        let cursor = '0';
+        const cleanedResources = [];
+        const prefix = this.redisService.getAppPrefix();
+        // SCAN for all editing:* keys scoped to this application
+        do {
+            const result = await redisClient.scan(cursor, {
+                MATCH: `${prefix}editing:*`,
+                COUNT: 100, // Process in batches
+            });
+            cursor = result.cursor;
+            const keys = result.keys;
+            // Check each key for this user and remove if present
+            for (const key of keys) {
+                try {
+                    // Check if user is in this hash
+                    const exists = await redisClient.hExists(key, userId);
+                    if (exists) {
+                        // Remove user from this editing state
+                        await redisClient.hDel(key, userId);
+                        // Parse key to get resource info
+                        // Key format: {prefix}editing:{resourceType}:{resourceId}
+                        // Remove prefix first, then parse
+                        const keyWithoutPrefix = prefix && key.startsWith(prefix)
+                            ? key.slice(prefix.length)
+                            : key;
+                        const parts = keyWithoutPrefix.split(':');
+                        // parts[0] = "editing", parts[1] = resourceType, parts[2] = resourceId
+                        if (parts.length >= 3 && parts[0] === 'editing') {
+                            cleanedResources.push({
+                                resourceType: parts[1],
+                                resourceId: parts[2],
+                            });
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger.warn('Failed to check/delete editing state for key', {
+                        key,
+                        userId: userId.substring(0, 8),
+                        error: error instanceof Error ? error.message : 'Unknown',
+                    });
+                }
+            }
+        } while (cursor !== '0');
+        // Broadcast editing:end to all affected resource rooms
+        for (const resource of cleanedResources) {
+            const roomName = buildResourceRoomName(resource.resourceType, resource.resourceId);
+            this.io?.to(roomName).emit(CoreWebSocketEvent.RESOURCE_EDITING_END, {
+                resourceType: resource.resourceType,
+                resourceId: resource.resourceId,
+                initiatorUserId: userId,
+                reason: 'disconnect',
+                timestamp: new Date(),
+            });
+        }
+        if (cleanedResources.length > 0) {
+            this.logDebug('Cleaned up editing states for disconnected user', {
+                userId: userId.substring(0, 8),
+                cleanedCount: cleanedResources.length,
+            });
+        }
+    }
+    // =====================================================
+    // DISCONNECTION HANDLING
+    // =====================================================
+    /**
+     * Handle socket disconnection - cleanup state and notify rooms
+     */
+    handleSocketDisconnection(socketId, auth) {
+        // Remove from authenticated sockets
+        this.authenticatedSockets.delete(socketId);
+        this.resourceSubscriptionsBySocket.delete(socketId);
+        const userId = auth.initiatorIds?.userId;
+        if (userId) {
+            // Remove from user sockets tracking
+            const userSocketIds = this.userSockets.get(userId);
+            if (userSocketIds) {
+                userSocketIds.delete(socketId);
+                if (userSocketIds.size === 0) {
+                    this.userSockets.delete(userId);
+                    // User completely disconnected - cleanup editing states
+                    this.cleanupEditingStatesForUser(userId);
+                }
+            }
+        }
+        // Remove from organization sockets
+        for (const roleInfo of auth.initiatorRoles) {
+            if (roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && roleInfo.relatedResourceId) {
+                const orgSocketIds = this.organizationSockets.get(roleInfo.relatedResourceId);
+                if (orgSocketIds) {
+                    orgSocketIds.delete(socketId);
+                    if (orgSocketIds.size === 0) {
+                        this.organizationSockets.delete(roleInfo.relatedResourceId);
+                    }
+                }
+            }
+        }
+        this.logDebug('Socket disconnected', {
+            socketId,
+            userId: userId?.substring(0, 8),
+            remainingConnections: this.authenticatedSockets.size
+        });
+    }
+    // =====================================================
+    // CLEANUP
+    // =====================================================
+    /**
+     * Cleanup resources
+     */
+    async cleanup() {
+        try {
+            if (this.io) {
+                this.io.close();
+                this.io = null;
+            }
+            this.authenticatedSockets.clear();
+            this.userSockets.clear();
+            this.organizationSockets.clear();
+            this.rooms.clear();
+            this.resourceEditingState.clear();
+            this.resourceSubscriptionsBySocket.clear();
+            this.logDebug('WebSocket service cleanup completed');
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            this.logger.error('Error during WebSocket cleanup', { error: errorMessage });
+        }
+    }
+};
+WebSocketService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.RedisService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.AuthorizationsService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
+    __param(7, inject('Container')),
+    __metadata("design:paramtypes", [LoggerService,
+        AppConfigurationService,
+        ErrorBuilderBackendService,
+        RedisService,
+        ExecutionContextCreatorBackendService,
+        AuthorizationsBackendService,
+        ResourcesRegistryBackendService,
+        Container])
+], WebSocketService);
+export { WebSocketService };
+//# sourceMappingURL=websocket.service.js.map