Skip to main content

Class: MFAStrategy

Defined in: src/auth/MFAStrategy.ts:187

Implements a multi-factory authentication (MFA) strategy that performs basic id and password verification, followed by a secondary authentication. This strategy requires an existing user account to have already registered a valid password that will be validated as well as at least one secondary authentication method.

Supported secondary authentication (2FA) methods:

  • FIDO2 - A hardware-based key challenge exchange that the user has access to (e.g. Yubikey, Passkey, etc).
  • OTP - A One Time Password (OTP) sent to one of the user's verified contacts.
  • TOTP - A Time-Based One Time Password (TOTP) configured on a device the user owns or has access to.

The login flow has three phases:

  1. Verify Basic - The client sends a request with the user's id and password, either as a JSON/form body ({ id, password }) or via an Authorization: Basic header. The server returns { uid, methods }: the user's internal uid (needed to identify subsequent phase 2/3 requests as this session's, regardless of what login identifier — email, alias, etc. — was used for phase 1) and the list of available secondary authentication methods.
  2. Challenge - The client requests a selected 2FA challenge, submitting the uid from phase 1 as id and identifying the method by methodId. If FIDO2 is selected, a WebAuthn challenge scoped to that credential is generated and stored in the session. If OTP is selected, a challenge token is generated, stored in the session, and sent to the selected verified contact. If TOTP is selected, no challenge/notification is generated or sent — the client's authenticator app already has the current code — but the selection is still recorded in the session so phase 3 knows which secret to verify against.
  3. Verify - The client submits the completed 2FA challenge. The challenge is verified against the one stored in the session, and the associated user is resolved using the getUser() callback.

Implements​

  • AuthStrategy

Constructors​

Constructor​

new MFAStrategy(options): MFAStrategy

Defined in: src/auth/MFAStrategy.ts:191

Parameters​

options​

MFAStrategyOptions

Returns​

MFAStrategy

Properties​

name​

readonly name: string = "mfa"

Defined in: src/auth/MFAStrategy.ts:188

The unique name of the strategy used to register with the AuthMiddleware.

Implementation of​

AuthStrategy.name

Methods​

authenticate()​

authenticate(req, res, required?): Promise<AuthResult | undefined>

Defined in: src/auth/MFAStrategy.ts:195

Attempts to perform authentication with the given request data. If authentication was successful, returns an AuthResult containing the authentication details. If authentication fails and required is set to true throws an error, otherwise returns undefined.

Parameters​

req​

HttpRequest

The request containing data to attempt authentication with.

res​

HttpResponse

The response to use when writing back directly to the client.

required?​

boolean

Returns​

Promise<AuthResult | undefined>

Implementation of​

AuthStrategy.authenticate

authenticateSync()​

authenticateSync(req, res, required?): AuthResult | undefined

Defined in: src/auth/MFAStrategy.ts:254

Attempts to perform authentication with the given request data. If authentication was successful, returns an AuthResult containing the authentication details. If authentication fails and required is set to true throws an error, otherwise returns undefined.

This is the synchronous version of authenticate that performs blocking based authentication.

Parameters​

req​

HttpRequest

The request containing data to attempt authentication with.

res​

HttpResponse

The response to use when writing back directly to the client.

required?​

boolean

Returns​

AuthResult | undefined

Implementation of​

AuthStrategy.authenticateSync

challenge()​

protected challenge(payload, req, res): Promise<void>

Defined in: src/auth/MFAStrategy.ts:258

Parameters​

payload​

any

req​

HttpRequest

res​

HttpResponse

Returns​

Promise<void>

verifyBasic()​

protected verifyBasic(payload, req, res): Promise<JWTUser | undefined>

Defined in: src/auth/MFAStrategy.ts:352

Parameters​

payload​

any

req​

HttpRequest

res​

HttpResponse

Returns​

Promise<JWTUser | undefined>

verifyFIDO()​

protected verifyFIDO(payload, req, res): Promise<JWTUser | undefined>

Defined in: src/auth/MFAStrategy.ts:395

Parameters​

payload​

any

req​

HttpRequest

res​

HttpResponse

Returns​

Promise<JWTUser | undefined>

verifyOTP()​

protected verifyOTP(payload, req, res): Promise<JWTUser | undefined>

Defined in: src/auth/MFAStrategy.ts:451

Parameters​

payload​

any

req​

HttpRequest

res​

HttpResponse

Returns​

Promise<JWTUser | undefined>

verifyRecoveryCode()​

protected verifyRecoveryCode(payload, req, res): Promise<JWTUser | undefined>

Defined in: src/auth/MFAStrategy.ts:506

Parameters​

payload​

any

req​

HttpRequest

res​

HttpResponse

Returns​

Promise<JWTUser | undefined>

verifyTOTP()​

protected verifyTOTP(payload, req, res): Promise<JWTUser | undefined>

Defined in: src/auth/MFAStrategy.ts:470

Parameters​

payload​

any

req​

HttpRequest

res​

HttpResponse

Returns​

Promise<JWTUser | undefined>