Class InteractiveAuth

Abstracts the logic used to drive the interactive auth process.

Components implementing an interactive auth flow should instantiate one of these, passing in the necessary callbacks to the constructor. They should then call attemptAuth, which will return a promise which will resolve or reject when the interactive-auth process completes.

Meanwhile, calls will be made to the startAuthStage and doRequest callbacks, and information gathered from the user can be submitted with submitAuthDict.

Param

options object

Hierarchy

  • InteractiveAuth

Constructors

Properties

attemptAuthDeferred: null | IDeferred<IAuthData> = null
busyChangedCallback?: ((busy: boolean) => void)

Type declaration

    • (busy: boolean): void
    • Called whenever the interactive auth logic becomes busy submitting information provided by the user or finishes. After this has been called with true the UI should indicate that a request is in progress until it is called again with false.

      Parameters

      • busy: boolean

      Returns void

chosenFlow: null | IFlow = null
clientSecret: string
currentStage: null | string = null
data: IAuthData
emailAttempt: number = 1
emailSid?: string
inputs: IInputs
matrixClient: MatrixClient
requestCallback: ((auth: null | IAuthData, background: boolean) => Promise<IAuthData>)

Type declaration

    • (auth: null | IAuthData, background: boolean): Promise<IAuthData>
    • Called with the new auth dict to submit the request. Also passes a second deprecated arg which is a flag set to true if this request is a background request. The busyChanged callback should be used instead of the background flag. Should return a promise which resolves to the successful response or rejects with a MatrixError.

      Parameters

      Returns Promise<IAuthData>

requestEmailTokenCallback: ((email: string, secret: string, attempt: number, session: string) => Promise<{
    sid: string;
}>)

Type declaration

    • (email: string, secret: string, attempt: number, session: string): Promise<{
          sid: string;
      }>
    • A function that takes the email address (string), clientSecret (string), attempt number (int) and sessionId (string) and calls the relevant requestToken function and returns the promise returned by that function. If the resulting promise rejects, the rejection will propagate through to the attemptAuth promise.

      Parameters

      • email: string
      • secret: string
      • attempt: number
      • session: string

      Returns Promise<{
          sid: string;
      }>

requestingEmailToken: boolean = false
stateUpdatedCallback: ((nextStage: AuthType, status: IStageStatus) => void)

Type declaration

    • (nextStage: AuthType, status: IStageStatus): void
    • Called when the status of the UI auth changes, ie. when the state of an auth stage changes of when the auth flow moves to a new stage. The arguments are: the login type (eg m.login.password); and an object which is either an error or an informational object specific to the login type. If the 'errcode' key is defined, the object is an error, and has keys: errcode: string, the textual error code, eg. M_UNKNOWN error: string, human readable string describing the error

      The login type specific objects are as follows: m.login.email.identity: * emailSid: string, the sid of the active email auth session

      Parameters

      Returns void

submitPromise: null | Promise<void> = null

Methods

  • begin the authentication process.

    Returns

    which resolves to the response on success, or rejects with the error on failure. Rejects with NoAuthFlowFoundError if no suitable authentication flow can be found

    Returns Promise<IAuthData>

  • Internal

    Pick one of the flows from the returned list If a flow using all of the inputs is found, it will be returned, otherwise, null will be returned.

    Only flows using all given inputs are chosen because it is likely to be surprising if the user provides a credential and it is not used. For example, for registration, this could result in the email not being used which would leave the account with no means to reset a password.

    Returns

    flow

    Throws

    NoAuthFlowFoundError If no suitable authentication flow can be found

    Returns IFlow

  • Internal

    Pick the next auth stage

    Returns

    login type

    Throws

    NoAuthFlowFoundError If no suitable authentication flow can be found

    Returns undefined | AuthType

  • Internal

    Fire off a request, and either resolve the promise, or call startAuthStage.

    Parameters

    • auth: null | IAuthData

      new auth dict, including session id

    • background: boolean = false

      If true, this request is a background poll, so it failing will not result in the attemptAuth promise being rejected. This can be set to true for requests that just poll to see if auth has been completed elsewhere.

    Returns Promise<void>

  • get the client secret used for validation sessions with the identity server.

    Returns

    client secret

    Returns string

  • Gets the sid for the email validation session Specific to m.login.email.identity

    Returns

    The sid of the email auth session

    Returns undefined | string

  • get the auth session ID

    Returns

    session id

    Returns undefined | string

  • get the server params for a given stage

    Returns

    any parameters from the server for this stage

    Parameters

    • loginType: string

      login type for the stage

    Returns undefined | Record<string, any>

  • Poll to check if the auth session or current stage has been completed out-of-band. If so, the attemptAuth promise will be resolved.

    Returns Promise<void>

  • Requests a new email token and sets the email sid for the validation session

    Returns Promise<void>

  • Sets the sid for the email validation session This must be set in order to successfully poll for completion of the email validation. Specific to m.login.email.identity

    Parameters

    • sid: string

      The sid for the email validation session

    Returns void

  • Internal

    Pick the next stage and call the callback

    Throws

    NoAuthFlowFoundError If no suitable authentication flow can be found

    Returns void

  • submit a new auth dict and fire off the request. This will either make attemptAuth resolve/reject, or cause the startAuthStage callback to be called for a new stage.

    Parameters

    • authData: IAuthDict

      new auth dict to send to the server. Should include a type property denoting the login type, as well as any other params for that stage.

    • background: boolean = false

      If true, this request failing will not result in the attemptAuth promise being rejected. This can be set to true for requests that just poll to see if auth has been completed elsewhere.

    Returns Promise<void>

Generated using TypeDoc