cipher-utility

A utility library for robust and secure cryptographic operations using Node.js crypto module. It provides easy-to-use methods for encrypting and decrypting text with AES-GCM, leveraging Scrypt for key derivation.

Features

• Strong Encryption: Uses AES-GCM ( Galois/Counter Mode) which provides both confidentiality and authenticity. Supports aes-256-gcm, aes-192-gcm, and aes-128-gcm.
• Secure Key Derivation: Employs scryptSync for deriving encryption keys from passwords, offering protection against brute-force attacks.
• Random Salt & IV: Automatically generates a unique salt and initialization vector (IV) for each encryption operation, enhancing security.
• Additional Authenticated Data (AAD): Supports AAD to ensure the integrity of non-confidential data alongside the encrypted payload.
• Customizable Parameters: Allows configuration of Scrypt parameters (N, r, p) for fine-tuning security vs. performance.
• Flexible Encodings: Supports base64 and hex encodings for encrypted data, IV, tag, and salt.
• Type-Safe: Written in TypeScript with comprehensive type definitions.
• Error Handling: Gracefully handles decryption failures (e.g., wrong password, corrupted data) by returning null.

Installation

npm install cipher-utility
# or
yarn add cipher-utility
# or
bun add cipher-utility

Usage

import { Cipher } from 'cipher-utility';

const cipher = new Cipher();

const text = 'This is a secret message!';
const password = 'super-strong-password123';

// Encrypt
const encrypted = cipher.encrypt(text, password);

// Decrypt
const decrypted = cipher.decrypt(encrypted, password);

console.log('Decrypted:', decrypted); // Output: This is a secret message!

API

new Cipher(params?: ScryptParams)

Creates a new Cipher instance.

• params (optional): An object to customize Scrypt parameters.
  • N: CPU/memory cost parameter (default: 4096).
  • r: Block size (default: 8).
  • p: Parallelization parameter (default: 1).

Note: The key length is automatically determined based on the algorithm used (16 bytes for AES-128, 24 bytes for AES-192, 32 bytes for AES-256).

cipher.encrypt(text, password, algorithm?, encoding?, aad?)

Encrypts the input text.

• text: string: The plaintext to encrypt.
• password: string: The password to derive the encryption key.
• algorithm?: CipherGCMTypes: The AES-GCM algorithm to use (default: 'aes-256-gcm'). Supported: 'aes-256-gcm', 'aes-192-gcm', 'aes-128-gcm'.
• encoding?: Encoding: The encoding for the output strings (encrypted, iv, tag, salt) (default: 'base64'). Supported: 'base64', 'hex'.
• aad?: string: Optional Additional Authenticated Data.
• Returns: EncryptedData object:

  type EncryptedData = {
    encrypted: string; // The encrypted text
    iv: string;        // The initialization vector
    tag: string;       // The authentication tag
    salt: string;      // The salt used for key derivation
    aad?: string;     // The AAD, if provided
  };

cipher.decrypt(encryptedData, password, algorithm?, encoding?)

Decrypts the encrypted data.

• encryptedData: EncryptedData: The object returned by the encrypt method.
• password: string: The password used for encryption.
• algorithm?: CipherGCMTypes: The AES-GCM algorithm used for encryption (default: 'aes-256-gcm').
• encoding?: Encoding: The encoding used for the input strings in encryptedData (default: 'base64').
• Returns: string | null: The decrypted plaintext, or null if decryption fails (e.g., wrong password, tampered data, incorrect AAD).

Development

Prerequisites

• Node.js (LTS recommended)
• Bun (for running scripts, optional if you prefer npm/yarn)

Setup

1. Clone the repository:

   git clone https://github.com/liorcodev/cipher-utility.git
   cd cipher-utility

2. Install dependencies:

   bun install
   # or
   npm install

Scripts

• bun run format: Format code using Prettier.
• bun run dev: Run index.ts in watch mode (useful for quick testing).
• bun run build: Build the library using tsup. Output is in the dist folder.
• bun test: Run tests using Bun's test runner (tests are in src/cipher.test.ts).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE file for more information.