base-encryption

A unified encryption library for Node.js and browser environments, providing simple interfaces for one-way hashing and two-way AES encryption.

🎉 Version 3.1 - Performance & Security Optimization

Common-Encryption v3.1 introduces configurable security levels, providing optimal performance for every use case:

• ⚡ Up to 297x faster encryption with configurable security levels
• 🎯 Smart defaults - Choose fast, standard, high, or maximum security
• ✅ OWASP 2023 compliant by default (600,000 iterations)
• 🔄 Full backward compatibility - existing code works unchanged
• 🔐 AES-GCM authenticated encryption with hardware acceleration
• 📦 84% smaller bundle - uses native Web Crypto API

Node.js 18+ Required | v2.x encrypted data cannot be decrypted by v3.x

⚠️ Security Notice

Version 3.0 meets modern cryptographic standards and is suitable for production use with appropriate security practices.

Security Features:

• ✅ OWASP 2023 Compliant: 600,000 PBKDF2-SHA256 iterations
• ✅ Authenticated Encryption: AES-GCM prevents tampering and padding oracle attacks
• ✅ Hardware Acceleration: Native Web Crypto API performance
• ⚠️ MD5 Support: Available for non-security use cases (checksums, IDs) but NOT for password hashing or authentication

Appropriate Use Cases:

• Production web applications
• Password-protected data encryption
• Secure configuration storage
• Cross-platform encrypted storage
• Educational and development purposes

Important Considerations:

• MD5 hashing should ONLY be used for checksums or ID generation, never for security
• Use SHA-256 for all security-sensitive hashing operations
• Always use strong, unique passphrases for encryption
• AES-GCM provides both encryption and authentication in a single operation

Overview

base-encryption (published from common-encryption source) provides a modern, cross-platform encryption library that works seamlessly in both Node.js and browser environments. It offers:

• Cross-Platform Compatibility: Single API for Node.js 18+ and modern browsers
• AES-256-GCM Encryption: Authenticated encryption with native Web Crypto API
• Multiple Hashing Algorithms: SHA-256 (default) and MD5 support
• Automatic Type Handling: Works with strings and objects (auto-JSON conversion)
• Promise-Based API: Modern async/await patterns
• Zero Dependencies: Uses native browser/Node.js crypto
• Production Ready: OWASP 2023 compliant security standards

Installation

npm install common-encryption

Requirements:

• Node.js 18 or higher
• Modern browsers (Chrome, Firefox, Safari, Edge - 97%+ compatibility)

⚠️ Breaking Changes in v3.0

API Changes

• All functions now return Promises (must use async/await or .then())
• Node.js 18+ required (for Web Crypto API support)
• Encrypted data format changed (v2.x data cannot be decrypted)

Before (v2.x):

const hash = commonEncryption.oneWayEncrypt('data', true);
const encrypted = commonEncryption.twoWayEncrypt('secret', 'password');

After (v3.0):

const hash = await commonEncryption.oneWayEncrypt('data', true);
const encrypted = await commonEncryption.twoWayEncrypt('secret', 'password');

Data Format Incompatibility

• v2.x used AES-CBC with format: [salt][iv][ciphertext]
• v3.0 uses AES-GCM with format: [salt][iv][authTag][ciphertext]
• You cannot decrypt v2.x data with v3.0 due to algorithm change

📚 Migration Guide: v2.x → v3.0

Step 1: Update Package

npm install common-encryption@^3.1.1

Step 2: Update All Function Calls

Add async/await to all encryption/decryption calls:

// v2.x
function myFunction() {
  const encrypted = commonEncryption.twoWayEncrypt(data, password);
  return encrypted;
}

// v3.0
async function myFunction() {
  const encrypted = await commonEncryption.twoWayEncrypt(data, password);
  return encrypted;
}

Step 3: Re-encrypt Existing Data

v3.0 cannot decrypt v2.x encrypted data. You must:

1. Decrypt all existing data with v2.x
2. Upgrade to v3.0
3. Re-encrypt data with v3.0

// One-time migration script
import v2 from '[email protected]';
import commonEncryption from '[email protected]';

