Rename and move crypto.IBootstrapCrossSigningOpts (#3352)

* Define `UIAuthCallback` type and use in `IBootstrapCrossSigningOpts`

* Move `IBootstrapCrossSigningOpts` to `crypto-api` and rename

* Replace uses of `IBootstrapCrossSigningOpts`

... with `BootstrapCrossSigningOpts`

* Update src/crypto-api.ts

spec/unit/crypto/cross-signing.spec.ts

@@ -24,10 +24,11 @@ import * as olmlib from "../../../src/crypto/olmlib";
 import { MatrixError } from "../../../src/http-api";
 import { logger } from "../../../src/logger";
 import { ICrossSigningKey, ICreateClientOpts, ISignedKey, MatrixClient } from "../../../src/client";
-import { CryptoEvent, IBootstrapCrossSigningOpts } from "../../../src/crypto";
+import { CryptoEvent } from "../../../src/crypto";
 import { IDevice } from "../../../src/crypto/deviceinfo";
 import { TestClient } from "../../TestClient";
 import { resetCrossSigningKeys } from "./crypto-utils";
+import { BootstrapCrossSigningOpts } from "../../../src/crypto-api";
 
 const PUSH_RULES_RESPONSE: Response = {
     method: "GET",
@@ -146,7 +147,7 @@ describe("Cross Signing", function () {
         alice.uploadKeySignatures = async () => ({ failures: {} });
         alice.setAccountData = async () => ({});
         alice.getAccountDataFromServer = async <T extends { [k: string]: any }>(): Promise<T | null> => ({} as T);
-        const authUploadDeviceSigningKeys: IBootstrapCrossSigningOpts["authUploadDeviceSigningKeys"] = async (func) => {
+        const authUploadDeviceSigningKeys: BootstrapCrossSigningOpts["authUploadDeviceSigningKeys"] = async (func) => {
             await func({});
         };
 

src/client.ts

@@ -74,7 +74,6 @@ import {
     CryptoEventHandlerMap,
     fixBackupKey,
     ICryptoCallbacks,
-    IBootstrapCrossSigningOpts,
     ICheckOwnCrossSigningTrustOpts,
     isCryptoAvailable,
     VerificationMethod,
@@ -205,7 +204,7 @@ import { LocalNotificationSettings } from "./@types/local_notifications";
 import { buildFeatureSupportMap, Feature, ServerSupport } from "./feature";
 import { CryptoBackend } from "./common-crypto/CryptoBackend";
 import { RUST_SDK_STORE_PREFIX } from "./rust-crypto/constants";
-import { CryptoApi } from "./crypto-api";
+import { BootstrapCrossSigningOpts, CryptoApi } from "./crypto-api";
 import { DeviceInfoMap } from "./crypto/DeviceList";
 import {
     AddSecretStorageKeyOpts,
@@ -2751,7 +2750,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      *
      * The cross-signing API is currently UNSTABLE and may change without notice.
      */
-    public bootstrapCrossSigning(opts: IBootstrapCrossSigningOpts): Promise<void> {
+    public bootstrapCrossSigning(opts: BootstrapCrossSigningOpts): Promise<void> {
         if (!this.crypto) {
             throw new Error("End-to-end encryption disabled");
         }

src/crypto-api.ts

@@ -17,6 +17,7 @@ limitations under the License.
 import type { IMegolmSessionData } from "./@types/crypto";
 import { Room } from "./models/room";
 import { DeviceMap } from "./models/device";
+import { UIAuthCallback } from "./interactive-auth";
 
 /**
  * Public interface to the cryptography parts of the js-sdk
@@ -123,6 +124,20 @@ export interface CryptoApi {
     getDeviceVerificationStatus(userId: string, deviceId: string): Promise<DeviceVerificationStatus | null>;
 }
 
+/**
+ * Options object for `CryptoApi.bootstrapCrossSigning`.
+ */
+export interface BootstrapCrossSigningOpts {
+    /** Optional. Reset the cross-signing keys even if keys already exist. */
+    setupNewCrossSigning?: boolean;
+
+    /**
+     * An application callback to collect the authentication data for uploading the keys. If not given, the keys
+     * will not be uploaded to the server (which seems like a bad thing?).
+     */
+    authUploadDeviceSigningKeys?: UIAuthCallback<void>;
+}
+
 export class DeviceVerificationStatus {
     /**
      * True if this device has been signed by its owner (and that signature verified).

src/crypto/EncryptionSetup.ts

@@ -19,7 +19,7 @@ import { MatrixEvent } from "../models/event";
 import { createCryptoStoreCacheCallbacks, ICacheCallbacks } from "./CrossSigning";
 import { IndexedDBCryptoStore } from "./store/indexeddb-crypto-store";
 import { Method, ClientPrefix } from "../http-api";
-import { Crypto, ICryptoCallbacks, IBootstrapCrossSigningOpts } from "./index";
+import { Crypto, ICryptoCallbacks } from "./index";
 import {
     ClientEvent,
     ClientEventHandlerMap,
@@ -31,9 +31,10 @@ import {
 import { IKeyBackupInfo } from "./keybackup";
 import { TypedEventEmitter } from "../models/typed-event-emitter";
 import { AccountDataClient, SecretStorageKeyDescription } from "../secret-storage";
+import { BootstrapCrossSigningOpts } from "../crypto-api";
 
 interface ICrossSigningKeys {
-    authUpload: IBootstrapCrossSigningOpts["authUploadDeviceSigningKeys"];
+    authUpload: BootstrapCrossSigningOpts["authUploadDeviceSigningKeys"];
     keys: Record<"master" | "self_signing" | "user_signing", ICrossSigningKey>;
 }
 

src/crypto/index.ts

@@ -88,10 +88,13 @@ import {
     ServerSideSecretStorageImpl,
 } from "../secret-storage";
 import { ISecretRequest } from "./SecretSharing";
-import { DeviceVerificationStatus } from "../crypto-api";
+import { BootstrapCrossSigningOpts, DeviceVerificationStatus } from "../crypto-api";
 import { Device, DeviceMap } from "../models/device";
 import { deviceInfoToDevice } from "./device-converter";
 
+/* re-exports for backwards compatibility */
+export type { BootstrapCrossSigningOpts as IBootstrapCrossSigningOpts } from "../crypto-api";
+
 const DeviceVerification = DeviceInfo.DeviceVerification;
 
 const defaultVerificationMethods = {
@@ -127,16 +130,6 @@ interface IInitOpts {
     pickleKey?: string;
 }
 
-export interface IBootstrapCrossSigningOpts {
-    /** Optional. Reset even if keys already exist. */
-    setupNewCrossSigning?: boolean;
-    /**
-     * A function that makes the request requiring auth. Receives the auth data as an object.
-     * Can be called multiple times, first with an empty authDict, to obtain the flows.
-     */
-    authUploadDeviceSigningKeys?(makeRequest: (authData: any) => Promise<{}>): Promise<void>;
-}
-
 export interface ICryptoCallbacks extends SecretStorageCallbacks {
     getCrossSigningKey?: (keyType: string, pubKey: string) => Promise<Uint8Array | null>;
     saveCrossSigningKeys?: (keys: Record<string, Uint8Array>) => void;
@@ -769,7 +762,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
     public async bootstrapCrossSigning({
         authUploadDeviceSigningKeys,
         setupNewCrossSigning,
-    }: IBootstrapCrossSigningOpts = {}): Promise<void> {
+    }: BootstrapCrossSigningOpts = {}): Promise<void> {
         logger.log("Bootstrapping cross-signing");
 
         const delegateCryptoCallbacks = this.baseApis.cryptoCallbacks;

src/interactive-auth.ts

@@ -20,6 +20,7 @@ import { logger } from "./logger";
 import { MatrixClient } from "./client";
 import { defer, IDeferred } from "./utils";
 import { MatrixError } from "./http-api";
+import { UIAResponse } from "./@types/uia";
 
 const EMAIL_STAGE_TYPE = "m.login.email.identity";
 const MSISDN_STAGE_TYPE = "m.login.msisdn";
@@ -118,6 +119,16 @@ export class NoAuthFlowFoundError extends Error {
     }
 }
 
+/**
+ * The type of an application callback to perform the user-interactive bit of UIA.
+ *
+ * It is called with a single parameter, `makeRequest`, which is a function which takes the UIA parameters and
+ * makes the HTTP request.
+ *
+ * The generic parameter `T` is the type of the response of the endpoint, once it is eventually successful.
+ */
+export type UIAuthCallback<T> = (makeRequest: (authData: IAuthDict) => Promise<UIAResponse<T>>) => Promise<T>;
+
 interface IOpts {
     /**
      * A matrix client to use for the auth process