https://github.com/venables/bookshelf-secure-password
A Bookshelf.js plugin for handling secure passwords
https://github.com/venables/bookshelf-secure-password
bcrypt bookshelf bookshelf-plugin hash password secure secure-by-default secure-password security
Last synced: about 1 year ago
JSON representation
A Bookshelf.js plugin for handling secure passwords
- Host: GitHub
- URL: https://github.com/venables/bookshelf-secure-password
- Owner: venables
- License: mit
- Created: 2015-07-25T19:37:45.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2023-01-11T01:48:07.000Z (over 3 years ago)
- Last Synced: 2025-03-28T18:12:12.422Z (about 1 year ago)
- Topics: bcrypt, bookshelf, bookshelf-plugin, hash, password, secure, secure-by-default, secure-password, security
- Language: JavaScript
- Size: 534 KB
- Stars: 24
- Watchers: 3
- Forks: 14
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# bookshelf-secure-password
[](https://www.npmjs.com/package/bookshelf-secure-password)
[](https://travis-ci.org/venables/bookshelf-secure-password)
[](https://coveralls.io/github/venables/bookshelf-secure-password)
[](https://david-dm.org/venables/bookshelf-secure-password)
[](http://standardjs.com/)
[](https://github.com/venables/bookshelf-secure-password/blob/master/LICENSE.txt)
[](https://www.npmjs.com/package/bookshelf-secure-password)
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](http://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html) 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
```javascript
const bookshelf = require('bookshelf')(knex)
const securePassword = require('bookshelf-secure-password')
bookshelf.plugin(securePassword)
```
2. Add `hasSecurePassword` to the model(s) which require a secure password
```javascript
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:
```javascript
const User = bookshelf.Model.extend({
tableName: 'users',
hasSecurePassword: 'custom_password_digest_field'
})
```
3. Now, when you set a password and save the record, it will be hashed as `password_digest`:
```javascript
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'
})
```
4. To authenticate against the password, simply call the instance method `authenticate`, which returns a `Promise` resolving to the authenticated Model.
```javascript
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
```javascript
const User = require('./models/User')
/**
* Sign up a new user.
*
* @returns {Promise.} 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.} 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 `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
## Testing
To run the tests locally, simply run `yarn test` or `npm test`