A Bookshelf.js plugin for handling secure passwords
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
.travis.yml
LICENSE.txt
README.md
package.json
yarn.lock

README.md

bookshelf-secure-password

Version Build Status Coverage Status Dependency Status Standard - JavaScript Style Guide License Downloads

A Bookshelf.js plugin for securely handling passwords.

Features

  • Securely store passwords in the database using BCrypt with ease.
  • Minimal setup required: just install the module, and make a password_digest column in the database!
  • Follows the latest security guidelines, using a BCrypt cost of 12
  • Inspired by and similar to has_secure_password in Ruby on Rails.

Installation

yarn add bookshelf-secure-password

or

npm install bookshelf-secure-password --save

Usage

  1. Enable the plugin in your Bookshelf setup
const bookshelf = require('bookshelf')(knex)
const securePassword = require('bookshelf-secure-password')

bookshelf.plugin(securePassword)
  1. Add hasSecurePassword to the model(s) which require a secure password
const User = bookshelf.Model.extend({
  tableName: 'users',
  hasSecurePassword: true
})

By default, this will use the database column named password_digest. To use a different column, simply change true to be the column name. For example:

const User = bookshelf.Model.extend({
  tableName: 'users',
  hasSecurePassword: 'custom_password_digest_field'
})
  1. Now, when you set a password and save the record, it will be hashed as password_digest:
user = new User({ password: 'testing' })
user.get('password') // => undefined
user.get('password_digest') // => undefined

user.save().then(function () {
  user.get('password') // => undefined
  user.get('password_digest') // => '$2a$12$SzUDit15feMdVCtfSzopc.0LuqeHlJInqq/1Ol8uxCC5QydHpVWFy'
})
  1. To authenticate against the password, simply call the instance method authenticate, which returns a Promise resolving to the authenticated Model.
user.authenticate('some-password').then(function (user) {
  // do something with the authenticated user
}, function (err) {
  // invalid password.
  // `err` will be of type `PasswordMismatchError`, which extends the `Error` class
})

Example

const User = require('./models/User')

/**
 * Sign up a new user.
 *
 * @returns {Promise.<User>} A promise resolving to the newly registered User, or rejected with an error.
 */
function signUp (email, password) {
  let user = new User({ email: email, password: password })

  return user.save()
}

/**
 * Sign in with a given email, password combination
 *
 * @returns {Promise.<User>} A promise resolving to the authenticated User, or rejected with a `PasswordMismatchError`.
 */
function signIn (email, password) {
  return User.forge({ email: email })
    .fetch()
    .then(function (user) {
      return user.authenticate(password)
    })
}

Notes

  • BCrypt requires that passwords are 72 characters maximum (it ignores characters after 72).
  • This library enables the built-in virtuals plugin on Bookshelf for the virtual password field.
  • Passing a null value to the password will clear the password_digest.
  • Passing undefined or a zero-length string to the password will leave the password_digest as-is

Testing

To run the tests locally, simply run yarn test or npm test