async function migrateData(oldEncryptedData, password) {
  // Decrypt with v2
  const plaintext = v2.twoWayDecrypt(oldEncryptedData, password);
  
  // Re-encrypt with v3
  const newEncryptedData = await commonEncryption.twoWayEncrypt(plaintext, password);
  
  return newEncryptedData;
}

Step 4: Update Node.js Version

Ensure Node.js 18+ is installed:

node --version  # Should be v18.0.0 or higher

📚 Migration Guide: v3.0 → v3.1

Performance Improvements Available

Version 3.1 introduces optional performance optimizations. Your existing v3.0 code continues to work without changes.

Why v3.0 Was Slow

Version 3.0 used a fixed 600,000 PBKDF2 iterations for all encryptions to meet OWASP 2023 compliance. While secure, this was overkill for many use cases:

• Real-time APIs suffered from ~113ms encryption latency
• Standard application data didn't need password-strength security
• Transport encryption was unnecessarily slow

What's New in v3.1

Version 3.1 adds configurable security levels while maintaining maximum security as the default:

• ✅ Default unchanged: 600,000 iterations (OWASP 2023 compliant)
• ⚡ Optional fast mode: 2,000 iterations (~0.36ms, 297x faster)
• ⚖️ Optional standard mode: 10,000 iterations (~2.14ms, 52x faster)
• 🔐 Optional high mode: 100,000 iterations (~19ms, 5.9x faster)

No Changes Required

Your existing v3.0 code works identically in v3.1:

// v3.0 code - no changes needed
const encrypted = await commonEncryption.twoWayEncrypt(data, passphrase);
const decrypted = await commonEncryption.twoWayDecrypt(encrypted, passphrase);
// Still uses 600,000 iterations (maximum security)

Opting Into Faster Performance

To improve performance for non-password use cases, add the options parameter:

Before (v3.0):

// Real-time API - slow (113ms)
async function encryptAPIResponse(data) {
  return await commonEncryption.twoWayEncrypt(data, apiKey);
}

After (v3.1):

// Real-time API - fast (0.36ms, 297x faster)
async function encryptAPIResponse(data) {
  return await commonEncryption.twoWayEncrypt(
    data,
    apiKey,
    { securityLevel: 'fast' }
  );
}

Migration Examples

Use Case 1: Session Tokens

// v3.0 - Slow (113ms)
const token = await commonEncryption.twoWayEncrypt(sessionData, secret);

// v3.1 - Fast (2.14ms, 52x faster)
const token = await commonEncryption.twoWayEncrypt(
  sessionData,
  secret,
  { securityLevel: 'standard' }
);

Use Case 2: User Preferences

// v3.0 - Slow (113ms)
const encrypted = await commonEncryption.twoWayEncrypt(preferences, userKey);

// v3.1 - Fast (2.14ms, 52x faster)
const encrypted = await commonEncryption.twoWayEncrypt(
  preferences,
  userKey,
  { securityLevel: 'standard' }
);

Use Case 3: Passwords (Keep Maximum Security)

// v3.0 and v3.1 - Same behavior (113ms, OWASP 2023 compliant)
const encrypted = await commonEncryption.twoWayEncrypt(password, masterKey);
// No changes needed - maximum security by default

Performance Improvements Summary

| Use Case | v3.0 Time | v3.1 Time | Improvement | |----------|-----------|-----------|-------------| | Real-time APIs | ~113ms | ~0.36ms | 297x faster | | Session tokens | ~113ms | ~2.14ms | 52x faster | | User data | ~113ms | ~19ms | 5.9x faster | | Passwords | ~113ms | ~113ms | Same (secure) |

Data Compatibility

All v3.0 encrypted data can be decrypted in v3.1:

• The encrypted data format hasn't changed
• Security levels only affect encryption speed, not the output format
• Mix and match: use different levels for different data

// v3.0 encrypted data
const v30Data = "...encrypted with v3.0...";

// v3.1 can decrypt it
const decrypted = await commonEncryption.twoWayDecrypt(v30Data, passphrase);
// Works perfectly - full backward compatibility

🆕 What's New in v3.1

Configurable Security Levels

• ⚡ Fast mode: 2,000 iterations for real-time applications
• ⚖️ Standard mode: 10,000 iterations for general data
• 🔐 High mode: 100,000 iterations for sensitive data
• 🛡️ Maximum mode: 600,000 iterations (default, OWASP 2023)

