@vlasky/shacrypt 0.2.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/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+shacrypt is a Node.js native addon that provides cross-platform support for SHA-256 crypt and SHA-512 crypt password hashing. It wraps around Ulrich Drepper's C implementation for high performance cryptographic operations.
+
+## Architecture
+
+- **Native C++ addon**: Built using node-gyp and NAN (Native Abstractions for Node.js)
+- **Core C implementations**: `sha256crypt.c` and `sha512crypt.c` contain the actual cryptographic algorithms
+- **Node.js wrapper**: `shacrypt.cc` provides the V8/Node.js bindings with both sync and async interfaces
+- **JavaScript API**: `shacrypt.js` provides the public API with input validation and parameter handling
+- **Dual execution modes**: Synchronous calls block the event loop, asynchronous calls use libuv thread pool
+
+## Key Files
+
+- `src/shacrypt.cc` - Main C++ addon code with NAN bindings
+- `src/sha256crypt.c` and `src/sha512crypt.c` - Core cryptographic implementations
+- `shacrypt.js` - JavaScript API wrapper with validation logic
+- `binding.gyp` - Build configuration for the native addon
+- `test/tests.js` - Comprehensive test vectors for both SHA-256 and SHA-512
+
+## Development Commands
+
+### Build the native addon
+```bash
+npm install
+# or
+make
+```
+
+### Run tests
+```bash
+make test
+# or
+npm test
+```
+
+The tests use Mocha with test vectors that validate against known good SHA crypt implementations.
+
+### Clean build artifacts
+```bash
+make clean
+```
+
+## API Design
+
+Both `sha256crypt()` and `sha512crypt()` support:
+- Synchronous and asynchronous execution (callback as last parameter)
+- Automatic salt generation if not provided
+- Custom round counts (defaults to 5000, minimum 1000)
+- Salt string validation and formatting
+
+The JavaScript wrapper handles parameter validation and salt formatting before calling the native C++ functions.

package/Makefile

@@ -9,7 +9,7 @@ shacrypt: node_modules src/*
 # Tests
 #
 test: shacrypt
-	@mocha
+	@./node_modules/.bin/mocha
 
 
 #

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.2.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": [
@@ -9,17 +9,18 @@
   ],
   "main": "shacrypt",
   "scripts": {
+    "install": "node-gyp rebuild",
     "test": "make test"
   },
   "dependencies": {
-    "nan": "^2.14.0"
+    "nan": "^2.22.2"
   },
   "devDependencies": {
-      "mocha": "~=2.3.4",
-      "chai": "~=3.4.1"
+      "mocha": "^10.8.2",
+      "chai": "^4.5.0"
   },
   "engines": {
-    "node": ">= 0.8.0"
+    "node": ">= 16.0.0"
   },
   "bugs": {
     "url": "https://github.com/vlasky/shacrypt/issues"

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/src/sha256crypt.c

@@ -449,7 +449,7 @@ sha256_crypt_r (const char *key, const char *salt, char *buffer, int buflen)
   sha256_init_ctx (&alt_ctx);
 
   /* For every character in the password add the entire password.  */
-  for (cnt = 0; cnt < 16 + alt_result[0]; ++cnt)
+  for (cnt = 0; cnt < (size_t)(16 + alt_result[0]); ++cnt)
     sha256_process_bytes (salt, salt_len, &alt_ctx);
 
   /* Finish the digest.  */

package/src/sha512crypt.c

@@ -479,7 +479,7 @@ sha512_crypt_r (const char *key, const char *salt, char *buffer, int buflen)
   sha512_init_ctx (&alt_ctx);
 
   /* For every character in the password add the entire password.  */
-  for (cnt = 0; cnt < 16 + alt_result[0]; ++cnt)
+  for (cnt = 0; cnt < (size_t)(16 + alt_result[0]); ++cnt)
     sha512_process_bytes (salt, salt_len, &alt_ctx);
 
   /* Finish the digest.  */

package/src/shacrypt.cc

@@ -19,17 +19,49 @@ using Nan::Null;
 using Nan::To;
 
 NAN_METHOD(sha256crypt) {
+  if (info.Length() < 2) {
+    Nan::ThrowError("Wrong number of arguments");
+    return;
+  }
+
+  if (!info[0]->IsString() || !info[1]->IsString()) {
+    Nan::ThrowTypeError("Arguments must be strings");
+    return;
+  }
+
   Nan::Utf8String key(info[0]);
   Nan::Utf8String salt(info[1]);
 
-  info.GetReturnValue().Set(Nan::New(sha256_crypt(*key, *salt)).ToLocalChecked());
+  const char* result = sha256_crypt(*key, *salt);
+  if (!result) {
+    Nan::ThrowError("sha256_crypt failed");
+    return;
+  }
+
+  info.GetReturnValue().Set(Nan::New(result).ToLocalChecked());
 }
 
 NAN_METHOD(sha512crypt) {
+  if (info.Length() < 2) {
+    Nan::ThrowError("Wrong number of arguments");
+    return;
+  }
+
+  if (!info[0]->IsString() || !info[1]->IsString()) {
+    Nan::ThrowTypeError("Arguments must be strings");
+    return;
+  }
+
   Nan::Utf8String key(info[0]);
   Nan::Utf8String salt(info[1]);
 
-  info.GetReturnValue().Set(Nan::New(sha512_crypt(*key, *salt)).ToLocalChecked());
+  const char* result = sha512_crypt(*key, *salt);
+  if (!result) {
+    Nan::ThrowError("sha512_crypt failed");
+    return;
+  }
+
+  info.GetReturnValue().Set(Nan::New(result).ToLocalChecked());
 }
 
 
