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
matrix-org · May 19, 2023 · 3f48a95 · 3f48a95
1 parent b5d544d
commit 3f48a95
Show file tree

Hide file tree

Showing 5 changed files with 32 additions and 12 deletions.
diff --git 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
@@ -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
@@ -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
@@ -64,9 +64,29 @@ 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 { 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";
-export { CryptoEvent } from "./crypto";
 
 let cryptoStoreFactory = (): CryptoStore => new MemoryCryptoStore();
 

diff --git 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 */