@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 | Yes | - | Password is not required if staticKey and staticKeyEncoding is provided. Password is used to derive the encryption/decryption key. | Both | | salt | string | Yes | - | Salt is not required if staticKey and staticKeyEncoding is provided. Salt used in key derivation. | Both | | staticKey | string | Yes | - | staticKey is not required if the password and salt is provided. 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 | Yes | - | staticKeyEncoding is not required if the password and salt is provided. 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 it is default to utf8. For encryption, you can choose between hex or base64 as the output string. | Both | | IVEncodingInput | 'hex' | 'base64' | No | 'hex'. | Sets the encoding format of the provided IV used for decryption. WARNING⚠️: Make sure to use the correct encoding of the provided IV. If you use the staticIV on encryption as base64, the IVEncodingInput must be base64 also. | 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.

1. Open terminal
2. type node. This will enter the node REPL.
3. Type this: console.log(require('crypto').randomBytes(32).toString('hex'))
4. It will return something like this: c02e74c1c3f829e13b298361c39e9df263dc5efb16d0639f00255a86863447e0
5. Copy it and save on your secrets.
6. 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 ❤️