Performance Improvements

• 🚀 Up to 297x faster encryption with fast mode
• 📊 Configurable trade-offs between speed and security
• 🔄 Full backward compatibility with v3.0
• ✅ Zero breaking changes - existing code works unchanged

Developer Experience

• 📝 Simple API: Just add { securityLevel: 'fast' } option
• 🎯 Smart defaults: Maximum security without configuration
• 📊 Benchmark tool: Test performance on your hardware
• 📖 Comprehensive docs: Clear guidance for every use case

🆕 What's New in v3.0

Security Improvements

• ✅ PBKDF2 iterations increased from 100 to 600,000 (OWASP 2023 compliant)
• ✅ AES-GCM authenticated encryption prevents tampering and padding oracle attacks
• ✅ Hardware-accelerated crypto via native Web Crypto API
• ✅ Cryptographically secure random IV and salt generation

Performance Improvements

• ⚡ 10-100x faster encryption/decryption
• 📦 84% smaller bundle (50KB vs 330KB)
• 🚀 Zero crypto dependencies to maintain

Modern Standards

• 🌐 Web Crypto API - W3C standard, future-proof
• 📱 Universal compatibility - Browser and Node.js with same code
• 🔄 ES6 modules - Modern JavaScript import/export
• ✨ Promise-based API - Modern async patterns

Usage

Importing the Library

Node.js (ES Modules):

import commonEncryption from 'common-encryption';

Node.js (CommonJS):

const commonEncryption = require('common-encryption');

Browser (ES6 modules):

import commonEncryption from './node_modules/common-encryption/dist/index.js';

Browser (script tag):

<script src="node_modules/common-encryption/dist/index.js"></script>
<script>
  // Library is available as commonEncryption
</script>

Quick Start Examples

One-Way Hashing (SHA-256)

// Using async function
async function hashData() {
  const data = "mySecretData";
  const useSHA256 = true;
  
  // Hash the data
  const hash = await commonEncryption.oneWayEncrypt(data, useSHA256);
  console.log(hash); // SHA-256 hash string
}

// Or using top-level await (in ES modules)
const hash = await commonEncryption.oneWayEncrypt("mySecretData", true);
console.log(hash);

One-Way Hashing (MD5)

async function hashWithMD5() {
  const data = "myData";
  const useMD5 = false; // false = use MD5
  
  // Hash with MD5 (for checksums/IDs only, NOT for security)
  const hash = await commonEncryption.oneWayEncrypt(data, useMD5);
  console.log(hash); // MD5 hash string
}

Hash Comparison

async function verifyHash() {
  const hash = await commonEncryption.oneWayEncrypt("myPassword", true);
  const userInput = "myPassword";
  
  // Compare without exposing the original
  const isMatch = await commonEncryption.oneWayCompare(hash, userInput, true);
  console.log(isMatch); // true
}

Two-Way Encryption (String)

async function encryptString() {
  const passphrase = "mySecurePassphrase";
  const sensitiveData = "Sensitive Information";
  
  try {
    // Encrypt
    const encrypted = await commonEncryption.twoWayEncrypt(sensitiveData, passphrase);
    console.log(encrypted); // AES-256-GCM encrypted string
    
    // Decrypt
    const decrypted = await commonEncryption.twoWayDecrypt(encrypted, passphrase);
    console.log(decrypted); // "Sensitive Information"
  } catch (error) {
    console.error('Encryption failed:', error);
  }
}

Two-Way Encryption (Object)

async function encryptObject() {
  const passphrase = "mySecurePassphrase";
  const dataObject = {
    username: "john_doe",
    email: "[email protected]",
    preferences: { theme: "dark" }
  };
  
  // Automatically stringifies objects
  const encrypted = await commonEncryption.twoWayEncrypt(dataObject, passphrase);
  console.log(encrypted); // AES-256-GCM encrypted string
  
  // Decrypt returns JSON string
  const decrypted = await commonEncryption.twoWayDecrypt(encrypted, passphrase);
  const parsedData = JSON.parse(decrypted);
  console.log(parsedData); // Original object structure
}

Error Handling

