├── .github
└── workflows
│ ├── ci.yml
│ └── release.yml
├── .gitignore
├── .nycrc
├── LICENSE
├── README.md
├── index.ts
├── package.json
├── src
└── ncrypt.ts
├── test
└── ncrypt.test.ts
├── tsconfig.json
└── yarn.lock
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
1 | name: Test
2 | on:
3 | push:
4 | branches: [ master ]
5 | pull_request:
6 | branches: [ master ]
7 |
8 | jobs:
9 | build:
10 | runs-on: ubuntu-latest
11 | steps:
12 | - uses: actions/checkout@v3
13 | - uses: actions/setup-node@v3
14 | with:
15 | node-version: 12
16 | cache: 'yarn'
17 | - run: yarn install --production=false
18 | - run: yarn test
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
1 | name: publish
2 | on:
3 | release:
4 | types: [published]
5 |
6 | jobs:
7 | test:
8 | name: test
9 | runs-on: ubuntu-latest
10 | steps:
11 | - name: checkout and setup
12 | uses: actions/checkout@v4
13 | with:
14 | fetch-depth: 0
15 | ref: master
16 |
17 | - name: node setup
18 | uses: actions/setup-node@v4
19 | with:
20 | node-version: 12
21 | cache: 'yarn'
22 |
23 | - name: install dependencies
24 | run: yarn install --frozen-lockfile
25 | - name: run test suites
26 | run: yarn test
27 |
28 | publish:
29 | name: publish
30 | needs: test
31 | runs-on: ubuntu-latest
32 | steps:
33 | - name: checkout
34 | uses: actions/checkout@v4
35 | with:
36 | fetch-depth: 0
37 | ref: master
38 |
39 | - name: node setup
40 | uses: actions/setup-node@v4
41 | with:
42 | node-version: 12
43 | registry-url: https://registry.npmjs.org
44 | cache: 'yarn'
45 |
46 | - name: install dependencies
47 | run: yarn install --frozen-lockfile
48 | - name: build source
49 | run: yarn build
50 | - name: publish
51 | run: yarn publish --access=public
52 | env:
53 | NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
54 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Logs
2 | logs
3 | *.log
4 | npm-debug.log*
5 | yarn-debug.log*
6 | yarn-error.log*
7 |
8 | # Runtime data
9 | pids
10 | *.pid
11 | *.seed
12 | *.pid.lock
13 |
14 | # Directory for instrumented libs generated by jscoverage/JSCover
15 | lib-cov
16 |
17 | # Coverage directory used by tools like istanbul
18 | coverage
19 |
20 | # nyc test coverage
21 | .nyc_output
22 |
23 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
24 | .grunt
25 |
26 | # Bower dependency directory (https://bower.io/)
27 | bower_components
28 |
29 | # node-waf configuration
30 | .lock-wscript
31 |
32 | # Compiled binary addons (https://nodejs.org/api/addons.html)
33 | build/Release
34 |
35 | # Dependency directories
36 | node_modules/
37 | jspm_packages/
38 |
39 | # TypeScript v1 declaration files
40 | typings/
41 |
42 | # Optional npm cache directory
43 | .npm
44 |
45 | # Optional eslint cache
46 | .eslintcache
47 |
48 | # Optional REPL history
49 | .node_repl_history
50 |
51 | # Output of 'npm pack'
52 | *.tgz
53 |
54 | # Yarn Integrity file
55 | .yarn-integrity
56 |
57 | # dotenv environment variables file
58 | .env
59 |
60 | # next.js build output
61 | .next
62 |
63 | # distribution folder
64 | dist/
--------------------------------------------------------------------------------
/.nycrc:
--------------------------------------------------------------------------------
1 | {
2 | "cache": false,
3 | "check-coverage": false,
4 | "extension": [
5 | ".ts"
6 | ],
7 | "require": [
8 | "ts-node/register"
9 | ],
10 | "include": [
11 | "**/*js",
12 | "**/*ts"
13 | ],
14 | "exclude": [
15 | "dist/**",
16 | "coverage/**",
17 | "node_modules/**",
18 | "**/*.d.ts",
19 | "**/*.test.ts"
20 | ],
21 | "sourceMap": true,
22 | "reporter": [
23 | "html",
24 | "text",
25 | "text-summary"
26 | ],
27 | "all": true,
28 | "instrument": true
29 | }
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2019 Ajima Chukwuemeka
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # NcryptJs
2 |
3 |  [](https://coveralls.io/github/ajimae/ncrypt-js) 
4 |
5 | [](https://github.com/ajimae/ncrypt-js/releases) [](https://github/languages/code-size/ajimae/ncrypt-js) [](https://github.com/ajimae/ncrypt-js/issues) [](https://www.npmjs.com/package/ncrypt-js/v/2.0.0#license)
6 |
7 | **_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.
8 |
9 | ## Contents
10 |
11 | * [NcryptJs](#NcryptJs)
12 | * [Contents](#contents)
13 | * [Getting Started](#getting-started)
14 | * [Installation](#installation)
15 | * [Documentation](#documentation)
16 | * [NcryptJs Methods](#ncryptjs-methods)
17 | * [Using the `randomString()` methods](#using-randomstring-method)
18 | * [Using `encrypt()` and `decrypt()` methods](#using-encrypt-and-decrypt-methods)
19 | * [Stirng Encryption](#string-encryption)
20 | * [Object Encryption](#object-encryption)
21 | * [Built With](#built-with)
22 | * [Contribution](#contribution)
23 | * [Version Management](#version-management)
24 | * [Authors](#authors)
25 | * [License](#license)
26 | * [Acknowledgments](#acknowledgments)
27 |
28 |
36 |
37 | ## Getting Started
38 |
39 | This library is available through these javascript node package manager [npm](https://www.npmjs.org/) and [yarn](https://www.yarnpkg.com/).
40 |
41 | ## Installation
42 |
43 | To use this library, first ensure you have a package manager initialized either with [npm](https://www.npmjs.org/) or [yarn](https://www.yarnpkg.com/)
44 |
45 | ```bash
46 | # for npm use:
47 | npm install --save ncrypt-js
48 |
49 | # for yarn use:
50 | yarn add ncrypt-js
51 | ```
52 |
53 | To include **_ncrypt-js_** in your project. use one of these:
54 |
55 | ```js
56 | // ES6 and later
57 | import ncrypt from "ncrypt-js";
58 | // or import { ncrypt } from "ncrypt-js"
59 | ```
60 |
61 | However, if you are using ECMAScript 5 and older, use the require statement:
62 |
63 | ```js
64 | // ES5 and older
65 | var { ncrypt } = require("ncrypt-js");
66 | ```
67 |
68 | ## Documentation
69 |
70 | **_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).
71 |
72 | ### NcryptJs Methods
73 |
74 |
75 | ### List of **_NcryptJs_** Methods.
76 |
77 |
78 |
79 | | Methods | Description | Parameters | Return |
80 | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
81 | | [_static_] **randomString()** | Random String. |**size**: _number_ - An optional size of the generated `randomBytes`.
**enc:** _base64/hex_ - Encoding used for encoding the `randomBytes` defaults to _`base64`_ |**encoded**: _string_ - encoded string. |
82 | | **encrypt()** | Encrypts data. |**data**: _object/string/number/boolean_ - The data to be encrypted.
|**ciphered**: _string_ - encrypted data. |
83 | | **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).
84 |
85 |
86 | ### Using randomString method
87 |
88 | 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.
89 |
90 | ```ts
91 | var { ncrypt } = require('ncrypt-js'); // or import ncrypt from 'ncrypt-js'
92 |
93 | var randomStr = ncrypt.randomString(8, 'base64');
94 | console.log(randomStr) // t78WcmYAFOY=
95 |
96 | // signature
97 | ncrypt.randomString(size?: number, enc?: 'base64' | 'hex');
98 | ```
99 |
100 | ### Using encrypt() and decrypt() methods
101 | 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.
102 |
103 | 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.
104 |
105 | ```diff
106 | - var { encrypt, decrypt } = require("ncrypt-js");
107 | + var { ncrypt } = require("ncrypt-js");
108 |
109 |
110 | var data = "Hello World!";
111 | var _secretKey = "some-super-secret-key";
112 |
113 | + var { encrypt, decrypt } = new ncrypt(_secretKey);
114 |
115 | // encrypting super sensitive data here
116 | - var encryptedData = encrypt(data, _secretKey);
117 | + var encryptedData = encrypt(data);
118 |
119 | console.log("Encryption process...");
120 | console.log("Plain Text : " + data);
121 | console.log("Cipher Text : " + encryptedData);
122 |
123 | // decrypting the encrypted super sensitive data here
124 | var decryptedData = decrypt(encryptedData);
125 | console.log("... and then decryption...");
126 | console.log("Decipher Text : " + decryptedData);
127 | console.log("...done.");
128 | ```
129 |
130 | ### String Encryption
131 |
132 | ```javascript
133 | var { ncrypt } = require("ncrypt-js");
134 |
135 | var data = "Hello World!";
136 | var _secretKey = "some-super-secret-key";
137 |
138 | var ncryptObject = new ncrypt(_secretKey);
139 |
140 | // encrypting super sensitive data here
141 | var encryptedData = ncryptObject.encrypt(data);
142 | console.log("Encryption process...");
143 | console.log("Plain Text : " + data);
144 | console.log("Cipher Text : " + encryptedData);
145 |
146 | // decrypted super encrypted data here
147 | var decryptedData = ncryptObject.decrypt(encryptedData);
148 | console.log("... and then decryption...");
149 | console.log("Decipher Text : " + decryptedData);
150 | console.log("...done.");
151 | ```
152 |
153 | ### Object Encryption
154 |
155 | Encryption and decryption of JavaScript object literal has never been simpler than this.
156 |
157 | To encrypt and decrypt JavaScript object literal, simply use `encrypt()` and `decrypt()` function from an instance. This will use AES-CBC encryption algorithm.
158 |
159 |
160 | ```javascript
161 | var { ncrypt } = require("ncrypt-js");
162 |
163 | var _secretKey = "some-super-secret-key";
164 | var object = {
165 | NycryptJs: "is cool and fun.",
166 | You: "should try it!"
167 | }
168 |
169 | var ncryptObject = new ncrypt('ncrypt-js');
170 |
171 | // encrypting super sensitive data here
172 | var encryptedObject = ncryptObject.encrypt(object);
173 | console.log("Encryption process...");
174 | console.log("Plain Object : ", object);
175 | console.log("Encrypted Object : " + encryptedObject);
176 |
177 | // decrypted super sensitive data here
178 | var decryptedObject = ncryptObject.decrypt(encryptedObject);
179 | console.log("... and then decryption...");
180 | console.log("Decipher Text : ", decryptedObject);
181 | console.log("...done.");
182 | ````
183 | 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.
184 |
185 | ```bash
186 | # .env
187 |
188 | # used internally to set the `key`
189 | KEY='sshhhh this is a super secret key'
190 |
191 | # used internally to set the `encoding` - ['base64' | 'binary' | 'hex' | 'ucs-2' | 'ucs2' | 'utf16le']
192 | NCRYPT_ENC='hex'
193 |
194 | SECRET='this is our hashing secret'
195 | ```
196 | When creating your object, you can use the `SECRET` from your environment e.g:
197 |
198 | ```js
199 | var { ncrypt } = require('ncrypt-js');
200 | var { encrypt, decrypt } = new ncrypt(process.env.SECRET);
201 | ...
202 | ```
203 | _**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._
204 |
205 | _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_
206 |
207 | ## Built With
208 |
209 | Written in [TypeScript](https://typscriptlang.org/), built into ECMAScript 5 using the TypeScript compiler.
210 |
211 | ## Contribution
212 |
213 | To contribute, simply fork this project, and issue a pull request.
214 |
215 | ## Versioning
216 |
217 | 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).
218 |
219 | ## Authors
220 |
221 | * **Chukwuemeka Ajima** - _Initial work_ - [ajimae](https://github.com/ajimae)
222 |
223 |
224 |
225 |
226 | ## License
227 |
228 | This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
229 |
230 | ## Acknowledgments
231 |
232 | * This library was developed to simplify how data is encrypted and decrypted in javascript.
233 | * Made available by open source and special thanks to [Shahid](https://twitter.com/codeforgeek) for his super simple [article](https://codeforgeek.com/encrypt-and-decrypt-data-in-node-js/) on node core encryption (crypto) library.
234 | * Thanks to [danang-id](https://github.com/danang-id) whose [README](https://github.com/danang-id/simple-crypto-js/blob/master/README.md) was very insightful and [Jorgeblom](https://stackoverflow.com/users/2861702/jorgeblom) for his custom cipher algorithm on this stackoverflow [answer](https://stackoverflow.com/a/54026460/4907157)
235 |
--------------------------------------------------------------------------------
/index.ts:
--------------------------------------------------------------------------------
1 | import ncrypt from './src/ncrypt';
2 |
3 | module.exports = ncrypt;
4 | module.exports.ncrypt = ncrypt;
5 | export default ncrypt;
6 | export { ncrypt }
7 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "ncrypt-js",
3 | "version": "2.1.2",
4 | "description": "a light weight javascript data encryption and decryption library",
5 | "main": "dist/index.js",
6 | "scripts": {
7 | "clean": "rm -rf dist",
8 | "prepare": "yarn build",
9 | "build": "yarn clean;tsc --outDir dist",
10 | "test": "cross-env TS_NODE_FILES=true nyc mocha --exit --require ts-node/register --colors test/**/*.ts",
11 | "coverage": "nyc report --reporter=text-lcov | coveralls"
12 | },
13 | "repository": {
14 | "type": "git",
15 | "url": "git+https://github.com/ajimae/ncrypt-js.git"
16 | },
17 | "keywords": [
18 | "ncrypt-js",
19 | "crypto",
20 | "cipher",
21 | "decrypt",
22 | "encrypt",
23 | "typescript",
24 | "ecmascript5",
25 | "encryption",
26 | "cryptojs",
27 | "cryptography",
28 | "decryption",
29 | "javascript-library"
30 | ],
31 | "author": "ajimae",
32 | "license": "MIT",
33 | "bugs": {
34 | "url": "https://github.com/ajimae/ncrypt-js/issues"
35 | },
36 | "homepage": "https://github.com/ajimae/ncrypt-js#readme",
37 | "devDependencies": {
38 | "@types/chai": "^4.2.10",
39 | "@types/mocha": "^5.2.7",
40 | "@types/node": "^12.12.29",
41 | "chai": "^4.2.0",
42 | "coveralls": "^3.0.9",
43 | "cross-env": "^5.2.1",
44 | "mocha": "^6.2.2",
45 | "mocha-istanbul": "^0.3.0",
46 | "mocha-lcov-reporter": "^1.3.0",
47 | "nyc": "^14.1.1",
48 | "ts-node": "^8.6.2",
49 | "typescript": "3.8.3"
50 | },
51 | "files": [
52 | "dist",
53 | "package.json",
54 | "LICENSE"
55 | ]
56 | }
57 |
--------------------------------------------------------------------------------
/src/ncrypt.ts:
--------------------------------------------------------------------------------
1 | import * as crypto from 'crypto';
2 |
3 | type TNCRYPT_ENC = 'base64' | 'binary' | 'hex' | 'ucs-2' | 'ucs2' | 'utf16le';
4 |
5 | /**
6 | * @class Ncrypt
7 | * @type {Ncrypt.