Skip to main content

MFA

@webda/core

Class: MFA

Defined in: packages/core/src/models/mfa.model.ts:247

Multi-Factor Authentication behavior: second factors and recovery codes of the model holding it.

Actions are exposed as <Model>.<Attribute>.<Action>. The configured login attribute also completes authentication. Other attributes use the model canAct(context, "<attribute>.<action>") policy. Verification records the operation in the session and returns a proof bound to the owner and attribute.

Attempts are counted atomically on the owner: a model holding the behavior declares them, as User does, _mfaAttempts: number = 0 and _lastMfaAttemptAt?: number.

Webda Behavior​

Webda/MFA

Constructors​

Constructor​

new MFA(data?): MFA

Defined in: packages/core/src/models/mfa.model.ts:270

Parameters​

data?​

any

initial or stored data

Returns​

MFA

Properties​

__recoveryCodes?​

optional __recoveryCodes?: string[]

Defined in: packages/core/src/models/mfa.model.ts:265

SHA-256 hashes of unused recovery codes, never output in clear text

factors​

factors: object = {}

Defined in: packages/core/src/models/mfa.model.ts:262

State of each configured second-factor method

Index Signature​

[method: string]: FactorEntry<any>

Parameters​

static Parameters: typeof MfaParameters = MfaParameters

Defined in: packages/core/src/models/mfa.model.ts:248

Accessors​

totp​

Get Signature​

get totp(): EncryptedField<TotpSecret>

Defined in: packages/core/src/models/mfa.model.ts:347

Encrypted TOTP secret field

Returns​

EncryptedField<TotpSecret>

the encrypted TOTP field

totpEnabledAt​

Get Signature​

get totpEnabledAt(): number

Defined in: packages/core/src/models/mfa.model.ts:355

Timestamp when TOTP was enabled

Returns​

number

enabled timestamp or undefined

Set Signature​

set totpEnabledAt(val): void

Defined in: packages/core/src/models/mfa.model.ts:363

Set timestamp when TOTP was enabled

Parameters​
val​

number

enabled timestamp

Returns​

void

totpLastStep​

Get Signature​

get totpLastStep(): number

Defined in: packages/core/src/models/mfa.model.ts:371

Last accepted time step for TOTP

Returns​

number

last step number or undefined

Set Signature​

set totpLastStep(val): void

Defined in: packages/core/src/models/mfa.model.ts:379

Set last accepted time step for TOTP

Parameters​
val​

number

last accepted step number

Returns​

void

Methods​

challenge()​

challenge(method): Promise<any>

Defined in: packages/core/src/models/mfa.model.ts:727

Send a code for a factor delivering codes (e.g. SMS), before confirming or verifying it.

Parameters​

method​

string

provider method, e.g. "sms"

Returns​

Promise<any>

challenge data, e.g. the masked destination and the code lifetime

clearFactor()​

clearFactor(method): void

Defined in: packages/core/src/models/mfa.model.ts:339

Remove a factor method

Parameters​

method​

string

factor method name

Returns​

void

confirm()​

confirm(method, code): Promise<any>

Defined in: packages/core/src/models/mfa.model.ts:713

Confirm a pending factor.

Parameters​

method​

string

provider method

code​

string

factor code

Returns​

Promise<any>

recovery codes and, for the login attribute, new tokens

confirmFactor()​

confirmFactor(method, code): Promise<{ recoveryCodes: string[]; }>

Defined in: packages/core/src/models/mfa.model.ts:581

Enable a pending factor with a valid code. Recovery codes are issued with the first factor and cover every factor: a factor added later keeps them and answers none

Parameters​

method​

string

method name

code​

string

code of the pending factor

Returns​

Promise<{ recoveryCodes: string[]; }>

the recovery codes issued, empty when the existing ones are kept

consumeRecoveryCode()​

consumeRecoveryCode(code): boolean

Defined in: packages/core/src/models/mfa.model.ts:449

Consume a recovery code (constant-time hash compare), does not save

Parameters​

code​

string

raw recovery code submitted by user

Returns​

boolean

true if valid and consumed

disable()​

disable(method, code): Promise<void>

Defined in: packages/core/src/models/mfa.model.ts:777

Disable a factor and remove session verification of this attribute.

Parameters​

method​

string

provider method

code​

string

factor or recovery code

Returns​

Promise<void>

disableFactor()​

disableFactor(method, code): Promise<void>

Defined in: packages/core/src/models/mfa.model.ts:625

Disable a factor with its code or a recovery code; the recovery codes go with the last factor

Parameters​

method​

string

method name

code​

string

code of this factor or a recovery code

Returns​

Promise<void>

enroll()​

