MatrixRTC: Add combined toDeviceAndRoomKeyTransport (#4792)

* Add to-device and room transport

* Lint

* add doc string

* hook up automatic toDeviceKeyTransport -> roomKeyTransport switching

* lint, rename, imports

* fix logging

* fix test logger

* use mockLogger better in tests

* improve logging and reduce `EnabledTransportsChanged` emission.

* fix this binding

* lint

* simplify `onTransportChanged` callback

* refactor to construct the transports outside the RoomAndToDeviceKeyTransport

* update tests to use new RoomAndToDeiviceTransport constructor

* add depractaion comments

spec/unit/matrixrtc/RoomAndToDeviceTransport.spec.ts

@@ -0,0 +1,146 @@
+/*
+Copyright 2025 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { type Mocked } from "jest-mock";
+
+import { makeKey, makeMockEvent, makeMockRoom, membershipTemplate, mockCallMembership } from "./mocks";
+import { EventType, type IRoomTimelineData, type Room, RoomEvent, type MatrixClient } from "../../../src";
+import { ToDeviceKeyTransport } from "../../../src/matrixrtc/ToDeviceKeyTransport.ts";
+import {
+    getMockClientWithEventEmitter,
+    mockClientMethodsEvents,
+    mockClientMethodsUser,
+} from "../../test-utils/client.ts";
+import { type Statistics } from "../../../src/matrixrtc";
+import { KeyTransportEvents } from "../../../src/matrixrtc/IKeyTransport.ts";
+import { type Logger } from "../../../src/logger.ts";
+import { RoomAndToDeviceEvents, RoomAndToDeviceTransport } from "../../../src/matrixrtc/RoomAndToDeviceKeyTransport.ts";
+import { RoomKeyTransport } from "../../../src/matrixrtc/RoomKeyTransport.ts";
+
+describe("RoomAndToDeviceTransport", () => {
+    const roomId = "!room:id";
+
+    let mockClient: Mocked<MatrixClient>;
+    let statistics: Statistics;
+    let mockLogger: Mocked<Logger>;
+    let transport: RoomAndToDeviceTransport;
+    let mockRoom: Room;
+    let sendEventMock: jest.Mock;
+    let roomKeyTransport: RoomKeyTransport;
+    let toDeviceKeyTransport: ToDeviceKeyTransport;
+    let toDeviceSendKeySpy: jest.SpyInstance;
+    let roomSendKeySpy: jest.SpyInstance;
+    beforeEach(() => {
+        sendEventMock = jest.fn();
+        mockClient = getMockClientWithEventEmitter({
+            encryptAndSendToDevice: jest.fn(),
+            getDeviceId: jest.fn().mockReturnValue("MYDEVICE"),
+            ...mockClientMethodsEvents(),
+            ...mockClientMethodsUser("@alice:example.org"),
+            sendEvent: sendEventMock,
+        });
+        mockRoom = makeMockRoom([]);
+        mockLogger = {
+            debug: jest.fn(),
+            warn: jest.fn(),
+            getChild: jest.fn(),
+        } as unknown as Mocked<Logger>;
+        mockLogger.getChild.mockReturnValue(mockLogger);
+        statistics = {
+            counters: {
+                roomEventEncryptionKeysSent: 0,
+                roomEventEncryptionKeysReceived: 0,
+            },
+            totals: {
+                roomEventEncryptionKeysReceivedTotalAge: 0,
+            },
+        };
+        roomKeyTransport = new RoomKeyTransport(mockRoom, mockClient, statistics);
+        toDeviceKeyTransport = new ToDeviceKeyTransport(
+            "@alice:example.org",
+            "MYDEVICE",
+            mockRoom.roomId,
+            mockClient,
+            statistics,
+        );
+        transport = new RoomAndToDeviceTransport(toDeviceKeyTransport, roomKeyTransport, mockLogger);
+        toDeviceSendKeySpy = jest.spyOn(toDeviceKeyTransport, "sendKey");
+        roomSendKeySpy = jest.spyOn(roomKeyTransport, "sendKey");
+    });
+
+    it("should enable to device transport when starting", () => {
+        transport.start();
+        expect(transport.enabled.room).toBeFalsy();
+        expect(transport.enabled.toDevice).toBeTruthy();
+    });
+    it("only sends to device keys when sending a key", async () => {
+        transport.start();
+        await transport.sendKey("1235", 0, [mockCallMembership(membershipTemplate, roomId, "@alice:example.org")]);
+        expect(toDeviceSendKeySpy).toHaveBeenCalledTimes(1);
+        expect(roomSendKeySpy).toHaveBeenCalledTimes(0);
+        expect(transport.enabled.room).toBeFalsy();
+        expect(transport.enabled.toDevice).toBeTruthy();
+    });
+
+    it("enables room transport and disables to device transport when receiving a room key", async () => {
+        transport.start();
+        const onNewKeyFromTransport = jest.fn();
+        const onTransportEnabled = jest.fn();
+        transport.on(KeyTransportEvents.ReceivedKeys, onNewKeyFromTransport);
+        transport.on(RoomAndToDeviceEvents.EnabledTransportsChanged, onTransportEnabled);
+        mockRoom.emit(
+            RoomEvent.Timeline,
+            makeMockEvent(EventType.CallEncryptionKeysPrefix, "@bob:example.org", roomId, {
+                call_id: "",
+                keys: [makeKey(0, "testKey")],
+                sent_ts: Date.now(),
+                device_id: "AAAAAAA",
+            }),
+            undefined,
+            undefined,
+            false,
+            {} as IRoomTimelineData,
+        );
+        await jest.advanceTimersByTimeAsync(1);
+        expect(transport.enabled.room).toBeTruthy();
+        expect(transport.enabled.toDevice).toBeFalsy();
+
+        await transport.sendKey("1235", 0, [mockCallMembership(membershipTemplate, roomId, "@alice:example.org")]);
+        expect(sendEventMock).toHaveBeenCalledTimes(1);
+        expect(roomSendKeySpy).toHaveBeenCalledTimes(1);
+        expect(toDeviceSendKeySpy).toHaveBeenCalledTimes(0);
+        expect(onTransportEnabled).toHaveBeenCalledWith({ toDevice: false, room: true });
+    });
+    it("does log that it did nothing when disabled", () => {
+        transport.start();
+        const onNewKeyFromTransport = jest.fn();
+        const onTransportEnabled = jest.fn();
+        transport.on(KeyTransportEvents.ReceivedKeys, onNewKeyFromTransport);
+        transport.on(RoomAndToDeviceEvents.EnabledTransportsChanged, onTransportEnabled);
+
+        transport.setEnabled({ toDevice: false, room: false });
+        const dateNow = Date.now();
+        roomKeyTransport.emit(KeyTransportEvents.ReceivedKeys, "user", "device", "roomKey", 0, dateNow);
+        toDeviceKeyTransport.emit(KeyTransportEvents.ReceivedKeys, "user", "device", "toDeviceKey", 0, Date.now());
+
+        expect(mockLogger.debug).toHaveBeenCalledWith("To Device transport is disabled, ignoring received keys");
+        // for room key transport we will never get a disabled message because its will always just turn on
+        expect(onTransportEnabled).toHaveBeenNthCalledWith(1, { toDevice: false, room: false });
+        expect(onTransportEnabled).toHaveBeenNthCalledWith(2, { toDevice: false, room: true });
+        expect(onNewKeyFromTransport).toHaveBeenCalledTimes(1);
+        expect(onNewKeyFromTransport).toHaveBeenCalledWith("user", "device", "roomKey", 0, dateNow);
+    });
+});

src/matrixrtc/EncryptionManager.ts

@@ -6,6 +6,11 @@ import { safeGetRetryAfterMs } from "../http-api/errors.ts";
 import { type CallMembership } from "./CallMembership.ts";
 import { type KeyTransportEventListener, KeyTransportEvents, type IKeyTransport } from "./IKeyTransport.ts";
 import { isMyMembership, type Statistics } from "./types.ts";
+import {
+    type EnabledTransports,
+    RoomAndToDeviceEvents,
+    RoomAndToDeviceTransport,
+} from "./RoomAndToDeviceKeyTransport.ts";
 
 /**
  * This interface is for testing and for making it possible to interchange the encryption manager.
@@ -105,6 +110,10 @@ export class EncryptionManager implements IEncryptionManager {
         this.manageMediaKeys = this.joinConfig?.manageMediaKeys ?? this.manageMediaKeys;
 
         this.transport.on(KeyTransportEvents.ReceivedKeys, this.onNewKeyReceived);
+        // Deprecate RoomKeyTransport: this can get removed.
+        if (this.transport instanceof RoomAndToDeviceTransport) {
+            this.transport.on(RoomAndToDeviceEvents.EnabledTransportsChanged, this.onTransportChanged);
+        }
         this.transport.start();
         if (this.joinConfig?.manageMediaKeys) {
             this.makeNewSenderKey();
@@ -287,6 +296,10 @@ export class EncryptionManager implements IEncryptionManager {
         }
     };
 
+    private onTransportChanged: (enabled: EnabledTransports) => void = () => {
+        this.requestSendCurrentKey();
+    };
+
     public onNewKeyReceived: KeyTransportEventListener = (userId, deviceId, keyBase64Encoded, index, timestamp) => {
         this.logger.debug(`Received key over key transport ${userId}:${deviceId} at index ${index}`);
         this.setEncryptionKey(userId, deviceId, index, keyBase64Encoded, timestamp);

src/matrixrtc/IKeyTransport.ts

@@ -20,6 +20,10 @@ export enum KeyTransportEvents {
     ReceivedKeys = "received_keys",
 }
 
+export type KeyTransportEventsHandlerMap = {
+    [KeyTransportEvents.ReceivedKeys]: KeyTransportEventListener;
+};
+
 export type KeyTransportEventListener = (
     userId: string,
     deviceId: string,
@@ -28,10 +32,6 @@ export type KeyTransportEventListener = (
     timestamp: number,
 ) => void;
 
-export type KeyTransportEventsHandlerMap = {
-    [KeyTransportEvents.ReceivedKeys]: KeyTransportEventListener;
-};
-
 /**
  * Generic interface for the transport used to share room keys.
  * Keys can be shared using different transports, e.g. to-device messages or room messages.

src/matrixrtc/MatrixRTCSession.ts

@@ -28,10 +28,16 @@ import { MembershipManager } from "./NewMembershipManager.ts";
 import { EncryptionManager, type IEncryptionManager } from "./EncryptionManager.ts";
 import { LegacyMembershipManager } from "./LegacyMembershipManager.ts";
 import { logDurationSync } from "../utils.ts";
-import { ToDeviceKeyTransport } from "./ToDeviceKeyTransport.ts";
 import { type Statistics } from "./types.ts";
 import { RoomKeyTransport } from "./RoomKeyTransport.ts";
 import type { IMembershipManager } from "./IMembershipManager.ts";
+import {
+    RoomAndToDeviceEvents,
+    type RoomAndToDeviceEventsHandlerMap,
+    RoomAndToDeviceTransport,
+} from "./RoomAndToDeviceKeyTransport.ts";
+import { TypedReEmitter } from "../ReEmitter.ts";
+import { ToDeviceKeyTransport } from "./ToDeviceKeyTransport.ts";
 
 export enum MatrixRTCSessionEvent {
     // A member joined, left, or updated a property of their membership.
@@ -162,7 +168,10 @@ export type JoinSessionConfig = MembershipConfig & EncryptionConfig;
  * A MatrixRTCSession manages the membership & properties of a MatrixRTC session.
  * This class doesn't deal with media at all, just membership & properties of a session.
  */
-export class MatrixRTCSession extends TypedEventEmitter<MatrixRTCSessionEvent, MatrixRTCSessionEventHandlerMap> {
+export class MatrixRTCSession extends TypedEventEmitter<
+    MatrixRTCSessionEvent | RoomAndToDeviceEvents,
+    MatrixRTCSessionEventHandlerMap & RoomAndToDeviceEventsHandlerMap
+> {
     private membershipManager?: IMembershipManager;
     private encryptionManager?: IEncryptionManager;
     // The session Id of the call, this is the call_id of the call Member event.
@@ -348,6 +357,10 @@ export class MatrixRTCSession extends TypedEventEmitter<MatrixRTCSessionEvent, M
         const roomState = this.roomSubset.getLiveTimeline().getState(EventTimeline.FORWARDS);
         roomState?.off(RoomStateEvent.Members, this.onRoomMemberUpdate);
     }
+    private reEmitter = new TypedReEmitter<
+        MatrixRTCSessionEvent | RoomAndToDeviceEvents,
+        MatrixRTCSessionEventHandlerMap & RoomAndToDeviceEventsHandlerMap
+    >(this);
 
     /**
      * Announces this user and device as joined to the MatrixRTC session,
@@ -385,15 +398,16 @@ export class MatrixRTCSession extends TypedEventEmitter<MatrixRTCSessionEvent, M
             // Create Encryption manager
             let transport;
             if (joinConfig?.useExperimentalToDeviceTransport) {
-                this.logger.info("Using experimental to-device transport for encryption keys");
-                transport = new ToDeviceKeyTransport(
-                    this.client.getUserId()!,
-                    this.client.getDeviceId()!,
-                    this.roomSubset.roomId,
-                    this.client,
-                    this.statistics,
-                    this.logger,
-                );
+                this.logger.info("Using to-device with room fallback transport for encryption keys");
+                const [uId, dId] = [this.client.getUserId()!, this.client.getDeviceId()!];
+                const [room, client, statistics] = [this.roomSubset, this.client, this.statistics];
+                // Deprecate RoomKeyTransport: only ToDeviceKeyTransport is needed once deprecated
+                const roomKeyTransport = new RoomKeyTransport(room, client, statistics);
+                const toDeviceTransport = new ToDeviceKeyTransport(uId, dId, room.roomId, client, statistics);
+                transport = new RoomAndToDeviceTransport(toDeviceTransport, roomKeyTransport, this.logger);
+
+                // Expose the changes so the ui can display the currently used transport.
+                this.reEmitter.reEmit(transport, [RoomAndToDeviceEvents.EnabledTransportsChanged]);
             } else {
                 transport = new RoomKeyTransport(this.roomSubset, this.client, this.statistics);
             }

src/matrixrtc/RoomAndToDeviceKeyTransport.ts

@@ -0,0 +1,119 @@
+/*
+Copyright 2025 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { logger as rootLogger, type Logger } from "../logger.ts";
+import { KeyTransportEvents, type KeyTransportEventsHandlerMap, type IKeyTransport } from "./IKeyTransport.ts";
+import { type CallMembership } from "./CallMembership.ts";
+import type { RoomKeyTransport } from "./RoomKeyTransport.ts";
+import type { ToDeviceKeyTransport } from "./ToDeviceKeyTransport.ts";
+import { TypedEventEmitter } from "../models/typed-event-emitter.ts";
+
+// Deprecate RoomAndToDeviceTransport: This whole class is only a stop gap until we remove RoomKeyTransport.
+export interface EnabledTransports {
+    toDevice: boolean;
+    room: boolean;
+}
+
+export enum RoomAndToDeviceEvents {
+    EnabledTransportsChanged = "enabled_transports_changed",
+}
+export type RoomAndToDeviceEventsHandlerMap = {
+    [RoomAndToDeviceEvents.EnabledTransportsChanged]: (enabledTransports: EnabledTransports) => void;
+};
+/**
+ * A custom transport that subscribes to room key events (via `RoomKeyTransport`) and to device key events (via: `ToDeviceKeyTransport`)
+ * The public setEnabled method allows to turn one or the other on or off on the fly.
+ * It will emit `RoomAndToDeviceEvents.EnabledTransportsChanged` if the enabled transport changes to allow comminitcating this to
+ * the user in the ui.
+ *
+ * Since it will always subscribe to both (room and to device) but only emit for the enabled ones, it can detect
+ * if a room key event was received and autoenable it.
+ */
+export class RoomAndToDeviceTransport
+    extends TypedEventEmitter<
+        KeyTransportEvents | RoomAndToDeviceEvents,
+        KeyTransportEventsHandlerMap & RoomAndToDeviceEventsHandlerMap
+    >
+    implements IKeyTransport
+{
+    private readonly logger: Logger;
+    private _enabled: EnabledTransports = { toDevice: true, room: false };
+    public constructor(
+        private toDeviceTransport: ToDeviceKeyTransport,
+        private roomKeyTransport: RoomKeyTransport,
+        parentLogger?: Logger,
+    ) {
+        super();
+        this.logger = (parentLogger ?? rootLogger).getChild(`[RoomAndToDeviceTransport]`);
+        // update parent loggers for the sub transports so filtering for `RoomAndToDeviceTransport` contains their logs too
+        this.toDeviceTransport.setParentLogger(this.logger);
+        this.roomKeyTransport.setParentLogger(this.logger);
+
+        this.roomKeyTransport.on(KeyTransportEvents.ReceivedKeys, (...props) => {
+            // Turn on the room transport if we receive a roomKey from another participant
+            // and disable the toDevice transport.
+            if (!this._enabled.room) {
+                this.logger.debug("Received room key, enabling room key transport, disabling toDevice transport");
+                this.setEnabled({ toDevice: false, room: true });
+            }
+            this.emit(KeyTransportEvents.ReceivedKeys, ...props);
+        });
+        this.toDeviceTransport.on(KeyTransportEvents.ReceivedKeys, (...props) => {
+            if (this._enabled.toDevice) {
+                this.emit(KeyTransportEvents.ReceivedKeys, ...props);
+            } else {
+                this.logger.debug("To Device transport is disabled, ignoring received keys");
+            }
+        });
+    }
+
+    /** Set which transport type should be used to send and receive keys.*/
+    public setEnabled(enabled: { toDevice: boolean; room: boolean }): void {
+        if (this.enabled.toDevice !== enabled.toDevice || this.enabled.room !== enabled.room) {
+            this._enabled = enabled;
+            this.emit(RoomAndToDeviceEvents.EnabledTransportsChanged, enabled);
+        }
+    }
+
+    /** The currently enabled transports that are used to send and receive keys.*/
+    public get enabled(): EnabledTransports {
+        return this._enabled;
+    }
+
+    public start(): void {
+        // always start the underlying transport since we need to enable room transport
+        // when someone else sends us a room key. (we need to listen to roomKeyTransport)
+        this.roomKeyTransport.start();
+        this.toDeviceTransport.start();
+    }
+
+    public stop(): void {
+        // always stop since it is always running
+        this.roomKeyTransport.stop();
+        this.toDeviceTransport.stop();
+    }
+
+    public async sendKey(keyBase64Encoded: string, index: number, members: CallMembership[]): Promise<void> {
+        this.logger.debug(
+            `Sending key with index ${index} to call members (count=${members.length}) via:` +
+                (this._enabled.room ? "room transport" : "") +
+                (this._enabled.room && this._enabled.toDevice ? "and" : "") +
+                (this._enabled.toDevice ? "to device transport" : ""),
+        );
+        if (this._enabled.room) await this.roomKeyTransport.sendKey(keyBase64Encoded, index, members);
+        if (this._enabled.toDevice) await this.toDeviceTransport.sendKey(keyBase64Encoded, index, members);
+    }
+}

src/matrixrtc/RoomKeyTransport.ts

@@ -29,8 +29,10 @@ export class RoomKeyTransport
     extends TypedEventEmitter<KeyTransportEvents, KeyTransportEventsHandlerMap>
     implements IKeyTransport
 {
-    private readonly logger: Logger;
-
+    private logger: Logger = rootLogger;
+    public setParentLogger(parentLogger: Logger): void {
+        this.logger = parentLogger.getChild(`[RoomKeyTransport]`);
+    }
     public constructor(
         private room: Pick<Room, "on" | "off" | "roomId">,
         private client: Pick<
@@ -41,7 +43,7 @@ export class RoomKeyTransport
         parentLogger?: Logger,
     ) {
         super();
-        this.logger = (parentLogger ?? rootLogger).getChild(`[RoomKeyTransport]`);
+        this.setParentLogger(parentLogger ?? rootLogger);
     }
     public start(): void {
         this.room.on(RoomEvent.Timeline, (ev) => void this.consumeCallEncryptionEvent(ev));

src/matrixrtc/ToDeviceKeyTransport.ts

@@ -31,7 +31,10 @@ export class ToDeviceKeyTransport
     extends TypedEventEmitter<KeyTransportEvents, KeyTransportEventsHandlerMap>
     implements IKeyTransport
 {
-    private readonly logger: Logger;
+    private logger: Logger = rootLogger;
+    public setParentLogger(parentLogger: Logger): void {
+        this.logger = parentLogger.getChild(`[ToDeviceKeyTransport]`);
+    }
 
     public constructor(
         private userId: string,
@@ -42,7 +45,7 @@ export class ToDeviceKeyTransport
         parentLogger?: Logger,
     ) {
         super();
-        this.logger = (parentLogger ?? rootLogger).getChild(`[ToDeviceKeyTransport]`);
+        this.setParentLogger(parentLogger ?? rootLogger);
     }
 
     public start(): void {