ncrypt-js 2.1.2 → 2.2.0

package/README.md

@@ -1,6 +1,7 @@
 # NcryptJs
 
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ajimae/ncrypt-js/release.yml) [![Coverage Status](https://coveralls.io/repos/github/ajimae/ncrypt-js/badge.svg)](https://coveralls.io/github/ajimae/ncrypt-js) ![NPM Downloads](https://img.shields.io/npm/dw/ncrypt-js)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ajimae/ncrypt-js/.github%2Fworkflows%2Fci.yml)
+ [![Coverage Status](https://coveralls.io/repos/github/ajimae/ncrypt-js/badge.svg)](https://coveralls.io/github/ajimae/ncrypt-js) ![NPM Downloads](https://img.shields.io/npm/dw/ncrypt-js)
 
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/ajimae/ncrypt-js)](https://github.com/ajimae/ncrypt-js/releases) [![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/ajimae/ncrypt-js)](https://github/languages/code-size/ajimae/ncrypt-js) [![GitHub issues](https://img.shields.io/github/issues/ajimae/ncrypt-js)](https://github.com/ajimae/ncrypt-js/issues) [![NPM](https://img.shields.io/npm/l/ncrypt-js)](https://www.npmjs.com/package/ncrypt-js/v/2.0.0#license)
 
@@ -16,8 +17,9 @@
     * [NcryptJs Methods](#ncryptjs-methods)
     * [Using the `randomString()` methods](#using-randomstring-method)
     * [Using `encrypt()` and `decrypt()` methods](#using-encrypt-and-decrypt-methods)
-    * [Stirng Encryption](#string-encryption)
+    * [String Encryption](#string-encryption)
     * [Object Encryption](#object-encryption)
+    * [Using password hashing methods](#using-password-hashing-methods)
   * [Built With](#built-with)
   * [Contribution](#contribution)
   * [Version Management](#version-management)
@@ -79,6 +81,9 @@ var { ncrypt } = require("ncrypt-js");
 | Methods                                                                                              | Description                                                                                            | Parameters                                                                                             | Return                                                                                                 |
 | -------------------------------------------------------------                                          | --------------------------------------------------------------------------------------                 | -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                             | ----------------------------------------------------------------------------------------------------------------                                                                                                |
 | [_static_] **randomString()**                                                                                          | Random String.                                                                                     |**size**: _number_ - An optional size of the generated `randomBytes`. <br/>**enc:** _base64/hex_ - Encoding used for encoding the `randomBytes` defaults to _`base64`_ |**encoded**: _string_ - encoded string.                                                                    |
+| [_static_] **generate()**                                                                                          | Generates a hashed password.                                                                                     |**password**: _string_ - The password to hash. <br/>**options**: _object_ - Optional configuration object (see below). |**hashedPassword**: _string_ - The hashed password string.                                                                    |
+| [_static_] **verify()**                                                                                          | Verifies a password against a hashed password.                                                                 | **password**: _string_ - The password to verify. <br/>**hashedPassword**: _string_ - The hashed password to verify against. <br/>**options**: _object_ - Optional configuration object (see below).                        | **boolean** - Returns `true` if the password matches the hash, `false` otherwise.
+| [_static_] **isHashed()**                                                                                          | Checks if a string is a hashed password.                                                                 | **password**: _string_ - The string to check. <br/>**options**: _object_ - Optional configuration object (see below).                        | **boolean** - Returns `true` if the string appears to be a hashed password, `false` otherwise.
 | **encrypt()**                                                                                          | Encrypts data.                                                                                     |**data**: _object/string/number/boolean_ - The data to be encrypted. <br/>|**ciphered**: _string_ - encrypted data.                                                                    |
 | **decrypt()**                                                                                          | Decrypts the encrypted or ciphered data                                                                 | **encodedData**: string - The encrypted data: _string_ to be decrypted.                        | **data**: _string/object/number/boolean_ - The decrypted or original data (it might be string or object, depends on the initial input data type).
 
@@ -204,6 +209,110 @@ _**NOTE:** The secret is required to decrypt the encrypted data, if the secret u
 
 _Same goes for encoding, if data was encrypted using `hex` encoding format, decrypting with a `base64` encoding or other encoding format and vise versa will not work_
 
+### Using password hashing methods
+
+The `generate()`, `verify()`, and `isHashed()` static methods provide secure password hashing and verification functionality. These methods use HMAC (Hash-based Message Authentication Code) for password hashing.
+
+#### Generating a hashed password
+
+The `generate()` method creates a secure hash of a password with a randomly generated salt.
+
+```ts
+var { ncrypt } = require('ncrypt-js'); // or import ncrypt from 'ncrypt-js'
+
+var password = "mySecurePassword123";
+var hashedPassword = ncrypt.generate(password);
+console.log(hashedPassword); // sha1$abc12345$1$hashedvalue...
+
+// signature
+ncrypt.generate(password: string, options?: {
+  algorithm?: string;          // Hash algorithm (default: 'sha1')
+  saltLength?: number;         // Salt length in characters (default: 8)
+  iterations?: number;         // Number of hash iterations (default: 1)
+  encoding?: 'hex' | 'base64'; // Encoding format (default: 'hex')
+  separator?: string;          // Separator character (default: '$')
+});
+```
+
+#### Verifying a password
+
+The `verify()` method checks if a plain text password matches a previously hashed password.
+
+```ts
+var { ncrypt } = require('ncrypt-js');
+
+var password = "mySecurePassword123";
+var hashedPassword = ncrypt.generate(password);
+
+// Later, verify the password
+var isValid = ncrypt.verify(password, hashedPassword);
+console.log(isValid);           // true
+
+// signature
+ncrypt.verify(password: string, hashedPassword: string, options?: {
+  encoding?: 'hex' | 'base64';  // Encoding format (default: 'hex')
+  separator?: string;           // Separator character (default: '$')
+});
+```
+
+#### Checking if a string is hashed
+
+The `isHashed()` method checks if a string appears to be a hashed password by verifying its format.
+
+```ts
+var { ncrypt } = require('ncrypt-js');
+
+var hashedPassword = ncrypt.generate("password123");
+var isHashed = ncrypt.isHashed(hashedPassword);
+console.log(isHashed); // true
+
+var plainPassword = "password123";
+var isHashed = ncrypt.isHashed(plainPassword);
+console.log(isHashed); // false
+
+// signature
+ncrypt.isHashed(password: string, options?: {
+  separator?: string; // Separator character (default: '$')
+});
+```
+
+#### Advanced usage with custom options
+
+You can customize the hashing algorithm, salt length, iterations, encoding, and separator:
+
+```ts
+var { ncrypt } = require('ncrypt-js');
+
+// Generate with custom options
+var hashedPassword = ncrypt.generate("password123", {
+  algorithm: "sha256",   // Use SHA-256 instead of SHA-1
+  saltLength: 16,        // Use 16 character salt
+  iterations: 1000,      // Apply hashing 1000 times
+  encoding: "base64",    // Use base64 encoding
+  separator: "."         // Use '.' as separator instead of '$'
+});
+
+// Verify with matching options
+var isValid = ncrypt.verify("password123", hashedPassword, {
+  encoding: "base64",
+  separator: "."
+});
+console.log(isValid); // true
+```
+
+**Available hash algorithms:** Any algorithm supported by Node.js `crypto.createHmac()`, such as `'sha1'`, `'sha256'`, `'sha512'`, `'md5'`, etc.
+
+**Note:** The `encoding` and `separator` options must match between `generate()` and `verify()` calls for verification to succeed. To be safe, ensure you create a single options object and use the same object everywhere.
+
+```ts
+const same_options_obj = {
+  ...
+}
+
+ncrypt.generate("pass", same_options_obj)
+ncrypt.verify("pass", hasedPass, same_options_obj)
+```
+
 ## Built With 
 
 Written in [TypeScript](https://typscriptlang.org/), built into ECMAScript 5 using the TypeScript compiler.

package/dist/src/ncrypt.d.ts

@@ -1,3 +1,10 @@
+declare type THASH_ENC = {
+    algorithm?: string;
+    saltLength?: number;
+    iterations?: number;
+    encoding?: "base64" | "hex";
+    separator?: string;
+};
 /**
  * @class Ncrypt
  * @type {Ncrypt.<object>}
@@ -20,6 +27,9 @@ export default class Ncrypt {
      * crypto random initial vector generated from core node {crypto} module
      */
     private readonly initialVector;
+    /**
+     * hashing salt
+     */
     /**
      * crypto random key generated from core node {crypto} module
      * {note}: please read the value for KEY from your app's environment
@@ -61,6 +71,47 @@ export default class Ncrypt {
      * @returns {string.<string>} decrypted data
      */
     private decode;
+    /**
+     *
+     * generate salt method
+     * @param length
+     * @param enc
+     * @returns
+     */
+    private static generateSalt;
+    /**
+     *
+     * generate hash method
+     * @param algorithm
+     * @param salt
+     * @param password
+     * @param iterations
+     * @param enc
+     * @param separator
+     * @returns
+     */
+    private static generateHash;
+    /**
+     *
+     * generate hashed password method
+     * @param password
+     * @param options
+     * @returns
+     */
+    static generate(password: string, options?: THASH_ENC): string;
+    /**
+     *
+     * verify password method
+     */
+    static verify(password: string, hashedPassword: string, options?: THASH_ENC): boolean;
+    /**
+     *
+     * isHashed method
+     * @param password
+     * @param options
+     * @returns
+     */
+    static isHashed(password: string, options?: THASH_ENC): boolean;
     /**
      * generate random strings
      * @example
@@ -74,7 +125,7 @@ export default class Ncrypt {
      * @param {enc.<string>} enc
      * @returns {*.<string>} string
      */
-    static randomString(size?: number, enc?: 'hex' | 'base64'): string;
+    static randomString(size?: number, enc?: "hex" | "base64"): string;
     /**
      * data to be encrypted
      * @param {data.<stirng>} data
@@ -88,3 +139,4 @@ export default class Ncrypt {
      */
     decrypt(text: string): string | number | boolean | object;
 }
+export {};

package/dist/src/ncrypt.js

@@ -21,27 +21,32 @@ class Ncrypt {
         /**
          * algorithm used for encoding message
          */
-        this.algorithm = 'aes-256-cbc';
+        this.algorithm = "aes-256-cbc";
         /**
          * ecoding for encrypted stirng
          */
-        this.enc = (process.env.NCRYPT_ENC) || 'hex';
+        this.enc = process.env.NCRYPT_ENC || "hex";
         /**
          * crypto random initial vector generated from core node {crypto} module
          */
         this.initialVector = crypto.randomBytes(16);
+        /**
+         * hashing salt
+         */
+        // private readonly saltChars =
+        //   "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
         /**
          * crypto random key generated from core node {crypto} module
          * {note}: please read the value for KEY from your app's environment
          */
-        this.key = crypto.scryptSync(process.env.KEY || 'please provide a KEY in your .env file or config', 'salt', 32);
+        this.key = crypto.scryptSync(process.env.KEY || "please provide a KEY in your .env file or config", "salt", 32);
         /**
          * convert all entered text to decimal equivalent character codes
          * @param {text.<string>} text to be converted
          * @return {Array.<number>} array of character codes
          */
         this.convertTextToDecimal = (text) => {
-            return text.split('').map((value) => value.charCodeAt(0));
+            return text.split("").map((value) => value.charCodeAt(0));
         };
         /**
          * encode provided secret on decimal character codes
@@ -49,8 +54,7 @@ class Ncrypt {
          * @returns {*.<number>} decimal string
          */
         this.applySecretToCharacters = (charCodes) => {
-            return this.convertTextToDecimal(this.secret)
-                .reduce((firstValue, secondValue) => (firstValue ^ secondValue), charCodes);
+            return this.convertTextToDecimal(this.secret).reduce((firstValue, secondValue) => firstValue ^ secondValue, charCodes);
         };
         /**
          * convert character bytes to hexadecimal equivalent
@@ -58,7 +62,7 @@ class Ncrypt {
          * @returns {*.<string>} hexadecimal string
          */
         this.convertByteToHexadecimal = (number) => {
-            return ('0' + Number(number).toString(16)).substr(-2);
+            return ("0" + Number(number).toString(16)).substr(-2);
         };
         /**
          * intermediate data encoder function
@@ -78,11 +82,11 @@ class Ncrypt {
          * @returns {string.<string>} decrypted data
          */
         this.decode = (text) => {
-            if (typeof text !== 'string') {
-                throw new TypeError('argument must be a string, or a string-like object');
+            if (typeof text !== "string") {
+                throw new TypeError("argument must be a string, or a string-like object");
             }
-            const iv = text.split('.')[0];
-            const encryptedData = text.split('.')[1];
+            const iv = text.split(".")[0];
+            const encryptedData = text.split(".")[1];
             let _iv = Buffer.from(iv, this.enc);
             let encryptedText = Buffer.from(encryptedData, this.enc);
             let decipher = crypto.createDecipheriv(this.algorithm, Buffer.from(this.key), _iv);
@@ -95,6 +99,95 @@ class Ncrypt {
         this.encrypt = this.encrypt.bind(this);
         this.decrypt = this.decrypt.bind(this);
     }
+    /**
+     *
+     * generate salt method
+     * @param length
+     * @param enc
+     * @returns
+     */
+    static generateSalt(length, enc = "hex") {
+        if (typeof length != "number" ||
+            length <= 0 ||
+            length !== parseInt(length, 10)) {
+            throw new Error("Invalid salt length");
+        }
+        // ensure your JS environment supports the `crypto.randomBytes()` function
+        return crypto
+            .randomBytes(Math.ceil(length / 2))
+            .toString(enc)
+            .substring(0, length);
+    }
+    /**
+     *
+     * generate hash method
+     * @param algorithm
+     * @param salt
+     * @param password
+     * @param iterations
+     * @param enc
+     * @param separator
+     * @returns
+     */
+    static generateHash(algorithm, salt, password, iterations = 1, enc = "hex", separator = "$") {
+        try {
+            let hash = password;
+            for (let i = 0; i < iterations; ++i) {
+                hash = crypto.createHmac(algorithm, salt).update(hash).digest(enc);
+            }
+            return (algorithm + separator + salt + separator + iterations + separator + hash);
+        }
+        catch (e) {
+            throw new Error("Invalid message digest algorithm");
+        }
+    }
+    /**
+     *
+     * generate hashed password method
+     * @param password
+     * @param options
+     * @returns
+     */
+    static generate(password, options = {}) {
+        options.algorithm = options.algorithm || "sha1";
+        options.saltLength = options.saltLength || 8;
+        options.iterations = options.iterations || 1;
+        options.encoding = options.encoding || "hex";
+        options.separator = options.separator || "$";
+        let salt = this.generateSalt(options.saltLength, options.encoding);
+        return this.generateHash(options.algorithm, salt, password, options.iterations, options.encoding, options.separator);
+    }
+    /**
+     *
+     * verify password method
+     */
+    static verify(password, hashedPassword, options = {}) {
+        if (!password || !hashedPassword)
+            return false;
+        options.encoding = options.encoding || "hex";
+        options.separator = options.separator || "$";
+        let parts = hashedPassword.split(options.separator);
+        if (parts.length != 4)
+            return false;
+        try {
+            return (this.generateHash(parts[0], parts[1], password, parts[2], options.encoding, options.separator) == hashedPassword);
+        }
+        catch (e) { }
+        return false;
+    }
+    /**
+     *
+     * isHashed method
+     * @param password
+     * @param options
+     * @returns
+     */
+    static isHashed(password, options = {}) {
+        if (!password)
+            return false;
+        options.separator = options.separator || "$";
+        return password.split(options.separator).length == 4;
+    }
     /**
      * generate random strings
      * @example
@@ -108,7 +201,7 @@ class Ncrypt {
      * @param {enc.<string>} enc
      * @returns {*.<string>} string
      */
-    static randomString(size, enc = 'base64') {
+    static randomString(size, enc = "base64") {
         return crypto.randomBytes(size || 64).toString(enc);
     }
     /**
@@ -123,15 +216,17 @@ class Ncrypt {
          * hexadecimal mapping
          */
         try {
-            const encodedMessage = JSON.stringify(data).split('')
+            const encodedMessage = JSON.stringify(data)
+                .split("")
                 .map(this.convertTextToDecimal)
                 .map(this.applySecretToCharacters)
                 .map(this.convertByteToHexadecimal)
-                .join('');
+                .join("");
             return this.encode(encodedMessage);
         }
         catch (e) {
-            throw new Error('invalid data was entered, enter data of type object, number, string or boolean to be encrypted.' + e);
+            throw new Error("invalid data was entered, enter data of type object, number, string or boolean to be encrypted." +
+                e);
         }
     }
     /**
@@ -141,11 +236,12 @@ class Ncrypt {
      */
     decrypt(text) {
         const encodeData = this.decode(text);
-        const data = (encodeData).match(/.{1,2}/g)
+        const data = encodeData
+            .match(/.{1,2}/g)
             .map((hex) => parseInt(hex, 16))
             .map(this.applySecretToCharacters)
             .map((charCode) => String.fromCharCode(charCode))
-            .join('');
+            .join("");
         return JSON.parse(data);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncrypt-js",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "a light weight javascript data encryption and decryption library",
   "main": "dist/index.js",
   "scripts": {