From 3f48a954d82552a1449c80ed06a13407f779c456 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Fri, 19 May 2023 13:43:16 +0100
Subject: [PATCH] Move crypto classes into a separate namespace (#3385)

* Move crypto classes into a separate namespace

* Add in re-exports for backwards compatibility

* Update src/matrix.ts
---
 src/client.ts        |  4 ++--
 src/crypto-api.ts    |  4 ++--
 src/crypto/index.ts  | 12 ++++++------
 src/matrix.ts        | 24 ++++++++++++++++++++++--
 src/models/device.ts |  2 +-
 5 files changed, 33 insertions(+), 13 deletions(-)

diff --git a/src/client.ts b/src/client.ts
index 20bb09351..820b36386 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -2577,7 +2577,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      *     "master", "self_signing", or "user_signing".  Defaults to "master".
      *
      * @returns the key ID
-     * @deprecated prefer {@link CryptoApi#getCrossSigningKeyId}
+     * @deprecated prefer {@link Crypto.CryptoApi#getCrossSigningKeyId}
      */
     public getCrossSigningId(type: CrossSigningKey | string = CrossSigningKey.Master): string | null {
         if (!this.crypto) {
@@ -2624,7 +2624,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * @param userId - The ID of the user whose devices is to be checked.
      * @param deviceId - The ID of the device to check
      *
-     * @deprecated Use {@link CryptoApi.getDeviceVerificationStatus | `CryptoApi.getDeviceVerificationStatus`}
+     * @deprecated Use {@link Crypto.CryptoApi.getDeviceVerificationStatus | `CryptoApi.getDeviceVerificationStatus`}
      */
     public checkDeviceTrust(userId: string, deviceId: string): DeviceTrustLevel {
         if (!this.crypto) {
diff --git a/src/crypto-api.ts b/src/crypto-api.ts
index 6467ba183..5af016674 100644
--- a/src/crypto-api.ts
+++ b/src/crypto-api.ts
@@ -114,7 +114,7 @@ export interface CryptoApi {
     /**
      * Return whether we trust other user's signatures of their devices.
      *
-     * @see {@link CryptoApi#setTrustCrossSignedDevices}
+     * @see {@link Crypto.CryptoApi#setTrustCrossSignedDevices}
      *
      * @returns `true` if we trust cross-signed devices, otherwise `false`.
      */
@@ -252,7 +252,7 @@ export class DeviceVerificationStatus {
      * A device is "verified" if either:
      *  * it has been manually marked as such via {@link MatrixClient#setDeviceVerified}.
      *  * it has been cross-signed with a verified signing key, **and** the client has been configured to trust
-     *    cross-signed devices via {@link CryptoApi#setTrustCrossSignedDevices}.
+     *    cross-signed devices via {@link Crypto.CryptoApi#setTrustCrossSignedDevices}.
      *
      * @returns true if this device is verified via any means.
      */
diff --git a/src/crypto/index.ts b/src/crypto/index.ts
index 1e847152b..19989d3b5 100644
--- a/src/crypto/index.ts
+++ b/src/crypto/index.ts
@@ -611,7 +611,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
     }
 
     /**
-     * @deprecated Use {@link CryptoApi#getTrustCrossSignedDevices}.
+     * @deprecated Use {@link Crypto.CryptoApi#getTrustCrossSignedDevices}.
      */
     public getCryptoTrustCrossSignedDevices(): boolean {
         return this.trustCrossSignedDevices;
@@ -641,7 +641,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
     }
 
     /**
-     * @deprecated Use {@link CryptoApi#setTrustCrossSignedDevices}.
+     * @deprecated Use {@link Crypto.CryptoApi#setTrustCrossSignedDevices}.
      */
     public setCryptoTrustCrossSignedDevices(val: boolean): void {
         this.setTrustCrossSignedDevices(val);
@@ -1473,7 +1473,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
     }
 
     /**
-     * @deprecated Use {@link CryptoApi.getDeviceVerificationStatus}.
+     * @deprecated Use {@link Crypto.CryptoApi.getDeviceVerificationStatus}.
      */
     public checkDeviceTrust(userId: string, deviceId: string): DeviceTrustLevel {
         const device = this.deviceList.getStoredDevice(userId, deviceId);
@@ -1486,7 +1486,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      * @param userId - The ID of the user whose devices is to be checked.
      * @param device - The device info object to check
      *
-     * @deprecated Use {@link CryptoApi.getDeviceVerificationStatus}.
+     * @deprecated Use {@link Crypto.CryptoApi.getDeviceVerificationStatus}.
      */
     public checkDeviceInfoTrust(userId: string, device?: DeviceInfo): DeviceTrustLevel {
         const trustedLocally = !!device?.isVerified();
@@ -1835,7 +1835,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
      *
      * @param value - whether to blacklist all unverified devices by default
      *
-     * @deprecated Set {@link CryptoApi#globalBlacklistUnverifiedDevices | CryptoApi.globalBlacklistUnverifiedDevices} directly.
+     * @deprecated Set {@link Crypto.CryptoApi#globalBlacklistUnverifiedDevices | CryptoApi.globalBlacklistUnverifiedDevices} directly.
      */
     public setGlobalBlacklistUnverifiedDevices(value: boolean): void {
         this.globalBlacklistUnverifiedDevices = value;
@@ -1844,7 +1844,7 @@ export class Crypto extends TypedEventEmitter<CryptoEvent, CryptoEventHandlerMap
     /**
      * @returns whether to blacklist all unverified devices by default
      *
-     * @deprecated Reference {@link CryptoApi#globalBlacklistUnverifiedDevices | CryptoApi.globalBlacklistUnverifiedDevices} directly.
+     * @deprecated Reference {@link Crypto.CryptoApi#globalBlacklistUnverifiedDevices | CryptoApi.globalBlacklistUnverifiedDevices} directly.
      */
     public getGlobalBlacklistUnverifiedDevices(): boolean {
         return this.globalBlacklistUnverifiedDevices;
diff --git a/src/matrix.ts b/src/matrix.ts
index 203466574..e7fd2ad75 100644
--- a/src/matrix.ts
+++ b/src/matrix.ts
@@ -64,10 +64,30 @@ export { createNewMatrixCall } from "./webrtc/call";
 export type { MatrixCall } from "./webrtc/call";
 export { GroupCallEvent, GroupCallIntent, GroupCallState, GroupCallType } from "./webrtc/groupCall";
 export type { GroupCall } from "./webrtc/groupCall";
-export type { CryptoApi } from "./crypto-api";
-export { DeviceVerificationStatus } from "./crypto-api";
 export { CryptoEvent } from "./crypto";
 
+/**
+ * Types supporting cryptography.
+ *
+ * The most important is {@link Crypto.CryptoApi}, an instance of which can be retrieved via
+ * {@link MatrixClient.getCrypto}.
+ */
+export * as Crypto from "./crypto-api";
+
+/**
+ * Backwards compatibility re-export
+ * @internal
+ * @deprecated use {@link Crypto.CryptoApi}
+ */
+export type { CryptoApi } from "./crypto-api";
+
+/**
+ * Backwards compatibility re-export
+ * @internal
+ * @deprecated use {@link Crypto.DeviceVerificationStatus}
+ */
+export { DeviceVerificationStatus } from "./crypto-api";
+
 let cryptoStoreFactory = (): CryptoStore => new MemoryCryptoStore();
 
 /**
diff --git a/src/models/device.ts b/src/models/device.ts
index 6f63e2e06..0a451fd5a 100644
--- a/src/models/device.ts
+++ b/src/models/device.ts
@@ -27,7 +27,7 @@ export type DeviceMap = Map<string, Map<string, Device>>;
 type DeviceParameters = Pick<Device, "deviceId" | "userId" | "algorithms" | "keys"> & Partial<Device>;
 
 /**
- *  Information on a user's device, as returned by {@link CryptoApi.getUserDeviceInfo}.
+ *  Information on a user's device, as returned by {@link Crypto.CryptoApi.getUserDeviceInfo}.
  */
 export class Device {
     /** id of the device */