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.

Alias

module:interactive-auth

Param

options object

Param

A matrix client to use for the auth process

Param

error response from the last request. If null, a request will be made with no auth before starting.

Param

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.

Param

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.

Param

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

Param

Inputs provided by the user and used by different stages of the auto process. The inputs provided will affect what flow is chosen.

Param

An email address. If supplied, a flow using email verification will be chosen.

Param

An ISO two letter country code. Gives the country that opts.phoneNumber should be resolved relative to.

Param

A phone number. If supplied, a flow using phone number validation will be chosen.

Param

If resuming an existing interactive auth session, the sessionId of that session.

Param

If resuming an existing interactive auth session, the client secret for that session

Param

If returning from having completed m.login.email.identity auth, the sid for the email verification session.

Param

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.

Hierarchy

  • InteractiveAuth

Constructors

constructor

Properties

attemptAuthDeferred busyChangedCallback? chosenFlow clientSecret currentStage data emailAttempt emailSid? inputs matrixClient requestCallback requestEmailTokenCallback requestingEmailToken stateUpdatedCallback submitPromise

Methods

attemptAuth chooseFlow chooseStage doRequest firstUncompletedStage getChosenFlow getClientSecret getEmailSid getSessionId getStageParams poll requestEmailToken setEmailSid startNextAuthStage submitAuthDict

Constructors

constructor

Properties

Private attemptAuthDeferred

attemptAuthDeferred: null | IDeferred<IAuthData> = null

Private Optional Readonly busyChangedCallback

busyChangedCallback?: ((busy: boolean) => void)

Type declaration

    • (busy: boolean): void

    • Parameters

      • busy: boolean

      Returns void

Private chosenFlow

chosenFlow: null | IFlow = null

Private Readonly clientSecret

clientSecret: string

Private currentStage

currentStage: null | string = null

Private data

data: IAuthData

Private emailAttempt

emailAttempt: number = 1

Private Optional emailSid

emailSid?: string

Private Readonly inputs

inputs: IInputs

Private Readonly matrixClient

matrixClient: MatrixClient

Private Readonly requestCallback

requestCallback: ((auth: null | IAuthData, background: boolean) => Promise<IAuthData>)

Type declaration

Private Readonly requestEmailTokenCallback

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

    • Parameters

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

      Returns Promise<{
          sid: string;
      }>

Private requestingEmailToken

requestingEmailToken: boolean = false

Private Readonly stateUpdatedCallback

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

Type declaration

Private submitPromise

submitPromise: null | Promise<void> = null

Methods

attemptAuth

  • 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>

Private chooseFlow

  • Private

    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

    If no suitable authentication flow can be found

    Returns IFlow

Private chooseStage

Private doRequest

  • Private

    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>

Private firstUncompletedStage

getChosenFlow

getClientSecret

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

    Returns

    client secret

    Returns string

getEmailSid

  • 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

getSessionId

  • get the auth session ID

    Returns

    session id

    Returns undefined | string

getStageParams

  • 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

  • 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>

requestEmailToken

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

    Returns Promise<void>

setEmailSid

  • 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

Private startNextAuthStage

  • Private

    Pick the next stage and call the callback

    Throws

    If no suitable authentication flow can be found

    Returns void

submitAuthDict

  • 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>

Settings

Member Visibility

Theme

Generated using TypeDoc