aes256-async 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesus Graterol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# AES-256 Async
+
+The `aes256-async` package allows developers to easily encrypt and decrypt data by making use of the [AES-256](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) specification. It exposes syncrhonous and asynchronous functions to avoid blocking the main thread. Moreover, the secret can be of any size because it is hashed using the [Secure Hash Algorithm 2 (SHA-256)](https://en.wikipedia.org/wiki/SHA-2).
+
+
+
+
+
+</br>
+
+## Getting Started
+
+Install the package:
+```bash
+npm install -S aes256-async
+```
+
+
+## Usage
+
+Encrypt and decrypt data asynchronously:
+
+```typescript
+import { encrypt, decrypt } from 'aes256-async';
+
+const secret = 'My.$ecreT';
+
+await encrypt(secret, 'Hello world!')
+// OrGfQ/91d7p/1BN6Q07Jly5ZK0/7pyczjk5vgw==
+
+await decrypt(secret, 'OrGfQ/91d7p/1BN6Q07Jly5ZK0/7pyczjk5vgw==')
+// 'Hello world!'
+```
+
+
+Encrypt and decrypt data synchronously (blocking the main thread):
+
+```typescript
+import { encryptSync, decryptSync } from 'aes256-async';
+
+const secret = 'My.$ecreT';
+
+encryptSync(secret, 'Hello world!')
+// OrGfQ/91d7p/1BN6Q07Jly5ZK0/7pyczjk5vgw==
+
+decryptSync(secret, 'OrGfQ/91d7p/1BN6Q07Jly5ZK0/7pyczjk5vgw==')
+// 'Hello world!'
+```
+
+
+
+
+
+<br/>
+
+## Built With
+
+- TypeScript
+
+
+
+
+
+<br/>
+
+## Acknowledgements
+
+- [JamesMGreene/node-aes256](https://github.com/JamesMGreene/node-aes256)
+
+
+
+
+<br/>
+
+## Running the Tests
+
+```bash
+# integration tests
+npm run test:integration
+
+# unit tests
+npm run test:unit
+```
+
+
+
+
+
+<br/>
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)
+
+
+
+
+
+<br/>
+
+## Deployment
+
+Install dependencies:
+```bash
+npm install
+```
+
+
+Build the library:
+```bash
+npm start
+```
+
+
+Publish to `npm`:
+```bash
+npm publish
+```

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Decrypts an encrypted message back to readable text.
+ * @param secret
+ * @param encryptedData
+ * @returns Promise<string>
+ * @throws
+ * - INVALID_OR_EMPTY_DATA: if the data is not a string or is an empty string.
+ * - INVALID_SECRET: if the secret is not a string or is an empty string.
+ * - INVALID_ENCRYPTED_DATA: if the encrypted data decrypts to an invalid or empty string.
+ * - WRONG_SECRET: if the data cannot be decrypted.
+ */
+declare const decrypt: (secret: string, encryptedData: string) => Promise<string>;
+/**
+ * Encrypts a message to a piece of text that cannot be read unless it is decrypted with the secret
+ * that was used to encrypt it.
+ * @param secret
+ * @param data
+ * @returns Promise<string>
+ * @throws
+ * - INVALID_OR_EMPTY_DATA: if the data is not a string or is an empty string.
+ * - INVALID_SECRET: if the secret is not a string or is an empty string.
+ * - CORRUPTED_DATA: if the decrypted data does not match the original data.
+ * - WRONG_SECRET: if the data cannot be decrypted.
+ */
+declare const encrypt: (secret: string, data: string) => Promise<string>;
+/**
+ * Decrypts an encrypted message back to readable text.
+ * @param secret
+ * @param encryptedData
+ * @returns string
+ * @throws
+ * - INVALID_OR_EMPTY_DATA: if the data is not a string or is an empty string.
+ * - INVALID_SECRET: if the secret is not a string or is an empty string.
+ * - INVALID_ENCRYPTED_DATA: if the encrypted data decrypts to an invalid or empty string.
+ * - WRONG_SECRET: if the data cannot be decrypted.
+ */
+declare const decryptSync: (secret: string, encryptedData: string) => string;
+/**
+ * Encrypts a message to a piece of text that cannot be read unless it is decrypted with the secret
+ * that was used to encrypt it.
+ * @param secret
+ * @param data
+ * @returns string
+ * @throws
+ * - INVALID_OR_EMPTY_DATA: if the data is not a string or is an empty string.
+ * - INVALID_SECRET: if the secret is not a string or is an empty string.
+ * - CORRUPTED_DATA: if the decrypted data does not match the original data.
+ * - WRONG_SECRET: if the data cannot be decrypted.
+ */
+declare const encryptSync: (secret: string, data: string) => string;
+export { decrypt, encrypt, decryptSync, encryptSync, };

package/dist/index.js

@@ -0,0 +1 @@
+import{Buffer}from"node:buffer";import{decryptData,encryptData,decryptDataSync,encryptDataSync}from"./utils/index.js";import{validateInput,validateEncryptedBuffer,validateDecryptedData,validateEncryptionResult}from"./validations/index.js";const decrypt=async(t,a)=>{validateInput(t,a);const e=Buffer.from(a,"base64");validateEncryptedBuffer(e);const r=await decryptData(t,e);return validateDecryptedData(r),r},encrypt=async(t,a)=>{validateInput(t,a);const e=await encryptData(t,a);return validateEncryptionResult(a,await decrypt(t,e)),e},decryptSync=(t,a)=>{validateInput(t,a);const e=Buffer.from(a,"base64");validateEncryptedBuffer(e);const r=decryptDataSync(t,e);return validateDecryptedData(r),r},encryptSync=(t,a)=>{validateInput(t,a);const e=encryptDataSync(t,a);return validateEncryptionResult(a,decryptSync(t,e)),e};export{decrypt,encrypt,decryptSync,encryptSync};

package/dist/shared/constants.d.ts

@@ -0,0 +1,11 @@
+declare const CIPHER_ALGORITHM = "aes-256-ctr";
+declare const HASHING_ALGORITHM = "sha256";
+/**
+ * Illegal Character
+ * Many web pages and other document formats use UTF-8. This is the default character encoding.
+ * When decoding a Buffer into a string that does not exclusively contain valid UTF-8 data, the
+ * Unicode replacement character U+FFFD � will be used to represent those errors.
+ * https://nodejs.org/docs/latest/api/buffer.html#buffers-and-character-encodings
+ */
+declare const ILLEGAL_CHARACTER = "\uFFFD";
+export { CIPHER_ALGORITHM, HASHING_ALGORITHM, ILLEGAL_CHARACTER, };

package/dist/shared/constants.js

@@ -0,0 +1 @@
+const CIPHER_ALGORITHM="aes-256-ctr",HASHING_ALGORITHM="sha256",ILLEGAL_CHARACTER="�";export{CIPHER_ALGORITHM,HASHING_ALGORITHM,ILLEGAL_CHARACTER};

package/dist/shared/errors.d.ts

@@ -0,0 +1,5 @@
+type IErrors = 'INVALID_OR_EMPTY_DATA' | 'INVALID_SECRET' | 'INVALID_ENCRYPTED_DATA' | 'WRONG_SECRET' | 'CORRUPTED_DATA';
+declare const ERRORS: {
+    [key in IErrors]: IErrors;
+};
+export { ERRORS, };

package/dist/shared/errors.js

@@ -0,0 +1 @@
+const ERRORS={INVALID_OR_EMPTY_DATA:"INVALID_OR_EMPTY_DATA",INVALID_SECRET:"INVALID_SECRET",INVALID_ENCRYPTED_DATA:"INVALID_ENCRYPTED_DATA",WRONG_SECRET:"WRONG_SECRET",CORRUPTED_DATA:"CORRUPTED_DATA"};export{ERRORS};

package/dist/utils/index.d.ts

@@ -0,0 +1,42 @@
+import { Buffer } from 'node:buffer';
+/**
+ * Hashes the provided secret using the SHA-256 algorithm.
+ * @param secret
+ * @returns Promise<Buffer>
+ */
+declare const __hashSecret: (secret: string) => Promise<Buffer>;
+/**
+ * Hashes the provided secret using the SHA-256 algorithm.
+ * @param secret
+ * @returns Buffer
+ */
+declare const __hashSecretSync: (secret: string) => Buffer;
+/**
+ * Creates the cipher with random initialization vectors and returns the encrypted data.
+ * @param secret
+ * @param data
+ * @returns Promise<string>
+ */
+declare const encryptData: (secret: string, data: string) => Promise<string>;
+/**
+ * Creates the cipher with random initialization vectors and returns the encrypted data.
+ * @param secret
+ * @param data
+ * @returns string
+ */
+declare const encryptDataSync: (secret: string, data: string) => string;
+/**
+ * Creates the decipher and returns the result of the decryption.
+ * @param secret
+ * @param encryptedData
+ * @returns Promise<string>
+ */
+declare const decryptData: (secret: string, encryptedData: Buffer) => Promise<string>;
+/**
+ * Creates the decipher and returns the result of the decryption.
+ * @param secret
+ * @param encryptedData
+ * @returns string
+ */
+declare const decryptDataSync: (secret: string, encryptedData: Buffer) => string;
+export { __hashSecret, __hashSecretSync, encryptData, encryptDataSync, decryptData, decryptDataSync, };

package/dist/utils/index.js

@@ -0,0 +1 @@
+import{Buffer}from"node:buffer";import crypto from"node:crypto";import{CIPHER_ALGORITHM,HASHING_ALGORITHM}from"../shared/constants.js";const __hashSecret=r=>new Promise(((t,e)=>{const a=crypto.createHash(HASHING_ALGORITHM);a.on("readable",(()=>{const r=a.read();r&&t(r)})),a.on("error",(r=>e(r))),a.write(r),a.end()})),__hashSecretSync=r=>{const t=crypto.createHash(HASHING_ALGORITHM);return t.update(r),t.digest()},encryptData=async(r,t)=>{const e=crypto.randomBytes(16),a=crypto.createCipheriv(CIPHER_ALGORITHM,await __hashSecret(r),e),c=Buffer.from(t),n=a.update(c);return Buffer.concat([e,n,a.final()]).toString("base64")},encryptDataSync=(r,t)=>{const e=crypto.randomBytes(16),a=crypto.createCipheriv(CIPHER_ALGORITHM,__hashSecretSync(r),e),c=Buffer.from(t),n=a.update(c);return Buffer.concat([e,n,a.final()]).toString("base64")},decryptData=async(r,t)=>{const e=t.subarray(0,16),a=await __hashSecret(r),c=crypto.createDecipheriv(CIPHER_ALGORITHM,a,e),n=t.subarray(16);return Buffer.concat([c.update(n),c.final()]).toString()},decryptDataSync=(r,t)=>{const e=t.subarray(0,16),a=crypto.createDecipheriv(CIPHER_ALGORITHM,__hashSecretSync(r),e),c=t.subarray(16);return Buffer.concat([a.update(c),a.final()]).toString()};export{__hashSecret,__hashSecretSync,encryptData,encryptDataSync,decryptData,decryptDataSync};

package/dist/validations/index.d.ts

@@ -0,0 +1,35 @@
+import { Buffer } from 'node:buffer';
+/**
+ * Ensures the data and the secret are valid strings.
+ * @param secret
+ * @param data
+ * @throws
+ * - INVALID_OR_EMPTY_DATA: if the data is not a string or is an empty string.
+ * - INVALID_SECRET: if the secret is not a string or is an empty string.
+ */
+declare const validateInput: (secret: string, data: string) => void;
+/**
+ * Ensures the encrypted data is a valid string.
+ * @param input
+ * @throws
+ * - INVALID_ENCRYPTED_DATA: if the encrypted data decrypts to an invalid or empty string.
+ */
+declare const validateEncryptedBuffer: (input: Buffer) => void;
+/**
+ * Ensures the decrypted data is valid. So far, whenever an incorrect secret is provided, Node.js
+ * returns a string containing characters like �.
+ * @param data
+ * @throws
+ * - WRONG_SECRET: if the data cannot be decrypted.
+ */
+declare const validateDecryptedData: (data: string) => void;
+/**
+ * Compares the original data with the decrypted data to ensure the data was and can be decrypted
+ * correctly in the future.
+ * @param data
+ * @param decryptedData
+ * @throws
+ * - CORRUPTED_DATA: if the decrypted data does not match the original data.
+ */
+declare const validateEncryptionResult: (data: string, decryptedData: string) => void;
+export { validateInput, validateEncryptedBuffer, validateDecryptedData, validateEncryptionResult, };

package/dist/validations/index.js

@@ -0,0 +1 @@
+import{encodeError}from"error-message-utils";import{ILLEGAL_CHARACTER}from"../shared/constants.js";import{ERRORS}from"../shared/errors.js";const __validateSecret=e=>{if("string"!=typeof e||0===e.length)throw new Error(encodeError("The provided secret is invalid, please make sure to provide a non-empty string.",ERRORS.INVALID_SECRET))},__validateData=e=>{if("string"!=typeof e||0===e.length||e.includes(ILLEGAL_CHARACTER))throw new Error(encodeError("The provided data is invalid, please make sure to provide a non-empty string that only contains UTF-8 character encoding.",ERRORS.INVALID_OR_EMPTY_DATA))},validateInput=(e,r)=>{__validateSecret(e),__validateData(r)},validateEncryptedBuffer=e=>{if(e.length<17)throw new Error(encodeError("The provided encrypted data must decrypt to a non-empty string.",ERRORS.INVALID_ENCRYPTED_DATA))},validateDecryptedData=e=>{if("string"!=typeof e||0===e.length||e.includes(ILLEGAL_CHARACTER))throw new Error(encodeError("Failed to decrypt the data with the provided secret.",ERRORS.WRONG_SECRET))},validateEncryptionResult=(e,r)=>{if(e!==r)throw new Error(encodeError("The data could not be decrypted correctly.",ERRORS.CORRUPTED_DATA))};export{validateInput,validateEncryptedBuffer,validateDecryptedData,validateEncryptionResult};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "aes256-async",
+  "version": "1.0.0",
+  "description": "The aes256-async package allows developers to easily encrypt and decrypt data by making use of the AES-256 specification. It exposes syncrhonous and asynchronous functions to avoid blocking the main thread. Moreover, the secret can be of any size because it is hashed using the Secure Hash Algorithm 2 (SHA-256).",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "start": "ts-lib-builder --tsconfig=tsconfig.build.json",
+    "test": "echo \"Error: tests are executed with  npm run test:(e2e|integration|unit|bench)\" && exit 1",
+    "test:e2e": "vitest run --config=vitest.test-e2e.config.ts",
+    "test:integration": "vitest run --config vitest.test-integration.config.ts",
+    "test:unit": "vitest run --config vitest.test-unit.config.ts",
+    "test:bench": "vitest bench",
+    "watch-test:e2e": "vitest --config=vitest.test-e2e.config.ts",
+    "watch-test:integration": "vitest --config vitest.test-integration.config.ts",
+    "watch-test:unit": "vitest --config vitest.test-unit.config.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jesusgraterol/aes256-async.git"
+  },
+  "keywords": [
+    "encryption",
+    "security",
+    "aes-256",
+    "sha-256",
+    "web",
+    "utilities",
+    "privacy"
+  ],
+  "author": "Jesus Graterol",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jesusgraterol/aes256-async/issues"
+  },
+  "homepage": "https://github.com/jesusgraterol/aes256-async#readme",
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint-config-airbnb-typescript": "^18.0.0",
+    "ts-lib-builder": "^1.0.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "error-message-utils": "^1.1.2"
+  }
+}