slynova-org/hash

🔐 Framework-agnostic driver based system for password hashing algorithms in Node.js

hash is a framework-agnostic package which provides a powerful wrapper for password hashing algorithms in Node.js.

There are currently 2 drivers available:

• Argon2
• Bcrypt

---

Getting Started

This package is available in the npm registry. It can easily be installed with npm or yarn.

$ npm i @slynova/hash
# or
$ yarn add @slynova/hash

When you require the package in your file, it will give you access to the HashManager class. This class is a facade for the package and should be instantiated with a configuration object.

const { HashManager } = require('@slynova/hash')
const hash = new HashManager(config)

Once you instantiated the manager, you can use the HashManager#use() method to retrieve a driver an use it.

hash.use() // Returns the default driver (specified in the config)
hash.use('argon2') // Returns the argon2 driver
hash.use('bcrypt', customConfig) // Overwrite the default configuration of the driver

Driver's API

Each driver implements the Interface Hash.

Methods

make(value: string, config?: Argon2Config | BcryptConfig): Promise<string>

This method will hash a plain value using the provided driver.

await hash.use('bcrypt').make('foo')
// $2b$10$RFgHztUoooIJEhuR4/e3ue4lZg36HYcIY2D7ptjB494FI/ctohaa6

verify(value: string, hash: string): Promise<boolean>

This method will verify an existing hash with the plain value using the provided driver.

await hash.use('bcrypt').verify('foo', '$2b$10$RFgHztUoooIJEhuR4/e3ue4lZg36HYcIY2D7ptjB494FI/ctohaa6')

Contribution Guidelines

Any pull requests or discussions are welcome. Note that every pull request providing new feature or correcting a bug should be created with appropriate unit tests.

hash's Issues

Proposal for API changes

The hash module is a great package when using standalone. However, I was thinking of making handful of changes to make it jell well in the AdonisJs ecosystem.

Using AdonisJs manager

The @poppinss/manager package is something I am planning to use for every component, which uses the builder pattern or has driver based API.

The package assumes that you will make use of the IoC container, which makes sense for AdonisJs, but not for packages to be used standalone. To encounter that, we need to write bit of extra code and hide the IoC container layer from the end user.

Main hash class

class Hash extends Manager {
  constructor (container) {
    super(container)
  }
}

Now when we register the Hash class as a provider to the IoC container, we can provider the Ioc container reference to the class constructor.

When using it standalone, we can wrap this class inside another class.

class HashStandalone extends Hash {
  constructor () {
    super({}) // passing empty object
  }
}

The HashStandalone is shared for standalone usage.

Using driver over use.

Since, I am planning to keep the API identical everywhere, I would love to replace use with driver method, and driver method already exists on the Manager class.

Using PHC string format

The Phc string format encodes the hashing info within the hash string and it makes it possible to upgrade older hash values whenever required.

Adding needsRehash

You shared this with me earlier and I think, it's a good idea to add support for needsRehash and we will need PHC string format for that.

WHAT YEAH THINK?