Element-R: Pull out an interface from VerificationBase (#3414)

* pull out `Verifier` interface

* Mark old classes as deprecated

* Update integration tests to use new interface

Author: richvdh

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();
 

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<VerifierEvent, VerifierEventHandlerMap> {
+    /**
+     * 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<void>;
+
+    /**
+     * 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",
 

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<VerifierEvent, VerifierEventHandlerMap> {
+        // 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<VerifierEvent, VerifierEventHandlerMap>
+    implements Verifier
+{
     private cancelled = false;
     private _done = false;
     private promise: Promise<void> | null = null;

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;
 

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;