The other ones I found were too complicated and/or were missing
important features.
The main missing feature is the needsRehash() function: cryptography
is a fast-moving science and algorithms can quickly become obsolete or
their parameters need to be adjusted to compensate the performance
increase of recent computers (see OWASP's recommended work
factors).
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 hashy
Command line
Hashy also comes with a hashy executable, install it globally to use
it from anywhere:
> npm install --global hashy
Hashing a password:
> hashy [ -a <algorithm> ] <secret>
Verifying a password against a hash:
> hashy <secret> <hash>
Use -c/--cost to change the cost when hashing or verifying with
Bcrypt, and hashy --help for the full list of options.
[!WARNING]
The secret is visible in your shell history and, while the command
runs, to other users of the machine (e.g. via ps).
A secret starting with - must be preceded by --, e.g. hashy -- -secret.
[!IMPORTANT]
All functions fail on invalid input (unknown algorithm, malformed
hash…): hash() and verify() reject, getInfo() and
needsRehash() throw. Handle errors with try/catch as usual.
Creating a hash
const hash = await hashy.hash(password);
hash() handles two additional optional parameters:
algo: which algorithm to use, it defaults to "argon2";
options: additional options for the current algorithm, for bcrypt
it defaults to { cost: 10 }, for argon2 to whatever the
argon2 package itself
defaults to.
[!NOTE]
Bcrypt silently truncates passwords over 72 bytes, which means two
different passwords sharing the same 72-byte prefix would hash (and
verify) identically. To avoid this pitfall, hash() rejects with an
error rather than truncate silently. verify() still accepts them so
that existing hashes keep working until they are rehashed. If you
need to support longer passwords, use argon2 (the default) instead.
Checking a password against a hash
async function login(user, password) { if (!(await hashy.verify(password, user.passwordHash))) { return false; } // The password is known at this point: it's the only time the hash // can be upgraded to the current algorithm and options. if (hashy.needsRehash(user.passwordHash)) { user.passwordHash = await hashy.hash(password); await user.save(); } return true;}
needsRehash() checks whether the hash uses the current algorithm
(including the Argon2 variant) and options (the bcrypt cost must not be
lower). Like hash(), it handles the optional
algo and options parameters.
hashy.verify(password, hash).then(function (success) { if (success) { console.log("you are now authenticated!"); } else { console.warn("invalid password!"); }}, console.error);
Callbacks
The callback is passed last, after the optional parameters. See the example.
hashy.verify(password, hash, function (error, success) { if (error) { return console.error(error); } if (success) { console.log("you are now authenticated!"); } else { console.warn("invalid password!"); }});
Contributing
Contributions are very welcome, either on the documentation or on
the code.