MatrixRTC: ToDevice distribution for media stream keys (#4785)

* MatrixRTC: ToDevice distribution for media stream keys

* test: Add RTC to device transport test

* lint

* fix key indexing

* fix indexing take two
 - use correct value for: `onEncryptionKeysChanged`
 - only update `latestGeneratedKeyIndex` for "this user" key

* test: add test for join config `useExperimentalToDeviceTransport`

* update test to fail without the fixed encryption key index

* review

* review (dave)

---------

Co-authored-by: Timo <toger5@hotmail.de>

spec/unit/matrixrtc/MatrixRTCSession.spec.ts

@@ -486,14 +486,17 @@ describe("MatrixRTCSession", () => {
             let sendStateEventMock: jest.Mock;
             let sendDelayedStateMock: jest.Mock;
             let sendEventMock: jest.Mock;
+            let sendToDeviceMock: jest.Mock;
 
             beforeEach(() => {
                 sendStateEventMock = jest.fn();
                 sendDelayedStateMock = jest.fn();
                 sendEventMock = jest.fn();
+                sendToDeviceMock = jest.fn();
                 client.sendStateEvent = sendStateEventMock;
                 client._unstable_sendDelayedStateEvent = sendDelayedStateMock;
                 client.sendEvent = sendEventMock;
+                client.encryptAndSendToDevice = sendToDeviceMock;
 
                 mockRoom = makeMockRoom([]);
                 sess = MatrixRTCSession.roomSessionForRoom(client, mockRoom);
@@ -832,6 +835,7 @@ describe("MatrixRTCSession", () => {
             it("rotates key if a member leaves", async () => {
                 jest.useFakeTimers();
                 try {
+                    const KEY_DELAY = 3000;
                     const member2 = Object.assign({}, membershipTemplate, {
                         device_id: "BBBBBBB",
                     });
@@ -852,7 +856,8 @@ describe("MatrixRTCSession", () => {
                         sendEventMock.mockImplementation((_roomId, _evType, payload) => resolve(payload));
                     });
 
-                    sess.joinRoomSession([mockFocus], mockFocus, { manageMediaKeys: true });
+                    sess.joinRoomSession([mockFocus], mockFocus, { manageMediaKeys: true, makeKeyDelay: KEY_DELAY });
+                    const sendKeySpy = jest.spyOn((sess as unknown as any).encryptionManager.transport, "sendKey");
                     const firstKeysPayload = await keysSentPromise1;
                     expect(firstKeysPayload.keys).toHaveLength(1);
                     expect(firstKeysPayload.keys[0].index).toEqual(0);
@@ -869,14 +874,24 @@ describe("MatrixRTCSession", () => {
                         .mockReturnValue(makeMockRoomState([membershipTemplate], mockRoom.roomId));
                     sess.onRTCSessionMemberUpdate();
 
-                    jest.advanceTimersByTime(10000);
+                    jest.advanceTimersByTime(KEY_DELAY);
+                    expect(sendKeySpy).toHaveBeenCalledTimes(1);
+                    // check that we send the key with index 1 even though the send gets delayed when leaving.
+                    // this makes sure we do not use an index that is one too old.
+                    expect(sendKeySpy).toHaveBeenLastCalledWith(expect.any(String), 1, sess.memberships);
+                    // fake a condition in which we send another encryption key event.
+                    // this could happen do to someone joining the call.
+                    (sess as unknown as any).encryptionManager.sendEncryptionKeysEvent();
+                    expect(sendKeySpy).toHaveBeenLastCalledWith(expect.any(String), 1, sess.memberships);
+                    jest.advanceTimersByTime(7000);
 
                     const secondKeysPayload = await keysSentPromise2;
 
                     expect(secondKeysPayload.keys).toHaveLength(1);
                     expect(secondKeysPayload.keys[0].index).toEqual(1);
                     expect(onMyEncryptionKeyChanged).toHaveBeenCalledTimes(2);
-                    expect(sess!.statistics.counters.roomEventEncryptionKeysSent).toEqual(2);
+                    // initial, on leave and the fake one we do with: `(sess as unknown as any).encryptionManager.sendEncryptionKeysEvent();`
+                    expect(sess!.statistics.counters.roomEventEncryptionKeysSent).toEqual(3);
                 } finally {
                     jest.useRealTimers();
                 }
@@ -965,6 +980,29 @@ describe("MatrixRTCSession", () => {
                     jest.useRealTimers();
                 }
             });
+
+            it("send key as to device", async () => {
+                jest.useFakeTimers();
+                try {
+                    const keySentPromise = new Promise((resolve) => {
+                        sendToDeviceMock.mockImplementation(resolve);
+                    });
+
+                    const mockRoom = makeMockRoom([membershipTemplate]);
+                    sess = MatrixRTCSession.roomSessionForRoom(client, mockRoom);
+
+                    sess!.joinRoomSession([mockFocus], mockFocus, {
+                        manageMediaKeys: true,
+                        useExperimentalToDeviceTransport: true,
+                    });
+
+                    await keySentPromise;
+
+                    expect(sendToDeviceMock).toHaveBeenCalled();
+                } finally {
+                    jest.useRealTimers();
+                }
+            });
         });
 
         describe("receiving", () => {

spec/unit/matrixrtc/RoomKeyTransport.spec.ts

@@ -20,7 +20,7 @@ import { KeyTransportEvents } from "../../../src/matrixrtc/IKeyTransport";
 import { EventType, MatrixClient, RoomEvent } from "../../../src";
 import type { IRoomTimelineData, MatrixEvent, Room } from "../../../src";
 
-describe("RoomKyTransport", () => {
+describe("RoomKeyTransport", () => {
     let client: MatrixClient;
     let room: Room & {
         emitTimelineEvent: (event: MatrixEvent) => void;

spec/unit/matrixrtc/ToDeviceKeyTransport.spec.ts

@@ -0,0 +1,249 @@
+/*
+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 { makeMockEvent, membershipTemplate, mockCallMembership } from "./mocks";
+import { ClientEvent, EventType, type MatrixClient } from "../../../src";
+import { ToDeviceKeyTransport } from "../../../src/matrixrtc/ToDeviceKeyTransport.ts";
+import { getMockClientWithEventEmitter } from "../../test-utils/client.ts";
+import { type Statistics } from "../../../src/matrixrtc";
+import { KeyTransportEvents } from "../../../src/matrixrtc/IKeyTransport.ts";
+import { defer } from "../../../src/utils.ts";
+import { type Logger } from "../../../src/logger.ts";
+
+describe("ToDeviceKeyTransport", () => {
+    const roomId = "!room:id";
+
+    let mockClient: Mocked<MatrixClient>;
+    let statistics: Statistics;
+    let mockLogger: Mocked<Logger>;
+    let transport: ToDeviceKeyTransport;
+
+    beforeEach(() => {
+        mockClient = getMockClientWithEventEmitter({
+            encryptAndSendToDevice: jest.fn(),
+        });
+        mockLogger = {
+            debug: jest.fn(),
+            warn: jest.fn(),
+        } as unknown as Mocked<Logger>;
+        statistics = {
+            counters: {
+                roomEventEncryptionKeysSent: 0,
+                roomEventEncryptionKeysReceived: 0,
+            },
+            totals: {
+                roomEventEncryptionKeysReceivedTotalAge: 0,
+            },
+        };
+
+        transport = new ToDeviceKeyTransport("@alice:example.org", "MYDEVICE", roomId, mockClient, statistics, {
+            getChild: jest.fn().mockReturnValue(mockLogger),
+        } as unknown as Mocked<Logger>);
+    });
+
+    it("should send my keys on via to device", async () => {
+        transport.start();
+
+        const keyBase64Encoded = "ABCDEDF";
+        const keyIndex = 2;
+        await transport.sendKey(keyBase64Encoded, keyIndex, [
+            mockCallMembership(
+                Object.assign({}, membershipTemplate, { device_id: "BOBDEVICE" }),
+                roomId,
+                "@bob:example.org",
+            ),
+            mockCallMembership(
+                Object.assign({}, membershipTemplate, { device_id: "CARLDEVICE" }),
+                roomId,
+                "@carl:example.org",
+            ),
+            mockCallMembership(
+                Object.assign({}, membershipTemplate, { device_id: "MATDEVICE" }),
+                roomId,
+                "@mat:example.org",
+            ),
+        ]);
+
+        expect(mockClient.encryptAndSendToDevice).toHaveBeenCalledTimes(1);
+        expect(mockClient.encryptAndSendToDevice).toHaveBeenCalledWith(
+            "io.element.call.encryption_keys",
+            [
+                { userId: "@bob:example.org", deviceId: "BOBDEVICE" },
+                { userId: "@carl:example.org", deviceId: "CARLDEVICE" },
+                { userId: "@mat:example.org", deviceId: "MATDEVICE" },
+            ],
+            {
+                keys: {
+                    index: keyIndex,
+                    key: keyBase64Encoded,
+                },
+                member: {
+                    claimed_device_id: "MYDEVICE",
+                },
+                room_id: roomId,
+                session: {
+                    application: "m.call",
+                    call_id: "",
+                    scope: "m.room",
+                },
+            },
+        );
+
+        expect(statistics.counters.roomEventEncryptionKeysSent).toBe(1);
+    });
+
+    it("should emit when a key is received", async () => {
+        const deferred = defer<{ userId: string; deviceId: string; keyBase64Encoded: string; index: number }>();
+        transport.on(KeyTransportEvents.ReceivedKeys, (userId, deviceId, keyBase64Encoded, index, timestamp) => {
+            deferred.resolve({ userId, deviceId, keyBase64Encoded, index });
+        });
+        transport.start();
+
+        const testEncoded = "ABCDEDF";
+        const testKeyIndex = 2;
+
+        mockClient.emit(
+            ClientEvent.ToDeviceEvent,
+            makeMockEvent(EventType.CallEncryptionKeysPrefix, "@bob:example.org", undefined, {
+                keys: {
+                    index: testKeyIndex,
+                    key: testEncoded,
+                },
+                member: {
+                    claimed_device_id: "BOBDEVICE",
+                },
+                room_id: roomId,
+                session: {
+                    application: "m.call",
+                    call_id: "",
+                    scope: "m.room",
+                },
+            }),
+        );
+
+        const { userId, deviceId, keyBase64Encoded, index } = await deferred.promise;
+        expect(userId).toBe("@bob:example.org");
+        expect(deviceId).toBe("BOBDEVICE");
+        expect(keyBase64Encoded).toBe(testEncoded);
+        expect(index).toBe(testKeyIndex);
+
+        expect(statistics.counters.roomEventEncryptionKeysReceived).toBe(1);
+    });
+
+    it("should not sent to ourself", async () => {
+        const keyBase64Encoded = "ABCDEDF";
+        const keyIndex = 2;
+        await transport.sendKey(keyBase64Encoded, keyIndex, [
+            mockCallMembership(
+                Object.assign({}, membershipTemplate, { device_id: "MYDEVICE" }),
+                roomId,
+                "@alice:example.org",
+            ),
+        ]);
+
+        transport.start();
+
+        expect(mockClient.encryptAndSendToDevice).toHaveBeenCalledTimes(0);
+    });
+
+    it("should warn when there is a room mismatch", () => {
+        transport.start();
+
+        const testEncoded = "ABCDEDF";
+        const testKeyIndex = 2;
+
+        mockClient.emit(
+            ClientEvent.ToDeviceEvent,
+            makeMockEvent(EventType.CallEncryptionKeysPrefix, "@bob:example.org", undefined, {
+                keys: {
+                    index: testKeyIndex,
+                    key: testEncoded,
+                },
+                member: {
+                    claimed_device_id: "BOBDEVICE",
+                },
+                room_id: "!anotherroom:id",
+                session: {
+                    application: "m.call",
+                    call_id: "",
+                    scope: "m.room",
+                },
+            }),
+        );
+
+        expect(mockLogger.warn).toHaveBeenCalledWith("Malformed Event: Mismatch roomId");
+        expect(statistics.counters.roomEventEncryptionKeysReceived).toBe(0);
+    });
+
+    describe("malformed events", () => {
+        const MALFORMED_EVENT = [
+            {
+                keys: {},
+                member: { claimed_device_id: "MYDEVICE" },
+                room_id: "!room:id",
+                session: { application: "m.call", call_id: "", scope: "m.room" },
+            },
+            {
+                keys: { index: 0 },
+                member: { claimed_device_id: "MYDEVICE" },
+                room_id: "!room:id",
+                session: { application: "m.call", call_id: "", scope: "m.room" },
+            },
+            {
+                keys: { keys: "ABCDEF" },
+                member: { claimed_device_id: "MYDEVICE" },
+                room_id: "!room:id",
+                session: { application: "m.call", call_id: "", scope: "m.room" },
+            },
+            {
+                keys: { keys: "ABCDEF", index: 2 },
+                room_id: "!room:id",
+                session: { application: "m.call", call_id: "", scope: "m.room" },
+            },
+            {
+                keys: { keys: "ABCDEF", index: 2 },
+                member: {},
+                room_id: "!room:id",
+                session: { application: "m.call", call_id: "", scope: "m.room" },
+            },
+            {
+                keys: { keys: "ABCDEF", index: 2 },
+                member: { claimed_device_id: "MYDEVICE" },
+                session: { application: "m.call", call_id: "", scope: "m.room" },
+            },
+            {
+                keys: { keys: "ABCDEF", index: 2 },
+                member: { claimed_device_id: "MYDEVICE" },
+                room_id: "!room:id",
+                session: { application: "m.call", call_id: "", scope: "m.room" },
+            },
+        ];
+
+        test.each(MALFORMED_EVENT)("should warn on malformed event %j", (event) => {
+            transport.start();
+
+            mockClient.emit(
+                ClientEvent.ToDeviceEvent,
+                makeMockEvent(EventType.CallEncryptionKeysPrefix, "@bob:example.org", undefined, event),
+            );
+
+            expect(mockLogger.warn).toHaveBeenCalled();
+            expect(statistics.counters.roomEventEncryptionKeysReceived).toBe(0);
+        });
+    });
+});

spec/unit/matrixrtc/mocks.ts

@@ -123,7 +123,7 @@ export function makeMockRoomState(membershipData: MembershipData, roomId: string
 export function makeMockEvent(
     type: string,
     sender: string,
-    roomId: string,
+    roomId: string | undefined,
     content: any,
     timestamp?: number,
 ): MatrixEvent {