@@ -40,7 +72,12 @@ class SHA256CryptWorker : public AsyncWorker {
     }
 
     void Execute() {
-      result = sha256_crypt(key.c_str(), salt.c_str());
+      const char* crypt_result = sha256_crypt(key.c_str(), salt.c_str());
+      if (!crypt_result) {
+        SetErrorMessage("sha256_crypt failed");
+        return;
+      }
+      result = crypt_result;
     }
 
     void HandleOKCallback() {
@@ -61,7 +98,12 @@ class SHA512CryptWorker : public AsyncWorker {
     }
 
     void Execute() {
-      result = sha512_crypt(key.c_str(), salt.c_str());
+      const char* crypt_result = sha512_crypt(key.c_str(), salt.c_str());
+      if (!crypt_result) {
+        SetErrorMessage("sha512_crypt failed");
+        return;
+      }
+      result = crypt_result;
     }
 
     void HandleOKCallback() {
@@ -76,6 +118,21 @@ class SHA512CryptWorker : public AsyncWorker {
 };
 
 NAN_METHOD(sha256cryptasync) {
+  if (info.Length() < 3) {
+    Nan::ThrowError("Wrong number of arguments");
+    return;
+  }
+
+  if (!info[0]->IsString() || !info[1]->IsString()) {
+    Nan::ThrowTypeError("First two arguments must be strings");
+    return;
+  }
+
+  if (!info[2]->IsFunction()) {
+    Nan::ThrowTypeError("Third argument must be a function");
+    return;
+  }
+
   Nan::Utf8String key(info[0]);
   Nan::Utf8String salt(info[1]);
 
@@ -84,6 +141,21 @@ NAN_METHOD(sha256cryptasync) {
 }
 
 NAN_METHOD(sha512cryptasync) {
+  if (info.Length() < 3) {
+    Nan::ThrowError("Wrong number of arguments");
+    return;
+  }
+
+  if (!info[0]->IsString() || !info[1]->IsString()) {
+    Nan::ThrowTypeError("First two arguments must be strings");
+    return;
+  }
+
+  if (!info[2]->IsFunction()) {
+    Nan::ThrowTypeError("Third argument must be a function");
+    return;
+  }
+
   Nan::Utf8String key(info[0]);
   Nan::Utf8String salt(info[1]);
 
@@ -104,5 +176,6 @@ NAN_MODULE_INIT(init) {
     Nan::GetFunction(Nan::New<FunctionTemplate>(sha512cryptasync)).ToLocalChecked());
 }
 
+
 NODE_MODULE(shacrypt, init);
 

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"
     ],
@@ -97,3 +97,96 @@ 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() {
+            shacrypt.sha256crypt(123, 'salt');
+        }).to.throw('password must be a String');
+    });
+
+    it('should throw error for non-string password in sha512crypt', function() {
+        expect(function() {
+            shacrypt.sha512crypt(null, 'salt');
+        }).to.throw('password must be a String');
+    });
+
+    it('should handle missing password gracefully', function() {
+        expect(function() {
+            shacrypt.sha256crypt();
+        }).to.throw('password must be a String');
+    });
+
+    it('should generate salt when not provided', function() {
+        var result = shacrypt.sha256crypt('password');
+        result.should.match(/^\$5\$/);
+    });
+
+    it('should handle async callback errors for invalid password', function(done) {
+        try {
+            shacrypt.sha256crypt(123, 'salt', function(err, result) {
+                // This callback should not be called
+                done(new Error('Expected synchronous error'));
+            });
+        } catch (e) {
+            e.message.should.equal('password must be a String');
+            done();
+        }
+    });
+
+    it('should handle async callback errors for invalid password in sha512', function(done) {
+        try {
+            shacrypt.sha512crypt(undefined, 'salt', function(err, result) {
+                // This callback should not be called
+                done(new Error('Expected synchronous error'));
+            });
+        } catch (e) {
+            e.message.should.equal('password must be a String');
+            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\$/);
+    });
+});