@wireapp/core 46.45.3 → 46.46.1

package/lib/conversation/ConversationService/ConversationService.js

@@ -29,8 +29,7 @@ const core_crypto_1 = require("@wireapp/core-crypto");
 const protocol_messaging_1 = require("@wireapp/protocol-messaging");
 const conversation_2 = require("../../conversation/");
 const mls_1 = require("../../messagingProtocols/mls");
-const conversationRejoinQueue_1 = require("../../messagingProtocols/mls/conversationRejoinQueue");
-const CoreCryptoMLSError_1 = require("../../messagingProtocols/mls/MLSService/CoreCryptoMLSError");
+const recovery_1 = require("../../messagingProtocols/mls/recovery");
 const proteus_1 = require("../../messagingProtocols/proteus");
 const util_1 = require("../../util");
 const fullyQualifiedClientIdUtils_1 = require("../../util/fullyQualifiedClientIdUtils");
@@ -46,8 +45,8 @@ class ConversationService extends commons_1.TypedEventEmitter {
     messageTimer;
     logger = commons_1.LogFactory.getLogger('@wireapp/core/ConversationService');
     // Track groups currently undergoing recovery due to key material update failure to prevent duplicate work
-    recoveringKeyMaterialGroups = new Set();
     groupIdConversationMap = new Map();
+    MLSRecoveryOrchestrator;
     constructor(apiClient, proteusService, coreDatabase, groupIdFromConversationId, subconversationService, isMLSConversationRecoveryEnabled, _mlsService) {
         super();
         this.apiClient = apiClient;
@@ -58,15 +57,27 @@ class ConversationService extends commons_1.TypedEventEmitter {
         this.isMLSConversationRecoveryEnabled = isMLSConversationRecoveryEnabled;
         this._mlsService = _mlsService;
         this.messageTimer = new conversation_2.MessageTimer();
-        if (this._mlsService) {
-            this.mlsService.on(mls_1.MLSServiceEvents.MLS_EVENT_DISTRIBUTED, data => {
-                this.emit(mls_1.MLSServiceEvents.MLS_EVENT_DISTRIBUTED, data);
-            });
-            this.mlsService.on(mls_1.MLSServiceEvents.KEY_MATERIAL_UPDATE_FAILURE, ({ error, groupId }) => {
-                this.logger.warn(`Key material update failure for group ${groupId}`, { error });
-                return this.reactToKeyMaterialUpdateFailure({ error, groupId });
-            });
+        // Make MLS recovery orchestrator mandatory in this service
+        if (!this._mlsService) {
+            throw new Error('MLSService is required to construct ConversationService with MLS capabilities');
         }
+        this.mlsService.on(mls_1.MLSServiceEvents.MLS_EVENT_DISTRIBUTED, data => {
+            this.emit(mls_1.MLSServiceEvents.MLS_EVENT_DISTRIBUTED, data);
+        });
+        this.mlsService.on(mls_1.MLSServiceEvents.KEY_MATERIAL_UPDATE_FAILURE, ({ error, groupId }) => {
+            this.logger.warn(`Key material update failure for group ${groupId}`, { error });
+            return this.reactToKeyMaterialUpdateFailure({ error, groupId });
+        });
+        // Initialize MLS recovery orchestrator with default policies and single-flight de-duplication
+        const mapper = (0, recovery_1.createDefaultMlsErrorMapper)();
+        this.MLSRecoveryOrchestrator = new recovery_1.MlsRecoveryOrchestratorImpl(mapper, recovery_1.minimalDefaultPolicies, {
+            // Call the low-level API to avoid nested recovery when orchestrator triggers an external commit join
+            joinViaExternalCommit: (conversationId) => this.performJoinByExternalCommitAPI(conversationId),
+            resetAndReestablish: (conversationId) => this.handleBrokenMLSConversation(conversationId),
+            recoverFromEpochMismatch: (conversationId, subconvId) => this.recoverMLSGroupFromEpochMismatch(conversationId, subconvId),
+            addMissingUsers: (conversationId, groupId, users) => this.performAddUsersToMLSConversationAPI({ conversationId, groupId, qualifiedUsers: users }),
+            wipeMLSConversation: (groupId) => this.wipeMLSConversation(groupId),
+        });
     }
     get mlsService() {
         if (!this._mlsService) {
@@ -215,7 +226,17 @@ class ConversationService extends commons_1.TypedEventEmitter {
         }
         return this.establishMLSGroupConversation(groupId, qualifiedUsers, selfUserId, selfClientId, qualifiedId);
     }
-    async handleBrokenMLSConversation(conversationId, afterReset) {
+    /**
+     * Centralized handler for scenarios where an MLS conversation is detected as broken.
+     * It resets the conversation and then invokes the provided callback so callers can retry
+     * their original operation (e.g., re-adding/removing users, re-joining, etc.) with the new group id.
+     *
+     * Contract:
+     * - input: conversationId to reset; callback invoked after reset with the new group id
+     * - output: the value returned by the callback
+     * - error: throws if reset fails or new group id is missing
+     */
+    async handleBrokenMLSConversation(conversationId) {
         if (!(await this.isMLSConversationRecoveryEnabled())) {
             throw new Error('MLS conversation recovery is disabled');
         }
@@ -225,10 +246,6 @@ class ConversationService extends commons_1.TypedEventEmitter {
             this.logger.error(errorMessage, { conversationId });
             throw new Error(errorMessage);
         }
-        if (afterReset) {
-            return afterReset(newGroupId);
-        }
-        return undefined;
     }
     /**
      * Will create a conversation on backend and register it to CoreCrypto once created
@@ -248,222 +265,113 @@ class ConversationService extends commons_1.TypedEventEmitter {
             failedToAdd: failures,
         };
     }
-    async sendMLSMessage(params, shouldRetry = true) {
-        const { payload, groupId, conversationId } = params;
+    /**
+     * Send an MLS message wrapped with recovery.
+     *
+     * Uses the MLS recovery orchestrator to handle transient MLS errors (for example, wrong epoch)
+     * according to per-operation policies. When configured, the original send is retried once
+     * after a successful recovery. Unrecoverable errors are re-thrown by the orchestrator.
+     * The low-level send logic lives in {@link performSendMLSMessageAPI}.
+     */
+    async sendMLSMessage(params) {
+        const { groupId, conversationId } = params;
+        return this.MLSRecoveryOrchestrator.execute({
+            context: { operationName: recovery_1.OperationName.send, qualifiedConversationId: conversationId, groupId },
+            callBack: () => this.performSendMLSMessageAPI(params),
+        });
+    }
+    // Low-level API for sending an MLS message without any recovery logic
+    async performSendMLSMessageAPI(params) {
+        const { payload, groupId } = params;
         const groupIdBytes = bazinga64_1.Decoder.fromBase64(groupId).asBytes;
-        try {
-            // immediately execute pending commits before sending the message
-            await this.mlsService.commitPendingProposals(groupId, true, params);
-            const encrypted = await this.mlsService.encryptMessage(new core_crypto_1.ConversationId(groupIdBytes), protocol_messaging_1.GenericMessage.encode(payload).finish());
-            const response = await this.apiClient.api.conversation.postMlsMessage(encrypted);
-            const sentAt = response.time?.length > 0 ? response.time : new Date().toISOString();
-            const failedToSend = response?.failed || (response?.failed_to_send ?? []).length > 0
-                ? {
-                    queued: response?.failed_to_send,
-                    failed: response?.failed,
-                }
-                : undefined;
-            return {
-                id: payload.messageId,
-                sentAt,
-                failedToSend,
-                state: sentAt ? conversation_2.MessageSendingState.OUTGOING_SENT : conversation_2.MessageSendingState.CANCELED,
-            };
-        }
-        catch (error) {
-            this.logger.warn('Failed to send MLS message', { error, groupId });
-            if (!shouldRetry) {
-                this.logger.error("Tried to send MLS message but it's still failing after recovery", {
-                    error,
-                    groupId,
-                });
-                throw error;
-            }
-            /**
-             * Only thrown by core-crypto when we call commitPendingProposals
-             */
-            if ((0, CoreCryptoMLSError_1.isBrokenMLSConversationError)(error)) {
-                this.logger.info('Failed to send MLS message because broken MLS conversation, triggering a reset', {
-                    error,
-                    groupId,
-                });
-                await this.handleBrokenMLSConversation(conversationId);
-            }
-            /**
-             * We may have the same error from core-crypto or from the backend error mapper
-             * core-crypto throws its own error class when we call commitPendingProposals
-             * backend error mapper throws its own error class when we call postMlsMessage
-             */
-            if ((0, CoreCryptoMLSError_1.isMLSStaleMessageError)(error) || error instanceof conversation_1.MLSStaleMessageError) {
-                this.logger.info('Failed to send MLS message because of stale message, recovering by joining with external commit', {
-                    error,
-                    groupId,
-                });
-                await this.recoverMLSGroupFromEpochMismatch(conversationId);
-            }
-            /**
-             * We may have the same error from core-crypto or from the backend error mapper
-             * core-crypto throws its own error class when we call commitPendingProposals
-             * backend error mapper throws its own error class when we call postMlsMessage
-             */
-            if ((0, CoreCryptoMLSError_1.isMLSGroupOutOfSyncError)(error) || error instanceof conversation_1.MLSGroupOutOfSyncError) {
-                this.logger.info('Failed to send MLS message because of group out of sync, recovering by adding missing users', {
-                    error,
-                    groupId,
-                });
-                /**
-                 * We may get the missing users either from core-crypto error or from the backend error mapper
-                 */
-                let missingUsers = [];
-                if ((0, CoreCryptoMLSError_1.isMLSGroupOutOfSyncError)(error)) {
-                    missingUsers = (0, CoreCryptoMLSError_1.getMLSGroupOutOfSyncErrorMissingUsers)(error);
-                }
-                else {
-                    missingUsers = error.missing_users;
-                }
-                await this.addUsersToMLSConversation({
-                    groupId,
-                    conversationId,
-                    qualifiedUsers: missingUsers,
-                });
-            }
-            return this.sendMLSMessage(params, false);
-        }
+        // immediately execute pending commits before sending the message
+        await this.mlsService.commitPendingProposals(groupId, true, params);
+        const encrypted = await this.mlsService.encryptMessage(new core_crypto_1.ConversationId(groupIdBytes), protocol_messaging_1.GenericMessage.encode(payload).finish());
+        const response = await this.apiClient.api.conversation.postMlsMessage(encrypted);
+        const sentAt = response.time?.length > 0 ? response.time : new Date().toISOString();
+        const failedToSend = response?.failed || (response?.failed_to_send ?? []).length > 0
+            ? {
+                queued: response?.failed_to_send,
+                failed: response?.failed,
+            }
+            : undefined;
+        return {
+            id: payload.messageId,
+            sentAt,
+            failedToSend,
+            state: sentAt ? conversation_2.MessageSendingState.OUTGOING_SENT : conversation_2.MessageSendingState.CANCELED,
+        };
     }
     /**
-     * Will add users to existing MLS group by claiming their key packages and passing them to CoreCrypto.addClientsToConversation
+     * Add users to an existing MLS group with recovery.
      *
-     * @param qualifiedUsers List of qualified user ids (with optional skipOwnClientId field - if provided we will not claim key package for this self client)
-     * @param groupId Id of the group to which we want to add users
-     * @param conversationId Id of the conversation to which we want to add users
+     * Claims key packages and passes them to CoreCrypto.addClientsToConversation. The MLS recovery
+     * orchestrator handles recoverable failures (e.g., wrong epoch) and may retry the operation once
+     * depending on policy. The optional shouldRetry flag is ignored; retries are governed by policies.
+     *
+     * @param qualifiedUsers List of qualified user ids (use skipOwnClientId on self to avoid claiming its key package)
+     * @param groupId Id of the MLS group to add users to
+     * @param conversationId Qualified id of the conversation
      */
-    async addUsersToMLSConversation({ qualifiedUsers, groupId, conversationId, shouldRetry = true, }) {
-        try {
-            this.logger.info(`Adding users to MLS conversation`, { groupId, conversationId, qualifiedUsers });
-            const exisitingClientIdsInGroup = await this.mlsService.getClientIdsInGroup(groupId);
-            const conversation = await this.getConversation(conversationId);
-            const { keyPackages, failures: keysClaimingFailures } = await this.mlsService.getKeyPackagesPayload(qualifiedUsers, exisitingClientIdsInGroup);
-            // We had cases where did not get any key packages, but still used core-crypto to call the backend (which results in failure).
-            if (keyPackages && keyPackages.length > 0) {
-                await this.mlsService.addUsersToExistingConversation(groupId, keyPackages);
-                //We store the info when user was added (and key material was created), so we will know when to renew it
-                await this.mlsService.resetKeyMaterialRenewal(groupId);
-            }
-            return {
-                conversation,
-                failedToAdd: keysClaimingFailures,
-            };
-        }
-        catch (error) {
-            this.logger.warn('Failed to add users to MLS conversation', { error, groupId, conversationId });
-            if (!shouldRetry) {
-                this.logger.warn("Tried to add users to MLS conversation but it's still broken after reset", error);
-                throw error;
-            }
-            if ((0, CoreCryptoMLSError_1.isBrokenMLSConversationError)(error)) {
-                this.logger.warn("Tried to add users to MLS conversation but it's broken, resetting the conversation", error);
-                return this.handleBrokenMLSConversation(conversationId, newGroupId => this.addUsersToMLSConversation({ qualifiedUsers, groupId: newGroupId, conversationId, shouldRetry: false }));
-            }
-            if ((0, CoreCryptoMLSError_1.isMLSStaleMessageError)(error)) {
-                this.logger.info('Failed to add users to MLS conversation because of stale message, recovering by joining with external commit', {
-                    error,
-                    groupId,
-                });
-                await this.recoverMLSGroupFromEpochMismatch(conversationId);
-                return this.addUsersToMLSConversation({
-                    groupId,
-                    conversationId,
-                    qualifiedUsers,
-                    shouldRetry: false,
-                });
-            }
-            if ((0, CoreCryptoMLSError_1.isMLSGroupOutOfSyncError)(error)) {
-                this.logger.info('Failed to send MLS message because of group out of sync, recovering by adding missing users', {
-                    error,
-                    groupId,
-                });
-                const missingUsers = (0, CoreCryptoMLSError_1.getMLSGroupOutOfSyncErrorMissingUsers)(error);
-                return this.addUsersToMLSConversation({
-                    groupId,
-                    conversationId,
-                    qualifiedUsers: missingUsers,
-                    shouldRetry: false,
-                });
-            }
-            throw error;
-        }
+    async addUsersToMLSConversation({ qualifiedUsers, groupId, conversationId, }) {
+        return this.MLSRecoveryOrchestrator.execute({
+            context: { operationName: recovery_1.OperationName.addUsers, qualifiedConversationId: conversationId, groupId },
+            callBack: () => this.performAddUsersToMLSConversationAPI({ qualifiedUsers, groupId, conversationId }),
+        });
     }
-    async removeUsersFromMLSConversation({ groupId, conversationId, qualifiedUserIds, shouldRetry = true, }) {
-        try {
-            const clientsToRemove = await this.apiClient.api.user.postListClients({ qualified_users: qualifiedUserIds });
-            const fullyQualifiedClientIds = (0, fullyQualifiedClientIdUtils_1.mapQualifiedUserClientIdsToFullyQualifiedClientIds)(clientsToRemove.qualified_user_map);
-            await this.mlsService.removeClientsFromConversation(groupId, fullyQualifiedClientIds);
-            // key material gets updated after removing a user from the group, so we can reset last key update time value in the store
+    // Low-level API to add users without any recovery logic; used by orchestrator and direct callers
+    async performAddUsersToMLSConversationAPI({ qualifiedUsers, groupId, conversationId, }) {
+        this.logger.info(`Adding users to MLS conversation`, { groupId, conversationId, qualifiedUsers });
+        const exisitingClientIdsInGroup = await this.mlsService.getClientIdsInGroup(groupId);
+        const conversation = await this.getConversation(conversationId);
+        const { keyPackages, failures: keysClaimingFailures } = await this.mlsService.getKeyPackagesPayload(qualifiedUsers, exisitingClientIdsInGroup);
+        // We had cases where did not get any key packages, but still used core-crypto to call the backend (which results in failure).
+        if (keyPackages && keyPackages?.length > 0) {
+            await this.mlsService.addUsersToExistingConversation(groupId, keyPackages);
+            // We store the info when user was added (and key material was created), so we will know when to renew it
             await this.mlsService.resetKeyMaterialRenewal(groupId);
-            return await this.getConversation(conversationId);
-        }
-        catch (error) {
-            if (!shouldRetry) {
-                this.logger.warn("Tried to remove users from MLS conversation but it's still broken", error);
-                throw error;
-            }
-            if ((0, CoreCryptoMLSError_1.isBrokenMLSConversationError)(error)) {
-                this.logger.info("Tried to remove users from MLS conversation but it's broken, resetting the conversation", error);
-                return this.handleBrokenMLSConversation(conversationId, newGroupId => this.removeUsersFromMLSConversation({
-                    groupId: newGroupId,
-                    conversationId,
-                    qualifiedUserIds,
-                    shouldRetry: false,
-                }));
-            }
-            if ((0, CoreCryptoMLSError_1.isMLSStaleMessageError)(error)) {
-                this.logger.info('Failed to remove users from MLS conversation because of stale message, recovering by joining with external commit', {
-                    error,
-                    groupId,
-                });
-                await this.recoverMLSGroupFromEpochMismatch(conversationId);
-            }
-            if ((0, CoreCryptoMLSError_1.isMLSGroupOutOfSyncError)(error)) {
-                this.logger.info('Failed to send MLS message because of group out of sync, recovering by adding missing users', {
-                    error,
-                    groupId,
-                });
-                const missingUsers = (0, CoreCryptoMLSError_1.getMLSGroupOutOfSyncErrorMissingUsers)(error);
-                await this.addUsersToMLSConversation({
-                    groupId,
-                    conversationId,
-                    qualifiedUsers: missingUsers,
-                });
-            }
-            return this.removeUsersFromMLSConversation({
-                groupId,
-                conversationId,
-                qualifiedUserIds,
-                shouldRetry: false,
-            });
         }
+        return {
+            conversation,
+            failedToAdd: keysClaimingFailures,
+        };
     }
-    async joinByExternalCommit(conversationId, shouldRetry = true) {
-        try {
-            await this.mlsService.joinByExternalCommit(() => this.apiClient.api.conversation.getGroupInfo(conversationId));
-        }
-        catch (error) {
-            if (!shouldRetry) {
-                this.logger.warn("Tried to join MLS conversation but it's still broken after reset", error);
-                throw error;
-            }
-            this.logger.warn(`Failed to join MLS conversation ${conversationId.id} via external commit`, error);
-            if ((0, CoreCryptoMLSError_1.isBrokenMLSConversationError)(error)) {
-                this.logger.info('Resetting MLS conversation due to broken mls conversation error', error);
-                return this.handleBrokenMLSConversation(conversationId);
-            }
-            if ((0, CoreCryptoMLSError_1.isMLSStaleMessageError)(error)) {
-                this.logger.info('Failed to join MLS conversation with external commit because of stale message, recovering by joining with external commit', { error, conversationId });
-                await this.recoverMLSGroupFromEpochMismatch(conversationId);
-                return;
-            }
-            throw error;
-        }
+    /**
+     * Remove users from an existing MLS group with recovery.
+     *
+     * The MLS recovery orchestrator handles recoverable failures and may retry the operation once
+     * depending on policy. The optional shouldRetry flag is ignored; retries are policy-driven.
+     */
+    async removeUsersFromMLSConversation({ groupId, conversationId, qualifiedUserIds, }) {
+        return this.MLSRecoveryOrchestrator.execute({
+            context: { operationName: recovery_1.OperationName.removeUsers, qualifiedConversationId: conversationId, groupId },
+            callBack: () => this.performRemoveUsersFromMLSConversationAPI({ groupId, conversationId, qualifiedUserIds }),
+        });
+    }
+    // Low-level API to remove users without recovery logic; used by orchestrator and direct callers
+    async performRemoveUsersFromMLSConversationAPI({ groupId, conversationId, qualifiedUserIds, }) {
+        const clientsToRemove = await this.apiClient.api.user.postListClients({ qualified_users: qualifiedUserIds });
+        const fullyQualifiedClientIds = (0, fullyQualifiedClientIdUtils_1.mapQualifiedUserClientIdsToFullyQualifiedClientIds)(clientsToRemove.qualified_user_map);
+        await this.mlsService.removeClientsFromConversation(groupId, fullyQualifiedClientIds);
+        // key material gets updated after removing a user from the group, so we can reset last key update time value in the store
+        await this.mlsService.resetKeyMaterialRenewal(groupId);
+        return await this.getConversation(conversationId);
+    }
+    /**
+     * Join an MLS conversation via external commit with recovery.
+     *
+     * If the group is not established or is out of date, the orchestrator recovers accordingly.
+     * The join operation itself is not automatically re-run by policy.
+     */
+    async joinByExternalCommit(conversationId) {
+        await this.MLSRecoveryOrchestrator.execute({
+            context: { operationName: recovery_1.OperationName.joinExternalCommit, qualifiedConversationId: conversationId },
+            callBack: () => this.performJoinByExternalCommitAPI(conversationId),
+        });
+    }
+    // Low-level API call for joining via external commit (no recovery logic)
+    async performJoinByExternalCommitAPI(conversationId) {
+        await this.mlsService.joinByExternalCommit(() => this.apiClient.api.conversation.getGroupInfo(conversationId));
     }
     async refreshGroupIdConversationMap() {
         const conversations = await this.apiClient.api.conversation.getConversationList();
@@ -480,49 +388,35 @@ class ConversationService extends commons_1.TypedEventEmitter {
         }
         return this.groupIdConversationMap.get(groupId);
     }
+    /**
+     * React to a key material update failure using the recovery orchestrator.
+     *
+     * The original error is forwarded to the orchestrator under the 'keyMaterialUpdate' operation
+     * so it can map and apply the configured recovery policy. Unrecoverable errors are logged.
+     */
     reactToKeyMaterialUpdateFailure = async ({ error, groupId }) => {
-        // Deduplicate concurrent recoveries for the same group
-        if (this.recoveringKeyMaterialGroups.has(groupId)) {
-            this.logger.info(`Recovery already in progress for group ${groupId}, skipping duplicate trigger`);
+        this.logger.info(`Reacting to key material update failure for group ${groupId}`);
+        const conversation = await this.getConversationByGroupId(groupId);
+        if (!conversation) {
+            this.logger.warn(`No conversation found for group ${groupId}`, { error });
             return;
         }
-        this.recoveringKeyMaterialGroups.add(groupId);
         try {
-            this.logger.info(`Reacting to key material update failure for group ${groupId}`);
-            const conversation = await this.getConversationByGroupId(groupId);
-            if (!conversation) {
-                this.logger.warn(`No conversation found for group ${groupId}`);
-                throw error;
-            }
-            if ((0, CoreCryptoMLSError_1.isBrokenMLSConversationError)(error)) {
-                this.logger.info('Tried to update key material for a broken MLS conversation, initiating reset', error);
-                return this.handleBrokenMLSConversation(conversation.qualified_id);
-            }
-            if ((0, CoreCryptoMLSError_1.isMLSStaleMessageError)(error)) {
-                this.logger.info('Tried to update key material for a stale MLS conversation, recovering by joining with external commit', {
-                    error,
-                    groupId,
-                });
-                await this.recoverMLSGroupFromEpochMismatch(conversation.qualified_id);
-            }
-            if ((0, CoreCryptoMLSError_1.isMLSGroupOutOfSyncError)(error)) {
-                this.logger.info('Tried to update key material for an out of sync conversation, recovering by adding missing users', {
-                    error,
-                    groupId,
-                });
-                const missingUsers = (0, CoreCryptoMLSError_1.getMLSGroupOutOfSyncErrorMissingUsers)(error);
-                await this.addUsersToMLSConversation({
+            await this.MLSRecoveryOrchestrator.execute({
+                context: {
+                    operationName: recovery_1.OperationName.keyMaterialUpdate,
+                    qualifiedConversationId: conversation.qualified_id,
                     groupId,
-                    conversationId: conversation.qualified_id,
-                    qualifiedUsers: missingUsers,
-                });
-            }
-        }
-        catch (error) {
-            this.logger.error('Failed to react to key material update failure', { error, groupId });
+                },
+                callBack: async () => {
+                    // Surface the ORIGINAL error to the orchestrator for mapping & policy resolution
+                    // Deliberately throwing the raw value so mapper can recognize core-crypto/API error shapes
+                    throw error;
+                },
+            });
         }
-        finally {
-            this.recoveringKeyMaterialGroups.delete(groupId);
+        catch (e) {
+            this.logger.error('Failed to react to key material update failure', { error: e, groupId });
         }
     };
     async resetMLSConversation(conversationId) {
@@ -761,21 +655,38 @@ class ConversationService extends commons_1.TypedEventEmitter {
             throw error;
         }
     }
+    /**
+     * Handle an inbound MLS message-add event with recovery.
+     *
+     * Policies (see MlsRecoveryOrchestrator):
+     * - WrongEpoch.handleMessageAdd → recover from epoch mismatch and re-run once.
+     * - GroupOutOfSync.handleMessageAdd → not handled here; the error bubbles.
+     *
+     * Returns the decrypted payload when available. Unknown or unrecoverable errors are logged
+     * and result in null so event processing can continue safely.
+     */
     async handleMLSMessageAddEvent(event) {
         try {
-            return await this.mlsService.handleMLSMessageAddEvent(event, this.groupIdFromConversationId);
+            const { qualified_conversation: qualifiedConversationId, subconv } = event;
+            if (!qualifiedConversationId) {
+                throw new Error('Qualified conversation id is missing in the MLS message-add event');
+            }
+            return await this.MLSRecoveryOrchestrator.execute({
+                context: {
+                    operationName: recovery_1.OperationName.handleMessageAdd,
+                    qualifiedConversationId,
+                    subconvId: subconv,
+                },
+                callBack: async () => {
+                    return this.mlsService.handleMLSMessageAddEvent(event, this.groupIdFromConversationId);
+                },
+            });
         }
         catch (error) {
-            if ((0, CoreCryptoMLSError_1.isCoreCryptoMLSWrongEpochError)(error)) {
-                this.logger.warn(`Received message for the wrong epoch in conversation ${event.conversation}, handling epoch mismatch...`);
-                const { qualified_conversation: conversationId, subconv } = event;
-                if (!conversationId) {
-                    throw new Error('Qualified conversation id is missing in the event');
-                }
-                void (0, conversationRejoinQueue_1.queueConversationRejoin)(conversationId.id, () => this.recoverMLSGroupFromEpochMismatch(conversationId, subconv));
-                return null;
-            }
-            throw error;
+            // For unmapped or unrecoverable errors, avoid surfacing exceptions from event handling
+            // and instead log and return null so the event processing queue can continue safely.
+            this.logger.error('Failed to handle MLS message-add event after recovery; returning null', { error, event });
+            return null;
         }
     }
     async recoverMLSGroupFromEpochMismatch(conversationId, subconversationId) {
@@ -794,56 +705,25 @@ class ConversationService extends commons_1.TypedEventEmitter {
         }
         return this.handleConversationEpochMismatch(mlsConversation, () => this.emit('MLSConversationRecovered', { conversationId: mlsConversation.qualified_id }));
     }
-    async handleMLSWelcomeMessageEvent(event, retry = true) {
-        try {
-            this.logger.info('Handling MLS welcome message event', { event });
-            return await this.mlsService.handleMLSWelcomeMessageEvent(event, this.apiClient.validatedClientId);
-        }
-        catch (error) {
-            if (!retry) {
-                this.logger.error('Failed to handle MLS welcome message event and unable to recover', { event, error });
-                throw error;
-            }
-            this.logger.warn('Failed to handle MLS welcome message event', { event, error });
-            if ((0, core_crypto_1.isMlsOrphanWelcomeError)(error)) {
-                return this.handleMlsOrphanWelcomeEvent(event);
-            }
-            if ((0, core_crypto_1.isMlsConversationAlreadyExistsError)(error)) {
-                return this.handleMlsConversationAlreadyExistsEvent(event, error);
-            }
-            throw error;
-        }
-    }
-    handleMlsOrphanWelcomeEvent(event) {
-        this.logger.warn('Received an orphan welcome message, trying to join the conversation via external commit');
-        const { qualified_conversation: conversationId } = event;
-        // Note that we don't care about a subconversation here, as the welcome message is always for the parent conversation.
-        // Subconversations are always joined via external commit.
-        if (!conversationId) {
-            throw new Error('Qualified conversation id is missing in the event');
-        }
-        this.logger.warn(`Received an orphan welcome message, joining the conversation (${conversationId.id}) via external commit...`);
-        void (0, conversationRejoinQueue_1.queueConversationRejoin)(conversationId.id, () => this.joinByExternalCommit(conversationId));
-        return null;
-    }
     /**
-     * In case of an "MLS conversation already exists" error, we have to wipe the conversation from core-crypto
-     * and retry processing the welcome message.
+     * Handle an MLS welcome event with recovery.
+     *
+     * Policies (see MlsRecoveryOrchestrator):
+     * - OrphanWelcome → join via external commit (no auto re-run).
+     * - ConversationAlreadyExists → wipe local state and re-run welcome once.
+     *
+     * Always resolves to null; the effects are applied to local state.
      */
-    async handleMlsConversationAlreadyExistsEvent(event, error) {
-        try {
-            const conversationIdArray = error.context?.context?.conversationId;
-            const groupId = bazinga64_1.Encoder.toBase64(new Uint8Array(conversationIdArray)).asString;
-            this.logger.info('Conversation already exists error when processing welcome message, wiping the local conversation and retrying', {
-                extractedGroupIdFromError: groupId,
-            });
-            await this.wipeMLSConversation(groupId);
-            return this.handleMLSWelcomeMessageEvent(event, false);
-        }
-        catch (error) {
-            this.logger.error('Failed to handle MLS conversation already exists event', { event, error });
-            throw error;
-        }
+    async handleMLSWelcomeMessageEvent(event) {
+        this.logger.info('Handling MLS welcome message event (orchestrated)', { event });
+        await this.MLSRecoveryOrchestrator.execute({
+            context: {
+                operationName: recovery_1.OperationName.handleWelcome,
+                qualifiedConversationId: event.qualified_conversation,
+            },
+            callBack: () => this.mlsService.handleMLSWelcomeMessageEvent(event, this.apiClient.validatedClientId),
+        });
+        return null;
     }
     async handleOtrMessageAddEvent(event) {
         return this.proteusService.handleOtrMessageAddEvent(event);