From 7bc1dc6a5603953eb139ae3ba0c5926ddedb0aeb Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 7 Oct 2024 12:23:43 +0100 Subject: [PATCH] Expose crypto-api as its own typedoc module (#4439) Currently the crypto-api hierarchy is exposed only as a `Crypto` namespace under the "matrix" entrypoint in the documentation. This isn't really right: it's meant to be a separate entrypoint (in the same way as `types`, `testing` and `utils` are). This PR fixes that problem. --- src/crypto-api/index.ts | 33 ++++++++++++++++++++----------- src/crypto-api/keybackup.ts | 4 ++-- src/crypto-api/verification.ts | 4 ++-- src/matrix.ts | 7 +------ src/models/typed-event-emitter.ts | 8 ++++---- src/secret-storage.ts | 2 +- src/store/indexeddb.ts | 7 +++++-- typedoc.json | 2 +- 8 files changed, 37 insertions(+), 30 deletions(-) diff --git a/src/crypto-api/index.ts b/src/crypto-api/index.ts index 0ac684e8c63..ec099dabff0 100644 --- a/src/crypto-api/index.ts +++ b/src/crypto-api/index.ts @@ -25,6 +25,15 @@ import { BackupTrustInfo, KeyBackupCheck, KeyBackupInfo } from "./keybackup.ts"; import { ISignatures } from "../@types/signed.ts"; import { MatrixEvent } from "../models/event.ts"; +/** + * `matrix-js-sdk/lib/crypto-api`: End-to-end encryption support. + * + * The most important type is {@link CryptoApi}, an instance of which can be retrieved via + * {@link MatrixClient.getCrypto}. + * + * @packageDocumentation + */ + /** * Public interface to the cryptography parts of the js-sdk * @@ -181,7 +190,7 @@ export interface CryptoApi { /** * Return whether we trust other user's signatures of their devices. * - * @see {@link Crypto.CryptoApi#setTrustCrossSignedDevices} + * @see {@link CryptoApi.setTrustCrossSignedDevices} * * @returns `true` if we trust cross-signed devices, otherwise `false`. */ @@ -228,7 +237,7 @@ export interface CryptoApi { * * @throws an error if the device is unknown, or has not published any encryption keys. * - * @remarks Fires {@link CryptoEvent#DeviceVerificationChanged} + * @remarks Fires {@link matrix.CryptoEvent.DeviceVerificationChanged} */ setDeviceVerified(userId: string, deviceId: string, verified?: boolean): Promise; @@ -259,7 +268,7 @@ export interface CryptoApi { * * @returns True if cross-signing is ready to be used on this device * - * @throws May throw {@link ClientStoppedError} if the `MatrixClient` is stopped before or during the call. + * @throws May throw {@link matrix.ClientStoppedError} if the `MatrixClient` is stopped before or during the call. */ isCrossSigningReady(): Promise; @@ -327,7 +336,7 @@ export interface CryptoApi { * @returns The current status of cross-signing keys: whether we have public and private keys cached locally, and * whether the private keys are in secret storage. * - * @throws May throw {@link ClientStoppedError} if the `MatrixClient` is stopped before or during the call. + * @throws May throw {@link matrix.ClientStoppedError} if the `MatrixClient` is stopped before or during the call. */ getCrossSigningStatus(): Promise; @@ -407,8 +416,8 @@ export interface CryptoApi { * * If an all-devices verification is already in flight, returns it. Otherwise, initiates a new one. * - * To control the methods offered, set {@link ICreateClientOpts.verificationMethods} when creating the - * MatrixClient. + * To control the methods offered, set {@link matrix.ICreateClientOpts.verificationMethods} when creating the + * `MatrixClient`. * * @returns a VerificationRequest when the request has been sent to the other party. */ @@ -422,8 +431,8 @@ export interface CryptoApi { * * If a verification for this user/device is already in flight, returns it. Otherwise, initiates a new one. * - * To control the methods offered, set {@link ICreateClientOpts.verificationMethods} when creating the - * MatrixClient. + * To control the methods offered, set {@link matrix.ICreateClientOpts.verificationMethods} when creating the + * `MatrixClient`. * * @param userId - ID of the owner of the device to verify * @param deviceId - ID of the device to verify @@ -480,7 +489,7 @@ export interface CryptoApi { /** * Determine if a key backup can be trusted. * - * @param info - key backup info dict from {@link MatrixClient#getKeyBackupVersion}. + * @param info - key backup info dict from {@link matrix.MatrixClient.getKeyBackupVersion}. */ isKeyBackupTrusted(info: KeyBackupInfo): Promise; @@ -500,7 +509,7 @@ export interface CryptoApi { * * If there are existing backups they will be replaced. * - * The decryption key will be saved in Secret Storage (the {@link SecretStorageCallbacks.getSecretStorageKey} Crypto + * The decryption key will be saved in Secret Storage (the {@link matrix.SecretStorage.SecretStorageCallbacks.getSecretStorageKey} Crypto * callback will be called) * and the backup engine will be started. */ @@ -841,9 +850,9 @@ export class DeviceVerificationStatus { * Check if we should consider this device "verified". * * A device is "verified" if either: - * * it has been manually marked as such via {@link MatrixClient#setDeviceVerified}. + * * it has been manually marked as such via {@link matrix.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 Crypto.CryptoApi#setTrustCrossSignedDevices}. + * cross-signed devices via {@link CryptoApi.setTrustCrossSignedDevices}. * * @returns true if this device is verified via any means. */ diff --git a/src/crypto-api/keybackup.ts b/src/crypto-api/keybackup.ts index 8a82a5f4c13..efae30d0ec4 100644 --- a/src/crypto-api/keybackup.ts +++ b/src/crypto-api/keybackup.ts @@ -35,7 +35,7 @@ export interface Aes256AuthData { * Information about a server-side key backup. * * Returned by [`GET /_matrix/client/v3/room_keys/version`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3room_keysversion) - * and hence {@link MatrixClient#getKeyBackupVersion}. + * and hence {@link matrix.MatrixClient.getKeyBackupVersion}. */ export interface KeyBackupInfo { algorithm: string; @@ -63,7 +63,7 @@ export interface BackupTrustInfo { } /** - * The result of {@link Crypto.CryptoApi.checkKeyBackupAndEnable}. + * The result of {@link CryptoApi.checkKeyBackupAndEnable}. */ export interface KeyBackupCheck { backupInfo: KeyBackupInfo; diff --git a/src/crypto-api/verification.ts b/src/crypto-api/verification.ts index daa7bdbceed..468a5d7a9f2 100644 --- a/src/crypto-api/verification.ts +++ b/src/crypto-api/verification.ts @@ -119,7 +119,7 @@ export interface VerificationRequest * * If a verifier has already been created for this request, returns that verifier. * - * This does *not* send the `m.key.verification.start` event - to do so, call {@link Crypto.Verifier#verify} on the + * This does *not* send the `m.key.verification.start` event - to do so, call {@link Verifier.verify} on the * returned verifier. * * If no previous events have been sent, pass in `targetDevice` to set who to direct this request to. @@ -281,7 +281,7 @@ export interface Verifier extends TypedEventEmitter new MemoryCryptoStore(); diff --git a/src/models/typed-event-emitter.ts b/src/models/typed-event-emitter.ts index c3bec68d74b..3c90710165e 100644 --- a/src/models/typed-event-emitter.ts +++ b/src/models/typed-event-emitter.ts @@ -65,7 +65,7 @@ export class TypedEventEmitter< SuperclassArguments extends ListenerMap = Arguments, > extends EventEmitter { /** - * Alias for {@link TypedEventEmitter#on}. + * Alias for {@link on}. */ public addListener( event: T, @@ -124,7 +124,7 @@ export class TypedEventEmitter< } /** - * Alias for {@link TypedEventEmitter#removeListener} + * Alias for {@link removeListener} */ public off(event: T, listener: Listener): this { return super.off(event, listener); @@ -139,7 +139,7 @@ export class TypedEventEmitter< * being added, and called, multiple times. * * By default, event listeners are invoked in the order they are added. The - * {@link TypedEventEmitter#prependListener} method can be used as an alternative to add the + * {@link prependListener} method can be used as an alternative to add the * event listener to the beginning of the listeners array. * * @param event - The name of the event. @@ -158,7 +158,7 @@ export class TypedEventEmitter< * Returns a reference to the `EventEmitter`, so that calls can be chained. * * By default, event listeners are invoked in the order they are added. - * The {@link TypedEventEmitter#prependOnceListener} method can be used as an alternative to add the + * The {@link prependOnceListener} method can be used as an alternative to add the * event listener to the beginning of the listeners array. * * @param event - The name of the event. diff --git a/src/secret-storage.ts b/src/secret-storage.ts index 13e8bdc625b..2aa8a028aa7 100644 --- a/src/secret-storage.ts +++ b/src/secret-storage.ts @@ -164,7 +164,7 @@ export interface SecretStorageCallbacks { * Descriptions of the secret storage keys are also stored in server-side storage, per the * [matrix specification](https://spec.matrix.org/v1.6/client-server-api/#key-storage), so * before a key can be used in this way, it must have been stored on the server. This is - * done via {@link SecretStorage.ServerSideSecretStorage#addKey}. + * done via {@link ServerSideSecretStorage#addKey}. * * Obviously the keys themselves are not stored server-side, so the js-sdk calls this callback * in order to retrieve a secret storage key from the application. diff --git a/src/store/indexeddb.ts b/src/store/indexeddb.ts index 67d219e2bb3..443447b650b 100644 --- a/src/store/indexeddb.ts +++ b/src/store/indexeddb.ts @@ -24,7 +24,7 @@ import { logger } from "../logger.ts"; import { ISavedSync } from "./index.ts"; import { IIndexedDBBackend } from "./indexeddb-backend.ts"; import { ISyncResponse } from "../sync-accumulator.ts"; -import { TypedEventEmitter } from "../models/typed-event-emitter.ts"; +import { EventEmitterEvents, TypedEventEmitter } from "../models/typed-event-emitter.ts"; import { IStateEventWithRoomId } from "../@types/search.ts"; import { IndexedToDeviceBatch, ToDeviceBatchWithTxnId } from "../models/ToDeviceMessage.ts"; import { IStoredClientOpts } from "../client.ts"; @@ -118,7 +118,10 @@ export class IndexedDBStore extends MemoryStore { } } - public on = this.emitter.on.bind(this.emitter); + /** Re-exports `TypedEventEmitter.on` */ + public on(event: EventEmitterEvents | "degraded" | "closed", handler: (...args: any[]) => void): void { + this.emitter.on(event, handler); + } /** * @returns Resolved when loaded from indexed db. diff --git a/typedoc.json b/typedoc.json index 75b85b15bf8..9f4abe4103f 100644 --- a/typedoc.json +++ b/typedoc.json @@ -2,7 +2,7 @@ "$schema": "https://typedoc.org/schema.json", "plugin": ["typedoc-plugin-mdn-links", "typedoc-plugin-missing-exports", "typedoc-plugin-coverage"], "coverageLabel": "TypeDoc", - "entryPoints": ["src/matrix.ts", "src/types.ts", "src/testing.ts", "src/utils/*.ts"], + "entryPoints": ["src/matrix.ts", "src/crypto-api", "src/types.ts", "src/testing.ts", "src/utils/*.ts"], "excludeExternals": true, "out": "_docs" }