async function encryptWithErrorHandling() {
  try {
    const encrypted = await commonEncryption.twoWayEncrypt("secret", "password");
    const decrypted = await commonEncryption.twoWayDecrypt(encrypted, "password");
    console.log('Success:', decrypted);
  } catch (error) {
    if (error.message.includes('decrypt')) {
      console.error('Wrong password or corrupted data');
    } else {
      console.error('Encryption error:', error);
    }
  }
}

API Documentation

async oneWayEncrypt(data, sha = true)

Performs one-way hashing using SHA-256 or MD5.

Parameters:

• data (String|Object): Data to hash. Objects are automatically stringified.
• sha (Boolean, default: true): true for SHA-256, false for MD5

Returns:

• Promise<string | undefined>: Hexadecimal hash string

Example:

// SHA-256 (recommended)
const sha256Hash = await commonEncryption.oneWayEncrypt("data", true);

// MD5 (for checksums/IDs only, not for security)
const md5Hash = await commonEncryption.oneWayEncrypt("data", false);

// SHA-256 is default
const defaultHash = await commonEncryption.oneWayEncrypt("data");

async oneWayCompare(cypher, compare, sha = true)

Compares a hash with plain data by hashing the plain data and checking equality.

Parameters:

• cypher (String): The hash to compare against
• compare (String|Object): Plain data to hash and compare
• sha (Boolean, default: true): true for SHA-256, false for MD5 (must match the algorithm used to create cypher)

Returns:

• Promise<boolean>: true if hashes match, false otherwise

Example:

const hash = await commonEncryption.oneWayEncrypt("password123", true);
const isValid = await commonEncryption.oneWayCompare(hash, "password123", true);
console.log(isValid); // true

const isInvalid = await commonEncryption.oneWayCompare(hash, "wrongPassword", true);
console.log(isInvalid); // false

async twoWayEncrypt(data, passphrase, options)

Encrypts data using AES-256-GCM with a passphrase.

Parameters:

• data (String|Object): Data to encrypt. Objects are automatically stringified.
• passphrase (String): Encryption passphrase/password
• options (Object, optional): Encryption configuration
  • options.securityLevel (String): Security level - 'fast', 'standard', 'high', or 'maximum' (default)
  • options.iterations (Number): Custom PBKDF2 iterations (overrides securityLevel)

Returns:

• Promise<string>: Base64-encoded encrypted string containing salt, IV, authentication tag, and ciphertext

Example:

// Default: Maximum security (600,000 iterations)
const encrypted = await commonEncryption.twoWayEncrypt("secret", "my-passphrase");

// Fast mode: For real-time APIs (2,000 iterations)
const fastEncrypted = await commonEncryption.twoWayEncrypt(
  "secret",
  "my-passphrase",
  { securityLevel: 'fast' }
);

// Standard mode: Balanced (10,000 iterations)
const standardEncrypted = await commonEncryption.twoWayEncrypt(
  "secret",
  "my-passphrase",
  { securityLevel: 'standard' }
);

// High security: For sensitive data (100,000 iterations)
const highEncrypted = await commonEncryption.twoWayEncrypt(
  "secret",
  "my-passphrase",
  { securityLevel: 'high' }
);

// Custom iterations
const customEncrypted = await commonEncryption.twoWayEncrypt(
  "secret",
  "my-passphrase",
  { iterations: 5000 }
);

// With object
const obj = { key: "value" };
const encryptedObj = await commonEncryption.twoWayEncrypt(
  obj,
  "my-passphrase",
  { securityLevel: 'standard' }
);

async twoWayDecrypt(cypher, passphrase, options)

Decrypts AES-256-GCM encrypted data.

Parameters:

• cypher (String): Base64-encoded encrypted string (from twoWayEncrypt())
• passphrase (String): Decryption passphrase (must match encryption passphrase)
• options (Object, optional): Decryption configuration
  • options.securityLevel (String): Security level - must match encryption level
  • options.iterations (Number): Custom PBKDF2 iterations - must match encryption iterations

Returns:

• Promise<string>: Decrypted data as string. If the original data was an object, you'll need to JSON.parse() the result.

Example:

// Default: Maximum security
const encrypted = await commonEncryption.twoWayEncrypt("secret", "my-passphrase");
const decrypted = await commonEncryption.twoWayDecrypt(encrypted, "my-passphrase");
console.log(decrypted); // "secret"

