Add restoreKeybackup to CryptoApi.

spec/integ/crypto/megolm-backup.spec.ts

@@ -117,8 +117,10 @@ function mockUploadEmitter(
 describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backend: string, initCrypto: InitCrypto) => {
     // oldBackendOnly is an alternative to `it` or `test` which will skip the test if we are running against the
     // Rust backend. Once we have full support in the rust sdk, it will go away.
-    // const oldBackendOnly = backend === "rust-sdk" ? test.skip : test;
-    // const newBackendOnly = backend === "libolm" ? test.skip : test;
+    const oldBackendOnly = backend === "rust-sdk" ? test.skip : test;
+    const newBackendOnly = backend === "libolm" ? test.skip : test;
+
+    const isNewBackend = backend === "rust-sdk";
 
     let aliceClient: MatrixClient;
     /** an object which intercepts `/sync` requests on the test homeserver */
@@ -247,9 +249,9 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
             // On the first decryption attempt, decryption fails.
             await awaitDecryption(event);
             expect(event.decryptionFailureReason).toEqual(
-                backend === "libolm"
-                    ? DecryptionFailureCode.MEGOLM_UNKNOWN_INBOUND_SESSION_ID
-                    : DecryptionFailureCode.HISTORICAL_MESSAGE_WORKING_BACKUP,
+                isNewBackend
+                    ? DecryptionFailureCode.HISTORICAL_MESSAGE_WORKING_BACKUP
+                    : DecryptionFailureCode.MEGOLM_UNKNOWN_INBOUND_SESSION_ID,
             );
 
             // Eventually, decryption succeeds.
@@ -345,24 +347,28 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
             });
 
             const result = await advanceTimersUntil(
-                aliceClient.restoreKeyBackupWithRecoveryKey(
-                    testData.BACKUP_DECRYPTION_KEY_BASE58,
-                    undefined,
-                    undefined,
-                    check!.backupInfo!,
-                    {
-                        cacheCompleteCallback: () => onKeyCached(),
-                    },
-                ),
+                isNewBackend
+                    ? aliceCrypto.restoreKeyBackup(testData.BACKUP_DECRYPTION_KEY_BASE58)
+                    : aliceClient.restoreKeyBackupWithRecoveryKey(
+                          testData.BACKUP_DECRYPTION_KEY_BASE58,
+                          undefined,
+                          undefined,
+                          check!.backupInfo!,
+                          {
+                              cacheCompleteCallback: () => onKeyCached(),
+                          },
+                      ),
             );
 
             expect(result.imported).toStrictEqual(1);
 
-            await awaitKeyCached;
+            if (!isNewBackend) await awaitKeyCached;
 
             // The key should be now cached
             const afterCache = await advanceTimersUntil(
-                aliceClient.restoreKeyBackupWithCache(undefined, undefined, check!.backupInfo!),
+                isNewBackend
+                    ? aliceCrypto.restoreKeyBackup(undefined)
+                    : aliceClient.restoreKeyBackupWithCache(undefined, undefined, check!.backupInfo!),
             );
 
             expect(afterCache.imported).toStrictEqual(1);
