scrypt-for-humans

A human-friendly API wrapper for the Node.js Scrypt bindings, because the default bindings kind of suck.

This module will change and do the following things for you:

• Input values (passwords, usually) are expected in utf-8.
• Output/hash values are base64-encoded, and can be stored directly in your data store of choice.
• Scrypt parameters are set to scrypt.params(0.1), this can be overridden on a per-hash basis (see API documentation below).
• Scrypt errors, which are now proper Error types in the original library but still not easily distinguishable, are caught and rethrown as one of three correctly-inheriting Error types (see API documentation below). This means you can handle them like any other kind of Error.

The API supports both Promises and nodebacks.

License

WTFPL or CC0, whichever you prefer.

Donate

My income consists entirely of donations for my projects. If this module is useful to you, consider making a donation!

You can donate using Bitcoin, PayPal, Gratipay, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else.

Contributing

Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the .coffee files, not the .js files.

As this module could potentially deal with authentication, tests are needed; a pull request for those would be especially welcome.

Build tool of choice is gulp; simply run gulp while developing, and it will watch for changes.

Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.

Usage

var scrypt = require("scrypt-for-humans");
var Promise = require("bluebird");

/* Using Promises */

var theHash;

Promise.try(function(){
	return scrypt.hash("secretpassword");
}).then(function(hash){
	console.log("The hash is " + hash);
	theHash = hash;

	/* Now let's see if it verifies - number 1 is correct. */
	return scrypt.verifyHash("secretpassword", theHash);
}).then(function(){
	console.log("Number 1 was correct!");
}).catch(scrypt.PasswordError, function(err){
	console.log("Number 1 was wrong!");
}).then(function(){
	/* And let's see if it fails correctly - number 2 is wrong. */
	return scrypt.verifyHash("wrongpassword", theHash);
}).then(function(){
	console.log("Number 2 was correct!");
}).catch(scrypt.PasswordError, function(err){
	console.log("Number 2 was wrong!");
});

/* Using nodebacks */

scrypt.hash("secretpassword", {}, function(err, hash){
	console.log("The hash is " + hash);

	/* Now let's see if it verifies - number 1 is correct. */
	scrypt.verifyHash("secretpassword", hash, function(err, result){
		if(err) {
			console.log("Number 1 was wrong!", err);
		} else {
			console.log("Number 1 was correct!");
		}

		/* And let's see if it fails correctly - number 2 is wrong. */
		scrypt.verifyHash("wrongpassword", hash, function(err, result){
			if(err) {
				console.log("Number 2 was wrong!", err);
			} else {
				console.log("Number 2 was correct!");
			}
		});
	});
});

Upgrading to 2.0.0

Due to changes in the underlying scrypt library, there has been a minor indirect change in our documented API as well. Specifically, scrypt.scryptLib.params is now asynchronous by default, with (poor) support for ES6 Promises. The new documentation can be found here. Due to its inconsistent behaviour, I recommend manual promisification using Bluebird or es6-promisify.

The other changes in scrypt do not affect the scrypt-for-humans API, other than introducing support for Node.js 4. If you were not using custom params, you can remain using scrypt-for-humans like you have done previously.

API

scrypt.hash(input, [options, [callback]])

Creates a hash.

• input: The input to hash, usually a password.
• options: Optional. Custom options.
  • options.params: Sets the Scrypt parameters to use. Defaults to scrypt.params(0.1). If you want to change these, you'll probably need scrypt.scryptLib (documented below).
• callback: Optional. A nodeback to call upon completion. If omitted, the function will return a Promise.

If this is successful, the hash is returned as either the resolved Promise value or the second callback parameter, depending on the API you use.

If an error occurs, either the Promise will reject with it, or it will be passed as the first callback parameter, depending on the API you use. All errors correctly inherit from Error, and are documented below.

scrypt.verifyHash(input, hash, [callback])

Verifies an input against a hash.

• input: The input to hash, usually a password.
• hash: The hash to verify against, in base64 encoding (the default output format of scrypt.hash).
• callback: Optional. A nodeback to call upon completion. If omitted, the function will return a Promise.

If the input is correct and matches the hash, the Promise will resolve or the callback will be called with true as the value.

If the input does not match the hash, this is considered a PasswordError, not a false value!

If an error occurs, either the Promise will reject with it, or it will be passed as the first callback parameter, depending on the API you use. All errors correctly inherit from Error, and are documented below.

scrypt.PasswordError

This error is thrown if the input did not match the specified hash. The original error message is retained.

scrypt.InputError

This error is thrown if there is a different problem with the input (either the to-be-hashed value, or the hash), such as a malformed hash. The original error message is retained.

scrypt.InternalError

This error is thrown when an internal error of some other kind occurs in the scrypt library. The original error message is retained.

scrypt.scryptLib

Provides access to the underlying scrypt library that is used. Useful if you want to eg. specify custom Scrypt parameters.

Changelog

v1.0.0

Initial release.