ncrypt-js 2.0.1 → 2.1.1

package/README.md

@@ -6,25 +6,18 @@
 
 **_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.
 
-<!-- ```diff
-- const ReduxThunk = require('redux-thunk')
-+ const ReduxThunk = require('redux-thunk').default
-``` -->
-
 ## Contents
 
 * [NcryptJs](#NcryptJs)
   * [Contents](#contents)
-  <!-- * [Changes Log (What's New)](#changes-log-whats-new) -->
   * [Getting Started](#getting-started)
     * [Installation](#installation)
   * [Documentation](#documentation)
-    * [NcryptJs Functions](#ncryptjs-functions)
-    * [Using `encrypt()` and `decrypt()`](#using-encrypt-and-decrypt)
-    * [Using default imports](#Using-default-imports)
-    <!-- * [Change the Secret Key](#change-the-secret-key)
+    * [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)
     * [Object Encryption](#object-encryption)
-    * [Random Key Generator](#random-key-generator) -->
   * [Built With](#built-with)
   * [Contribution](#contribution)
   * [Version Management](#version-management)
@@ -59,56 +52,65 @@ yarn add ncrypt-js
 
 To include **_ncrypt-js_** in your project. use one of these:
 
-```diff
+```js
 // ES6 and later
-+ import ncrypt from "ncrypt-js";
-- import * as ncrypt from "ncrypt-js";
-
-// or
-- import { encrypt, decrypt } from "ncrypt-js";
+import ncrypt from "ncrypt-js";
+// or import { ncrypt } from "ncrypt-js"
 ```
 
 However, if you are using ECMAScript 5 and older, use the require statement:
 
-```diff
+```js
 // ES5 and older
-+ var ncrypt = require("ncrypt-js");
-
-// or
-- var { encrypt, decrypt } = require("ncrypt-js");
+var { ncrypt } = require("ncrypt-js");
 ```
 
 ## Documentation
 
 **_NcryptJs_** is a simple library with only two two exposed functions. This is all intentional mainly to keep everything simple. This is a complete documentation of the library and how to use it in your project. All examples work on both ECMAScript 6 (and later) and ECMAScript 5 (and older).
 
-### NcryptJs Functions
+### NcryptJs Methods
 
 
-### List of **_NcryptJs_** functions.
+### List of **_NcryptJs_** Methods.
 
 
 
-| Functions                                                                                              | Description                                                                                            | Parameters                                                                                             | Return                                                                                                 |
+| 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.                                                                    |
 | **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.
+
+```ts
+var { ncrypt } = require('ncrypt-js'); // or import ncrypt from 'ncrypt-js'
+
+var randomStr = ncrypt.randomString(8, 'base64');
+console.log(randomStr) // t78WcmYAFOY=
+
+// signature
+ncrypt.randomString(size?: number, enc?: 'base64' | 'hex');
+```
 
-#### Using `encrypt()` and `decrypt()` functons - As of version 2.0.0 directly importing or invoking these functions is deprecated, an object must be created with a secret first, before the methods can now be invoked on the created object.
+### Using encrypt() and decrypt() methods
+The `encrypt()` and `decrypt()` methods as of version 2.0.0 directly importing or invoking these methods is `deprecated`, an object must first be created with a secret, before the methods can then be invoked on the created object.
 
-To encrypt and decrypt data, simply use `encrypt()` and `decrypt()` functions respectively. This will use `AES-256-CBC` encryption algorithm as the mid-channel cipher.
+To `encrypt` and `decrypt` data, simply use `encrypt()` and `decrypt()` methods respectively. This will use `AES-256-CBC` encryption algorithm as the mid-channel cipher.
 
 ```diff
 - var { encrypt, decrypt } = require("ncrypt-js");
-+ var ncrypt = require("ncrypt-js");
++ var { ncrypt } = require("ncrypt-js");
 
 
 var data = "Hello World!";
 var _secretKey = "some-super-secret-key";
 
-+ var { encodeData, decodeData } = new ncrypt(_secretKey);
++ var { encrypt, decrypt } = new ncrypt(_secretKey);
 
 // encrypting super sensitive data here
 - var encryptedData = encrypt(data, _secretKey);
@@ -125,10 +127,10 @@ console.log("Decipher Text : " + decryptedData);
 console.log("...done.");
 ```
 
-### Using default imports
+### String Encryption
 
 ```javascript
-var ncrypt = require("ncrypt-js");
+var { ncrypt } = require("ncrypt-js");
 
 var data = "Hello World!";
 var _secretKey = "some-super-secret-key";
@@ -141,7 +143,7 @@ console.log("Encryption process...");
 console.log("Plain Text    : " + data);
 console.log("Cipher Text   : " + encryptedData);
 
-// decrypted super encrypted string here
+// decrypted super encrypted data here
 var decryptedData = ncryptObject.decrypt(encryptedData);
 console.log("... and then decryption...");
 console.log("Decipher Text : " + decryptedData);
@@ -156,7 +158,7 @@ To encrypt and decrypt JavaScript object literal, simply use `encrypt()` and `de
 
 
 ```javascript
-var ncrypt = require("ncrypt-js");
+var { ncrypt } = require("ncrypt-js");
 
 var _secretKey = "some-super-secret-key";
 var object = {
@@ -169,30 +171,36 @@ var ncryptObject = new ncrypt('ncrypt-js');
 // encrypting super sensitive data here
 var encryptedObject = ncryptObject.encrypt(object);
 console.log("Encryption process...");
-console.log("Plain Object     : " + object);
+console.log("Plain Object     : ", object);
 console.log("Encrypted Object : " + encryptedObject);
 
-// decrypted super encrypted string here
+// decrypted super sensitive data here
 var decryptedObject = ncryptObject.decrypt(encryptedObject);
 console.log("... and then decryption...");
-console.log("Decipher Text : " + decryptedObject);
+console.log("Decipher Text : ", decryptedObject);
 console.log("...done.");
 ````
 If you are using any sort of environmental key-value store, e.g `.env` and for additional security, you can add the following to your environment.
 
-```diff
-// .env
+```bash
+# .env
 
-KEY=sshhhh this is a super secret key
-SECRET=this is our hashing secret
-```
-Then when creating your object, you can use the SECRET from your environment e.g:
+# used internally to set the `key`
+KEY='sshhhh this is a super secret key'
+
+# used internally to set the `encoding` - ['base64' | 'binary' | 'hex' | 'ucs-2' | 'ucs2' | 'utf16le']
+NCRPT_ENC='hex'
+
+SECRET='this is our hashing secret'
 ```
-...
-var ncrypt = require('ncrypt-js');
+When creating your object, you can use the `SECRET` from your environment e.g:
+
+```js
+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._
 
 ## Built With 
 

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import ncrypt from './src/ncrypt';
+export default ncrypt;
+export { ncrypt };

package/dist/index.js

@@ -3,8 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ncrypt = void 0;
 const ncrypt_1 = __importDefault(require("./src/ncrypt"));
 exports.ncrypt = ncrypt_1.default;
 module.exports = ncrypt_1.default;
+module.exports.ncrypt = ncrypt_1.default;
 exports.default = ncrypt_1.default;

package/dist/src/ncrypt.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @class Ncrypt
+ * @type {Ncrypt.<object>}
+ */
+export default class Ncrypt {
+    /**
+     * encryption secret.
+     * @type {secret.<string>} secret
+     */
+    private secret;
+    /**
+     * algorithm used for encoding message
+     */
+    private readonly algorithm;
+    /**
+     * ecoding for encrypted stirng
+     */
+    private readonly enc;
+    /**
+     * crypto random initial vector generated from core node {crypto} module
+     */
+    private readonly initialVector;
+    /**
+     * crypto random key generated from core node {crypto} module
+     * {note}: please read the value for KEY from your app's environment
+     */
+    private readonly key;
+    /**
+     * object constructor
+     * @param {secret.<string>} secret
+     */
+    constructor(secret: string);
+    /**
+     * convert all entered text to decimal equivalent character codes
+     * @param {text.<string>} text to be converted
+     * @return {Array.<number>} array of character codes
+     */
+    private convertTextToDecimal;
+    /**
+     * encode provided secret on decimal character codes
+     * @param {charCode.<number, number[]>} charCodes
+     * @returns {*.<number>} decimal string
+     */
+    private applySecretToCharacters;
+    /**
+     * convert character bytes to hexadecimal equivalent
+     * @param {number.<number>} number
+     * @returns {*.<string>} hexadecimal string
+     */
+    private convertByteToHexadecimal;
+    /**
+     * intermediate data encoder function
+     * @param {string.<any>} text
+     * @param secret
+     * @returns {string} encrypted or cipher text
+     */
+    private encode;
+    /**
+     * intermediate data decoder function
+     * @param {string.<any>} text
+     * @returns {string.<string>} decrypted data
+     */
+    private decode;
+    /**
+     * generate random strings
+     * @example
+     *
+     * var fs = require('fs');
+     * var ncrypt = require('ncrypt-js');
+     *
+     * console.log(ncrypt.randomString(8, 'base64')); // g3lzZ48TW6w==
+     *
+     * @param {size.<number>} size
+     * @param {enc.<string>} enc
+     * @returns {*.<string>} string
+     */
+    static randomString(size?: number, enc?: 'hex' | 'base64'): string;
+    /**
+     * data to be encrypted
+     * @param {data.<stirng>} data
+     * @returns {*.<string>} encrypted text
+     */
+    encrypt(data: string | number | boolean | object): string;
+    /**
+     * text be decrypted
+     * @param {text.<stirng>} text
+     * @returns {*.<string>} decrypted data
+     */
+    decrypt(text: string): string | number | boolean | object;
+}

package/dist/src/ncrypt.js

@@ -1,75 +1,152 @@
 "use strict";
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
+    result["default"] = mod;
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const utils_1 = require("./utils");
+const crypto = __importStar(require("crypto"));
+/**
+ * @class Ncrypt
+ * @type {Ncrypt.<object>}
+ */
 class Ncrypt {
     /**
      * object constructor
-     * @param text
-     * @param secret
+     * @param {secret.<string>} secret
      */
     constructor(secret) {
+        /**
+         * algorithm used for encoding message
+         */
+        this.algorithm = 'aes-256-cbc';
+        /**
+         * ecoding for encrypted stirng
+         */
+        this.enc = (process.env.NCRYPT_ENC) || 'hex';
+        /**
+         * crypto random initial vector generated from core node {crypto} module
+         */
+        this.initialVector = crypto.randomBytes(16);
+        /**
+         * 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);
         /**
          * convert all entered text to decimal equivalent character codes
-         * @param {data.<string>} data to be converted
+         * @param {text.<string>} text to be converted
          * @return {Array.<number>} array of character codes
          */
-        this.convertTextToDecimal = (data) => data.split('').map((value) => value.charCodeAt(0));
+        this.convertTextToDecimal = (text) => {
+            return text.split('').map((value) => value.charCodeAt(0));
+        };
         /**
          * encode provided secret on decimal character codes
-         * @param {charCode<number[], *>} character codes
+         * @param {charCode.<number, number[]>} charCodes
+         * @returns {*.<number>} decimal string
          */
-        this.applySecretToCharacters = (charCodes) => this.convertTextToDecimal(this.secret)
-            .reduce((firstValue, secondValue) => (firstValue ^ secondValue), charCodes);
+        this.applySecretToCharacters = (charCodes) => {
+            return this.convertTextToDecimal(this.secret)
+                .reduce((firstValue, secondValue) => (firstValue ^ secondValue), charCodes);
+        };
         /**
          * convert character bytes to hexadecimal equivalent
-         * @param {number.<number>}
-         * @returns {string} hexadecimal string
+         * @param {number.<number>} number
+         * @returns {*.<string>} hexadecimal string
          */
         this.convertByteToHexadecimal = (number) => {
-            return ("0" + Number(number).toString(16)).substr(-2);
+            return ('0' + Number(number).toString(16)).substr(-2);
         };
         /**
-         * process data to be encrypted
-         * @param {}
-         * @returns {string.<string>} encoded string data
+         * intermediate data encoder function
+         * @param {string.<any>} text
+         * @param secret
+         * @returns {string} encrypted or cipher text
          */
-        this.encrypt = (data) => {
-            /**
-             * this does the actual processing return a string
-             * resulting from charCode conversion, salting and
-             * hexadecimal mapping
-             *
-             */
-            // if (data == void 0) throw new Error('invalid data was entered, enter data of type object, number, string or boolean to be encrypted.');
-            try {
-                const encodedMessage = JSON.stringify(data).split('')
-                    .map(this.convertTextToDecimal)
-                    .map(this.applySecretToCharacters)
-                    .map(this.convertByteToHexadecimal)
-                    .join('');
-                return utils_1.encode(encodedMessage);
-            }
-            catch (error) {
-                throw new Error('invalid data was entered, enter data of type object, number, string or boolean to be encrypted.');
+        this.encode = (text) => {
+            let cipher = crypto.createCipheriv(this.algorithm, Buffer.from(this.key), this.initialVector);
+            let encrypted = cipher.update(text);
+            encrypted = Buffer.concat([encrypted, cipher.final()]);
+            return `${this.initialVector.toString(this.enc)}.${encrypted.toString(this.enc)}`;
+        };
+        /**
+         * intermediate data decoder function
+         * @param {string.<any>} text
+         * @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');
             }
+            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);
+            let decrypted = decipher.update(encryptedText);
+            decrypted = Buffer.concat([decrypted, decipher.final()]);
+            return decrypted.toString();
         };
+        this.secret = secret;
+        // bind public instnace methods
+        this.encrypt = this.encrypt.bind(this);
+        this.decrypt = this.decrypt.bind(this);
+    }
+    /**
+     * generate random strings
+     * @example
+     *
+     * var fs = require('fs');
+     * var ncrypt = require('ncrypt-js');
+     *
+     * console.log(ncrypt.randomString(8, 'base64')); // g3lzZ48TW6w==
+     *
+     * @param {size.<number>} size
+     * @param {enc.<string>} enc
+     * @returns {*.<string>} string
+     */
+    static randomString(size, enc = 'base64') {
+        return crypto.randomBytes(size || 64).toString(enc);
+    }
+    /**
+     * data to be encrypted
+     * @param {data.<stirng>} data
+     * @returns {*.<string>} encrypted text
+     */
+    encrypt(data) {
         /**
-         * decodes encoded string resulting from util encryption
-         * @param {string.<stirng>} encodeData
-         * @returns {decodedData.<string>} decoded data
+         * this does the actual processing return a string
+         * resulting from charCode conversion, salting and
+         * hexadecimal mapping
          */
-        this.decrypt = (text) => {
-            const encodeData = utils_1.decode(text);
-            const data = encodeData.match(/.{1,2}/g)
-                .map((hex) => parseInt(hex, 16))
+        try {
+            const encodedMessage = JSON.stringify(data).split('')
+                .map(this.convertTextToDecimal)
                 .map(this.applySecretToCharacters)
-                .map((charCode) => String.fromCharCode(charCode))
+                .map(this.convertByteToHexadecimal)
                 .join('');
-            const arr = [];
-            arr.push(data);
-            return JSON.parse(data);
-        };
-        this.secret = secret;
+            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);
+        }
+    }
+    /**
+     * text be decrypted
+     * @param {text.<stirng>} text
+     * @returns {*.<string>} decrypted data
+     */
+    decrypt(text) {
+        const encodeData = this.decode(text);
+        const data = (encodeData).match(/.{1,2}/g)
+            .map((hex) => parseInt(hex, 16))
+            .map(this.applySecretToCharacters)
+            .map((charCode) => String.fromCharCode(charCode))
+            .join('');
+        return JSON.parse(data);
     }
 }
 exports.default = Ncrypt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ncrypt-js",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "a light weight javascript data encryption and decryption library",
   "main": "dist/index.js",
   "scripts": {
@@ -28,7 +28,7 @@
     "decryption",
     "javascript-library"
   ],
-  "author": "meeky",
+  "author": "ajimae",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/ajimae/ncrypt-js/issues"
@@ -46,16 +46,12 @@
     "mocha-lcov-reporter": "^1.3.0",
     "nyc": "^14.1.1",
     "ts-node": "^8.6.2",
-    "typescript": "^3.8.3"
+    "typescript": "3.8.3"
   },
   "files": [
     "dist",
     "package.json",
     "LICENSE",
     "tsconfig.json"
-  ],
-  "dependencies": {
-    "crypto": "^1.0.1",
-    "dotenv": "^16.4.5"
-  }
+  ]
 }

package/tsconfig.json

@@ -6,6 +6,7 @@
       "esModuleInterop": true,
       "noImplicitAny": true,
       "moduleResolution": "node",
+      "declaration": true,
       "sourceMap": false,
       "outDir": "dist",
       "baseUrl": ".",

package/dist/src/utils.js

@@ -1,49 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.decode = exports.encode = void 0;
-const crypto_1 = __importDefault(require("crypto")); // this is necessary for some version of nodejs without crypto module
-const algorithm = 'aes-256-cbc';
-/**
- * crypto random initial vector generated from core node {crypto} module
- */
-const initialVector = crypto_1.default.randomBytes(16);
-/**
- * crypto random key generated from core node {crypto} module
- *
- * {note}: please read the value for KEY from your app's environment
- */
-const _key = process.env.KEY || 'please provide a KEY in your .env file or config';
-const key = crypto_1.default.scryptSync(_key, 'salt', 32);
-/**
- * intermediate data encoder function
- * @param {string.<any>} text
- * @param secret
- * @returns {string} encrypted or cipher text
- */
-exports.encode = (text) => {
-    let cipher = crypto_1.default.createCipheriv(algorithm, Buffer.from(key), initialVector);
-    let encrypted = cipher.update(text);
-    encrypted = Buffer.concat([encrypted, cipher.final()]);
-    return `${initialVector.toString('hex')}.${encrypted.toString('hex')}`;
-};
-/**
- * intermediate data decoder function
- * @param {string.<any>} text
- * @returns {string.<string>} decrypted data
- */
-exports.decode = (text) => {
-    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];
-    let _iv = Buffer.from(iv, 'hex');
-    let encryptedText = Buffer.from(encryptedData, 'hex');
-    let decipher = crypto_1.default.createDecipheriv(algorithm, Buffer.from(key), _iv);
-    let decrypted = decipher.update(encryptedText);
-    decrypted = Buffer.concat([decrypted, decipher.final()]);
-    return decrypted.toString();
-};