mongoose-devise

Another flexible authentication solution for mongoosejs.

Requires:

Node >8.0.0.

Mongoose >5.0.0.

Usage

Standard installation of the plugin:

const mongoose = require('mongoose')
const devise = require('mongoose-devise')
// or
// const { devise } = require('mongoose-devise')
 
const UserSchema = new mongoose.Schema({})
UserSchema.plugin(devise)
 
mongoose.model('User', UserSchema)

IMPORTANT

• only the most common methods are documented. For more information check the tests
• in all cases, the opts parameter will be used to pass some configuration to the sendNotification method.

Registerable

module that allows you to register an access account or, disable a registered account.

#register(credentials, opts) :

a static method used to register credentials. It will return the registered user or the corresponding errors of the registration attempt.

const faker = require('faker')
 
User.register({
  email: faker.internet.email(),
  password: faker.internet.password()
})
.then(user)
.catch(error)

#unregister(beforeUnregister, afterUnregister) :

an instance method that lets you unregister (destroy a user). It receives two callbacks the parameter, one that executes before and the other after the save the object.

user.unregister(
  function () {
    // something before..
  },
  function () {
    // something later
  }
)
// #=> true

NOTE The implementation currently assigns the value of unregisteredAt to the current date.

Confirmable

TIP identifiable by the flag account_confirmation.

module that verifies whether an account has already been confirmed or conveys instructions for confirmation.

#confirm(confirmationToken) :

this static method receives a valid validationToken string to be able to confirm the unconfirmed record. Returns a user or the errors.

User.confirm('confirmation-token-valid')
  .then(user)
  .catch(error)

#confirm() :

instance method that confirms the account registration. Returns a boolean or errors in the process.

Examples

user.confirm()
  .then(isConfirmed)
  .catch(error)

#isConfirmed() :

verifies whether a user is confirmed or not.

Examples

user.isConfirmed()
// #=> true

Authenticable

authenticatable module, responsible for hashing the password and validating the authenticity of a user while signing in.

#authenticate(password, opts) :

authenticates the user's instance from a password passed by parameter. If no errors are processed, a boolean will be returned.

Examples

user.authenticate('secret')
  .then(isAuthenticated)
  .catch(error)

#authenticate(credentials, opts) :

a static method which takes in credentials in the format:

const faker = require('faker')
 
const credentials = {
  email: faker.internet.email(),
  password: faker.internet.password()
}

where a valid email and password corresponding to a database user must be reported. At the end, the user of the provided credentials will be returned, otherwise the corresponding errors.

Examples

User.authenticate(credentials)
  .then(user)
  .catch(error)

#validPassword(password) :

an instance method which takes in a plain string password and compare with the instance hashed password to see if they match.

Examples

user.validPassword('secret')
// #=> true

Recoverable

TIP identifiable by the flag password_recovery.

module that establishes user password reset and sends resetting instructions.

#recover(recoveryToken, newPassword) :

a static method used to retrieve an account bound to a recoverToken string. It receives two parameters, the first is the token and the second the new recovery password. Returns the linked user or any errors that occur.

Examples

User.recover('recovery-token-valid', 'new-password')
  .then(user)
  .catch(error)

#requestRecover(credentials, opts) :

a model static method which is used to request account password recovery. Returns the user or any errors that occur.

Examples

User.requestRecover({ email })
  .then(user)
  .catch(error)

Lockable

TIP identifiable by the flag account_recovery.

provide a means of locking an account after a specified number of failed sign-in attempts (defaults to 3 attempts).

NOTE user can unlock account via unlock instructions issued.

#lock(opts) :

an instance method that is used to lock an account. When invoked, it will check if the number of failedAttempts is greater than the configured maximum allowed login attempts, if so the account will get locked by setting lockedAt to the current timestamp.

Examples

user.lock()
  .then(isLocked)
  .catch(error)

#isLocked() :

