ncrypt-js 2.1.1 → 2.2.0

package/README.md

@@ -1,8 +1,9 @@
 # NcryptJs
 
-[![Build Status](https://travis-ci.com/ajimae/ncrypt-js.svg?branch=master)](https://travis-ci.com/ajimae/ncrypt-js) [![Coverage Status](https://coveralls.io/repos/github/ajimae/ncrypt-js/badge.svg)](https://coveralls.io/github/ajimae/ncrypt-js) [![NPM](https://img.shields.io/npm/l/ncrypt-js)](https://www.npmjs.com/package/ncrypt-js/v/2.0.0#license)
+![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)
+[![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)
 
 **_NcryptJs_** is a light weight javascript data encryption and decryption library. This library implements the nodejs default crypto functionality as a mid-channel cipher in addition to a simple and elegant custom data encoding and encryption algorithm.
 
@@ -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,13 +81,16 @@ 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).
 
 
 ### Using randomString method
 
-The `randomString()` static method can generate [random bytes](https://nodejs.org/api/crypto.html#cryptorandombytessize-callback) encoded into a `hexadecimal` or `base64` strings. This string can be useful in a variety of use cases e.g to generate database ids, to generate a unique string for a list, a unique serial strings etc.
+The `randomString()` static method can generate [random bytes](https://nodejs.org/api/crypto.html#cryptorandombytessize-callback) encoded into a `hexadecimal` or `base64` strings. This string can be useful in a variety of use cases e.g to generate database ids, to generate a unique string for a list, a unique serial strings, api keys etc.
 
 ```ts
 var { ncrypt } = require('ncrypt-js'); // or import ncrypt from 'ncrypt-js'
@@ -120,7 +125,7 @@ console.log("Encryption process...");
 console.log("Plain Text    : " + data);
 console.log("Cipher Text   : " + encryptedData);
 
-// decrypted super encrypted string here
+// decrypting the encrypted super sensitive data here
 var decryptedData = decrypt(encryptedData);
 console.log("... and then decryption...");
 console.log("Decipher Text : " + decryptedData);
@@ -189,7 +194,7 @@ If you are using any sort of environmental key-value store, e.g `.env` and for a
 KEY='sshhhh this is a super secret key'
 
 # used internally to set the `encoding` - ['base64' | 'binary' | 'hex' | 'ucs-2' | 'ucs2' | 'utf16le']
-NCRPT_ENC='hex'
+NCRYPT_ENC='hex'
 
 SECRET='this is our hashing secret'
 ```
@@ -200,7 +205,113 @@ var { ncrypt } = require('ncrypt-js');
 var { encrypt, decrypt } = new ncrypt(process.env.SECRET);
 ...
 ```
-_**NOTE:** The secret is required to decrypt the encrypted data, if the secret used to encrypt a specific data is lost, then that data cannot be decripted._
+_**NOTE:** The secret is required to decrypt the encrypted data, if the secret used to encrypt a specific data is lost, then that data cannot be decrypted._
+
+_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 
 
@@ -210,7 +321,7 @@ Written in [TypeScript](https://typscriptlang.org/), built into ECMAScript 5 usi
 
 To contribute, simply fork this project, and issue a pull request.
 
-## Version Management
+## Versioning
 
 We use [SemVer](http://semver.org/) for version management. For the versions available, see the [tags on this repository](https://github.com/ajimae/ncrypt-js/tags).
 

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);
@@ -91,10 +95,99 @@ class Ncrypt {
             return decrypted.toString();
         };
         this.secret = secret;
-        // bind public instnace methods
+        // bind public instance methods
         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.1",
+  "version": "2.2.0",
   "description": "a light weight javascript data encryption and decryption library",
   "main": "dist/index.js",
   "scripts": {
@@ -51,7 +51,6 @@
   "files": [
     "dist",
     "package.json",
-    "LICENSE",
-    "tsconfig.json"
+    "LICENSE"
   ]
 }

package/tsconfig.json

@@ -1,23 +0,0 @@
-{
-  "compilerOptions": {
-      "target": "es2015",
-      "module": "commonjs",
-      "lib": ["es2015", "es2016", "dom", "es2017", "es6", "es5"],
-      "esModuleInterop": true,
-      "noImplicitAny": true,
-      "moduleResolution": "node",
-      "declaration": true,
-      "sourceMap": false,
-      "outDir": "dist",
-      "baseUrl": ".",
-      "paths": {
-          "*": ["node_modules/*","src/types/*"]
-      }
-  },
-  "include": [
-    "src/**/*", "index.ts",
-  ],
-  "exclude": [
-    "test/**/*"
-  ]
-}