@alphaapps/nestjs-auth

Authentication Module:

Installation:

npm install @alphaapps/nestjs-auth

This is the basic module for authentication, and it can be used as the following:

@Module({
  imports: [
    AuthModule.register({
      userModel: User,
      expiresIn: 0,
      oneSessionPerAccount: false,
      loginMethods: [{
        loginField: 'phoneNumber',
        passwordField: 'pin'
      }, {
        loginField: 'email',
        passwordField: 'password'
      }]
    })
  ]
})
export default class AppModule {}

Options passed to the register method:

• userModel: typeof AuthUser: Indicates the main model if the user in the system. This model must extend the AuthUser (can be imported from @alphaapps/nestjs-auth) model in order for it to work.
• expiresIn: number The age of the authentication token (in seconds). 0 means the token does NOT expire.
• oneSessionPerAccount: boolean: When set to true will generate a new token on each successful login.
• loginMethods: { loginField: string, passwordField: string }[]: The allowed login methods in the system.
• property?: string: The name of the property for the user object to be saved in the request. default: 'user'
• anonymousRole?: string: The name of the role in the system that can access specific resources anonymously. default: 'any'
• userFindOptions?: FindOptions: The options sent to database when selecting the user. This is useful when we want to include any relation and has it with the user object in the request.
• authModulePath?: string: The path of the authentication routes.
• firebaseOTPValidation?: boolean: Indicates whether we use Firebase OTP service, or our own. default: false
• useRoles?: boolean: Indicates whether we have roles in the system or not. default: true
• rolesRelationName?: string: The name of the roles relation in the User model. default: 'associatedRoles'
• sendOTPSMS?: (number: string, message: string, data: Record<string, any>) => Promise<void>: A function called when sending an SMS. This is useful when we want to customize the OTP message.

Included Models:

• AuthUser: The main User model, the User model in the system must extend this model to add its custom properties and relations. It already has an association with Rols model.
• Role: The model used to define roles and ACLs in the system.
• VerifiactionCode: Used to save verification codes when validating a phone number.

A Note about roles:

Roles are dynamic in our applications, meaning they are saved in the database and retrieved on every startup of the app. In order to use it for pre-defined roles (like customer, client, agent... etc) an array of default roles is passed to the initiation of the RolesModule like this:

RoleModule.register([{
  role: 'default',
  resource: 'User',
  action: 'read:own'
}, {
  role: 'default',
  resource: 'User',
  action: 'update:own'
}])

Hint: RoleModule can be imported from @alphaapps/nestjs-auth

Auth Routes:

There's a bunch of routes that are generated when using this module that can be used out of the box.
All APIs are prefixed with the authModulePath specified in the AuthModule.register method.

• validate-number:
  • Body:
    • phoneNumber: string
  • Response:
    • next: 'login' | 'register'
    • user: User
  • Headers:
    • Accept-Language
    • X-App-Version
    • X-Device-Platform
• signup:
  Creates a new user in the application. It internally calls User.alphaCreate method which can be overridden in the User model inside the application.
  • Body:
    • name: string
    • phoneNumber?: string
    • pin?: string
    • email?: string
    • password?: string
    • additionalData?: Record<string, unknown> This is used to include any additional info in the sign-up process.
  • Headers:
    • Accept-Language
    • X-App-Version
    • X-Device-Platform
  • Response:
    • user: User
    • token: string
• signin:
  • Body:
    • phoneNumber?: string
    • pin?: string
    • email?: string
    • password?: string
  • Response:
    • user: User
    • token: string
• validate-otp:
  • Body:
    • phoneNumber: string
    • code: string
• reset-pin:
  • Body:
    • phoneNumber: string
    • code: string
    • pin: string
  • Headers:
    • Accept-Language
    • X-App-Version
    • X-Device-Platform
  • Response:
    • user: User
    • token: string
• resend-otp:
  • Body:
    • phoneNumber: string
  • Headers:
    • Accept-Language
    • X-App-Version
    • X-Device-Platform

Hint: In order to override the behaviour of one (or more) of the routes a controller with the same path as authModulePath can be used.
IMPORTANT: This module (that has the overridden routes) BEFORE the AuthModule in the AppModule imports