verifies whether a user is locked or not.

Examples

user.isLocked()
// #=> true

#unlock(unlockToken) :

a static method that unlocks a locked account with the provided unlockToken string.

• If the token expires, the new unlockToken will be generated.
• If the token is valid, the locked account will be unlocked and the unlockedAt attribute will be set to the current date and time. failedAttempts will be set to 0.

Examples

User.unlock('unlock-token-valid')
  .then(user)
  .catch(error)

Trackable

provide a means of tracking user signin activities.

track(ipAddress) :

this is the instance method that will update the tracking details. Optionally receives a valid ip string.

user.track()

Sending Notifications

the default implementation of mongoose-devise to send notifications is simple. This is because there are different use case(s) when it comes on sending notifications.

due to that reason, mongoose-devise requires that your model implements sendNotification method which accept record, action, done as its argurments.

record :

refer to the current user model instance.

action :

refer to the type of notifcation to be sent. There are just three types which are account_confirmation, account_recovery and password_recovery which are sent when new account is registered, when an account is locked and need to be unlocked and when account is requesting to recover the password respectively.

done :

is the callback that you must call after finishing sending the notification. By default this callback will update the notification send details based on the usage.

• all the methods that accept the opts parameter, pass this parameter to the callback done

Examples

const UserSchema = new Schema({})
 
// override send method i.e your notification sending: email, sms, etc
schema.methods.sendNotification = function (record, action, done) {
  done(opts => {
    // const host = isObject(opts) && (isObject(opts.req) && opts.req.isSecure())
    //   ? 'https'
    //   : 'http' + '://' + uri
 
    switch (action) {
      // if we send `confirmation email`
      case 'account_confirmation':
        console.log('Action type: %s.\nRecord: %s \n', action, JSON.stringify(record))
        break
 
      // if we send `account recovery`
      case 'password_recovery':
        console.log('Action type: %s.\nRecord: %s \n', action, JSON.stringify(record))
        break
 
      // if we send `account locked` information
      case 'account_recovery':
        console.log('Action type: %s.\nRecord: %s \n', action, JSON.stringify(record))
        break
 
      default:
        console.log('mailer', 'Template not found')
    }
  })
}

Sending issues

It is recommended to use job queue like kue or bull when implementing your send to reduce your API response time.

Custom messages

mongoose-devise uses messages to customize your application, you can configure the message definition variables manually

It is recommended to use an internalizer such as i18nex or node-i18n when implementing the support layer to the language.

// custom to pt-BR, default is en-US.
userSchema.plugin(devise, {
  authenticationFieldMessage: 'Endereço de email inválido',
  // authenticable
  authenticatorError: 'O {{field}} não foi informada',
  passwordError: 'Senha não informada',
  authenticatorNotExistError: 'Esse email não existe',
  credentialsNotExistError: 'Credênciais incorretas',
 
  // confirmable
  invalidConfirmationTokenError: 'Token de confirmação inválido',
  confirmationTokenExpiredError: 'Token de confirmação expirou',
  accountNotConfirmedError: 'Conta não confirmada',
 
  // registerable
  definitionsNotFoundError: 'Dados básicos não encontrados',
 
  // lockable
  accountLockedError: 'Conta bloqueada. Verifique as instruções de desbloqueio enviadas para o seu email',
  invalidUnlockTokenError: 'Token de desbloqueio inválido',
  unlockTokenExpiredError: 'Token de desbloqueio expirado',
 
  // recoverable
  accountWithoutAssociationError: 'Não existe conta associada a esse email',
  invalidRecoveryTokenError: 'Token de recuperação recusado',
  recoveryTokenExpiredError: 'Token de recuperação expirado'
})

See complete MVC solution based on Restify engines;

Restify Devise

Thanks

Inspired by irina.

Test

• Install all development dependencies

npm install

• Then run test

npm test

License

MIT

Copyright (c) 2018-present