// With security level
const fastEncrypted = await commonEncryption.twoWayEncrypt(
  "secret",
  "my-passphrase",
  { securityLevel: 'fast' }
);
const fastDecrypted = await commonEncryption.twoWayDecrypt(
  fastEncrypted,
  "my-passphrase",
  { securityLevel: 'fast' }
);

// With object
const objEncrypted = await commonEncryption.twoWayEncrypt(
  { key: "value" },
  "pass",
  { securityLevel: 'standard' }
);
const objDecrypted = await commonEncryption.twoWayDecrypt(
  objEncrypted,
  "pass",
  { securityLevel: 'standard' }
);
const obj = JSON.parse(objDecrypted); // { key: "value" }

Performance & Security Levels

Version 3.1 introduces configurable security levels to balance performance and security based on your use case.

Security Levels Comparison

| Level | Iterations | Avg Time | Performance | Best For | |-------|-----------|----------|-------------|----------| | fast | 2,000 | ~0.36ms | 297x faster | Real-time APIs, WebSockets, transport encryption | | standard | 10,000 | ~2.14ms | 52x faster | Standard application data, sessions, tokens | | high | 100,000 | ~19ms | 5.9x faster | Sensitive user data, financial records, PII | | maximum | 600,000 | ~113ms | Default | Passwords, OWASP 2023 compliant, regulatory data |

Performance baseline: Measured on modern hardware. Your results may vary.

Choosing the Right Security Level

🚀 Fast Mode (securityLevel: 'fast')

2,000 iterations - Optimized for performance-critical applications

Use Cases:

• Real-time API encryption/decryption
• WebSocket message encryption
• High-throughput data processing
• Transport layer encryption
• Temporary session data

Example:

// Real-time chat encryption
const encrypted = await commonEncryption.twoWayEncrypt(
  chatMessage,
  sessionKey,
  { securityLevel: 'fast' }
);

⚖️ Standard Mode (securityLevel: 'standard')

10,000 iterations - Balanced performance and security

Use Cases:

• General application data
• User preferences and settings
• Session tokens
• Non-sensitive cached data
• Development and testing

Example:

// User preferences encryption
const encrypted = await commonEncryption.twoWayEncrypt(
  userPreferences,
  userKey,
  { securityLevel: 'standard' }
);

🔐 High Mode (securityLevel: 'high')

100,000 iterations - Enhanced security for sensitive data

Use Cases:

• Personally Identifiable Information (PII)
• Financial records
• Healthcare data
• API keys and secrets
• Long-term stored credentials

Example:

// Financial data encryption
const encrypted = await commonEncryption.twoWayEncrypt(
  financialData,
  encryptionKey,
  { securityLevel: 'high' }
);

🛡️ Maximum Mode (securityLevel: 'maximum') - Default

600,000 iterations - OWASP 2023 compliant, maximum security

Use Cases:

• Password storage and verification
• Regulatory compliance (GDPR, HIPAA, PCI-DSS)
• Highly sensitive data
• Long-term archive encryption
• Security-critical applications

Example:

// Default - no options needed
const encrypted = await commonEncryption.twoWayEncrypt(
  password,
  masterKey
);

// Or explicitly
const encrypted = await commonEncryption.twoWayEncrypt(
  password,
  masterKey,
  { securityLevel: 'maximum' }
);

Performance Benchmarks

You can run performance benchmarks on your hardware:

node test/benchmark.js

Sample Output:

Security Level Performance Comparison
=====================================

Fast mode (2,000 iterations):
  Encryption: 0.32ms
  Decryption: 0.40ms
  Total: 0.72ms
  Throughput: 1389 ops/sec

Standard mode (10,000 iterations):
  Encryption: 2.01ms
  Decryption: 2.27ms
  Total: 4.28ms
  Throughput: 234 ops/sec

High mode (100,000 iterations):
  Encryption: 18.45ms
  Decryption: 19.73ms
  Total: 38.18ms
  Throughput: 26 ops/sec

Maximum mode (600,000 iterations):
  Encryption: 110.23ms
  Decryption: 115.89ms
  Total: 226.12ms
  Throughput: 4.4 ops/sec

Custom Iterations

For fine-grained control, you can specify custom iteration counts:

