pass-hash-toolkit

You don't know how to handle your passwords for your Auth system? You are scared about not guaranteeing a fully secure password storage? You'll find everything you need in this module!

What does this module

To sum up, it allows interaction with password hashing and salting. For those who don't know, a password needs to be crypted when it is stored, to prevent malevolent people from using it. This way, if the hacker manages to get your password, they cannot use it as it is crypted.

One way to encrypt passwords is turning it into a hash. It is an asymmetric process: it means you cannot decode the message from the encoded version.

In addition to that, we often add an extra security: the salt. It is generally random bytes generated when a user signs up, that modifies the hash. That implies, two users having the same password won't have the same hash, since their salt, generated randomly, is different.

What will you find

You will have access to functions like generateSalt() that will give you a random salt, getSaltedHash(password) which gives you a salted hash with the salt at the end, and many more!

This module is written in TypeScript

It wraps around the crypto module, and uses the script hash function.

How to install

To install this package, you can use this command

npm install pass-hash-toolkit --registry https://r.privjs.com

How to use

The module is centered around the Encrypt class, which contains all the functions. You will need to instanciate the class with (or without) parameters, specifying the hash and salt lengths

/**
 * Builds an object containing hashing automation functions
 * @param rawHashLength Raw hash length (default: 64)
 * I recommend at least 32 of length (that means a 32-long string of hexadecimal characters)
 * @param saltLength Salt length (default: 16)
 * I recommand at least 8 of length.
 */
public constructor(rawHashLength: number = 64, saltLength: number = 16)

You can generate a random salt by yourself with the generateSalt() function. It will take the length you passed in parameter when you instanciated the class.

/**
 * Returns a salt, which length is {@link Encrypt.saltLength saltLength} long
 * @returns the salt
 * @internal
 */
public generateSalt(): Buffer

If you ever want to hash a password with a specific salt, you can use the hash(password, salt) function. It will return a rawHashLength-length hexadecimal string.

/**
 * Gets the hash from given password and salt
 * @param password password to hash (this is the **clear password**)
 * @param salt salt to add to the hash
 * @returns hashed password
 * @internal
 */
public async hash(password: string, salt: Buffer): Buffer;

The salt is often stored at the end of the hash string. That means if you have ab8c6910f23a169c12bb2391678 as hash string and a,çèi$^ùab as the salt, the result will be ab8c6910f23a169c12bb2391678a,çèi$^ùab. You can directly store this into your database safely without questioning yourself.

/**
 * Returns a salted hash of a password
 * This is a concatenation of the password hash and the salt. It is meant to be stores directly in your database. You will need it for authentication.
 * @param password clear password to hash
 * @returns a salted hash
 */
public async getSaltedHash(password: string): Promise<Buffer>

Eventually, you can now store secured passwords, but you will need something to verify that when a user logs in, the password they gave is the same as the one that is stored in the database. That's why the verify function exists: it will tell you if the password matches. If it matches, the user can be logged in safely: the password is good.

/**
 * Function that verifies if a hash and a password match.
 * This is used to authenticate someone.
 * 
 * If this method returns true, the user has typed the good password
 * @param completeHash Complete hash (hash and salt, i.e. the output of the {@link Encrypt.getSaltedHash getSaltedHash} function)
 * @param clearPassword Clear password (i.e. the password as the user types it)
 * @returns true if hash and password match.
 */
public verify(completeHash: Buffer, clearPassword: string): boolean

You are now ready to start your authentication system!

Examples

Here are some examples for you to understand better how to use the module.

Let's suppose that you have a SQL database for these examples, with database.query() a function that sends queries to it.

Sign up

function signUp(username: string, password: string) {
    const enc = new Encrypt(); // Instanciate the Encrypt class
    const encodedPassword = enc.getSaltedHash(password); // Get the salted hash from the password the user typed
    database.query("INSERT INTO User VALUES(?, ?)", username, encodedPassword) // Saves into database the username and the encrypted password
}

Log in

function login(username: string, password: string) {
    const enc = new Encrypt(); // Instanciate the Encrypt class
    const hash = database.query("SELECT password FROM User WHERE username = ?", username); // Fetch the stored hash password
    const auth = enc.verify(hash, password); // Get the salted hash from the password the user is trying to connect
    if (auth) {
        return "You are logged in!"
    } else {
        return "The username or password are incorrect. Please try again."
    }
}

Any Questions

If you have any questions or any issues, you can email me at theo2001@laposte.net, I'd be glad to help you!