@a14313/encryption-utils

@a14313/encryption-utils

A lightweight and easy-to-use encryption/decryption utility for Node.js using AES (default aes-256-cbc) and the built-in crypto module.

Changelogs

Check the Changelogs

✨ Features

• AES-256-CBC encryption by default (customizable)
• Supports configurable encoding, key length, password, salt, and IV size
• Simple API for encrypting and decrypting string payloads
• Uses the scryptSync for generation of key
• Written in TypeScript

📦 Installation

npm

npm install @a14313/encryption-utils

pnpm

pnpm install @a14313/encryption-utils

Usage

🔧 Cryptography Options Table

encrypt(payload: string, options)

decrypt(payload: string, iv: string, options)

options

Option	Type	Required	Default	Description	Usage
algorithm	string	No	aes-256-cbc	Encryption algorithm (e.g., 'aes-256-cfb').	Both
password	string	No	-	Password is not required if staticKey and staticKeyEncoding is provided. Password is used to derive the encryption/decryption key.	Both
salt	string	No	-	Salt is not required if staticKey and staticKeyEncoding is provided. Salt used in key derivation.	Both
staticKey	string	No	-	Static key is used for generating a cipher. Make sure to generate your own key and use hex or base64 encoding when setting this.	Both
staticKeyEncoding	hex | base64	No	-	Sets the encoding of the provided staticKey.	Both
keyLength	number	No	32	Length of the derived key in bytes (16, 24, 32, etc.). Depending on the algorithm you set, you should set the keyLength accordingly. Recommended to use the default algorithm and keyLength.	Both
staticIV	string	No	Random 16 bytes IV	When setting staticIV make sure to generate your own 16 bytes IV with either hex or base64 encoding. WARNING⚠️: Setting a static IV is vulnerable to identical plaintext blocks. When the staticIV is set, the encrypted data will become predictable because it will produce identical blocks. It is recommended to use the default instead. Just don't use this property and it will set the default.	Encryption only
staticIVEncoding	hex | base64	No	-	Sets the encoding of the provided staticIV	Encryption only
encodingInput	'utf8'	No	'utf8'.	Encoding of the input string. For encryption, utf8. For decryption hex	Both
encodingOutput	'hex' | 'base64'	No	'hex'.	Output format of the encrypted string. For decryption, utf8.	Both
IVEncodingInput	'hex' | 'base64'	No	'hex'.	Sets the encoding format of the provided IV used for decryption.	Decryption only
includeLogs	boolean	No	false	If set to true this will log the arguments that has been passed on the function.	Both
ivSize	number	No	16	Size of the IV in bytes (usually 16 for AES) Deprecated. Check the 1.3.0	Encryption only (Deprecated)
type	'encryption' | 'decryption'	No	-	Operation mode to perform. This is for type discrimination. The type discrimination is managed internally. Check the 1.2.0	Both (Deprecated)

🔐 Encryption

For commonJS
const { encrypt } = require('@a14313/encryption-utils');

import { encrypt } from '@a14313/encryption-utils';

const encrypted = encrypt('hello world', {
    password: 'strong-password',
    salt: 'unique-salt',
});

// RETURN:
// {
//     message: 'Encrypted successfully',
//     iv: '33eeecbb0867738956153ebae70307e9',
//     value: 'c63033f6b55bbb8b194626b903d986a0'
// }

Dont worry about the iv being returned. It is needed for decrypting the data on your other service. Even when an attacker gets the iv, it is unique in every encryption 😉. This prevents the producing of identical plaintext blocks Learn more about plaintext blocks.
Plus, the attacker needs the password and salt. So keep it on the secrets manager or .env.

🔓 Decryption

For commonJS
const { decrypt } = require('@a14313/encryption-utils');

import { decrypt } from '@a14313/encryption-utils';

// Pass the generated "iv" from the encrypted data to the decrypt function or to the service that is decrypting the data. It's like a public key, kind of 😅. The iv will be used to decrypt the data.

const decrypted = decrypt(encrypted.value, encrypted.iv, {
    password: 'strong-password',
    salt: 'unique-salt',
});

// RETURN: hello world

More examples

Most of the time you wanna encrypt more complicated data types other than string.
What if you want to encrypt a data other than string? A number, boolean, object, array, etc.
Place it on an object 😎.

🔐 Encryption

const sampleObject = {
    stringType: 'Hello, world!',
    numberType: 42,
    booleanType: true,
    nullType: null,
    objectType: {
        nestedKey: 'nestedValue',
    },
    arrayType: [1, 'two', false, null],
    dateType: new Date(),
};

Then, stringify the object:

const encrypted = encrypt(JSON.stringify(sampleObject), {
    password: 'test',
    salt: 'salty',
});

Return:

{
    message: 'Encrypted successfully',
    iv: '3aa2876e83c2b7d232a26ae09070bc00',
    value: '0e7c40d896dfb13f93dfcfc67e0f1b64c458abe44405e005240a6f53a8596df8955a143e740f5e1a4f9c34ed646c356239ce4df67433812212bde4af29820361374bfee977aea02ff0b62db43959859a60d2d7a98ce3a420c08981b4e189810e8913eb9ab0dac62ff9d32e64a373c9317cf548bfdf0fdd7cf34ec78018db7118dcb9612399a0fd3cdc8c5e6a89b92f1d2fedc6478298f3c425a57b4ab82dd9bdd41b8dc72bc2e9aa65606282d240a037111ac1ec1364269c188b244275942a0c17f7c052f67569c4ef7ccb604d263348b7037a0b4f130182cfe0917d1fbcc1fd'
}

🔓 Decryption

const decrypted = decrypt(encrypted.value, encrypted.iv, {
    password: 'test',
    salt: 'salty',
});

Then, parse the returned string 😎:

console.log(JSON.parse(decrypted));

Return:

{
    stringType: 'Hello, world!',
    numberType: 42,
    booleanType: true,
    nullType: null,
    objectType: { nestedKey: 'nestedValue' },
    arrayType: [ 1, 'two', false, null ],
    dateType: '2025-07-29T00:43:36.885Z',
}

🚨 Important

Generate a strong password and salt using crypto and save it on your environment (.env) or secrets manager (recommended).

How to generate a secure password and salt

You should have a NodeJS or NVM installed on your machine.

• Open terminal
• type node. This will enter the node REPL.
• Type this: console.log(require('crypto').randomBytes(32).toString('hex'))
• It will return something like this: c02e74c1c3f829e13b298361c39e9df263dc5efb16d0639f00255a86863447e0
• Copy it and save on your secrets.
• Do the same for the salt.

Note: For passwords it is recommended to have 32 bytes for the length, and 16 bytes for the salt.

The generated password and salt for encryption should be the same on the service that is decrypting the data, otherwise it will fail.

Always put the passwords, salts, and secrets on the environment

Happy HACKING 😉

Made by developer for developer. Made with love ❤️