@vlasky/shacrypt 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [0.4.0] - 2025-06-27
+
+### Added
+- New ES6 async/await compatible functions: `sha256cryptAsync()` and `sha512cryptAsync()`
+- These functions return Promises and can be used with modern async/await syntax
+- Full test coverage for the new async functions
+
+### Changed
+- Updated documentation to include examples of the new async/await API
+
+## [0.3.0] - 2025-06-14
+
+### Added
+- Input validation and error handling to prevent crashes
+- Support for Node.js 16-23
+
+## [0.2.0] - 2019-12-16
+
+### Added
+- Asynchronous support through optional callback functions
+- Windows build compatibility improvements
+- Cross-platform portability enhancements
+
+### Changed
+- Updated nan to latest version 2.14.0 to make it work under Node.js v12
+- Replaced endian.h with portable_endian.h for better cross-platform support
+
+## Previous versions
+
+See git history for older changes.

package/README.md

@@ -4,9 +4,11 @@
 
 shacrypt provides cross-platform support for SHA-256 crypt and SHA-512 crypt in Node.js. It does not use the Node.js crypto API. Instead, it is implemented as a Node.js addon that wraps around the [C implementation programmed by Ulrich Drepper](http://www.akkadia.org/drepper/SHA-crypt.txt). This provides significantly increased performance.
 
-shacrypt provides two functions `sha256crypt()` and `sha512crypt()` that can be used both synchronously and asynchronously via callbacks.
+shacrypt provides four functions:
+- `sha256crypt()` and `sha512crypt()` - can be used both synchronously and asynchronously via callbacks
+- `sha256cryptAsync()` and `sha512cryptAsync()` - Promise-based async functions that support ES6 async/await
 
-Asynchronous mode is especially useful in that computation is performed in Node.js's libuv thread pool. This avoids blocking the event loop which results in better app responsiveness. As per Node.js convention, the callback function is provided as the final argument with the signature `function(error, result){}`.
+Asynchronous mode is especially useful in that computation is performed in Node.js's libuv thread pool. This avoids blocking the event loop which results in better app responsiveness. The callback-based functions follow Node.js convention with the callback function provided as the final argument with the signature `function(error, result){}`. The async/await functions return Promises and can be used with modern async/await syntax.
 
 ### Installation
 
@@ -17,35 +19,90 @@ npm install @vlasky/shacrypt
 NOTE: You will need to have C++ build tools installed on your system to successfully install the package. If you are running under Windows, you can download Microsoft's [Build Tools for Visual Studio 2017](https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2017).
 
 ### Usage
-* Prerequisite
+* Import the package:
 
 	```javascript
-	var shacrypt = require('shacrypt');
+	// CommonJS
+	const shacrypt = require('@vlasky/shacrypt');
+	
+	// ES6 modules
+	import * as shacrypt from '@vlasky/shacrypt';
 	```
 * Generate password hash:
 
 	```javascript
-	var hash = shacrypt.sha256crypt('super password');
+	const hash = shacrypt.sha256crypt('super password');
 	// hash = $5$rounds=5000$3a1afb28e54a0391$0d6RupbpABtxCaH8WWOemYwEcToDVZXX/tHpIy6O1U3
 	```
 * Validate password:
 
 	```javascript
-	console.log(hash == shacrypt.sha256crypt('super password', hash);
+	console.log(hash === shacrypt.sha256crypt('super password', hash));
 	// true
 	```
 * Specify number of rounds (default is 5000):
 
 	```javascript
-	var hash = shacrypt.sha256crypt('super password', 10000);
+	const hash = shacrypt.sha256crypt('super password', 10000);
 	// hash = $5$rounds=10000$b2c0a3ef466b2ec7$poVvVeQAQSE.yec0LBFddzQ9kZ4UxzA5VtsZQShAyt8
 	```
 * Provide your own SALT:
 
 	```javascript
-	var hash = shacrypt.sha256crypt('super password', 'my-salt');
+	const hash = shacrypt.sha256crypt('super password', 'my-salt');
 	// or with iterations=10000
-	var hash = shacrypt.sha256crypt('super password', 'my-salt', 10000);
+	const hash = shacrypt.sha256crypt('super password', 'my-salt', 10000);
+	```
+
+### Async/Await Usage
+
+The Promise-based async functions can be used with ES6 async/await syntax:
+
+* Basic usage with async/await:
+
+	```javascript
+	// CommonJS
+	const shacrypt = require('@vlasky/shacrypt');
+	
+	// ES6 modules
+	import * as shacrypt from '@vlasky/shacrypt';
+	
+	async function hashPassword() {
+	    const hash = await shacrypt.sha256cryptAsync('super password');
+	    console.log(hash);
+	    // hash = $5$rounds=5000$3a1afb28e54a0391$0d6RupbpABtxCaH8WWOemYwEcToDVZXX/tHpIy6O1U3
+	}
+	```
+
+* Validate password with async/await:
+
+	```javascript
+	async function validatePassword(password, hash) {
+	    const computedHash = await shacrypt.sha256cryptAsync(password, hash);
+	    return hash === computedHash;
+	}
+	```
+
+* Using SHA-512 with custom rounds:
+
+	```javascript
+	async function strongHash() {
+	    const hash = await shacrypt.sha512cryptAsync('super password', 'my-salt', 10000);
+	    console.log(hash);
+	}
+	```
+
+* Error handling:
+
+	```javascript
+	async function hashWithErrorHandling() {
+	    try {
+	        const hash = await shacrypt.sha512cryptAsync('password');
+	        return hash;
+	    } catch (error) {
+	        console.error('Hashing failed:', error);
+	    }
+	}
 	```
 
 ## Authors

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vlasky/shacrypt",
-  "description": "Wrapper over sha256-crypt and sha512-crypt functions originally created by Ulrich Drepper https://www.akkadia.org/drepper/SHA-crypt.txt",
-  "version": "0.3.0",
+  "description": "Node.js wrapper over sha256-crypt and sha512-crypt functions originally created by Ulrich Drepper https://www.akkadia.org/drepper/SHA-crypt.txt",
+  "version": "0.4.0",
   "homepage": "https://github.com/vlasky/shacrypt",
   "author": "Vlad Lasky <github@vladlasky.com> (https://github.com/vlasky/)",
   "contributors": [

package/shacrypt.js

@@ -1,20 +1,24 @@
 "use strict";
 
-var shacrypt = require('./build/Release/shacrypt');
-var crypto   = require('crypto');
+const shacrypt = require('./build/Release/shacrypt');
+const crypto   = require('crypto');
+const util     = require('util');
 
-var isString = function(obj) {
-	return Object.prototype.toString.call(obj) == '[object String]';
+const sha256cryptAsync = util.promisify(shacrypt.sha256cryptasync);
+const sha512cryptAsync = util.promisify(shacrypt.sha512cryptasync);
+
+const isString = (obj) => {
+	return Object.prototype.toString.call(obj) === '[object String]';
 };
 
-var isNumber = function(obj) {
-	return Object.prototype.toString.call(obj) == '[object Number]';
+const isNumber = (obj) => {
+	return Object.prototype.toString.call(obj) === '[object Number]';
 };
 
 function validate(prefix, password, salt, rounds) {
 
-	var _salt = salt,
-		_rounds = rounds || 5000;
+	const _rounds = rounds || 5000;
+	let _salt = salt;
 
 	if (!isString(password)) {
 		throw new Error('password must be a String');
@@ -24,12 +28,12 @@ function validate(prefix, password, salt, rounds) {
 		_salt = crypto.randomBytes(16).toString('hex');
 
 		if (isNumber(salt)) {
-			_salt = prefix + 'rounds=' + salt + '$' + _salt;
+			_salt = `${prefix}rounds=${salt}$${_salt}`;
 		}
 	}
 
-	if (isNumber(_rounds) && _salt.indexOf(prefix) == -1) {
-		_salt = prefix + 'rounds=' + _rounds + '$' + _salt;
+	if (isNumber(_rounds) && _salt.indexOf(prefix) === -1) {
+		_salt = `${prefix}rounds=${_rounds}$${_salt}`;
 	}
 
 	return _salt;
@@ -74,3 +78,33 @@ exports.sha512crypt = function(password, salt, rounds, callback) {
           return shacrypt.sha512crypt(password, salt);
         }
 };
+
+/**
+ * Generate SHA256-CRYPT hash (async/await compatible)
+ *
+ * @param  {String} password
+ * @param  {String} [salt]
+ * @param  {Number} [rounds]
+ * @return {Promise<String>}
+ */
+exports.sha256cryptAsync = async function(password, salt, rounds) {
+
+	salt = validate('$5$', password, salt, rounds);
+
+	return sha256cryptAsync(password, salt);
+};
+
+/**
+ * Generate SHA512-CRYPT hash (async/await compatible)
+ *
+ * @param  {String} password
+ * @param  {String} [salt]
+ * @param  {Number} [rounds]
+ * @return {Promise<String>}
+ */
+exports.sha512cryptAsync = async function(password, salt, rounds) {
+
+	salt = validate('$6$', password, salt, rounds);
+
+	return sha512cryptAsync(password, salt);
+};

package/test/tests.js

@@ -2,9 +2,9 @@
 
 /* global it  */
 
-var shacrypt = require('../shacrypt');
+const shacrypt = require('../shacrypt');
 
-var tests256 = [
+const tests256 = [
     ["$5$saltstring", "Hello world!",
         "$5$saltstring$5B8vYYiY.CVt1RlTTf8KbXBH3hsxY/GNooZaBBGWEc5"
     ],
@@ -36,7 +36,7 @@ var tests256 = [
     ],
 ];
 
-var tests512 = [
+const tests512 = [
     ["$6$saltstring", "Hello world!",
         "$6$saltstring$svn8UoSVapNtMuq1ukKS4tPQd8iKwSMHWjl/O817G3uBnIFNjnQJuesI68u4OTLiBFdcbYEdFCoEOfaS35inz1"
     ],
@@ -98,6 +98,22 @@ tests512.forEach(function(test) {
     });
 });
 
+describe('Async/await functions', function() {
+    tests256.forEach(function(test) {
+        it(test[1] + ' (async/await)', async function() {
+            const result = await shacrypt.sha256cryptAsync(test[1], test[0]);
+            result.should.be.eql(test[2]);
+        });
+    });
+
+    tests512.forEach(function(test) {
+        it(test[1] + ' (async/await)', async function() {
+            const result = await shacrypt.sha512cryptAsync(test[1], test[0]);
+            result.should.be.eql(test[2]);
+        });
+    });
+});
+
 describe('Input validation', function() {
     it('should throw error for non-string password in sha256crypt', function() {
         expect(function() {
@@ -145,4 +161,32 @@ describe('Input validation', function() {
             done();
         }
     });
+
+    it('should reject with error for non-string password in sha256cryptAsync', async function() {
+        try {
+            await shacrypt.sha256cryptAsync(123, 'salt');
+            throw new Error('Expected error to be thrown');
+        } catch (e) {
+            e.message.should.equal('password must be a String');
+        }
+    });
+
+    it('should reject with error for non-string password in sha512cryptAsync', async function() {
+        try {
+            await shacrypt.sha512cryptAsync(null, 'salt');
+            throw new Error('Expected error to be thrown');
+        } catch (e) {
+            e.message.should.equal('password must be a String');
+        }
+    });
+
+    it('should generate salt when not provided in sha256cryptAsync', async function() {
+        const result = await shacrypt.sha256cryptAsync('password');
+        result.should.match(/^\$5\$/);
+    });
+
+    it('should generate salt when not provided in sha512cryptAsync', async function() {
+        const result = await shacrypt.sha512cryptAsync('password');
+        result.should.match(/^\$6\$/);
+    });
 });