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

package/lib/messagingProtocols/mls/MLSService/commitBundleUtil.test.js

@@ -18,7 +18,7 @@
  *
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-const mls_1 = require("@pydio/protocol-messaging/web/mls");
+const mls_1 = require("@wireapp/protocol-messaging/web/mls");
 const bazinga64_1 = require("bazinga64");
 const core_crypto_1 = require("@wireapp/core-crypto");
 const commitBundleUtil_1 = require("./commitBundleUtil");
@@ -26,18 +26,18 @@ describe('toProtobufCommitBundle', () => {
     it('encode commit bundles', () => {
         const payload = {
             commit: Uint8Array.from([0]),
-            welcome: Uint8Array.from([1]),
+            welcome: new core_crypto_1.Welcome(Uint8Array.from([1])),
             groupInfo: {
                 ratchetTreeType: core_crypto_1.RatchetTreeType.Full,
-                payload: Uint8Array.from([2]),
+                payload: new core_crypto_1.GroupInfo(Uint8Array.from([2])),
                 encryptionType: core_crypto_1.GroupInfoEncryptionType.Plaintext,
             },
         };
         const result = (0, commitBundleUtil_1.toProtobufCommitBundle)(payload);
         const { commit, welcome, groupInfoBundle } = mls_1.mls.CommitBundle.decode(result);
         expect(bazinga64_1.Encoder.toBase64(commit)).toEqual(bazinga64_1.Encoder.toBase64(payload.commit));
-        expect(bazinga64_1.Encoder.toBase64(welcome)).toEqual(bazinga64_1.Encoder.toBase64(payload.welcome));
-        expect(bazinga64_1.Encoder.toBase64(groupInfoBundle.groupInfo)).toEqual(bazinga64_1.Encoder.toBase64(payload.groupInfo.payload));
+        expect(bazinga64_1.Encoder.toBase64(welcome)).toEqual(bazinga64_1.Encoder.toBase64(payload.welcome?.copyBytes()));
+        expect(bazinga64_1.Encoder.toBase64(groupInfoBundle.groupInfo)).toEqual(bazinga64_1.Encoder.toBase64(payload.groupInfo.payload.copyBytes()));
         expect(groupInfoBundle.ratchetTreeType).toEqual(mls_1.mls.RatchetTreeType.FULL);
         expect(groupInfoBundle.groupInfoType).toEqual(mls_1.mls.GroupInfoType.PUBLIC_GROUP_STATE);
     });

package/lib/messagingProtocols/mls/conversationRejoinQueue.js

@@ -38,8 +38,8 @@ async function queueConversationRejoin(groupId, rejoinFn) {
     }
 }
 function resumeRejoiningMLSConversations() {
-    sendingQueue.pause(false);
+    sendingQueue.resume();
 }
 function pauseRejoiningMLSConversations() {
-    sendingQueue.pause(true);
+    sendingQueue.pause();
 }

package/lib/messagingProtocols/mls/recovery/MlsErrorMapper.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A small, library-free Chain of Responsibility to normalize diverse MLS/core-crypto/backend
+ * errors into a closed {@link DomainMlsError} union. This module is side-effect free and only
+ * classifies errors; recovery actions are implemented by a separate orchestrator.
+ */
+import { SUBCONVERSATION_ID } from '@wireapp/api-client/lib/conversation';
+import { QualifiedId } from '@wireapp/api-client/lib/user';
+import { MlsErrorType } from '@wireapp/core-crypto';
+/**
+ * Domain error taxonomy used by policies and orchestrator.
+ *
+ * These are intentionally decoupled from concrete error classes to keep the orchestrator stable.
+ */
+export type DomainMlsErrorType = MlsErrorType | 'KeyMaterialUpdateFailure' | 'GroupOutOfSync' | 'GroupNotEstablished';
+/**
+ * Normalized error shape produced by the mapper.
+ */
+export type DomainMlsError = {
+    /** The domain classification. */
+    type: DomainMlsErrorType;
+    /** Optional human-friendly message for logging only. */
+    message?: string;
+    /** The original error value, preserved for debugging. */
+    cause?: unknown;
+    /** Lightweight, structured context to inform recovery. */
+    context?: {
+        /** Conversation qualified id if known. */
+        qualifiedConversationId?: QualifiedId;
+        /** MLS group id (base64) if available. */
+        groupId?: string;
+        /** Expected/observed epoch number if relevant. */
+        epoch?: number | bigint;
+        /** Users reported as missing by the backend or MLS layer. */
+        missingUsers?: QualifiedId[];
+        /** Subconversation context (e.g. conference). */
+        subconvId?: SUBCONVERSATION_ID;
+        /** HTTP status when the source error came from the backend. */
+        httpStatus?: number;
+    };
+};
+/**
+ * Optional context supplied by the caller to improve mapping precision.
+ */
+export type ErrorContextInput = {
+    qualifiedConversationId?: QualifiedId;
+    groupId?: string;
+    subconvId?: SUBCONVERSATION_ID;
+};
+/** One handler in the chain. Must be side-effect free. */
+export interface ErrorHandler {
+    /** True if this handler can map the provided error given optional context. */
+    canHandle(error: unknown, context?: ErrorContextInput): boolean;
+    /** Return a mapped error or undefined to defer to later handlers. */
+    map(error: unknown, context?: ErrorContextInput): DomainMlsError;
+}
+/** Public mapper interface returning a normalized {@link DomainMlsError}. */
+export interface MlsErrorMapper {
+    map(error: unknown, context?: ErrorContextInput): DomainMlsError;
+}
+/**
+ * Deterministic chain execution
+ *
+ * The first handler that both
+ * canHandle and returns a non-undefined mapping wins. If none map, an Unknown error is returned.
+ */
+export declare class ChainedMlsErrorMapper implements MlsErrorMapper {
+    private readonly handlers;
+    constructor(handlers: ErrorHandler[]);
+    map(error: unknown, context?: ErrorContextInput): DomainMlsError;
+}
+/**
+ * Factory for the default mapper chain used by the orchestrator.
+ *
+ * Order matters: earlier handlers have higher precedence. The selection reflects
+ * the most common recovery decisions needed by the orchestrator.
+ */
+export declare function createDefaultMlsErrorMapper(): MlsErrorMapper;
+//# sourceMappingURL=MlsErrorMapper.d.ts.map

package/lib/messagingProtocols/mls/recovery/MlsErrorMapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MlsErrorMapper.d.ts","sourceRoot":"","sources":["../../../../src/messagingProtocols/mls/recovery/MlsErrorMapper.ts"],"names":[],"mappings":"AAmBA;;;;GAIG;AAEH,OAAO,EAAC,kBAAkB,EAA+C,MAAM,sCAAsC,CAAC;AACtH,OAAO,EAAC,WAAW,EAAC,MAAM,8BAA8B,CAAC;AAGzD,OAAO,EAA+D,YAAY,EAAC,MAAM,sBAAsB,CAAC;AAYhH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,0BAA0B,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAEtH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,iCAAiC;IACjC,IAAI,EAAE,kBAAkB,CAAC;IACzB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,OAAO,CAAC,EAAE;QACR,0CAA0C;QAC1C,uBAAuB,CAAC,EAAE,WAAW,CAAC;QACtC,0CAA0C;QAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,kDAAkD;QAClD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACxB,6DAA6D;QAC7D,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;QAC7B,iDAAiD;QACjD,SAAS,CAAC,EAAE,kBAAkB,CAAC;QAC/B,+DAA+D;QAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,uBAAuB,CAAC,EAAE,WAAW,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAChE,qEAAqE;IACrE,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAAC;CAClE;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAAC;CAClE;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;gBAE9B,QAAQ,EAAE,YAAY,EAAE;IAIpC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,cAAc;CAYjE;AA4FD;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,cAAc,CAS5D"}

package/lib/messagingProtocols/mls/recovery/MlsErrorMapper.js

@@ -0,0 +1,173 @@
+"use strict";
+/*
+ * Wire
+ * Copyright (C) 2025 Wire Swiss GmbH
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see http://www.gnu.org/licenses/.
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChainedMlsErrorMapper = void 0;
+exports.createDefaultMlsErrorMapper = createDefaultMlsErrorMapper;
+/**
+ * A small, library-free Chain of Responsibility to normalize diverse MLS/core-crypto/backend
+ * errors into a closed {@link DomainMlsError} union. This module is side-effect free and only
+ * classifies errors; recovery actions are implemented by a separate orchestrator.
+ */
+const conversation_1 = require("@wireapp/api-client/lib/conversation");
+const bazinga64_1 = require("bazinga64");
+const core_crypto_1 = require("@wireapp/core-crypto");
+// Reuse existing type-guards from the MLS layer
+const CoreCryptoMLSError_1 = require("../MLSService/CoreCryptoMLSError");
+/**
+ * Deterministic chain execution
+ *
+ * The first handler that both
+ * canHandle and returns a non-undefined mapping wins. If none map, an Unknown error is returned.
+ */
+class ChainedMlsErrorMapper {
+    handlers;
+    constructor(handlers) {
+        this.handlers = handlers.slice();
+    }
+    map(error, context) {
+        for (const handler of this.handlers) {
+            if (handler.canHandle(error, context)) {
+                const mapped = handler.map(error, context);
+                if (mapped) {
+                    return mapped;
+                }
+            }
+        }
+        return FallbackHandler.map(error, context);
+    }
+}
+exports.ChainedMlsErrorMapper = ChainedMlsErrorMapper;
+/** ---------------------- Concrete handlers ---------------------- */
+/** Wrong epoch or stale message from MLS/core-crypto/backend. */
+const WrongEpochHandler = {
+    canHandle: err => (0, CoreCryptoMLSError_1.isCoreCryptoMLSWrongEpochError)?.(err) || (0, CoreCryptoMLSError_1.isMLSStaleMessageError)?.(err) || err instanceof conversation_1.MLSStaleMessageError,
+    map: (err, context) => ({
+        type: core_crypto_1.MlsErrorType.WrongEpoch,
+        message: 'Epoch mismatch or stale message',
+        cause: err,
+        context: {
+            qualifiedConversationId: context?.qualifiedConversationId,
+            groupId: context?.groupId,
+            subconvId: context?.subconvId,
+        },
+    }),
+};
+/** Local MLS state indicates the conversation is broken/not established. */
+const BrokenConversationHandler = {
+    canHandle: err => (0, CoreCryptoMLSError_1.isBrokenMLSConversationError)?.(err) === true,
+    map: (err, context) => ({
+        type: 'GroupNotEstablished',
+        message: 'Broken MLS conversation',
+        cause: err,
+        context: { qualifiedConversationId: context?.qualifiedConversationId, groupId: context?.groupId },
+    }),
+};
+/** Backend/MLS reports missing users; group is out-of-sync. */
+const GroupOutOfSyncHandler = {
+    canHandle: err => (0, CoreCryptoMLSError_1.isMLSGroupOutOfSyncError)?.(err) === true || err instanceof conversation_1.MLSGroupOutOfSyncError,
+    map: (err, context) => {
+        let missingUsers = [];
+        if ((0, CoreCryptoMLSError_1.isMLSGroupOutOfSyncError)?.(err)) {
+            missingUsers = (0, CoreCryptoMLSError_1.getMLSGroupOutOfSyncErrorMissingUsers)(err);
+        }
+        else if (err instanceof conversation_1.MLSGroupOutOfSyncError) {
+            missingUsers = err.missing_users;
+        }
+        if (missingUsers.length === 0) {
+            throw new Error('Error is not a GroupOutOfSync error with missing users');
+        }
+        return {
+            type: 'GroupOutOfSync',
+            message: 'Group out of sync; missing users detected',
+            cause: err,
+            context: { qualifiedConversationId: context?.qualifiedConversationId, groupId: context?.groupId, missingUsers },
+        };
+    },
+};
+/** core-crypto indicates a local group already exists for the welcome's group id. */
+const ConversationAlreadyExistsHandler = {
+    canHandle: error => (0, core_crypto_1.isMlsConversationAlreadyExistsError)?.(error) === true,
+    map: (error, context) => {
+        if (!(0, core_crypto_1.isMlsConversationAlreadyExistsError)(error)) {
+            throw new Error('Error is not a ConversationAlreadyExists error');
+        }
+        const groupId = tryExtractGroupIdFromCoreCryptoError(error);
+        return {
+            type: core_crypto_1.MlsErrorType.ConversationAlreadyExists,
+            message: 'Conversation already exists',
+            cause: error,
+            context: { groupId, qualifiedConversationId: context?.qualifiedConversationId },
+        };
+    },
+};
+/** Orphan welcome (no matching state); caller should try to join. */
+const OrphanWelcomeHandler = {
+    canHandle: err => (0, core_crypto_1.isMlsOrphanWelcomeError)?.(err) === true,
+    map: (err, context) => ({
+        type: core_crypto_1.MlsErrorType.OrphanWelcome,
+        message: 'Orphan welcome message',
+        cause: err,
+        context: { qualifiedConversationId: context?.qualifiedConversationId },
+    }),
+};
+/** Fallback classification when no handler matches. */
+const FallbackHandler = {
+    canHandle: () => true,
+    map: (err, context) => err instanceof Error
+        ? { type: core_crypto_1.MlsErrorType.Other, message: err.message, cause: err, context }
+        : { type: core_crypto_1.MlsErrorType.Other, message: String(err), cause: err, context },
+};
+/**
+ * Factory for the default mapper chain used by the orchestrator.
+ *
+ * Order matters: earlier handlers have higher precedence. The selection reflects
+ * the most common recovery decisions needed by the orchestrator.
+ */
+function createDefaultMlsErrorMapper() {
+    return new ChainedMlsErrorMapper([
+        WrongEpochHandler,
+        BrokenConversationHandler,
+        GroupOutOfSyncHandler,
+        ConversationAlreadyExistsHandler,
+        OrphanWelcomeHandler,
+        FallbackHandler,
+    ]);
+}
+/** ---------------------- helpers ---------------------- */
+/**
+ * Extract the base64 group id from a core-crypto error if present.
+ *
+ * core-crypto encodes the conversation id bytes under `error.context.context.conversationId`.
+ * We convert the byte array to base64 for uniform handling in higher layers.
+ */
+function tryExtractGroupIdFromCoreCryptoError(err) {
+    try {
+        // core-crypto error.context?.context?.conversationId is a byte array (number[])
+        const conversationIdArray = err?.context?.context?.conversationId;
+        if (!conversationIdArray) {
+            return undefined;
+        }
+        return bazinga64_1.Encoder.toBase64(new Uint8Array(conversationIdArray)).asString;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Intentionally not handling HTTP/network errors here; let them bubble up unmodified.

package/lib/messagingProtocols/mls/recovery/MlsErrorMapper.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=MlsErrorMapper.test.d.ts.map

package/lib/messagingProtocols/mls/recovery/MlsErrorMapper.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MlsErrorMapper.test.d.ts","sourceRoot":"","sources":["../../../../src/messagingProtocols/mls/recovery/MlsErrorMapper.test.ts"],"names":[],"mappings":""}

package/lib/messagingProtocols/mls/recovery/MlsErrorMapper.test.js

@@ -0,0 +1,117 @@
+"use strict";
+/*
+ * Wire
+ * Copyright (C) 2025 Wire Swiss GmbH
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see http://www.gnu.org/licenses/.
+ *
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const conversation_1 = require("@wireapp/api-client/lib/conversation");
+const bazinga64_1 = require("bazinga64");
+const core_crypto_1 = require("@wireapp/core-crypto");
+const MlsErrorMapper_1 = require("./MlsErrorMapper");
+const CoreCryptoMLSError_1 = require("../MLSService/CoreCryptoMLSError");
+// Helpers
+const id = { id: 'conv-id', domain: 'wire.test' };
+const groupIdBase64 = bazinga64_1.Encoder.toBase64(new Uint8Array([1, 2, 3, 4])).asString;
+const mapper = (0, MlsErrorMapper_1.createDefaultMlsErrorMapper)();
+function map(error, extra) {
+    return mapper.map(error, { qualifiedConversationId: id, groupId: extra?.groupId });
+}
+describe('MlsErrorMapper', () => {
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    it('maps WrongEpoch via stale message class instance', () => {
+        const err = new conversation_1.MLSStaleMessageError('stale');
+        const mapped = map(err, { groupId: groupIdBase64 });
+        expect(mapped.type).toBe('WrongEpoch');
+        expect(mapped.context?.qualifiedConversationId).toEqual(id);
+        expect(mapped.context?.groupId).toBe(groupIdBase64);
+    });
+    it('maps GroupNotEstablished for broken conversation error', () => {
+        const err = {
+            type: core_crypto_1.ErrorType.Mls,
+            context: {
+                type: core_crypto_1.MlsErrorType.MessageRejected,
+                context: { reason: (0, CoreCryptoMLSError_1.serializeAbortReason)({ message: CoreCryptoMLSError_1.UPLOAD_COMMIT_BUNDLE_ABORT_REASONS.BROKEN_MLS_CONVERSATION }) },
+            },
+        };
+        const mapped = map(err);
+        expect(mapped.type).toBe('GroupNotEstablished');
+    });
+    it('maps GroupOutOfSync with missing users list', () => {
+        const missing = [
+            { id: 'u1', domain: 'wire.test' },
+            { id: 'u2', domain: 'wire.test' },
+        ];
+        const err = {
+            type: core_crypto_1.ErrorType.Mls,
+            context: {
+                type: core_crypto_1.MlsErrorType.MessageRejected,
+                context: {
+                    reason: (0, CoreCryptoMLSError_1.serializeAbortReason)({
+                        message: CoreCryptoMLSError_1.UPLOAD_COMMIT_BUNDLE_ABORT_REASONS.MLS_GROUP_OUT_OF_SYNC,
+                        missing_users: missing,
+                    }),
+                },
+            },
+        };
+        const mapped = map(err, { groupId: groupIdBase64 });
+        expect(mapped.type).toBe('GroupOutOfSync');
+        expect(mapped.context?.missingUsers).toEqual(missing);
+        expect(mapped.context?.groupId).toBe(groupIdBase64);
+    });
+    it('maps ConversationAlreadyExists and extracts groupId bytes', () => {
+        const conversationIdArray = [1, 2, 3, 4];
+        const expectedGroupId = bazinga64_1.Encoder.toBase64(new Uint8Array(conversationIdArray)).asString;
+        const err = {
+            type: core_crypto_1.ErrorType.Mls,
+            context: { type: core_crypto_1.MlsErrorType.ConversationAlreadyExists, context: { conversationId: conversationIdArray } },
+        };
+        const mapped = map(err);
+        expect(mapped.type).toBe('ConversationAlreadyExists');
+        expect(mapped.context?.groupId).toBe(expectedGroupId);
+    });
+    it('maps OrphanWelcome', () => {
+        const err = { type: core_crypto_1.ErrorType.Mls, context: { type: core_crypto_1.MlsErrorType.OrphanWelcome } };
+        const mapped = map(err);
+        expect(mapped.type).toBe('OrphanWelcome');
+        expect(mapped.context?.qualifiedConversationId).toEqual(id);
+    });
+    it('falls back to Unknown for unmapped error', () => {
+        const err = new Error('random');
+        const mapped = map(err);
+        expect(mapped.type).toBe(core_crypto_1.MlsErrorType.Other);
+        expect(mapped.cause).toBe(err);
+    });
+    it('honors handler priority (WrongEpoch before GroupOutOfSync)', () => {
+        const err = new Error('ambiguous');
+        err.name = CoreCryptoMLSError_1.CORE_CRYPTO_ERROR_NAMES.MlsErrorWrongEpoch; // triggers WrongEpoch guard
+        // Also craft message-rejected with out-of-sync to trigger GroupOutOfSync guard
+        err.type = core_crypto_1.ErrorType.Mls;
+        err.context = {
+            type: core_crypto_1.MlsErrorType.MessageRejected,
+            context: {
+                reason: (0, CoreCryptoMLSError_1.serializeAbortReason)({
+                    message: CoreCryptoMLSError_1.UPLOAD_COMMIT_BUNDLE_ABORT_REASONS.MLS_GROUP_OUT_OF_SYNC,
+                    missing_users: [],
+                }),
+            },
+        };
+        const mapped = map(err);
+        expect(mapped.type).toBe('WrongEpoch');
+    });
+});

package/lib/messagingProtocols/mls/recovery/MlsRecoveryOrchestrator.d.ts

@@ -0,0 +1,167 @@
+import { SUBCONVERSATION_ID } from '@wireapp/api-client/lib/conversation';
+import { QualifiedId } from '@wireapp/api-client/lib/user';
+import { DomainMlsErrorType, MlsErrorMapper } from './MlsErrorMapper';
+import { BaseCreateConversationResponse } from '../../../conversation';
+/**
+ * Coordinates recovery actions for MLS operations.
+ *
+ * The orchestrator takes an arbitrary async "operation" (e.g. send, add users, handle welcome),
+ * executes it, and on failure maps the thrown error to a DomainMlsError via {@link MlsErrorMapper}.
+ * A recovery policy is then resolved and executed exactly-once per unique key, with optional
+ * re-run of the original operation after recovery.
+ *
+ * Key properties:
+ * - Single-flight: duplicate recoveries (same action+conversation+group+subconv) are deduplicated.
+ * - Per-operation policies: the same DomainMlsError can map to different actions depending on operation.
+ * - Non-invasive: the orchestrator has no MLS logic; it calls provided deps to perform actions.
+ */
+/**
+ * Concrete recovery actions the orchestrator can trigger.
+ */
+export declare enum RecoveryActionKind {
+    /**
+     * Issue an external-commit join for the conversation.
+     */
+    JoinViaExternalCommit = "JoinViaExternalCommit",
+    /**
+     * Fetch missing epoch state and reconcile.
+     */
+    RecoverFromEpochMismatch = "RecoverFromEpochMismatch",
+    /**
+     * Tear down local MLS state and re-create the group.
+     */
+    ResetAndReestablish = "ResetAndReestablish",
+    /**
+     * Add users reported as missing to get the group back in sync.
+     */
+    AddMissingUsers = "AddMissingUsers",
+    /**
+     * Remove local MLS artifacts for the group and retry welcome handling.
+     */
+    WipeAndReprocessWelcome = "WipeAndReprocessWelcome",
+    /**
+     * No matching policy found; treated as no-op and the original error is re-thrown.
+     */
+    Unknown = "Unknown"
+}
+/**
+ * Retry behavior for an operation under recovery.
+ */
+export type RetryPolicy = {
+    maxAttempts: number;
+    delayMs?: number;
+    /**
+     * Whether to retry the original operation once after a successful recovery
+     */
+    reRunOriginalOperation?: boolean;
+};
+/**
+ * A single recovery policy that pairs an action with a retry configuration.
+ */
+export type RecoveryPolicy = {
+    action: RecoveryActionKind;
+    retryConfig: RetryPolicy;
+};
+type PerOperationPolicies = Partial<Record<OperationName, RecoveryPolicy>>;
+/**
+ * Global policy table from DomainMlsErrorType to RecoveryPolicy.
+ *
+ * A value can be either a flat policy (applies to all operations) or a per-operation
+ * map that allows different actions depending on the invoking operation.
+ */
+export type PolicyTable = Partial<Record<DomainMlsErrorType, RecoveryPolicy | PerOperationPolicies>>;
+export declare enum OperationName {
+    send = "send",
+    addUsers = "addUsers",
+    removeUsers = "removeUsers",
+    joinExternalCommit = "joinExternalCommit",
+    handleWelcome = "handleWelcome",
+    handleMessageAdd = "handleMessageAdd",
+    keyMaterialUpdate = "keyMaterialUpdate"
+}
+/**
+ * Context about the operation being orchestrated. Used for policy selection and keying.
+ */
+export type OperationContext = {
+    operationName: OperationName;
+    qualifiedConversationId?: QualifiedId;
+    groupId?: string;
+    subconvId?: SUBCONVERSATION_ID;
+};
+/**
+ * Public orchestrator interface. Wrap your async operation with {@link execute}.
+ *
+ * The callback is invoked immediately. If it throws, the orchestrator maps the error,
+ * performs recovery according to policies, optionally waits, and may re-run the callback once.
+ */
+export interface MlsRecoveryOrchestrator {
+    execute(params: executeParams<void>): Promise<void>;
+    execute<T>(params: executeParams<T>): Promise<T>;
+}
+/**
+ * Concrete side-effecting functions the orchestrator uses to perform recovery.
+ * Provided by the MLS layer/service.
+ */
+export type OrchestratorDeps = {
+    joinViaExternalCommit: (conversationId: QualifiedId) => Promise<void>;
+    resetAndReestablish: (conversationId: QualifiedId) => Promise<void>;
+    recoverFromEpochMismatch: (conversationId: QualifiedId, subconvId?: SUBCONVERSATION_ID) => Promise<void>;
+    addMissingUsers: (conversationId: QualifiedId, groupId: string, users: QualifiedId[]) => Promise<BaseCreateConversationResponse>;
+    wipeMLSConversation: (groupId: string) => Promise<void>;
+};
+/**
+ * Parameters for {@link execute}.
+ */
+type executeParams<T> = {
+    context: OperationContext;
+    callBack: () => Promise<T>;
+    retry?: boolean;
+};
+/**
+ * Default implementation with in-process deduplication keyed by action and context.
+ */
+export declare class MlsRecoveryOrchestratorImpl implements MlsRecoveryOrchestrator {
+    private readonly mapper;
+    private readonly policies;
+    private readonly deps;
+    private readonly inProgressRecoveries;
+    private readonly logger;
+    constructor(mapper: MlsErrorMapper, policies: PolicyTable, deps: OrchestratorDeps, inProgressRecoveries?: Set<string>, logger?: import("logdown").Logger);
+    /**
+     * Execute the provided callback, and on failure, map and perform a configured recovery.
+     * If {@link RetryPolicy.reRunOriginalOperation} is true, the callback is re-invoked once after recovery.
+     */
+    execute(params: executeParams<void>): Promise<void>;
+    execute<T>(params: executeParams<T>): Promise<T>;
+    /** Resolve the effective policy for the mapped error and operation. Supports per-operation policies. */
+    private getPolicyFor;
+    /**
+     * Execute the concrete recovery action once per unique recovery key. Throws if required context is missing.
+     * For WipeAndReprocessWelcome, attempts to derive groupId from either the operation context or error context.
+     */
+    private performRecovery;
+    /**
+     * Build a stable deduplication key from action and operation context.
+     */
+    private getRecoveryKey;
+    /**
+     * Ensure the provided async task runs at most once for the given key at a time.
+     */
+    private runOnceWithKey;
+    /** Optionally wait before re-invoking the original operation. */
+    private maybeDelay;
+    private sleep;
+}
+/**
+ * Minimal default policies used by the initial integration. These can be extended over time.
+ *
+ * Highlights:
+ * - WrongEpoch: reconcile and retry for typed ops; do not re-run for join.
+ * - GroupNotEstablished: reset and re-establish; typed ops re-run once.
+ * - GroupOutOfSync: add missing users and retry for typed ops.
+ * - ConversationAlreadyExists (welcome): wipe local MLS state and re-run welcome once.
+ * - OrphanWelcome (welcome): attempt join via external commit; do not re-run.
+ */
+export declare const minimalDefaultPolicies: PolicyTable;
+export {};
+//# sourceMappingURL=MlsRecoveryOrchestrator.d.ts.map

package/lib/messagingProtocols/mls/recovery/MlsRecoveryOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MlsRecoveryOrchestrator.d.ts","sourceRoot":"","sources":["../../../../src/messagingProtocols/mls/recovery/MlsRecoveryOrchestrator.ts"],"names":[],"mappings":"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"}