// Custom iteration count
const encrypted = await commonEncryption.twoWayEncrypt(
  data,
  passphrase,
  { iterations: 5000 }
);

// Must match when decrypting
const decrypted = await commonEncryption.twoWayDecrypt(
  encrypted,
  passphrase,
  { iterations: 5000 }
);

Note: The iteration count is not stored in the encrypted data. You must use the same iteration count for decryption.

Backward Compatibility

Version 3.1 is fully backward compatible with v3.0:

• Existing code without options parameter continues to work
• Default behavior unchanged (600,000 iterations)
• No breaking changes to API or data format

// v3.0 code - still works in v3.1
const encrypted = await commonEncryption.twoWayEncrypt(data, passphrase);
const decrypted = await commonEncryption.twoWayDecrypt(encrypted, passphrase);

Security Considerations

Production-Ready Security

Version 3.0 implements modern cryptographic standards:

1. OWASP 2023 Compliant

   • 600,000 PBKDF2-HMAC-SHA256 iterations
   • Meets current recommendations for password-based encryption
   • Protects against brute-force attacks

2. Authenticated Encryption (AES-GCM)

   • Combines encryption and authentication in a single operation
   • Prevents tampering and modification of encrypted data
   • Eliminates padding oracle attack vulnerabilities
   • 128-bit authentication tag ensures data integrity

3. Hardware Acceleration

   • Native Web Crypto API uses hardware acceleration when available
   • Significantly faster than pure JavaScript implementations
   • Consistent security across platforms

4. Cryptographically Secure Randomness

   • All IVs and salts generated using cryptographically secure random number generator
   • Ensures uniqueness and unpredictability
   • No weak or predictable random sources

Secure Usage Guidelines

// ✅ DO: Use SHA-256 for security-sensitive hashing
const hash = await commonEncryption.oneWayEncrypt(password, true);

// ✅ DO: Use strong passphrases for encryption
const strongPassphrase = "correct-horse-battery-staple-with-numbers-123";
const encrypted = await commonEncryption.twoWayEncrypt(data, strongPassphrase);

// ✅ DO: Handle errors properly
try {
  const decrypted = await commonEncryption.twoWayDecrypt(encrypted, passphrase);
} catch (error) {
  console.error('Decryption failed - wrong password or corrupted data');
}

// ⚠️ CAUTION: MD5 only for checksums and IDs, never for security
const checksum = await commonEncryption.oneWayEncrypt(data, false);

// ❌ DON'T: Use MD5 for password hashing
const badHash = await commonEncryption.oneWayEncrypt(password, false); // BAD!

When to Use This Library

✅ Recommended For:

• Web applications needing client-side encryption
• Secure storage of user preferences
• Password-protected configuration files
• Cross-platform encrypted data exchange
• Development and testing environments
• Educational purposes

⚠️ Consider Alternatives For:

• Server-side password storage (use bcrypt or Argon2)
• Large file encryption (use streaming encryption)
• Key management systems (use dedicated KMS solutions)
• Regulatory compliance (may require certified libraries)

Technical Details

v3.0 Cryptographic Specifications

• Encryption Algorithm: AES-256-GCM (authenticated encryption)
• Key Derivation: PBKDF2-SHA256 with 600,000 iterations
• Key Size: 256 bits (32 bytes)
• IV Size: 12 bytes (96 bits) - optimal for AES-GCM
• Authentication Tag: 16 bytes (128 bits)
• Salt: 16 bytes (random per encryption)
• Hash Algorithms: SHA-256 (default), MD5 (for IDs only)

Encrypted Data Format

[16-byte salt][12-byte IV][16-byte auth tag][ciphertext]

All encoded as Base64 for text transmission and storage.

Cross-Platform Implementation

• Browser: Uses native window.crypto.subtle Web Crypto API
• Node.js 18+: Uses native crypto.webcrypto module
• No polyfills needed: 97%+ browser support (Chrome, Firefox, Safari, Edge)
• Unified codebase: Same code works in both environments

Performance

• 10-100x faster than crypto-js implementation
• Hardware-accelerated encryption (when available)
• Zero dependencies - no external crypto libraries
• Smaller bundle - 84% reduction in package size

Browser Compatibility

