matrix/matrix-js-sdk
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-js-sdk.git synced 2025-04-18 07:04:03 +03:00
Code

Expose crypto-api as its own typedoc module (#4439)

Browse Source 
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.
This commit is contained in:
Richard van der Hoff 2024-10-07 12:38:28 +01:00 committed by GitHub
parent 3386c66b98
commit 73ab7c342a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 37 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
src/crypto-api/index.ts
View File

@ -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<void>;
@ -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<boolean>;
@ -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<CrossSigningStatus>;
@ -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<BackupTrustInfo>;
@ -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.
*/

4
src/crypto-api/keybackup.ts
View File

@ -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;

4
src/crypto-api/verification.ts
View File

@ -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<VerifierEvent, VerifierEvent
* Cancel a verification.
*
* We will send an `m.key.verification.cancel` if the verification is still in flight. The verification promise
* will reject, and a {@link Crypto.VerifierEvent#Cancel} will be emitted.
* will reject, and a {@link crypto-api.VerifierEvent.Cancel | VerifierEvent.Cancel} will be emitted.
*
* @param e - the reason for the cancellation.
*/

7
src/matrix.ts
View File

@ -108,12 +108,7 @@ export type { ISSOFlow as SSOFlow, LoginFlow } from "./@types/auth.ts";
export type { IHierarchyRelation as HierarchyRelation, IHierarchyRoom as HierarchyRoom } from "./@types/spaces.ts";
export { LocationAssetType } from "./@types/location.ts";
/**
* Types supporting cryptography.
*
* The most important is {@link Crypto.CryptoApi}, an instance of which can be retrieved via
* {@link MatrixClient.getCrypto}.
*/
/** @deprecated Backwards-compatibility re-export. Import from `crypto-api` directly. */
export * as Crypto from "./crypto-api/index.ts";
let cryptoStoreFactory = (): CryptoStore => new MemoryCryptoStore();

8
src/models/typed-event-emitter.ts
View File

@ -65,7 +65,7 @@ export class TypedEventEmitter<
SuperclassArguments extends ListenerMap<any> = Arguments,
> extends EventEmitter {
/**
* Alias for {@link TypedEventEmitter#on}.
* Alias for {@link on}.
*/
public addListener<T extends Events | EventEmitterEvents>(
event: T,
@ -124,7 +124,7 @@ export class TypedEventEmitter<
}
/**
* Alias for {@link TypedEventEmitter#removeListener}
* Alias for {@link removeListener}
*/
public off<T extends Events | EventEmitterEvents>(event: T, listener: Listener<Events, Arguments, T>): 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.

2
src/secret-storage.ts
View File

@ -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.

7
src/store/indexeddb.ts
View File

@ -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.

2
typedoc.json
View File

@ -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"
}