Add restoreKeybackup to CryptoApi.

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

@@ -23,6 +23,7 @@ import {
     createClient,
     Crypto,
     CryptoEvent,
+    encodeBase64,
     ICreateClientOpts,
     IEvent,
     IMegolmSessionData,
@@ -316,6 +317,10 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
 
         beforeEach(async () => {
             fetchMock.get("path:/_matrix/client/v3/room_keys/version", testData.SIGNED_BACKUP_DATA);
+            fetchMock.get(
+                `path:/_matrix/client/v3/room_keys/version/${testData.SIGNED_BACKUP_DATA.version}`,
+                testData.SIGNED_BACKUP_DATA,
+            );
 
             aliceClient = await initTestClient();
             aliceCrypto = aliceClient.getCrypto()!;
@@ -621,11 +626,10 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("megolm-keys backup (%s)", (backe
                 };
                 fetchMock.get("express:/_matrix/client/v3/room_keys/keys", fullBackup);
 
-                const check = await aliceCrypto.checkKeyBackupAndEnable();
-                const recoveryKey = await aliceCrypto.getSecretStorageBackupPrivateKey();
-                expect(recoveryKey).not.toBeNull();
+                await aliceCrypto.loadSessionBackupPrivateKeyFromSecretStorage();
+                const decryptionKey = await aliceCrypto.getSessionBackupPrivateKey();
+                expect(encodeBase64(decryptionKey!)).toStrictEqual(testData.BACKUP_DECRYPTION_KEY_BASE64);
 
-                await aliceCrypto.storeSessionBackupPrivateKey(recoveryKey!, check!.backupInfo!.version!);
                 const result = await aliceCrypto.restoreKeyBackup();
                 expect(result.imported).toStrictEqual(1);
             },

src/crypto-api/index.ts

@@ -470,15 +470,6 @@ export interface CryptoApi {
     //
     ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
-    /**
-     * Fetch the backup decryption key we have saved in our secret storage.
-     *
-     * This can be used for gossiping the key to other devices.
-     *
-     * @returns the key, if any, or null
-     */
-    getSecretStorageBackupPrivateKey(): Promise<Uint8Array | null>;
-
     /**
      * Fetch the backup decryption key we have saved in our store.
      *
@@ -511,6 +502,12 @@ export interface CryptoApi {
      */
     storeSessionBackupPrivateKey(key: Uint8Array, version: string): Promise<void>;
 
+    /**
+     * Fetch the backup decryption key from the secret storage, fetch the backup info version.
+     * Store locally the key and the backup info version by calling {@link storeSessionBackupPrivateKey}.
+     */
+    loadSessionBackupPrivateKeyFromSecretStorage(): Promise<void>;
+
     /**
      * Get the current status of key backup.
      *
@@ -555,21 +552,24 @@ export interface CryptoApi {
     deleteKeyBackupVersion(version: string): Promise<void>;
 
     /**
-     * Download the last key backup from the homeserver (endpoint GET /room_keys/keys/).
+     * Download and restore the last key backup from the homeserver (endpoint GET /room_keys/keys/).
      * The key backup is decrypted and imported by using the decryption key stored locally. The decryption key should be stored locally by using {@link CryptoApi#storeSessionBackupPrivateKey}.
      *
+     * Warning: the full key backup may be quite large, so this operation may take several hours to complete.
+     * Use of {@link KeyBackupRestoreOpts.progressCallback} is recommended.
      * @param opts
      */
     restoreKeyBackup(opts?: KeyBackupRestoreOpts): Promise<KeyBackupRestoreResult>;
 
     /**
      * Restores a key backup using a passphrase.
-     * @param phassphrase - The passphrase to use to restore the key backup.
+     * The decoded key (derivated from the passphrase) is store locally by calling {@link CryptoApi#storeSessionBackupPrivateKey}.
+     * @param passphrase - 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>;
+    restoreKeyBackupWithPassphrase(passphrase: string, opts?: KeyBackupRestoreOpts): Promise<KeyBackupRestoreResult>;
 
     ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
     //

src/crypto/index.ts

@@ -1308,6 +1308,13 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
         });
     }
 
+    /**
+     * Implementation of {@link Crypto.loadSessionBackupPrivateKeyFromSecretStorage}.
+     */
+    public loadSessionBackupPrivateKeyFromSecretStorage(): Promise<void> {
+        throw new Error("Not implmeented");
+    }
+
     /**
      * Get the current status of key backup.
      *
@@ -4322,18 +4329,11 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      * Stub function -- restoreKeyBackupWithPassphrase is not implemented here, so throw error
      */
     public restoreKeyBackupWithPassphrase(
-        phassphrase: string,
+        passphrase: string,
         opts: KeyBackupRestoreOpts,
     ): Promise<KeyBackupRestoreResult> {
         throw new Error("Not implemented");
     }
-
-    /**
-     * Stub function -- getSecretStorageBackupPrivateKey is not implemented here, so throw error
-     */
-    public getSecretStorageBackupPrivateKey(): Promise<Uint8Array | null> {
-        throw new Error("Not implemented");
-    }
 }
 
 /**

src/rust-crypto/backup.ts

@@ -38,6 +38,7 @@ import { sleep } from "../utils.ts";
 import { BackupDecryptor } from "../common-crypto/CryptoBackend.ts";
 import { ImportRoomKeyProgressData, ImportRoomKeysOpts, CryptoEvent } from "../crypto-api/index.ts";
 import { AESEncryptedSecretStoragePayload } from "../@types/AESEncryptedSecretStoragePayload.ts";
+import { encodeBase64 } from "../base64.ts";
 
 /** Authentification of the backup info, depends on algorithm */
 type AuthData = KeyBackupInfo["auth_data"];
@@ -497,16 +498,18 @@ export class RustBackupManager extends TypedEventEmitter<RustBackupCryptoEvents,
      */
     private keysCountInBatch(batch: RustSdkCryptoJs.KeysBackupRequest): number {
         const parsedBody: KeyBackup = JSON.parse(batch.body);
-        return calculateKeyCountInKeyBackup(parsedBody);
+        return countKeysInBackup(parsedBody);
     }
 
     /**
-     * Get information about the current key backup from the server
-     *
+     * Get information about a key backup from the server
+     * - If version is provided, get information about that backup version.
+     * - If no version is provided, get information about the latest backup.
+     * @param version - The version of the backup to get information about.
      * @returns Information object from API or null if there is no active backup.
      */
-    private async requestKeyBackupVersion(): Promise<KeyBackupInfo | null> {
-        return await requestKeyBackupVersion(this.http);
+    public async requestKeyBackupVersion(version?: string): Promise<KeyBackupInfo | null> {
+        return await requestKeyBackupVersion(this.http, version);
     }
 
     /**
@@ -593,36 +596,36 @@ export class RustBackupManager extends TypedEventEmitter<RustBackupCryptoEvents,
     /**
      * Restore a key backup.
      *
-     * @param backupInfoVersion - The version of the backup to restore.
+     * @param backupVersion - The version of the backup to restore.
      * @param backupDecryptor - The backup decryptor to use to decrypt the keys.
      * @param opts - Options for the restore.
      * @returns The total number of keys and the total imported.
      */
     public async restoreKeyBackup(
-        backupInfoVersion: string,
+        backupVersion: string,
         backupDecryptor: BackupDecryptor,
         opts?: KeyBackupRestoreOpts,
     ): Promise<KeyBackupRestoreResult> {
-        const keyBackup = await this.downloadKeyBackup(backupInfoVersion);
+        const keyBackup = await this.downloadKeyBackup(backupVersion);
         opts?.progressCallback?.({
             stage: "load_keys",
         });
 
-        return this.importKeyBackup(keyBackup, backupInfoVersion, backupDecryptor, opts);
+        return this.importKeyBackup(keyBackup, backupVersion, backupDecryptor, opts);
     }
 
     /**
      * Call `/room_keys/keys` to download the key backup (room keys) for the given backup version.
      * https://spec.matrix.org/latest/client-server-api/#get_matrixclientv3room_keyskeys
      *
-     * @param backupInfoVersion
+     * @param backupVersion
      * @returns The key backup response.
      */
-    private downloadKeyBackup(backupInfoVersion: string): Promise<KeyBackup> {
+    private downloadKeyBackup(backupVersion: string): Promise<KeyBackup> {
         return this.http.authedRequest<KeyBackup>(
             Method.Get,
             "/room_keys/keys",
-            { version: backupInfoVersion },
+            { version: backupVersion },
             undefined,
             {
                 prefix: ClientPrefix.V3,
@@ -635,7 +638,7 @@ export class RustBackupManager extends TypedEventEmitter<RustBackupCryptoEvents,
      * Call the opts.progressCallback with the progress of the import.
      *
      * @param keyBackup - The response from the server containing the keys to import.
-     * @param backupInfoVersion - The version of the backup info.
+     * @param backupVersion - The version of the backup info.
      * @param backupDecryptor - The backup decryptor to use to decrypt the keys.
      * @param opts - Options for the import.
      *
@@ -645,15 +648,15 @@ export class RustBackupManager extends TypedEventEmitter<RustBackupCryptoEvents,
      */
     private async importKeyBackup(
         keyBackup: KeyBackup,
-        backupInfoVersion: string,
+        backupVersion: string,
         backupDecryptor: BackupDecryptor,
         opts?: KeyBackupRestoreOpts,
     ): Promise<KeyBackupRestoreResult> {
         // We have a full backup here, it can get quite big, so we need to decrypt and import it in chunks.
 
         const CHUNK_SIZE = 200;
         // Get the total count as a first pass
-        const totalKeyCount = calculateKeyCountInKeyBackup(keyBackup);
+        const totalKeyCount = countKeysInBackup(keyBackup);
         let totalImported = 0;
         let totalFailures = 0;
 
@@ -677,7 +680,7 @@ export class RustBackupManager extends TypedEventEmitter<RustBackupCryptoEvents,
 
             // We have a chunk of decrypted keys: import them
             try {
-                await this.importBackedUpRoomKeys(currentChunk, backupInfoVersion);
+                await this.importBackedUpRoomKeys(currentChunk, backupVersion);
                 totalImported += currentChunk.length;
             } catch (e) {
                 totalFailures += currentChunk.length;
@@ -797,11 +800,23 @@ export class RustBackupDecryptor implements BackupDecryptor {
     }
 }
 
+/**
+ * Fetch a key backup info from the server.
+ * - If `version` is provided call GET /room_keys/version/$version and get the backup info for that version.
+ * https://spec.matrix.org/latest/client-server-api/#get_matrixclientv3room_keysversionversion
+ * - If not, call GET /room_keys/version and get the latest backup info.
+ * https://spec.matrix.org/latest/client-server-api/#get_matrixclientv3room_keysversion
+ * @param http
+ * @param version - the specific version of the backup info to fetch
+ * @returns The key backup info or null if there is no backup.
+ */
 export async function requestKeyBackupVersion(
     http: MatrixHttpApi<IHttpOpts & { onlyData: true }>,
+    version?: string,
 ): Promise<KeyBackupInfo | null> {
     try {
-        return await http.authedRequest<KeyBackupInfo>(Method.Get, "/room_keys/version", undefined, undefined, {
+        const path = version ? encodeUri("/room_keys/version/$version", { $version: version }) : "/room_keys/version";
+        return await http.authedRequest<KeyBackupInfo>(Method.Get, path, undefined, undefined, {
             prefix: ClientPrefix.V3,
         });
     } catch (e) {
@@ -814,12 +829,23 @@ export async function requestKeyBackupVersion(
 }
 
 /**
- * This method calculates the total number of keys present in a key backup
+ * Checks if the provided decryption key matches the public key of the key backup info.
+ * @param decryptionKey - The decryption key to check.
+ * @param keyBackupInfo - The key backup info to check against.
+ * @returns `true` if the decryption key matches the key backup info, `false` otherwise.
+ */
+export function decryptionKeyMatchKeyBackupInfo(decryptionKey: Uint8Array, keyBackupInfo: KeyBackupInfo): boolean {
+    const backupDecryptionKey = RustSdkCryptoJs.BackupDecryptionKey.fromBase64(encodeBase64(decryptionKey));
+    const authData = <Curve25519AuthData>keyBackupInfo.auth_data;
+    return authData.public_key === backupDecryptionKey.megolmV1PublicKey.publicKeyBase64;
+}
+
+/**
+ * Counts the total number of keys present in a key backup.
  * @param keyBackup - The key backup to count the keys from.
- *
  * @returns The total number of keys in the backup.
  */
-function calculateKeyCountInKeyBackup(keyBackup: KeyBackup): number {
+function countKeysInBackup(keyBackup: KeyBackup): number {
     let count = 0;
     for (const { sessions } of Object.values(keyBackup.rooms)) {
         count += Object.keys(sessions).length;