| Browser | Version | Support | |---------|---------|---------| | Chrome | 37+ | ✅ Full | | Firefox | 34+ | ✅ Full | | Safari | 11+ | ✅ Full | | Edge | 79+ | ✅ Full | | Opera | 24+ | ✅ Full |

Node.js Compatibility

• Required: Node.js 18.0.0 or higher
• Recommended: Node.js 20+ LTS for best performance
• Web Crypto API available via crypto.webcrypto

Development

Requirements

• Node.js 18 or higher
• npm 8 or higher

Running Tests

npm test  # All 25 tests should pass

Test Coverage

• ✅ One-way encryption (SHA-256, MD5)
• ✅ One-way comparison (SHA-256, MD5)
• ✅ Two-way encryption/decryption (strings)
• ✅ Two-way encryption/decryption (objects)
• ✅ Two-way encryption/decryption (arrays)
• ✅ Non-deterministic encryption (random IV per call)
• ✅ Wrong password handling
• ✅ Corrupted data handling
• ✅ Edge cases and error conditions

All tests use native Node.js test runner - no external test frameworks required.

Building from Source

# Install dependencies
npm install

# Build production bundle
npm run build

The build process:

1. Transpiles and bundles source code with Webpack
2. Generates optimized output in index.js
3. Creates UMD bundle for universal compatibility

Project Structure

common-encryption/
├── src/
│   ├── crypto-utils.js    # Web Crypto API wrapper
│   └── index.js           # Main library implementation
├── test/
│   └── test.js            # Test suite (25 tests)
├── webpack.config.js      # Build configuration
├── package.json
└── README.md

Changelog

Version 3.1.0 (2026-02-02)

Performance & Security Optimization Release

New Features:

• ⚡ Configurable security levels: fast, standard, high, maximum
• 🎯 297x faster encryption with fast mode (0.36ms vs 113ms)
• 📊 Performance benchmarks: Built-in benchmark tool (node test/benchmark.js)
• 🔄 Full backward compatibility: No breaking changes

Security Levels:

• Fast: 2,000 iterations (~0.36ms) - Real-time APIs
• Standard: 10,000 iterations (~2.14ms) - General data
• High: 100,000 iterations (~19ms) - Sensitive data
• Maximum: 600,000 iterations (~113ms) - Default, OWASP 2023

API Enhancements:

• ✅ options.securityLevel parameter for twoWayEncrypt()
• ✅ options.iterations parameter for custom control
• ✅ Matching parameters for twoWayDecrypt()
• 📝 Comprehensive documentation and examples

Performance:

• Up to 297x faster encryption (fast mode)
• Up to 52x faster encryption (standard mode)
• Up to 5.9x faster encryption (high mode)
• Maintains OWASP 2023 compliance as default

Migration:

• See v3.0 → v3.1 Migration Guide above
• Zero breaking changes - existing code works unchanged

Version 3.0.0 (2026-01-29)

Major Release - Breaking Changes

Security Improvements:

• ⬆️ PBKDF2 iterations increased from 100 to 600,000
• 🔐 Switched from AES-CBC to AES-GCM authenticated encryption
• ✅ Now OWASP 2023 compliant
• 🔒 Hardware-accelerated native Web Crypto API

Performance Improvements:

• ⚡ 10-100x faster encryption/decryption
• 📦 84% smaller bundle size (50KB vs 330KB)
• 🚀 Zero crypto dependencies

API Changes:

• 🔄 All functions now return Promises (async/await required)
• 📱 Node.js 18+ required
• 🌐 Native Web Crypto API (no crypto-js)
• ⚠️ Data format changed - v2.x data cannot be decrypted

Migration:

• See Migration Guide above

Version 2.0.5 (Previous)

• Legacy version using crypto-js
• AES-CBC encryption
• 100 PBKDF2 iterations
• Not recommended for production use

License

Apache-2.0 - See LICENSE file for details.

Contributing & Support

• Repository: github.com/carlosgalveias/base-encryption
• Issues: GitHub Issues
• NPM Package: base-encryption

Version: 3.1.0

Production Ready: Version 3.1 implements modern cryptographic standards with configurable security levels. Choose the appropriate security level for your use case - from real-time performance (fast mode) to maximum security (OWASP 2023 compliant). For mission-critical applications, consider additional security reviews and consult with security professionals for your specific use case.