Modules

Class AuthenticationEngine<Account>

Authentication Engine manages user authentication and account.

Type parameters

Account: AccountModel

Hierarchy

AuthenticationEngine

Constructors

constructor

Methods

Constructors

constructor

new AuthenticationEngine<Account>(options: AuthenticationEngineOptions<Account>): AuthenticationEngine<Account>

Type parameters
- Account: AccountModel
Parameters
- options: AuthenticationEngineOptions<Account>
Returns AuthenticationEngine<Account>

Methods

activateAccount

activateAccount(activateAccountToken: string): Promise<void>

Activate previously registered account.

throws

{Exception} With code:
- ErrorCodes.SESSION_NOT_FOUND when token is not valid
- ErrorCodes.ACCOUNT_WITH_DUPLICATED_FIELDS when account contains duplicated fields. This scenario might occur because unactivated accounts are stored in a temporary storage ActivateAccountSessionRepository and while user tries to activate his account, another user was able to register an account with same fields and activate it before (very unlikely, but still might happen). In case this exception is thrown, user account registration is considered failed and user to register another account.

Parameters
- activateAccountToken: string
  
  Activate account token.
Returns Promise<void>

authenticate

authenticate(authenticationContext: AuthenticationContext): Promise<AuthenticationStatus<Account>>

Authenticates user.

Authentication process consists from multiple AuthenticationStepName and is performed in a state machine fashion. Authentication process state is persisted by AuthenticationSession and FailedAuthenticationAttemptSession.

Transition to next state/step is announced to client via AuthenticationStatus.nextStep. Depending on this, he needs to provide additional data.
When an error is encountered, it will be set into AuthenticationStatus.error. In case it is a AuthenticationStatusError.soft error caused by invalid credentials, user can continue authentication from AuthenticationStatus.nextStep. In case it is a AuthenticationStatusError.hard error, user needs to abort authentication.
When password-less authentication by challenge-response mechanism is used, generated challenge will be sent by AuthenticationStatus.token property.
When authentication completes successfully, only AuthenticationStatus.authenticated property will be present in the authentication status.
The following AuthenticationStatus property combinations might be returned:
- AuthenticationStatus.nextStep - previous authentication step was performed successfully and client needs to move to next step
- AuthenticationStatus.nextStep and AuthenticationStatus.token - nonce was generated successfully by AuthenticationStepName.GENERATE_CHALLENGE step and stored in this property, client needs to move to next step AuthenticationStepName.CHALLENGE_RESPONSE
- AuthenticationStatus.nextStep and AuthenticationStatusError.soft - previous authentication step failed and client needs to move to next step (might be the same as previous one or differ)
- AuthenticationStatusError.hard - authentication failed with hard error, account was disabled and client needs to abort authentication.
- AuthenticationStatus.authenticated - authentication completed successfully
  
  Depending on the authentication next step, client needs to provide the following data:
- NONE - authentication needs to be started by client by either providing AuthenticationContextInterface.password or AuthenticationContextInterface.generateChallenge
- AuthenticationStepName.CHALLENGE_RESPONSE - client needs to provide encrypted nonce in the AuthenticationContextInterface.responseForChallenge
- AuthenticationStepName.PASSWORD - password was invalid and client needs to provide another AuthenticationContextInterface.password
- AuthenticationStepName.RECAPTCHA - invalid password/nonce was provided too many times and client needs to provide another AuthenticationContextInterface.password/AuthenticationContextInterface.responseForChallenge and also AuthenticationContextInterface.recaptcha
- AuthenticationStepName.TWO_FACTOR_AUTH_CHECK - client needs to provide 2fa token sent to him via side channel in the AuthenticationContextInterface.twoFactorAuthenticationToken
  
  On successful authentication, AuthenticationStatus.authenticated property will contain user account.
Parameters
- authenticationContext: AuthenticationContext
  
  Authentication context.
Returns Promise<AuthenticationStatus<Account>>

Authentication status.

changeForgottenPassword

changeForgottenPassword(token: string, newPassword: string): Promise<void>

Change forgotten password.
On successful password change, OnForgottenPasswordChangedHook will be called.
In case any exception is thrown, operation is considered failed, and user needs to start again account recovery (i.e. obtain a new forgot password token). This restriction is imposed in order to prevent replay attacks. The only exception from this rule is when ErrorCodes.SESSION_NOT_FOUND error code is thrown, as in this case forgot password token wasn't invalidated.

throws