@@ -398,8 +404,13 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
 
         it("Should import full backup in chunks", async function () {
             const importMockImpl = jest.fn();
-            // @ts-ignore - mock a private method for testing purpose
-            aliceCrypto.importBackedUpRoomKeys = importMockImpl;
+            if (isNewBackend) {
+                // @ts-ignore - mock a private method for testing purpose
+                jest.spyOn(aliceCrypto.backupManager, "importBackedUpRoomKeys").mockImplementation(importMockImpl);
+            } else {
+                // @ts-ignore - mock a private method for testing purpose
+                jest.spyOn(aliceCrypto, "importBackedUpRoomKeys").mockImplementation(importMockImpl);
+            }
 
             // We need several rooms with several sessions to test chunking
             const { response, expectedTotal } = createBackupDownloadResponse([45, 300, 345, 12, 130]);
@@ -409,15 +420,19 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
             const check = await aliceCrypto.checkKeyBackupAndEnable();
 
             const progressCallback = jest.fn();
-            const result = await aliceClient.restoreKeyBackupWithRecoveryKey(
-                testData.BACKUP_DECRYPTION_KEY_BASE58,
-                undefined,
-                undefined,
-                check!.backupInfo!,
-                {
-                    progressCallback,
-                },
-            );
+            const result = await (isNewBackend
+                ? aliceCrypto.restoreKeyBackup(testData.BACKUP_DECRYPTION_KEY_BASE58, {
+                      progressCallback,
+                  })
+                : aliceClient.restoreKeyBackupWithRecoveryKey(
+                      testData.BACKUP_DECRYPTION_KEY_BASE58,
+                      undefined,
+                      undefined,
+                      check!.backupInfo!,
+                      {
+                          progressCallback,
+                      },
+                  ));
 
             expect(result.imported).toStrictEqual(expectedTotal);
             // Should be called 5 times: 200*4 plus one chunk with the remaining 32
@@ -451,8 +466,7 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
         });
 
         it("Should continue to process backup if a chunk import fails and report failures", async function () {
-            // @ts-ignore - mock a private method for testing purpose
-            aliceCrypto.importBackedUpRoomKeys = jest
+            const importMockImpl = jest
                 .fn()
                 .mockImplementationOnce(() => {
                     // Fail to import first chunk
@@ -461,22 +475,32 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
                 // Ok for other chunks
                 .mockResolvedValue(undefined);
 
+            if (isNewBackend) {
+                // @ts-ignore - mock a private method for testing purpose
+                jest.spyOn(aliceCrypto.backupManager, "importBackedUpRoomKeys").mockImplementation(importMockImpl);
+            } else {
+                // @ts-ignore - mock a private method for testing purpose
+                jest.spyOn(aliceCrypto, "importBackedUpRoomKeys").mockImplementation(importMockImpl);
+            }
+
             const { response, expectedTotal } = createBackupDownloadResponse([100, 300]);
 
             fetchMock.get("express:/_matrix/client/v3/room_keys/keys", response);
 
             const check = await aliceCrypto.checkKeyBackupAndEnable();
 
             const progressCallback = jest.fn();
-            const result = await aliceClient.restoreKeyBackupWithRecoveryKey(
-                testData.BACKUP_DECRYPTION_KEY_BASE58,
-                undefined,
-                undefined,
-                check!.backupInfo!,
-                {
-                    progressCallback,
-                },
-            );
+            const result = await (isNewBackend
+                ? aliceCrypto.restoreKeyBackup(testData.BACKUP_DECRYPTION_KEY_BASE58, { progressCallback })
+                : aliceClient.restoreKeyBackupWithRecoveryKey(
+                      testData.BACKUP_DECRYPTION_KEY_BASE58,
+                      undefined,
+                      undefined,
+                      check!.backupInfo!,
+                      {
+                          progressCallback,
+                      },
+                  ));
 
             expect(result.total).toStrictEqual(expectedTotal);
             // A chunk failed to import
@@ -528,19 +552,21 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
 
             const check = await aliceCrypto.checkKeyBackupAndEnable();
 
-            const result = await aliceClient.restoreKeyBackupWithRecoveryKey(
-                testData.BACKUP_DECRYPTION_KEY_BASE58,
-                undefined,
-                undefined,
-                check!.backupInfo!,
-            );
+            const result = await (isNewBackend
+                ? aliceCrypto.restoreKeyBackup(testData.BACKUP_DECRYPTION_KEY_BASE58)
+                : aliceClient.restoreKeyBackupWithRecoveryKey(
+                      testData.BACKUP_DECRYPTION_KEY_BASE58,
+                      undefined,
+                      undefined,
+                      check!.backupInfo!,
+                  ));
 
             expect(result.total).toStrictEqual(expectedTotal);
             // A chunk failed to import
             expect(result.imported).toStrictEqual(expectedTotal - decryptionFailureCount);
         });
 
-        it("recover specific session from backup", async function () {
+        oldBackendOnly("recover specific session from backup", async function () {
             fetchMock.get(
                 "express:/_matrix/client/v3/room_keys/keys/:room_id/:session_id",
                 testData.CURVE25519_KEY_BACKUP_DATA,
@@ -576,14 +602,35 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
             const check = await aliceCrypto.checkKeyBackupAndEnable();
 
             await expect(
-                aliceClient.restoreKeyBackupWithRecoveryKey(
-                    "EsTx A7Xn aNFF k3jH zpV3 MQoN LJEg mscC HecF 982L wC77 mYQD",
-                    undefined,
-                    undefined,
-                    check!.backupInfo!,
-                ),
+                isNewBackend
+                    ? aliceCrypto.restoreKeyBackup("EsTx A7Xn aNFF k3jH zpV3 MQoN LJEg mscC HecF 982L wC77 mYQD")
+                    : aliceClient.restoreKeyBackupWithRecoveryKey(
+                          "EsTx A7Xn aNFF k3jH zpV3 MQoN LJEg mscC HecF 982L wC77 mYQD",
+                          undefined,
+                          undefined,
+                          check!.backupInfo!,
+                      ),
             ).rejects.toThrow();
         });
+
+        newBackendOnly("Should restore the backup from the secret storage", async () => {
+            // @ts-ignore - mock a private method for testing purpose
+            jest.spyOn(aliceCrypto.secretStorage, "get").mockResolvedValue(testData.BACKUP_DECRYPTION_KEY_BASE64);
+
+            const fullBackup = {
+                rooms: {
+                    [ROOM_ID]: {
+                        sessions: {
+                            [testData.MEGOLM_SESSION_DATA.session_id]: testData.CURVE25519_KEY_BACKUP_DATA,
+                        },
+                    },
+                },
+            };
+            fetchMock.get("express:/_matrix/client/v3/room_keys/keys", fullBackup);
+
+            const result = await aliceCrypto.restoreKeyBackup(undefined);
+            expect(result.imported).toStrictEqual(1);
+        });
     });
 
     describe("backupLoop", () => {

src/client.ts

@@ -3696,6 +3696,8 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * @param opts - Optional params such as callbacks
      * @returns Status of restoration with `total` and `imported`
      * key counts.
+     *
+     * @deprecated Prefer {@link CryptoApi.restoreKeyBackupWithPassphrase | `CryptoApi.restoreKeyBackupWithPassphrase`}.
      */
     public async restoreKeyBackupWithPassword(
         password: string,
@@ -3741,6 +3743,8 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * @param opts - Optional params such as callbacks
      * @returns Status of restoration with `total` and `imported`
      * key counts.
+     *
+     * @deprecated Prefer {@link CryptoApi.restoreKeyBackup | `CryptoApi.restoreKeyBackup`}.
      */
     public async restoreKeyBackupWithSecretStorage(
         backupInfo: IKeyBackupInfo,
@@ -3778,6 +3782,8 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
 
      * @returns Status of restoration with `total` and `imported`
      * key counts.
+     *
+     * @deprecated Prefer {@link CryptoApi.restoreKeyBackup | `CryptoApi.restoreKeyBackup`}.
      */
     public restoreKeyBackupWithRecoveryKey(
         recoveryKey: string,
@@ -3811,6 +3817,15 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
         return this.restoreKeyBackup(privKey, targetRoomId!, targetSessionId!, backupInfo, opts);
     }
 
+    /**
+     * Restore from an existing key backup via a private key stored locally
+     * @param targetRoomId
+     * @param targetSessionId
+     * @param backupInfo
+     * @param opts
+     *
+     * @deprecated Prefer {@link CryptoApi.restoreKeyBackup | `CryptoApi.restoreKeyBackup`}.
+     */
     public async restoreKeyBackupWithCache(
         targetRoomId: undefined,
         targetSessionId: undefined,

src/crypto-api/index.ts

@@ -22,7 +22,13 @@ import { DeviceMap } from "../models/device.ts";
 import { UIAuthCallback } from "../interactive-auth.ts";
 import { PassphraseInfo, SecretStorageCallbacks, SecretStorageKeyDescription } from "../secret-storage.ts";
 import { VerificationRequest } from "./verification.ts";
-import { BackupTrustInfo, KeyBackupCheck, KeyBackupInfo } from "./keybackup.ts";
+import {
+    BackupTrustInfo,
+    KeyBackupCheck,
+    KeyBackupInfo,
+    KeyBackupRestoreOpts,
+    KeyBackupRestoreResult,
+} from "./keybackup.ts";
 import { ISignatures } from "../@types/signed.ts";
 import { MatrixEvent } from "../models/event.ts";
 
@@ -539,6 +545,25 @@ export interface CryptoApi {
      */
     deleteKeyBackupVersion(version: string): Promise<void>;
 
+    /**
+     * Restores a key backup.
+     * If the recovery key is not provided, it will try to restore the key backup using the recovery key stored
+     * in the local cache or in the Secret Storage.
+     *
+     * @param recoveryKey - The recovery key to use to restore the key backup.
+     * @param opts
+     */
+    restoreKeyBackup(recoveryKey: string | undefined, opts?: KeyBackupRestoreOpts): Promise<KeyBackupRestoreResult>;
+
+    /**
+     * Restores a key backup using a passphrase.
+     * @param phassphrase - The passphrase to use to restore the key backup.
+     * @param opts
+     *
+     * @deprecated Deriving a backup key from a passphrase is not part of the matrix spec. Instead, a random key is generated and stored/ shared via 4S.
+     */
+    restoreKeyBackupWithPassphrase(phassphrase: string, opts?: KeyBackupRestoreOpts): Promise<KeyBackupRestoreResult>;
+
     ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
     //
     // Dehydrated devices

src/crypto-api/keybackup.ts

@@ -16,6 +16,7 @@ limitations under the License.
 
 import { ISigned } from "../@types/signed.ts";
 import { AESEncryptedSecretStoragePayload } from "../@types/AESEncryptedSecretStoragePayload.ts";
+import { ImportRoomKeyProgressData } from "./index.ts";
 
 export interface Curve25519AuthData {
     public_key: string;
@@ -87,3 +88,28 @@ export interface KeyBackupSession<T = Curve25519SessionData | AESEncryptedSecret
 export interface KeyBackupRoomSessions {
     [sessionId: string]: KeyBackupSession;
 }
+
+/**
+ * Extra parameters for {@link CryptoApi.restoreKeyBackup} and {@link CryptoApi.restoreKeyBackupWithPassphrase}.
+ */
+export interface KeyBackupRestoreOpts {
+    /**
+     * Reports ongoing progress of the import process.
+     * @param progress
+     */
+    progressCallback?: (progress: ImportRoomKeyProgressData) => void;
+}
+
+/**
+ * The result of {@link CryptoApi.restoreKeyBackup}.
+ */
+export interface KeyBackupRestoreResult {
+    /**
+     * The total number of keys that were found in the backup.
+     */
+    total: number;
+    /**
+     * The number of keys that were imported.
+     */
+    imported: number;
+}

src/crypto/index.ts

@@ -102,6 +102,8 @@ import {
     OwnDeviceKeys,
     CryptoEvent as CryptoApiCryptoEvent,
     CryptoEventHandlerMap as CryptoApiCryptoEventHandlerMap,
+    KeyBackupRestoreResult,
+    KeyBackupRestoreOpts,
 } from "../crypto-api/index.ts";
 import { Device, DeviceMap } from "../models/device.ts";
 import { deviceInfoToDevice } from "./device-converter.ts";
@@ -4308,6 +4310,26 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
     public async startDehydration(createNewKey?: boolean): Promise<void> {
         throw new Error("Not implemented");
     }
+
+    /**
+     * Stub function -- restoreKeyBackup is not implemented here, so throw error
+     */
+    public restoreKeyBackup(
+        recoveryKey: string | undefined,
+        opts: KeyBackupRestoreOpts,
+    ): Promise<KeyBackupRestoreResult> {
+        throw new Error("Not implemented");
+    }
+
+    /**
+     * Stub function -- restoreKeyBackupWithPassphrase is not implemented here, so throw error
+     */
+    public restoreKeyBackupWithPassphrase(
+        phassphrase: string,
+        opts: KeyBackupRestoreOpts,
+    ): Promise<KeyBackupRestoreResult> {
+        throw new Error("Not implemented");
+    }
 }
 
 /**