diff --git a/spec/integ/crypto/verification.spec.ts b/spec/integ/crypto/verification.spec.ts index fff80fd08..bd8d15cec 100644 --- a/spec/integ/crypto/verification.spec.ts +++ b/spec/integ/crypto/verification.spec.ts @@ -18,9 +18,8 @@ import fetchMock from "fetch-mock-jest"; import { MockResponse } from "fetch-mock"; import { createClient, MatrixClient } from "../../../src"; -import { ShowQrCodeCallbacks, ShowSasCallbacks, VerifierEvent } from "../../../src/crypto-api/verification"; +import { ShowQrCodeCallbacks, ShowSasCallbacks, Verifier, VerifierEvent } from "../../../src/crypto-api/verification"; import { escapeRegExp } from "../../../src/utils"; -import { VerificationBase } from "../../../src/crypto/verification/Base"; import { CRYPTO_BACKENDS, InitCrypto } from "../../test-utils/test-utils"; import { SyncResponder } from "../../test-utils/SyncResponder"; import { @@ -170,7 +169,7 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("verification (%s)", (backend: st expect(request.chosenMethod).toEqual("m.sas.v1"); // there should now be a verifier - const verifier: VerificationBase = request.verifier!; + const verifier: Verifier = request.verifier!; expect(verifier).toBeDefined(); expect(verifier.getShowSasCallbacks()).toBeNull(); @@ -325,7 +324,7 @@ describe.each(Object.entries(CRYPTO_BACKENDS))("verification (%s)", (backend: st expect(request.chosenMethod).toEqual("m.reciprocate.v1"); // there should now be a verifier - const verifier: VerificationBase = request.verifier!; + const verifier: Verifier = request.verifier!; expect(verifier).toBeDefined(); expect(verifier.getReciprocateQrCodeCallbacks()).toBeNull(); diff --git a/src/crypto-api/verification.ts b/src/crypto-api/verification.ts index b78c713ee..8a078df1c 100644 --- a/src/crypto-api/verification.ts +++ b/src/crypto-api/verification.ts @@ -15,8 +15,67 @@ limitations under the License. */ import { MatrixEvent } from "../models/event"; +import { TypedEventEmitter } from "../models/typed-event-emitter"; -/** Events emitted by `Verifier`. */ +/** + * A `Verifier` is responsible for performing the verification using a particular method, such as via QR code or SAS + * (emojis). + * + * A verifier object can be created by calling `VerificationRequest.beginVerification`; one is also created + * automatically when a `m.key.verification.start` event is received for an existing VerificationRequest. + * + * Once a verifier object is created, the verification can be started by calling the {@link Verifier#verify} method. + */ +export interface Verifier extends TypedEventEmitter { + /** + * Returns true if the verification has been cancelled, either by us or the other side. + */ + get hasBeenCancelled(): boolean; + + /** + * The ID of the other user in the verification process. + */ + get userId(): string; + + /** + * Start the key verification, if it has not already been started. + * + * This means sending a `m.key.verification.start` if we are the first responder, or a `m.key.verification.accept` + * if the other side has already sent a start event. + * + * @returns Promise which resolves when the verification has completed, or rejects if the verification is cancelled + * or times out. + */ + verify(): Promise; + + /** + * 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. + * + * @param e - the reason for the cancellation. + */ + cancel(e: Error): void; + + /** + * Get the details for an SAS verification, if one is in progress + * + * Returns `null`, unless this verifier is for a SAS-based verification and we are waiting for the user to confirm + * the SAS matches. + */ + getShowSasCallbacks(): ShowSasCallbacks | null; + + /** + * Get the details for reciprocating QR code verification, if one is in progress + * + * Returns `null`, unless this verifier is for reciprocating a QR-code-based verification (ie, the other user has + * already scanned our QR code), and we are waiting for the user to confirm. + */ + getReciprocateQrCodeCallbacks(): ShowQrCodeCallbacks | null; +} + +/** Events emitted by {@link Verifier} */ export enum VerifierEvent { /** * The verification has been cancelled, by us or the other side. @@ -29,7 +88,7 @@ export enum VerifierEvent { /** * SAS data has been exchanged and should be displayed to the user. * - * The payload is the {@link ShowQrCodeCallbacks} object. + * The payload is the {@link ShowSasCallbacks} object. */ ShowSas = "show_sas", diff --git a/src/crypto/verification/Base.ts b/src/crypto/verification/Base.ts index de6a0f836..18818989e 100644 --- a/src/crypto/verification/Base.ts +++ b/src/crypto/verification/Base.ts @@ -32,6 +32,7 @@ import { TypedEventEmitter } from "../../models/typed-event-emitter"; import { ShowQrCodeCallbacks, ShowSasCallbacks, + Verifier, VerifierEvent, VerifierEventHandlerMap, } from "../../crypto-api/verification"; @@ -56,14 +57,18 @@ export type VerificationEventHandlerMap = { [VerificationEvent.Cancel]: (e: Error | MatrixEvent) => void; }; +/** @deprecated Avoid referencing this class directly; instead use {@link Crypto.Verifier}. */ // The type parameters of VerificationBase are no longer used, but we need some placeholders to maintain // backwards compatibility with applications that reference the class. export class VerificationBase< - // eslint-disable-next-line @typescript-eslint/no-unused-vars - Events extends string = VerifierEvent, - // eslint-disable-next-line @typescript-eslint/no-unused-vars - Arguments = VerifierEventHandlerMap, -> extends TypedEventEmitter { + // eslint-disable-next-line @typescript-eslint/no-unused-vars + Events extends string = VerifierEvent, + // eslint-disable-next-line @typescript-eslint/no-unused-vars + Arguments = VerifierEventHandlerMap, + > + extends TypedEventEmitter + implements Verifier +{ private cancelled = false; private _done = false; private promise: Promise | null = null; diff --git a/src/crypto/verification/QRCode.ts b/src/crypto/verification/QRCode.ts index a51db2e34..1a7538583 100644 --- a/src/crypto/verification/QRCode.ts +++ b/src/crypto/verification/QRCode.ts @@ -36,6 +36,7 @@ export type QrCodeEvent = VerifierEvent; /** @deprecated use VerifierEvent */ export const QrCodeEvent = VerifierEvent; +/** @deprecated Avoid referencing this class directly; instead use {@link Crypto.Verifier}. */ export class ReciprocateQRCode extends Base { public reciprocateQREvent?: ShowQrCodeCallbacks; diff --git a/src/crypto/verification/SAS.ts b/src/crypto/verification/SAS.ts index f15adf585..b5063c01d 100644 --- a/src/crypto/verification/SAS.ts +++ b/src/crypto/verification/SAS.ts @@ -219,6 +219,7 @@ export type SasEvent = VerifierEvent; /** @deprecated use VerifierEvent */ export const SasEvent = VerifierEvent; +/** @deprecated Avoid referencing this class directly; instead use {@link Crypto.Verifier}. */ export class SAS extends Base { private waitingForAccept?: boolean; public ourSASPubKey?: string;