@vvlad1973/crypto

A TypeScript library for encrypting and decrypting text using AES-256-CTR encryption with PBKDF2 key derivation.

This library uses Node.js native crypto module for secure encryption operations.

Features

• AES-256-CTR encryption
• PBKDF2 key derivation with configurable parameters
• Support for both number and Buffer initialization vectors
• TypeScript support with full type definitions
• Dual API: constructor with options object or separate parameters
• UUID v4 generation utility
• Zero external dependencies (uses native Node.js crypto)

Installation

npm install @vvlad1973/crypto

Usage

Importing

import Crypto, { CryptoOptions, isCrypto } from '@vvlad1973/crypto';

Basic Usage

import Crypto from '@vvlad1973/crypto';

const password = 'your-password';
const salt = 'your-salt';

// Create an instance using separate parameters
const crypto = new Crypto(password, salt);

// Encrypt a text
const plainText = 'Hello, World!';
const encryptedText = crypto.encrypt(plainText);
console.log('Encrypted:', encryptedText);

// Decrypt the text
const decryptedText = crypto.decrypt(encryptedText);
console.log('Decrypted:', decryptedText);

Using Options Object

import Crypto, { CryptoOptions } from '@vvlad1973/crypto';

const options: CryptoOptions = {
  password: 'your-password',
  salt: 'your-salt',
  algorithm: 'SHA512',
  iterations: 1000,
  keyLength: 32,
  iv: 5
};

const crypto = new Crypto(options);
const encrypted = crypto.encrypt('Secret message');
const decrypted = crypto.decrypt(encrypted);

Using Buffer IV

import Crypto from '@vvlad1973/crypto';
import { randomBytes } from 'crypto';

// Generate a random 16-byte initialization vector
const ivBuffer = randomBytes(16);

const crypto = new Crypto({
  password: 'your-password',
  salt: 'your-salt',
  iv: ivBuffer
});

const encrypted = crypto.encrypt('Secret message');

Generating UUIDs

import Crypto from '@vvlad1973/crypto';

// Generate a UUID v4
const uuid = Crypto.getUUID();
console.log(uuid); // e.g., '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

Type Guard

import Crypto, { isCrypto } from '@vvlad1973/crypto';

const crypto = new Crypto('password', 'salt');

if (isCrypto(crypto)) {
  // TypeScript knows crypto has encrypt/decrypt methods
  const encrypted = crypto.encrypt('text');
}

API

Constructor

Using separate parameters

new Crypto(
  password: string,
  salt: string,
  algorithm?: string,
  iterations?: number,
  keyLength?: number,
  iv?: number | Buffer
)

Using options object

new Crypto(options: CryptoOptions)

CryptoOptions interface:

interface CryptoOptions {
  password: string;      // Password for key derivation
  salt: string;          // Salt for key derivation
  algorithm?: string;    // Hash algorithm (default: 'SHA512')
  iterations?: number;   // PBKDF2 iterations (default: 1000)
  keyLength?: number;    // Key length in bytes (default: 32)
  iv?: number | Buffer;  // Initialization vector (default: random 16 bytes)
}

Parameters:

• password - The password used for PBKDF2 key derivation
• salt - The salt used for PBKDF2 key derivation
• algorithm - Hash algorithm for PBKDF2 (default: 'SHA512')
• iterations - Number of PBKDF2 iterations (default: 1000)
• keyLength - Derived key length in bytes (default: 32 for AES-256)
• iv - Initialization vector: either a number (converted to 16-byte Buffer) or a Buffer directly (default: random 16 bytes)

Instance Methods

encrypt(text: string): string

Encrypts the given text using AES-256-CTR encryption.

• text - The plain text to encrypt
• Returns: The encrypted text as a hexadecimal string

decrypt(text: string): string

Decrypts the given encrypted text using AES-256-CTR decryption.

• text - The encrypted text as a hexadecimal string
• Returns: The decrypted plain text

Static Methods

Crypto.getUUID(): string

Generates a random UUID v4 string using Node.js native crypto.

• Returns: A UUID v4 string (e.g., '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d')

Utility Functions

isCrypto(object: any): object is Crypto

Type guard function to check if an object is an instance of Crypto.

• object - The object to check
• Returns: true if the object is a Crypto instance, false otherwise

Testing

This library uses Vitest for testing with comprehensive coverage requirements.

Run all tests

npm test

Run tests in watch mode

npm run test:watch

Run tests with UI

npm run test:ui

Generate coverage report

npm run test:coverage

Coverage Requirements

• Lines: 90%
• Functions: 85%
• Branches: 90%
• Statements: 90%

Current coverage: 100% across all metrics

Building

To build the TypeScript project:

npm run build

This will compile TypeScript files to the dist directory with type definitions.

Documentation

To generate TypeDoc documentation:

npm run doc

Documentation will be generated in the docs directory.

License

This project is licensed under the MIT License with Commercial Use - see the LICENSE file for details.

Author

Vladislav Vnukovskiy [email protected]