Introduction

SecurePass (argon2-pass) is a module for the creation of hashes from passwords, allowing you to store passwords securely. The module also provides a facility for the generation and verification of one time authentication tokens for use in your own password reset flows. This module is a wrapper for libsodium's implementation of the Argon2ID password hashing algorithm and Poly1305.

Features

• Uses the state of the art, secure modern password hashing algorithm Argon2ID.
• Uses Buffer's for safer memory management.
• Uses static functions for basic operations, so you don't have to create a new instance every time.
• asynchronous functions are defined to work with async/await, promises and callbacks. Synchronous versions are also available just in-case you don't want your hashing and verification to be asynchronous.
• Allows for generation of one time use authentication tokens to be used in your own password reset flow.
• Easily configurable work factors, allowing you to increase the security of your hashes over time.
• Three default difficulty configurations for password hashing, as defined in libsodium's implementation. Allowing you to configure your security level based on some recommended predefined values.
• Simple rehashing of passwords you are already storing. Allowing you to improve the security of your hashes over time.
• The module is written in typescript and ships with a type definition file by default.

Installation

Install argon2-pass using yarn:

yarn add argon2-pass

Or via npm:

npm install argon2-pass

Usage

Basic Usage Information:

import { SecurePass, VerificationResult } from 'argon2-pass';

async function main() {
  // Create a new instance of SecurePass. Optional difficulty configurations can be passed in here.
  const sp = new SecurePass();
  
  // Passwords and Hashes are stored as buffers internally.
  const password = Buffer.from('SamplePassword');
  const hash = await sp.hashPassword(password);

  // Hash Verification returns an enumerator for easy validation of passwords against hashes.
  const result = await sp.verifyHash(password, hash);
  if (SecurePass.isInvalidOrUnrecognized(result)) { 
    console.log('Hash not created by SecurePass or invalid');
  } else if (SecurePass.isInvalid(result)) {
    console.log('Password not valid when compared with supplied hash');
  } else if (SecurePass.isValid(result)) {
    console.log('Password and Hash are a match');
  } else if (SecurePass.isValidNeedsRehash(result)) {
    console.log('Password and Hash are a match, but the security of the hash could be improved by rehashing.');
  }

  // Generation of one time authentication codes.
  const otac = SecurePass.generateOneTimeAuthCode(Buffer.from('DrBarnabus'));

  // Validate the one time authentication code with the random key.
  // The random key should never be sent with the code, and should be kept secret.
  if (SecurePass.verifyOneTimeAuthCode(otac.code, otac.key)) {
    console.log('OTA Code is valid!');
  } else {
    console.log('OTA Code is invalid!');
  }
}

// Call the async function defined above to run the example.
main();

For full documentation, please refer to the full documentation site. The documentation was generated automaticaly with TypeDoc.

Testing

This package is configured with jest tests, these tests ensure that the module is working correctly and as specified as well as generating code coverage reports to ensure every line of code is covered by a unit test.

To run the jest tests manualy run the test script defined in package.json:

yarn test

This module also has the following automated testing:

• CI Builds on Travis.
• Code Coverage Reports on CodeCov.
• Dependency Update Checks on david-dm.
• Dependency Vulnerabilities Checks on snyk.
• Automated Code Review and Quality Report on codacy.

Acknowledgements

• Special thanks to the creators of libsodium and sodium-native both of which are used extensively in this package, and without which the creation of this module wouldn't have been possible.

Licence

Licensed under MIT.

Copyright (C) 2018 DrBarnabus