enroll(method, input?): Promise<any>

Defined in: packages/core/src/models/mfa.model.ts:702

Start enrollment on this attribute.

Parameters​

method​

string

provider method, e.g. "totp"

input?​

any

provider-specific enrollment input

Returns​

Promise<any>

enrollment data

getFactor()​

getFactor<T>(method): FactorEntry<T>

Defined in: packages/core/src/models/mfa.model.ts:330

Get or create a factor entry, ensuring its data is an EncryptedField

Type Parameters​

T​

T = any

Parameters​

method​

string

factor method name (e.g. "totp")

Returns​

FactorEntry<T>

factor entry

getOwner()​

protected getOwner(): any

Defined in: packages/core/src/models/mfa.model.ts:298

Owning model (set by behavior hydration)

Returns​

any

the owner or undefined when detached

getParameters()​

getParameters(): MfaParameters

Defined in: packages/core/src/models/mfa.model.ts:254

Resolve the policy of this model attribute; detached credentials use defaults.

Returns​

MfaParameters

typed MFA configuration

getScope()​

getScope(): object

Defined in: packages/core/src/models/mfa.model.ts:661

Identity of this attached behavior, derived from model metadata rather than client input.

Returns​

object

the owner, attribute and operation prefix

attribute​

attribute: string

owner​

owner: any

prefix​

prefix: string

hasRecoveryCodes()​

hasRecoveryCodes(): boolean

Defined in: packages/core/src/models/mfa.model.ts:410

Returns​

boolean

true if unused recovery codes are available

isEnabled()​

isEnabled(method?): boolean

Defined in: packages/core/src/models/mfa.model.ts:388

Check if MFA is enabled (or a specific method is enabled)

Parameters​

method?​

string

method name to check (optional)

Returns​

boolean

true if enabled

methods()​

methods(): string[]

Defined in: packages/core/src/models/mfa.model.ts:400

List enabled second factor methods

Returns​

string[]

method names

recover()​

recover(code): Promise<any>

Defined in: packages/core/src/models/mfa.model.ts:767

Verify a recovery code for this attribute.

Parameters​

code​

string

recovery code

Returns​

Promise<any>

a proof and, when completing login, tokens

recoveryCodes()​

recoveryCodes(code): Promise<{ recoveryCodes: string[]; }>

Defined in: packages/core/src/models/mfa.model.ts:796

Replace recovery codes for this attribute.

Parameters​

code​

string

factor or recovery code

Returns​

Promise<{ recoveryCodes: string[]; }>

new recovery codes

regenerateRecoveryCodes()​

regenerateRecoveryCodes(code): Promise<{ recoveryCodes: string[]; }>

Defined in: packages/core/src/models/mfa.model.ts:642

Replace the recovery codes, with the code of any enabled factor or a recovery code

Parameters​

code​

string

verification code

Returns​

Promise<{ recoveryCodes: string[]; }>

the new recovery codes

sendChallenge()​

sendChallenge(method): Promise<any>

Defined in: packages/core/src/models/mfa.model.ts:557

Send a code for a pending or enabled factor, for methods delivering codes (e.g. SMS)

Parameters​

method​

string

method name

Returns​

Promise<any>

the challenge data for the client

startEnrollment()​

startEnrollment(method, input?): Promise<any>

Defined in: packages/core/src/models/mfa.model.ts:539

Start the enrollment of a factor, pending until confirmed

Parameters​

method​

string

method name

input?​

any

factor-specific enrollment input

Returns​

Promise<any>

the enrollment data for the client (e.g. TOTP secret and URI)

verify()​

verify(code, method?): Promise<any>

Defined in: packages/core/src/models/mfa.model.ts:757

Verify this attribute, completing login only when it is the configured login factor.

Parameters​

code​

string

factor or recovery code

method?​

string

optional method restriction

Returns​

Promise<any>

a proof and, when completing login, tokens

verifyCode()​

verifyCode(code, method?): Promise<string>

Defined in: packages/core/src/models/mfa.model.ts:605

Check a code: against one factor, as a recovery code with method "recovery", or without method against every enabled factor then the recovery codes

Parameters​

code​

string

submitted code

method?​

string

method to check with

Returns​

Promise<string>

the method that accepted the code

verifyTotp()​

verifyTotp(code, window?, now?): Promise<boolean>

Defined in: packages/core/src/models/mfa.model.ts:421

Verify a code against the confirmed or pending secret; enforces window + single use, does not save

Parameters​

code​

string

submitted code

window?​

number = 1

allowed time step drift (default 1)

now?​

number

optional timestamp in milliseconds (defaults to Date.now())

Returns​

Promise<boolean>

true if verified and not replayed