Skip to main content

Class: MFAStrategyOptions

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

Describes the configuration options that can be used to initialize MFAStrategy.

Constructors​

Constructor​

new MFAStrategyOptions(): MFAStrategyOptions

Returns​

MFAStrategyOptions

Properties​

encryptionKey?​

optional encryptionKey?: string

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

The 64-character hex encryption key (TOTPConfig.encryption_key) to decrypt a stored TOTP secret with before verifying, if secrets are encrypted at rest. Omit if secrets are stored as plaintext (the default) - see encryptTOTPSecret()/decryptTOTPSecret() in shared.ts.

fidoConfig?​

optional fidoConfig?: PasskeyConfig

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

The FIDO2/Passkey configuration to use when a FIDO2 secondary auth is used.

headerKey​

headerKey: string = "authorization"

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

The name of the header to look for when performing header based authentication. Default value is Authorization.

headerScheme​

headerScheme: string = "basic"

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

The authorization scheme type when using header based authentication. Default value is basic.

require2FA​

require2FA: boolean = true

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

Set to true to require that user's must provide secondary authentication to succeed, otherwise set to false. Default is true.

Methods​

checkRateLimit()?​

optional checkRateLimit(identifier, req): Promise<void>

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

Optional hook invoked with the claimed identifier before password/OTP verification. Implementations should throw to reject the request once a caller-defined attempt threshold has been exceeded (see RateLimiter). A no-op when not provided.

Parameters​

identifier​

string

req​

HttpRequest

Returns​

Promise<void>

consumeRecoveryCode()?​

optional consumeRecoveryCode(uid, codeIndex, req?): Promise<void>

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

Persists that the recovery code at codeIndex within the identified recovery-codes secret has been consumed, so it can never be used again. Called once, only after verifyRecoveryCode() has already matched the submitted code against that entry's hash. Optional — required only to support the RECOVERY_CODE secondary authentication method; without it, a verified code would remain usable indefinitely.

Parameters​

uid​

string

The unique id of the secondary auth method (== the underlying secret's id) that was verified.

codeIndex​

number

The index, within that secret's codes array, of the entry that was matched.

req?​

HttpRequest

The source HTTP request. Optional - only passed by verifyRecoveryCode(), so it's available to an implementation that wants to record e.g. the source IP the code was used from.

Returns​

Promise<void>

getCredentialById()​

getCredentialById(credentialId): Promise<StoredPasskeyCredential | undefined>

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

Retrieves a previously-registered FIDO2 credential by its ID, for verifying a FIDO2 secondary authentication challenge response. Returns undefined if no credential with that ID is known. NOTE: You must override this function to support the FIDO2 secondary authentication method.

Parameters​

credentialId​

string

Returns​

Promise<StoredPasskeyCredential | undefined>

getMethod()​

getMethod(id, uid): Promise<MFAMethod | undefined>

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

Retrieves the user's secondary authentication method for a given id. Implementations must only return a method that actually belongs to uid — this is the authorization boundary that prevents one user's 2FA challenge from being triggered/consumed using another user's authentication method. NOTE: You must override this function when using this strategy.

Parameters​

id​

string

The unique id of the secondary auth method to retrieve.

uid​

string

The unique id of the user the method must belong to.

Returns​

Promise<MFAMethod | undefined>

getMethods()​

getMethods(id): Promise<MFAMethod[]>

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

Retrieves the list of secondary authentication methods for the user with the given id. NOTE: You must override this function when using this strategy.

Parameters​

id​

string

The unique id of the user.

Returns​

Promise<MFAMethod[]>

getUser()​

getUser(uid): Promise<JWTUser | undefined>

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

Retrieves the user data for the given unique identifier after authentication has completed successfully. NOTE: You must override this function when using this strategy.

Parameters​

uid​

string

Returns​

Promise<JWTUser | undefined>

notifyContact()​

notifyContact(contact, totp): Promise<void>

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

Sends a notification to the specified contact with the provided MFA code. NOTE: You must override this function when using this strategy.

Parameters​

contact​

OTPContact

The contact to send the MFA code to.

totp​

string

The MFA code to send to the user.

Returns​

Promise<void>

updateCredentialCounter()​

updateCredentialCounter(credentialId, newCounter): Promise<void>

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

Persists the updated signature counter for the given FIDO2 credential after a successful challenge. Must be called on every successful FIDO2 secondary authentication to guard against cloned authenticators. NOTE: You must override this function to support the FIDO2 secondary authentication method.

Parameters​

credentialId​

string

newCounter​

number

Returns​

Promise<void>

updateSecretTimeStep()?​

optional updateSecretTimeStep(uid, timeStep): Promise<void>

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

Persists the given time step as the last one successfully used for the identified TOTP secret, so a captured/replayed token within its validity window can't be used to authenticate a second time. Optional — when omitted, successfully-verified TOTP codes remain valid for reuse until they naturally expire.

Parameters​

uid​

string

The unique id of the secondary auth method (== the underlying secret's id) that was verified.

timeStep​

number

The RFC 6238 time step at which the token was verified.

Returns​

Promise<void>

verify()​

verify(id, password): Promise<JWTUser | undefined>

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

Called to verify the provided user's id and password. NOTE: You must override this function when using this strategy.

Parameters​

id​

string

The unique id of the user whose password must be verified.

password​

string

The password of the user to verify.

Returns​

Promise<JWTUser | undefined>

The successfully verified user data, otherwise undefined.