Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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

A Bookshelf.js plugin for securely handling passwords.


  • 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.


yarn add bookshelf-secure-password


npm install bookshelf-secure-password --save


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

  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.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


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 })


 * 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 })
    .then(function (user) {
      return user.authenticate(password)


  • BCrypt requires that passwords are 72 characters maximum (it ignores characters after 72).
  • This library enables the bookshelf-virtuals-plugin 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


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