Hashy
![PackagePhobia](https://badgen.net/packagephobia/install/hashy)
![Latest Commit](https://badgen.net/github/last-commit/JsCommunity/hashy)
Hash passwords the right way (Argon2 & bcrypt support)
Hashy is small Node.js library which aims to do
passwords hashing the correct
way.
It has been heavily inspired by the new PHP password hashing
API but, following
the Node.js philosophy, hashing is done asynchronously.
Furthermore, to make the interfaces as easy to use as possible, async
functions can either be used with callbacks or they return
promises
which will make them super easy to work with async functions!
Supported algorithms:
Why a new library?
The other ones I found were too complicated and/or were missing
important features.
The main missing feature is the needRehash()
function: cryptography
is a fast-moving science and algorithms can quickly become obsolete or
their parameters needs to be adjusted to compensate the performance
increase of recent computers (e.g. bcrypt cost
factor).
This is exactly what this function is for: checking whether a hash
uses the correct algorithm (and options) to see if we need to compute
a new hash for this password.
Install
Installation of the npm package:
> npm install --save hashy
Hashy requires promises support, for Node versions prior to 0.12 see
this page to
enable them.
How to use it?
First, you may take a look at examples: using callbacks, promises or async functions (requires Node >= 7.6).
Creating a hash
hashy.hash(password, function (error, hash) {
if (error) {
return console.log(error);
}
console.log("generated hash: ", hash);
});
hash()
handles additionaly two parameters which may be passed before the callback:
algo
: which algorithm to use, it defaults to 'bcrypt'
;options
: additional options for the current algorithm, for bcrypt
it defaults to {cost: 10}.
.
Checking a password against a hash
hashy.verify(password, hash, function (error, success) {
if (error) {
return console.error(err);
}
if (success) {
console.log("you are now authenticated!");
} else {
console.warn("invalid password!");
}
});
Getting information about a hash
const info = hashy.getInfo(hash);
Checking whether a hash is up to date
As I said earlier, we must be able to check
whether the hash is up to date, i.e. if it has been generated by the
last algorithm available with the last set of options.
if (hashy.needsRehash(hash)) {
}
It handles the optional algo
and options
parameters like
hash()
.
Changing default options.
The default options for a given algorithm is available at hashy.options[>algo<]
.
hashy.options.bcrypt.cost = 12;
Using promises
Same interface as above but without the callbacks!
hashy.hash(password).then(function (hash) {
console.log('generated hash:' hash)
})
hashy.verify(password, hash).then(function (success) {
if (success) {
console.log('you are now authenticated!')
} else {
console.warn('invalid password!')
}
})
As you can see, you don't even have to handle errors if you don't want
to!
Using async functions
Note: only available since Node.js 7.6.
Same interface as promises but much more similar to a synchronous
code!
(async function () {
const hash = await hashy.hash(password);
console.log("generated hash:", hash);
})()(
async function () {
if (await hashy.verify(password, hash)) {
console.log("you are now authenticated!");
} else {
console.warn("invalid password!");
}
},
)();
Contributing
Contributions are very welcome, either on the documentation or on
the code.
You may:
- report any issue
you've encountered;
- fork and create a pull request.
License
Hashy is released under the MIT
license.