@wireapp/core 46.46.6-beta.14.f6fd03fe6 → 46.46.6

package/lib/conversation/ConversationService/ConversationService.js

@@ -19,16 +19,17 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConversationService = void 0;
-const protocol_messaging_1 = require("@pydio/protocol-messaging");
 const conversation_1 = require("@wireapp/api-client/lib/conversation");
 const data_1 = require("@wireapp/api-client/lib/conversation/data");
 const event_1 = require("@wireapp/api-client/lib/event");
-const http_1 = require("@wireapp/api-client/lib/http");
+const team_1 = require("@wireapp/api-client/lib/team");
 const bazinga64_1 = require("bazinga64");
 const commons_1 = require("@wireapp/commons");
+const core_crypto_1 = require("@wireapp/core-crypto");
+const protocol_messaging_1 = require("@wireapp/protocol-messaging");
 const conversation_2 = require("../../conversation/");
-const conversationRejoinQueue_1 = require("../../messagingProtocols/mls/conversationRejoinQueue");
-const CoreCryptoMLSError_1 = require("../../messagingProtocols/mls/MLSService/CoreCryptoMLSError");
+const mls_1 = require("../../messagingProtocols/mls");
+const recovery_1 = require("../../messagingProtocols/mls/recovery");
 const proteus_1 = require("../../messagingProtocols/proteus");
 const util_1 = require("../../util");
 const fullyQualifiedClientIdUtils_1 = require("../../util/fullyQualifiedClientIdUtils");