{Exception} With code:
- ErrorCodes.SESSION_NOT_FOUND when token is not valid
- ErrorCodes.ACCOUNT_NOT_FOUND when account not found
- ErrorCodes.ACCOUNT_DISABLED when account is disabled
- ErrorCodes.WEAK_PASSWORD when new password is too weak

Parameters
- token: string
  
  Forgot password token issued by AuthenticationEngine.createForgotPasswordSession procedure.
  Token needs to be in plaintext.
- newPassword: string
  
  New account password.
Returns Promise<void>

changePassword

changePassword<Context>(changePasswordContext: Context): Promise<void>

Changes user password.
After successful changing, OnPasswordChangedHook will be called and then email notification will be sent to user by EmailSender.
In case any exception is thrown, operation is considered failed.

throws

{Exception} With code:
- ErrorCodes.ACCOUNT_NOT_FOUND when account id is not valid
- ErrorCodes.ACCOUNT_DISABLED when account is disabled.
- ErrorCodes.INCORRECT_PASSWORD when provided password is not valid
- ErrorCodes.SIMILAR_PASSWORDS when ChangePasswordContext.oldPassword is too similar with ChangePasswordContext.newPassword
- ErrorCodes.WEAK_PASSWORD when ChangePasswordContext.newPassword is too weak

Important! This method has authorization implications. It needs to be called only by authenticated users and they can change only their password.

Type parameters
- Context: ChangePasswordContext
Parameters
- changePasswordContext: Context
  
  Change password context.
Returns Promise<void>

createForgotPasswordSession

createForgotPasswordSession(accountUniqueFieldName: `readBy${Capitalize}`, accountUniqueFieldValue: string, sideChannel: "email" | "sms"): Promise<Account>

Creates forgot password session and starts account recovery procedure.
Creates forgot password token and sends it via specified sideChannel.
If account has AccountModel.pubKey, token will be encrypted before being sent to user. In this case user needs to decrypt token with his Private Key and send plaintext token back to server.
In case any exception is thrown, operation is considered failed.

