Interface VerificationRequest

An incoming, or outgoing, request to verify a user or a device via cross-signing.

interface VerificationRequest {
    get accepting(): boolean;
    get cancellationCode(): string | null;
    get cancellingUserId(): string | undefined;
    get chosenMethod(): string | null;
    get declining(): boolean;
    get initiatedByMe(): boolean;
    get isSelfVerification(): boolean;
    get methods(): string[];
    get otherDeviceId(): string | undefined;
    get otherUserId(): string;
    get pending(): boolean;
    get phase(): VerificationPhase;
    get roomId(): string | undefined;
    get timeout(): number | null;
    get transactionId(): string | undefined;
    get verifier(): Verifier | undefined;
    accept(): Promise<void>;
    addListener<T extends EventEmitterEvents | Change>(
        event: T,
        listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
    ): this;
    cancel(params?: { code?: string; reason?: string }): Promise<void>;
    emit<T extends Change>(
        event: T,
        ...args: Parameters<VerificationRequestEventHandlerMap[T]>,
    ): boolean;
    emit<T extends Change>(
        event: T,
        ...args: Parameters<VerificationRequestEventHandlerMap[T]>,
    ): boolean;
    emitPromised<T extends Change>(
        event: T,
        ...args: Parameters<VerificationRequestEventHandlerMap[T]>,
    ): Promise<boolean>;
    emitPromised<T extends Change>(
        event: T,
        ...args: Parameters<VerificationRequestEventHandlerMap[T]>,
    ): Promise<boolean>;
    generateQRCode(): Promise<Uint8ClampedArray<ArrayBufferLike> | undefined>;
    listenerCount(event: EventEmitterEvents | Change): number;
    listeners(event: EventEmitterEvents | Change): Function[];
    off<T extends EventEmitterEvents | Change>(
        event: T,
        listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
    ): this;
    on<T extends EventEmitterEvents | Change>(
        event: T,
        listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
    ): this;
    once<T extends EventEmitterEvents | Change>(
        event: T,
        listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
    ): this;
    otherPartySupportsMethod(method: string): boolean;
    prependListener<T extends EventEmitterEvents | Change>(
        event: T,
        listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
    ): this;
    prependOnceListener<T extends EventEmitterEvents | Change>(
        event: T,
        listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
    ): this;
    rawListeners(event: EventEmitterEvents | Change): Function[];
    removeAllListeners(event?: EventEmitterEvents | Change): this;
    removeListener<T extends EventEmitterEvents | Change>(
        event: T,
        listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
    ): this;
    scanQRCode(qrCodeData: Uint8ClampedArray): Promise<Verifier>;
    startVerification(method: string): Promise<Verifier>;
}

Hierarchy (View Summary)

TypedEventEmitter<VerificationRequestEvent, VerificationRequestEventHandlerMap>
- VerificationRequest

Accessors

accepting