@@ -39,18 +40,44 @@ class ConversationService extends commons_1.TypedEventEmitter {
     coreDatabase;
     groupIdFromConversationId;
     subconversationService;
+    isMLSConversationRecoveryEnabled;
     _mlsService;
     messageTimer;
     logger = commons_1.LogFactory.getLogger('@wireapp/core/ConversationService');
-    constructor(apiClient, proteusService, coreDatabase, groupIdFromConversationId, subconversationService, _mlsService) {
+    // Track groups currently undergoing recovery due to key material update failure to prevent duplicate work
+    groupIdConversationMap = new Map();
+    MLSRecoveryOrchestrator;
+    constructor(apiClient, proteusService, coreDatabase, groupIdFromConversationId, subconversationService, isMLSConversationRecoveryEnabled, _mlsService) {
         super();
         this.apiClient = apiClient;
         this.proteusService = proteusService;
         this.coreDatabase = coreDatabase;
         this.groupIdFromConversationId = groupIdFromConversationId;
         this.subconversationService = subconversationService;
+        this.isMLSConversationRecoveryEnabled = isMLSConversationRecoveryEnabled;
         this._mlsService = _mlsService;
         this.messageTimer = new conversation_2.MessageTimer();
+        // 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: this.wipeMLSConversation,
+        });
     }
     get mlsService() {
         if (!this._mlsService) {
@@ -116,7 +143,7 @@ class ConversationService extends commons_1.TypedEventEmitter {
      */
     async send(params) {
         function isMLS(params) {
-            return params.protocol === conversation_1.ConversationProtocol.MLS;
+            return params.protocol === team_1.CONVERSATION_PROTOCOL.MLS;
         }
         return (0, messageSender_1.sendMessage)(() => (isMLS(params) ? this.sendMLSMessage(params) : this.proteusService.sendMessage(params)));
     }
@@ -197,42 +224,71 @@ class ConversationService extends commons_1.TypedEventEmitter {
         if (!groupId) {
             throw new Error('No group_id found in response which is required for creating MLS conversations.');
         }
-        const { events, failures } = await this.mlsService.registerConversation(groupId, qualifiedUsers.concat(selfUserId), {
+        return this.establishMLSGroupConversation(groupId, qualifiedUsers, selfUserId, selfClientId, qualifiedId);
+    }
+    /**
+     * 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');
+        }
+        const { conversation: { group_id: newGroupId }, } = await this.resetMLSConversation(conversationId);
+        if (!newGroupId) {
+            const errorMessage = 'Tried to reset MLS conversation but no group_id found in response';
+            this.logger.error(errorMessage, { conversationId });
+            throw new Error(errorMessage);
+        }
+    }
+    /**
+     * Will create a conversation on backend and register it to CoreCrypto once created
+     * @param conversationData
+     */
+    async establishMLSGroupConversation(groupId, userIdsToAdd, selfUserId, selfClientId, conversationQualifiedId) {
+        const failures = await this.mlsService.registerConversation(groupId, userIdsToAdd.concat(selfUserId), {
             creator: {
                 user: selfUserId,
                 client: selfClientId,
             },
         });
         // We fetch the fresh version of the conversation created on backend with the newly added users
-        const conversation = await this.apiClient.api.conversation.getConversation(qualifiedId);
+        const conversation = await this.apiClient.api.conversation.getConversation(conversationQualifiedId);
         return {
-            events,
             conversation,
             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;
         // immediately execute pending commits before sending the message
-        await this.mlsService.commitPendingProposals(groupId);
-        const encrypted = await this.mlsService.encryptMessage(groupIdBytes, protocol_messaging_1.GenericMessage.encode(payload).finish());
-        let response = null;
-        let sentAt = '';
-        try {
-            response = await this.apiClient.api.conversation.postMlsMessage(encrypted);
-            sentAt = response.time?.length > 0 ? response.time : new Date().toISOString();
-        }
-        catch (error) {
-            const isMLSStaleMessageError = error instanceof http_1.BackendError && error.label === http_1.BackendErrorLabel.MLS_STALE_MESSAGE;
-            if (isMLSStaleMessageError) {
-                await this.recoverMLSGroupFromEpochMismatch(conversationId);
-                if (shouldRetry) {
-                    return this.sendMLSMessage(params, false);
-                }
-            }
-            throw error;
-        }
+        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,
@@ -247,40 +303,166 @@ class ConversationService extends commons_1.TypedEventEmitter {
         };
     }
     /**
-     * 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.
+     *
+     * 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 (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
+     * @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, }) {
-        const { keyPackages, failures: keysClaimingFailures } = await this.mlsService.getKeyPackagesPayload(qualifiedUsers);
-        const { events, failures } = keyPackages.length > 0
-            ? await this.mlsService.addUsersToExistingConversation(groupId, keyPackages)
-            : { events: [], failures: [] };
+        return this.MLSRecoveryOrchestrator.execute({
+            context: { operationName: recovery_1.OperationName.addUsers, qualifiedConversationId: conversationId, groupId },
+            callBack: () => this.performAddUsersToMLSConversationAPI({ qualifiedUsers, groupId, conversationId }),
+        });
+    }
+    // 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);
-        //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);
+        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 {
-            events,
             conversation,
-            failedToAdd: [...keysClaimingFailures, ...failures],
+            failedToAdd: keysClaimingFailures,
         };
     }
+    /**
+     * 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);
-        const messageResponse = 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.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);
-        const conversation = await this.getConversation(conversationId);
-        return {
-            events: messageResponse.events,
-            conversation,
-        };
+        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) {
-        return this.mlsService.joinByExternalCommit(() => this.apiClient.api.conversation.getGroupInfo(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();
+        this.groupIdConversationMap.clear();
+        for (const conversation of conversations.found || []) {
+            if (conversation.group_id) {
+                this.groupIdConversationMap.set(conversation.group_id, conversation);
+            }
+        }
+    }
+    async getConversationByGroupId(groupId) {
+        if (!this.groupIdConversationMap.has(groupId)) {
+            await this.refreshGroupIdConversationMap();
+        }
+        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 }) => {
+        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;
+        }
+        try {
+            await this.MLSRecoveryOrchestrator.execute({
+                context: {
+                    operationName: recovery_1.OperationName.keyMaterialUpdate,
+                    qualifiedConversationId: conversation.qualified_id,
+                    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;
+                },
+            });
+        }
+        catch (e) {
+            this.logger.error('Failed to react to key material update failure', { error: e, groupId });
+        }
+    };
+    async resetMLSConversation(conversationId) {
+        this.logger.info(`Resetting MLS conversation with id ${conversationId.id}`);
+        // STEP 1: Fetch the conversation to retrieve the group ID & epoch
+        const conversation = await this.apiClient.api.conversation.getConversation(conversationId);
+        const { group_id: groupId, epoch } = conversation;
+        if (!groupId || !epoch) {
+            const errorMessage = 'Could not find group id or epoch for the conversation';
+            this.logger.error(errorMessage, { conversationId });
+            throw new Error(errorMessage);
+        }
+        // STEP 2: Request backend to reset the conversation
+        this.logger.info(`Requesting backend to reset the conversation (group_id: ${groupId}, epoch: ${String(epoch)})`);
+        await this.apiClient.api.conversation.resetMLSConversation({
+            epoch,
+            groupId,
+        });
+        // STEP 3: fetch self user info
+        this.logger.info(`Re-establishing the conversation by re-adding all members (conversation_id: ${conversationId.id})`);
+        const { validatedClientId: clientId, userId, domain } = this.apiClient;
+        if (!userId || !domain) {
+            const errorMessage = 'Could not find userId or domain of the self user';
+            this.logger.error(errorMessage, { conversationId });
+            throw new Error(errorMessage);
+        }
+        const selfUserQualifiedId = { id: userId, domain };
+        // STEP 4: Fetch the updated conversation data from backend to retrieve the new group ID
+        const updatedConversation = await this.apiClient.api.conversation.getConversation(conversationId);
+        const { group_id: newGroupId, members } = updatedConversation;
+        this.logger.info(`MLS conversation new group ID fetched from backend ${conversationId.id}`, {
+            newGroupId,
+        });
+        if (!newGroupId || !clientId) {
+            throw new Error(`Failed to recover MLS conversation: missing groupId (${newGroupId}), or clientId (${clientId})`);
+        }
+        const usersToReAdd = members.others.map(member => member.qualified_id).filter(userId => !!userId);
+        // STEP 5: Re-establish the conversation by re-adding all members
+        return await this.establishMLSGroupConversation(newGroupId, usersToReAdd, selfUserQualifiedId, clientId, conversationId).then(result => {
+            this.logger.info(`Successfully reset MLS conversation`, {
+                conversationId: conversationId.id,
+                oldGroupId: groupId,
+                newGroupId,
+            });
+            return result;
+        });
     }
     /**
      * Will check if mls group exists locally.
@@ -297,9 +479,9 @@ class ConversationService extends commons_1.TypedEventEmitter {
     async isMLSGroupEstablishedLocally(groupId) {
         return this.mlsService.isConversationEstablished(groupId);
     }
-    async wipeMLSConversation(groupId) {
+    wipeMLSConversation = async (groupId) => {
         return this.mlsService.wipeConversation(groupId);
-    }
+    };
     async matchesEpoch(groupId, backendEpoch) {
         const localEpoch = await this.mlsService.getEpoch(groupId);
         this.logger.debug(`Comparing conversation's (group_id: ${groupId}) local and backend epoch number: {local: ${String(localEpoch)}, backend: ${backendEpoch}}`);
@@ -367,8 +549,14 @@ class ConversationService extends commons_1.TypedEventEmitter {
     async hasEpochMismatch(groupId, epoch) {
         const isEstablished = await this.mlsGroupExistsLocally(groupId);
         const doesEpochMatch = isEstablished && (await this.matchesEpoch(groupId, epoch));
-        //if conversation is not established or epoch does not match -> try to rejoin
-        return !isEstablished || !doesEpochMatch;
+        // if conversation is not established or epoch does not match -> try to rejoin
+        const hasEpochMismatch = !isEstablished || !doesEpochMatch;
+        this.logger.info(`Conversation (group_id: ${groupId}) epoch mismatch check result: ${hasEpochMismatch}`, {
+            isEstablished,
+            doesEpochMatch,
+            epoch,
+        });
+        return hasEpochMismatch;
     }
     /**
      * Get a MLS 1:1-conversation with a given user.
@@ -438,47 +626,71 @@ class ConversationService extends commons_1.TypedEventEmitter {
      * @param qualifiedUsers - list of qualified users to add to the group (should not include the self user)
      */
     async tryEstablishingMLSGroup({ groupId, conversationId, selfUserId, qualifiedUsers, }) {
-        const wasGroupEstablishedBySelfClient = await this.mlsService.tryEstablishingMLSGroup(groupId);
-        if (!wasGroupEstablishedBySelfClient) {
-            this.logger.debug('Group was not established by self client, skipping adding users to the group.');
-            return;
-        }
-        this.logger.debug('Group was established by self client, adding other users to the group...');
-        const usersToAdd = [
-            ...qualifiedUsers,
-            { ...selfUserId, skipOwnClientId: this.apiClient.validatedClientId },
-        ];
-        const { conversation } = await this.addUsersToMLSConversation({
-            conversationId,
-            groupId,
-            qualifiedUsers: usersToAdd,
-        });
-        const addedUsers = conversation.members.others;
-        if (addedUsers.length > 0) {
-            this.logger.debug(`Successfully added ${addedUsers} users to the group.`);
+        try {
+            const wasGroupEstablishedBySelfClient = await this.mlsService.tryEstablishingMLSGroup(groupId);
+            if (!wasGroupEstablishedBySelfClient) {
+                this.logger.debug('Group was not established by self client, skipping adding users to the group.');
+                return;
+            }
+            this.logger.debug('Group was established by self client, adding other users to the group...');
+            const usersToAdd = [
+                ...qualifiedUsers,
+                { ...selfUserId, skipOwnClientId: this.apiClient.validatedClientId },
+            ];
+            const { conversation } = await this.addUsersToMLSConversation({
+                conversationId,
+                groupId,
+                qualifiedUsers: usersToAdd,
+            });
+            const addedUsers = conversation.members.others;
+            if (addedUsers.length > 0) {
+                this.logger.debug(`Successfully added ${addedUsers} users to the group.`);
+            }
+            else {
+                this.logger.debug('No other users were added to the group.');
+            }
         }
-        else {
-            this.logger.debug('No other users were added to the group.');
+        catch (error) {
+            this.logger.error('Failed to establish MLS group', error);
+            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');
-                }
-                (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) {
+        this.logger.info(`Recovering MLS group from epoch mismatch`, { conversationId, subconversationId });
         if (subconversationId) {
             const parentGroupId = await this.groupIdFromConversationId(conversationId);
             const subconversation = await this.apiClient.api.conversation.getSubconversation(conversationId, subconversationId);
@@ -493,24 +705,25 @@ class ConversationService extends commons_1.TypedEventEmitter {
         }
         return this.handleConversationEpochMismatch(mlsConversation, () => this.emit('MLSConversationRecovered', { conversationId: mlsConversation.qualified_id }));
     }
+    /**
+     * 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 handleMLSWelcomeMessageEvent(event) {
-        try {
-            return await this.mlsService.handleMLSWelcomeMessageEvent(event, this.apiClient.validatedClientId);
-        }
-        catch (error) {
-            if ((0, CoreCryptoMLSError_1.isCoreCryptoMLSOrphanWelcomeMessageError)(error)) {
-                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;
-            }
-            throw error;
-        }
+        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);