Important! When account not found err is thrown, REST API should not respond with error, in order to prevent user enumeration, i.e it should respond with ok (something like token was sent to specified email, even if account doesn't exist).

throws

{Exception} With code:
- ErrorCodes.ACCOUNT_NOT_FOUND when account unique field value is not valid
- ErrorCodes.ACCOUNT_DISABLED when account is disabled
- ErrorCodes.NO_TELEPHONE_NUMBER when account has no telephone number
- ErrorCodes.UNKNOWN_CREATE_FORGOT_PASSWORD_SESSION_SIDE_CHANNEL when invalid sideChannel was provided.

Parameters
- accountUniqueFieldName: `readBy${Capitalize}`
  
  Name of the account field, value of which user remembers.
- accountUniqueFieldValue: string
  
  Value of that field.
- sideChannel: "email" | "sms"
  
  Side channel used to send token to user.
Returns Promise<Account>

User account.

disableAccount

disableAccount(accountId: string, until: number, cause: string): Promise<void>

Disable user account.

Important! This operation should be done only by admin, or by application's business logic.

Parameters
- accountId: string
  
  Account id.
- until: number
  
  Unix timestamp until account will be disabled.
  Use {@link UnixTimestamp} or AccountStatus.DISABLED_UNTIL_ACTIVATION to disable account for an undefined amount of time.
- cause: string
  
  String message that contains explanation why account is disabled.
Returns Promise<void>

enableAccount

enableAccount(accountId: string): Promise<void>

Enable user account.

Important! This operation should be done only by admin.

Parameters
- accountId: string
  
  Account id.
Returns Promise<void>

getFailedAuthentications

getFailedAuthentications(accountId: string, startingFrom?: number, endingTo?: number): Promise<FailedAuthenticationModel[]>

Get failed authentication attempts into user account.

Important! This method has authorization implications. It needs to be called only by authenticated users for their account or by admin.

Parameters
- accountId: string
  
  Account id.
- Optional startingFrom: number
  
  Starting timestamp.
- Optional endingTo: number
  
  Ending timestamp.
Returns Promise<FailedAuthenticationModel[]>

getSuccessfulAuthentications

getSuccessfulAuthentications(accountId: string, startingFrom?: number, endingTo?: number): Promise<SuccessfulAuthenticationModel[]>

Get successful authentications into user account.

Important! This method has authorization implications. It needs to be called only by authenticated users for their account or by admin.

Parameters
- accountId: string
  
  Account id.
- Optional startingFrom: number
  
  Starting timestamp.
- Optional endingTo: number
  
  Ending timestamp.
Returns Promise<SuccessfulAuthenticationModel[]>

register

Register user account.
When account is registered, multi factor authentication is disabled.
Depending on the AccountModel.disabledUntil value:
- AccountStatus.ENABLED - account is enabled and stored by AccountRepository
- AccountStatus.DISABLED_UNTIL_ACTIVATION - account is disabled until activation and stored by ActivateAccountSessionRepository; token is generated and sent by EmailSender
  In case any exception is thrown, registration fails and needs to be repeated.
throws

{Exception} When:
- provided AccountModel.passwordHash is weak.
- account contains duplicate fields.

Parameters
- account: AccountToBeRegistered<Account>
  
  Account to be registered.
  Plaintext password needs to be stored in the AccountModel.passwordHash property.
Returns Promise<void>

setTwoFactorAuthEnabled

setTwoFactorAuthEnabled(accountId: string, enabled: boolean, context?: SetTwoFactorAuthenticationContext): Promise<null | Record<string, any>>

Enable/Disable two factor authentication on the user's account.
When SetTwoFactorAuthenticationContext.password is given, it will be verified against the account one. If it is not valid, Exception with ErrorCodes.INCORRECT_PASSWORD will be thrown. If invalid password was provided too many times, Exception with ErrorCodes.ACCOUNT_DISABLED will be thrown.

Important! This method has authorization implications. It needs to be called only by authenticated users for their account.

throws

{Exception} With code:
- ErrorCodes.ACCOUNT_NOT_FOUND when account id is not valid
- ErrorCodes.ACCOUNT_DISABLED when account is disabled.
- ErrorCodes.INCORRECT_PASSWORD when provided password is not valid

Parameters
- accountId: string
  
  Account id.
- enabled: boolean
  
  Whether it's enabled or not.
- Optional context: SetTwoFactorAuthenticationContext
  
  Operation context.
Returns Promise<null | Record<string, any>>

Result of the TwoFactorAuthStrategy.onTwoFactorAuthEnabled method.
Please check the result type of the AuthenticationEngineOptions.twoFactorAuthStrategy that you've chosen

verifyPassword

verifyPassword(password: string, account: Account, context: BaseContext): Promise<boolean>

Verifies user password.

throws

{Exception} With code:
- ErrorCodes.ACCOUNT_DISABLED when invalid password was provided too many times

Parameters
- password: string
  
  Password provided by user.
- account: Account
  
  User account.
- context: BaseContext
  
  Operation context.
Returns Promise<boolean>

Whether password is valid or not.

Class AuthenticationEngine<Account>

Type parameters

Account: AccountModel

Hierarchy

Constructors

Methods

Constructors

constructor

Type parameters

Account: AccountModel

Parameters

options: AuthenticationEngineOptions<Account>

Returns AuthenticationEngine<Account>

Methods

activateAccount

Parameters

activateAccountToken: string

Returns Promise<void>

authenticate

Parameters

authenticationContext: AuthenticationContext

Returns Promise<AuthenticationStatus<Account>>

changeForgottenPassword

Parameters

token: string

newPassword: string

Returns Promise<void>

changePassword

Type parameters

Context: ChangePasswordContext

Parameters

changePasswordContext: Context

Returns Promise<void>

createForgotPasswordSession

Parameters

accountUniqueFieldName: `readBy${Capitalize}`

accountUniqueFieldValue: string

sideChannel: "email" | "sms"

Returns Promise<Account>

disableAccount

Parameters

accountId: string

until: number

cause: string

Returns Promise<void>

enableAccount

Parameters

accountId: string

Returns Promise<void>

getFailedAuthentications

Parameters

accountId: string

Optional startingFrom: number

Optional endingTo: number

Returns Promise<FailedAuthenticationModel[]>

getSuccessfulAuthentications

Parameters

accountId: string

Optional startingFrom: number

Optional endingTo: number

Returns Promise<SuccessfulAuthenticationModel[]>

register

Parameters

account: AccountToBeRegistered<Account>

Returns Promise<void>

setTwoFactorAuthEnabled

Parameters

accountId: string

enabled: boolean

Optional context: SetTwoFactorAuthenticationContext

Returns Promise<null | Record<string, any>>

verifyPassword

Parameters

password: string

account: Account

context: BaseContext

Returns Promise<boolean>