get accepting(): boolean
True if we have started the process of sending an m.key.verification.ready (but have not necessarily received the remote echo which causes a transition to VerificationPhase.Ready.

Returns boolean
- Defined in src/crypto-api/verification.ts:70

cancellationCode

get cancellationCode(): string | null
If this request has been cancelled, the cancellation code (e.g m.user) which is responsible for cancelling this verification.

Returns string | null
- Defined in src/crypto-api/verification.ts:179

cancellingUserId

get cancellingUserId(): string | undefined
The id of the user that cancelled the request.

Only defined when phase is Cancelled

Returns string | undefined
- Defined in src/crypto-api/verification.ts:186

chosenMethod

get chosenMethod(): string | null
the method picked in the .start event

Returns string | null
- Defined in src/crypto-api/verification.ts:89

declining

get declining(): boolean
True if we have started the process of sending an m.key.verification.cancel (but have not necessarily received the remote echo which causes a transition to VerificationPhase.Cancelled).

Returns boolean
- Defined in src/crypto-api/verification.ts:76

initiatedByMe

get initiatedByMe(): boolean
True if this request was initiated by the local client.

For in-room verifications, the initiator is who sent the m.key.verification.request event. For to-device verifications, the initiator is who sent the m.key.verification.start event.

Returns boolean
- Defined in src/crypto-api/verification.ts:47

isSelfVerification

get isSelfVerification(): boolean
True if the other party in this request is one of this user's own devices.

Returns boolean
- Defined in src/crypto-api/verification.ts:56

methods

get methods(): string[]
once the phase is Started (and !initiatedByMe) or Ready: common methods supported by both sides

Returns string[]
- Defined in src/crypto-api/verification.ts:86

otherDeviceId

get otherDeviceId(): string | undefined
For verifications via to-device messages: the ID of the other device. Otherwise, undefined.

Returns string | undefined
- Defined in src/crypto-api/verification.ts:53

otherUserId

get otherUserId(): string
The user id of the other party in this request

Returns string
- Defined in src/crypto-api/verification.ts:50

pending

get pending(): boolean
True if the request has sent its initial event and needs more events to complete (ie it is in phase Requested, Ready or Started).

Returns boolean
- Defined in src/crypto-api/verification.ts:64

phase

get phase(): VerificationPhase
current phase of the request.

Returns VerificationPhase
- Defined in src/crypto-api/verification.ts:59

roomId

get roomId(): string | undefined
For an in-room verification, the ID of the room.

For to-device verifictions, undefined.

Returns string | undefined
- Defined in src/crypto-api/verification.ts:39

timeout

get timeout(): number | null
The remaining number of ms before the request will be automatically cancelled.

null indicates that there is no timeout

Returns number | null
- Defined in src/crypto-api/verification.ts:83

transactionId

get transactionId(): string | undefined
Unique ID for this verification request.

An ID isn't assigned until the first message is sent, so this may be undefined in the early phases.

Returns string | undefined
- Defined in src/crypto-api/verification.ts:32

verifier

get verifier(): Verifier | undefined
The verifier which is doing the actual verification, once the method has been established. Only defined when the phase is Started.

Returns Verifier | undefined
- Defined in src/crypto-api/verification.ts:157

Methods

accept

accept(): Promise<void>
Accepts the request, sending a .ready event to the other party

Returns Promise<void>
Promise which resolves when the event has been sent.
- Defined in src/crypto-api/verification.ts:107

addListener

addListener<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this
Alias for on.
Type Parameters
- T extends EventEmitterEvents | Change
Parameters
- event: T
- listener: Listener<Change, VerificationRequestEventHandlerMap, T>
Returns this
Inherited from TypedEventEmitter.addListener
- Defined in src/models/typed-event-emitter.ts:70

cancel

cancel(params?: { code?: string; reason?: string }): Promise<void>
Cancels the request, sending a cancellation to the other party
Parameters
- Optionalparams: { code?: string; reason?: string }
  Details for the cancellation, including reason (defaults to "User declined"), and code (defaults to m.user). Deprecated: this parameter is ignored by the Rust cryptography implementation.
Returns Promise<void>
Promise which resolves when the event has been sent.
- Defined in src/crypto-api/verification.ts:117

emit

emit<T extends Change>(
event: T,
...args: Parameters<VerificationRequestEventHandlerMap[T]>,
): boolean
Synchronously calls each of the listeners registered for the event named event, in the order they were registered, passing the supplied arguments to each.
Type Parameters
- T extends Change
Parameters
- event: T
  The name of the event to emit
- ...args: Parameters<VerificationRequestEventHandlerMap[T]>
  Arguments to pass to the listener
Returns boolean
true if the event had listeners, false otherwise.
Inherited from TypedEventEmitter.emit
- Defined in src/models/typed-event-emitter.ts:86
emit<T extends Change>(
event: T,
...args: Parameters<VerificationRequestEventHandlerMap[T]>,
): boolean
Synchronously calls each of the listeners registered for the event named event, in the order they were registered, passing the supplied arguments to each.
Type Parameters
- T extends Change
Parameters
- event: T
  The name of the event to emit
- ...args: Parameters<VerificationRequestEventHandlerMap[T]>
  Arguments to pass to the listener
Returns boolean
true if the event had listeners, false otherwise.
Inherited from TypedEventEmitter.emit
- Defined in src/models/typed-event-emitter.ts:87

emitPromised

emitPromised<T extends Change>(
event: T,
...args: Parameters<VerificationRequestEventHandlerMap[T]>,
): Promise<boolean>
Similar to emit but calls all listeners within a Promise.all and returns the promise chain
Type Parameters
- T extends Change
Parameters
- event: T
  The name of the event to emit
- ...args: Parameters<VerificationRequestEventHandlerMap[T]>
  Arguments to pass to the listener
Returns Promise<boolean>
true if the event had listeners, false otherwise.
Inherited from TypedEventEmitter.emitPromised
- Defined in src/models/typed-event-emitter.ts:98
emitPromised<T extends Change>(
event: T,
...args: Parameters<VerificationRequestEventHandlerMap[T]>,
): Promise<boolean>
Similar to emit but calls all listeners within a Promise.all and returns the promise chain
Type Parameters
- T extends Change
Parameters
- event: T
  The name of the event to emit
- ...args: Parameters<VerificationRequestEventHandlerMap[T]>
  Arguments to pass to the listener
Returns Promise<boolean>
true if the event had listeners, false otherwise.
Inherited from TypedEventEmitter.emitPromised
- Defined in src/models/typed-event-emitter.ts:102

generateQRCode

generateQRCode(): Promise<Uint8ClampedArray<ArrayBufferLike> | undefined>
Generate the data for a QR code allowing the other device to verify this one, if it supports it.

Returns the QR code data only when all of the following hold; otherwise it returns undefined:
- phase is VerificationPhase.Ready;
- the other party advertises support for scanning a QR code (ie, otherPartySupportsMethod("m.qr_code.scan.v1") is true); and
- this device has its cross-signing keys available locally. A frequent cause of an unexpected undefined is that cross-signing has not been set up or the keys have not yet been fetched, so the QR code cannot be constructed even though the phase and method checks pass.
On success, display the returned bytes as a QR code for the other device to scan; if the other side scans it and confirms, there is nothing further to do on this side.
Returns Promise<Uint8ClampedArray<ArrayBufferLike> | undefined>
- Defined in src/crypto-api/verification.ts:173

listenerCount

listenerCount(event: EventEmitterEvents | Change): number
Returns the number of listeners listening to the event named event.
Parameters
- event: EventEmitterEvents | Change
  The name of the event being listened for
Returns number
Inherited from TypedEventEmitter.listenerCount
- Defined in src/models/typed-event-emitter.ts:115

listeners

listeners(event: EventEmitterEvents | Change): Function[]
Returns a copy of the array of listeners for the event named event.
Parameters
- event: EventEmitterEvents | Change
Returns Function[]
Inherited from TypedEventEmitter.listeners
- Defined in src/models/typed-event-emitter.ts:122

off

off<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this
Alias for removeListener
Type Parameters
- T extends EventEmitterEvents | Change
Parameters
- event: T
- listener: Listener<Change, VerificationRequestEventHandlerMap, T>
Returns this
Inherited from TypedEventEmitter.off
- Defined in src/models/typed-event-emitter.ts:129

on

on<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this
Adds the listener function to the end of the listeners array for the event named event.

No checks are made to see if the listener has already been added. Multiple calls passing the same combination of event and listener will result in the listener being added, and called, multiple times.

By default, event listeners are invoked in the order they are added. The prependListener method can be used as an alternative to add the event listener to the beginning of the listeners array.
Type Parameters
- T extends EventEmitterEvents | Change
Parameters
- event: T
  The name of the event.
- listener: Listener<Change, VerificationRequestEventHandlerMap, T>
  The callback function
Returns this
a reference to the EventEmitter, so that calls can be chained.
Inherited from TypedEventEmitter.on
- Defined in src/models/typed-event-emitter.ts:150

once

once<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this
Adds a one-time listener function for the event named event. The next time event is triggered, this listener is removed and then invoked.

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 prependOnceListener method can be used as an alternative to add the event listener to the beginning of the listeners array.
Type Parameters
- T extends EventEmitterEvents | Change
Parameters
- event: T
  The name of the event.
- listener: Listener<Change, VerificationRequestEventHandlerMap, T>
  The callback function
Returns this
a reference to the EventEmitter, so that calls can be chained.
Inherited from TypedEventEmitter.once
- Defined in src/models/typed-event-emitter.ts:169

otherPartySupportsMethod

otherPartySupportsMethod(method: string): boolean
Checks whether the other party supports a given verification method. This is useful when setting up the QR code UI, as it is somewhat asymmetrical: if the other party supports SCAN_QR, we should show a QR code in the UI, and vice versa. For methods that need to be supported by both ends, use the methods property.
Parameters
- method: string
  the method to check
Returns boolean
true if the other party said they supported the method
- Defined in src/crypto-api/verification.ts:100

prependListener

prependListener<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this
Adds the listener function to the beginning of the listeners array for the event named event.

No checks are made to see if the listener has already been added. Multiple calls passing the same combination of event and listener will result in the listener being added, and called, multiple times.
Type Parameters
- T extends EventEmitterEvents | Change
Parameters
- event: T
  The name of the event.
- listener: Listener<Change, VerificationRequestEventHandlerMap, T>
  The callback function
Returns this
a reference to the EventEmitter, so that calls can be chained.
Inherited from TypedEventEmitter.prependListener
- Defined in src/models/typed-event-emitter.ts:186

prependOnceListener

prependOnceListener<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this
Adds a one-timelistener function for the event named event to the beginning of the listeners array. The next time event is triggered, this listener is removed, and then invoked.
Type Parameters
- T extends EventEmitterEvents | Change
Parameters
- event: T
  The name of the event.
- listener: Listener<Change, VerificationRequestEventHandlerMap, T>
  The callback function
Returns this
a reference to the EventEmitter, so that calls can be chained.
Inherited from TypedEventEmitter.prependOnceListener
- Defined in src/models/typed-event-emitter.ts:202

rawListeners

rawListeners(event: EventEmitterEvents | Change): Function[]
Returns a copy of the array of listeners for the event named eventName, including any wrappers (such as those created by .once()).
Parameters
- event: EventEmitterEvents | Change
Returns Function[]
Inherited from TypedEventEmitter.rawListeners
- Defined in src/models/typed-event-emitter.ts:243

removeAllListeners

removeAllListeners(event?: EventEmitterEvents | Change): this
Removes all listeners, or those of the specified event.

It is bad practice to remove listeners added elsewhere in the code, particularly when the EventEmitter instance was created by some other component or module (e.g. sockets or file streams).
Parameters
- Optionalevent: EventEmitterEvents | Change
  The name of the event. If undefined, all listeners everywhere are removed.
Returns this
a reference to the EventEmitter, so that calls can be chained.
Inherited from TypedEventEmitter.removeAllListeners
- Defined in src/models/typed-event-emitter.ts:219

removeListener

removeListener<T extends EventEmitterEvents | Change>(
event: T,
listener: Listener<Change, VerificationRequestEventHandlerMap, T>,
): this
Removes the specified listener from the listener array for the event named event.
Type Parameters
- T extends EventEmitterEvents | Change
Parameters
- event: T
- listener: Listener<Change, VerificationRequestEventHandlerMap, T>
Returns this
a reference to the EventEmitter, so that calls can be chained.
Inherited from TypedEventEmitter.removeListener
- Defined in src/models/typed-event-emitter.ts:232

scanQRCode

scanQRCode(qrCodeData: Uint8ClampedArray): Promise<Verifier>
Start a QR code verification by providing a scanned QR code for this verification flow.

Call this once the user has scanned the QR code displayed by the other device (for example, the bytes produced by that device's VerificationRequest#generateQRCode). Validates the QR code, and if it is ok, sends an m.key.verification.start event with method set to m.reciprocate.v1, to tell the other side the scan was successful.

See also VerificationRequest#startVerification which can be used to start other verification methods.
Parameters
- qrCodeData: Uint8ClampedArray
  the decoded QR code.
Returns Promise<Verifier>
A verifier; call .verify() on it to wait for the other side to complete the verification flow.
- Defined in src/crypto-api/verification.ts:151

startVerification

startVerification(method: string): Promise<Verifier>
Send an m.key.verification.start event to start verification via a particular method.

This is used for SAS (emoji) verification: method should be set to m.sas.v1. It does not start QR-code verification, and passing a QR-code method (such as m.reciprocate.v1, m.qr_code.scan.v1, or m.qr_code.show.v1) will be rejected with an "Unsupported verification method" error.

For QR-code verification, use VerificationRequest#generateQRCode to display a QR code to the other device, or VerificationRequest#scanQRCode to consume a QR code scanned from it. This is only possible once the phase is VerificationPhase.Ready; when it is, a client can typically offer the user any of three options: show a QR code, scan the other party's QR code, or fall back to emoji (SAS) verification via this method.
Parameters
- method: string
  the name of the verification method to use.
Returns Promise<Verifier>
The verifier which will do the actual verification.
- Defined in src/crypto-api/verification.ts:136

Interface VerificationRequest

Hierarchy (View Summary)

Index

Accessors

Methods

Accessors

accepting

Returns boolean

cancellationCode

Returns string | null

cancellingUserId

Returns string | undefined

chosenMethod

Returns string | null

declining

Returns boolean

initiatedByMe

Returns boolean

isSelfVerification

Returns boolean

methods

Returns string[]

otherDeviceId

Returns string | undefined

otherUserId

Returns string

pending

Returns boolean

phase

Returns VerificationPhase

roomId

Returns string | undefined

timeout

Returns number | null

transactionId

Returns string | undefined

verifier

Returns Verifier | undefined

Methods

accept

Returns Promise<void>

addListener

Type Parameters

Parameters

Returns this

cancel

Parameters

Returns Promise<void>

emit

Type Parameters

Parameters

Returns boolean

Type Parameters

Parameters

Returns boolean

emitPromised

Type Parameters

Parameters

Returns Promise<boolean>

Type Parameters

Parameters

Returns Promise<boolean>

generateQRCode

Returns Promise<Uint8ClampedArray<ArrayBufferLike> | undefined>

listenerCount

Parameters

Returns number

listeners

Parameters

Returns Function[]

off

Type Parameters

Parameters

Returns this

on

Type Parameters

Parameters

Returns this

once

Type Parameters