Provide more options for starting dehydration (#4664)

* provide more options for starting dehydration

* improve doc comments and tests

src/crypto-api/index.ts

@@ -41,6 +41,37 @@ import { MatrixEvent } from "../models/event.ts";
  * @packageDocumentation
  */
 
+/**
+ * The options to start device dehydration.
+ */
+export interface StartDehydrationOpts {
+    /**
+     * Force creation of a new dehydration key, even if there is already an
+     * existing dehydration key. If `false`, and `onlyIfKeyCached` is `false`, a
+     * new key will be created if there is no existing dehydration key, whether
+     * already cached in our local storage or stored in Secret Storage.
+     *
+     * Checking for the presence of the key in Secret Storage may result in the
+     * `getSecretStorageKey` callback being called.
+     *
+     * Defaults to `false`.
+     */
+    createNewKey?: boolean;
+    /**
+     * Only start dehydration if we have a dehydration key cached in our local
+     * storage. If `true`, Secret Storage will not be checked. Defaults to
+     * `false`.
+     */
+    onlyIfKeyCached?: boolean;
+    /**
+     * Try to rehydrate a device before creating a new dehydrated device.
+     * Setting this to `false` may be useful for situations where the client is
+     * known to pre-date the dehydrated device, and so rehydration is
+     * unnecessary. Defaults to `true`.
+     */
+    rehydrate?: boolean;
+}
+
 /**
  * Public interface to the cryptography parts of the js-sdk
  *
@@ -649,10 +680,11 @@ export interface CryptoApi {
     /**
      * Start using device dehydration.
      *
-     * - Rehydrates a dehydrated device, if one is available.
+     * - Rehydrates a dehydrated device, if one is available and `opts.rehydrate`
+     *   is `true`.
      * - Creates a new dehydration key, if necessary, and stores it in Secret
      *   Storage.
-     *   - If `createNewKey` is set to true, always creates a new key.
+     *   - If `opts.createNewKey` is set to true, always creates a new key.
      *   - If a dehydration key is not available, creates a new one.
      * - Creates a new dehydrated device, and schedules periodically creating
      *   new dehydrated devices.
@@ -661,11 +693,11 @@ export interface CryptoApi {
      * `true`, and must not be called until after cross-signing and secret
      * storage have been set up.
      *
-     * @param createNewKey - whether to force creation of a new dehydration key.
-     *   This can be used, for example, if Secret Storage is being reset.  Defaults
-     *   to false.
+     * @param opts - options for device dehydration. For backwards compatibility
+     *     with old code, a boolean can be given here, which will be treated as
+     *     the `createNewKey` option. However, this is deprecated.
      */
-    startDehydration(createNewKey?: boolean): Promise<void>;
+    startDehydration(opts?: StartDehydrationOpts | boolean): Promise<void>;
 
     ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
     //

src/crypto/index.ts

@@ -105,6 +105,7 @@ import {
     CryptoEventHandlerMap as CryptoApiCryptoEventHandlerMap,
     KeyBackupRestoreResult,
     KeyBackupRestoreOpts,
+    StartDehydrationOpts,
 } from "../crypto-api/index.ts";
 import { Device, DeviceMap } from "../models/device.ts";
 import { deviceInfoToDevice } from "./device-converter.ts";
@@ -4327,7 +4328,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
     /**
      * Stub function -- dehydration is not implemented here, so throw error
      */
-    public async startDehydration(createNewKey?: boolean): Promise<void> {
+    public async startDehydration(createNewKey?: StartDehydrationOpts | boolean): Promise<void> {
         throw new Error("Not implemented");
     }
 

src/rust-crypto/DehydratedDeviceManager.ts

@@ -23,7 +23,7 @@ import { IToDeviceEvent } from "../sync-accumulator.ts";
 import { ServerSideSecretStorage } from "../secret-storage.ts";
 import { decodeBase64 } from "../base64.ts";
 import { Logger } from "../logger.ts";
-import { CryptoEvent, CryptoEventHandlerMap } from "../crypto-api/index.ts";
+import { CryptoEvent, CryptoEventHandlerMap, StartDehydrationOpts } from "../crypto-api/index.ts";
 import { TypedEventEmitter } from "../models/typed-event-emitter.ts";
 
 /**
@@ -121,28 +121,39 @@ export class DehydratedDeviceManager extends TypedEventEmitter<DehydratedDevices
     /**
      * Start using device dehydration.
      *
-     * - Rehydrates a dehydrated device, if one is available.
+     * - Rehydrates a dehydrated device, if one is available and `opts.rehydrate`
+     *   is `true`.
      * - Creates a new dehydration key, if necessary, and stores it in Secret
      *   Storage.
-     *   - If `createNewKey` is set to true, always creates a new key.
+     *   - If `opts.createNewKey` is set to true, always creates a new key.
      *   - If a dehydration key is not available, creates a new one.
      * - Creates a new dehydrated device, and schedules periodically creating
      *   new dehydrated devices.
      *
-     * @param createNewKey - whether to force creation of a new dehydration key.
-     *   This can be used, for example, if Secret Storage is being reset.
+     * @param opts - options for device dehydration. For backwards compatibility
+     *     with old code, a boolean can be given here, which will be treated as
+     *     the `createNewKey` option. However, this is deprecated.
      */
-    public async start(createNewKey?: boolean): Promise<void> {
-        this.stop();
-        try {
-            await this.rehydrateDeviceIfAvailable();
-        } catch (e) {
-            // If rehydration fails, there isn't much we can do about it.  Log
-            // the error, and create a new device.
-            this.logger.info("dehydration: Error rehydrating device:", e);
-            this.emit(CryptoEvent.RehydrationError, (e as Error).message);
+    public async start(opts: StartDehydrationOpts | boolean = {}): Promise<void> {
+        if (typeof opts === "boolean") {
+            opts = { createNewKey: opts };
         }
-        if (createNewKey) {
+
+        if (opts.onlyIfKeyCached && !(await this.olmMachine.dehydratedDevices().getDehydratedDeviceKey())) {
+            return;
+        }
+        this.stop();
+        if (opts.rehydrate !== false) {
+            try {
+                await this.rehydrateDeviceIfAvailable();
+            } catch (e) {
+                // If rehydration fails, there isn't much we can do about it.  Log
+                // the error, and create a new device.
+                this.logger.info("dehydration: Error rehydrating device:", e);
+                this.emit(CryptoEvent.RehydrationError, (e as Error).message);
+            }
+        }
+        if (opts.createNewKey) {
             await this.resetKey();
         }
         await this.scheduleDeviceDehydration();

src/rust-crypto/rust-crypto.ts

@@ -67,6 +67,7 @@ import {
     CryptoEventHandlerMap,
     KeyBackupRestoreOpts,
     KeyBackupRestoreResult,
+    StartDehydrationOpts,
 } from "../crypto-api/index.ts";
 import { deviceKeysToDeviceMap, rustDeviceToJsDevice } from "./device-converter.ts";
 import { IDownloadKeyResult, IQueryKeysRequest } from "../client.ts";
@@ -1425,11 +1426,11 @@ export class RustCrypto extends TypedEventEmitter<RustCryptoEvents, CryptoEventH
     /**
      * Implementation of {@link CryptoApi#startDehydration}.
      */
-    public async startDehydration(createNewKey?: boolean): Promise<void> {
+    public async startDehydration(opts: StartDehydrationOpts | boolean = {}): Promise<void> {
         if (!(await this.isCrossSigningReady()) || !(await this.isSecretStorageReady())) {
             throw new Error("Device dehydration requires cross-signing and secret storage to be set up");
         }
-        return await this.dehydratedDeviceManager.start(createNewKey);
+        return await this.dehydratedDeviceManager.start(opts || {});
     }
 
     /**