WH Encrypt API - Node.js Package

Cross-platform encryption library providing consistent AES-256-GCM encryption for Node.js and Browser environments with full compatibility with C# implementation.

🚀 Features

• AES-256-GCM Encryption: Industry-standard authenticated encryption with integrity verification
• PBKDF2 Key Derivation: Secure key derivation with 100,000 iterations using SHA-256
• Cross-Platform Compatible: Full interoperability with C# implementation
• Browser Support: Web Crypto API compatibility for frontend applications
• TypeScript Support: Complete type definitions included
• Zero Dependencies: Uses Node.js built-in crypto module
• Security Validated: Tampering detection and key separation

📦 Installation

npm install wh-encrypt-api

💻 Usage Examples

Node.js Backend

const { createEncryption } = require("wh-encrypt-api");

// Initialize encryption service
const encryption = createEncryption("your-secret-key");

// Encrypt data (any JSON-serializable object)
const userData = { id: 123, name: "John Doe", active: true };
const encrypted = encryption.encryptData(userData);

// Decrypt data
const decrypted = encryption.decryptData(encrypted);
console.log(decrypted); // { id: 123, name: 'John Doe', active: true }

Browser Frontend

import { createBrowserEncryption } from "wh-encrypt-api";

// Initialize browser-compatible encryption
const encryption = createBrowserEncryption("your-secret-key");

// Encrypt data (async in browser)
const userData = { id: 123, name: "John Doe", active: true };
const encrypted = await encryption.encryptData(userData);

// Decrypt data (async in browser)
const decrypted = await encryption.decryptData(encrypted);
console.log(decrypted); // { id: 123, name: 'John Doe', active: true }

TypeScript

import { createEncryption, EncryptionInstance } from "wh-encrypt-api";

interface UserData {
  id: number;
  name: string;
  active: boolean;
}

const encryption: EncryptionInstance = createEncryption("your-secret-key");
const userData: UserData = { id: 123, name: "John Doe", active: true };

const encrypted: string = encryption.encryptData(userData);
const decrypted: UserData = encryption.decryptData(encrypted);

🔗 Cross-Platform Compatibility

This Node.js package is fully compatible with the C# implementation:

// Node.js: Encrypt data
const nodeEncryption = createEncryption("shared-secret");
const encrypted = nodeEncryption.encryptData({
  message: "Hello from Node.js!",
});

// The encrypted data can be decrypted by the C# implementation:
// using var csharpEncryption = new EncryptionService("shared-secret");
// var decrypted = csharpEncryption.DecryptData<dynamic>(encryptedFromNodejs);

📚 API Reference

createEncryption(secretKey, salt?)

Creates an encryption instance for Node.js environments.

Parameters:

• secretKey (string): The secret key for encryption/decryption
• salt (string, optional): Salt for key derivation (default: 'encryption-salt')

Returns: EncryptionInstance object with encryption methods

createBrowserEncryption(secretKey, salt?)

Creates an encryption instance for browser environments using Web Crypto API.

Parameters:

• secretKey (string): The secret key for encryption/decryption
• salt (string, optional): Salt for key derivation (default: 'encryption-salt')

Returns: BrowserEncryptionInstance object with async encryption methods

EncryptionInstance.encryptData(data)

Encrypts any JSON-serializable data using AES-256-GCM.

Parameters:

• data (any): Data to encrypt (will be JSON serialized)

Returns: Base64 encoded encrypted string

EncryptionInstance.decryptData(encryptedData)

Decrypts data encrypted with encryptData.

Parameters:

• encryptedData (string): Base64 encoded encrypted data

Returns: Original decrypted data

🔒 Security Specifications

Encryption Algorithm

• Cipher: AES-256-GCM (Galois/Counter Mode)
• Key Size: 256 bits (32 bytes)
• IV Size: 96 bits (12 bytes) - randomly generated per operation
• Authentication Tag: 128 bits (16 bytes)
• Additional Auth Data: "WH-Encryption-v1" for integrity verification

Key Derivation

• Algorithm: PBKDF2 with HMAC-SHA256
• Iterations: 100,000 (configurable)
• Salt: "encryption-salt" (default, configurable)
• Output: 256-bit derived key

Data Format

All encrypted data follows this format (Base64 encoded):

[IV: 12 bytes] + [Auth Tag: 16 bytes] + [Ciphertext: variable]

🧪 Testing

# Run unit tests
npm test

# Generate coverage report
npm run test:coverage

# Run cross-platform compatibility tests
npm run compatibility

# Validate library integrity
npm run validate

📈 Performance

Typical performance characteristics:

• Node.js: ~20-30 operations/second for 1KB payloads
• Browser: ~15-25 operations/second for 1KB payloads
• Memory: Minimal memory footprint

🔧 Environment Support

Node.js

• Versions: Node.js 16.0.0+
• Platforms: Windows, macOS, Linux
• Architectures: x64, ARM64

Browser

• Modern browsers with Web Crypto API support
• Chrome: 37+
• Firefox: 34+
• Safari: 7+
• Edge: 12+

🐛 Troubleshooting

Common Issues

Error: "crypto module not found"

• Ensure you're using Node.js 16+
• For browser environments, use createBrowserEncryption()

Error: "Invalid encrypted data"

• Verify the secret key matches between encryption and decryption
• Check that the encrypted data hasn't been modified or corrupted

Performance Issues

• Consider implementing caching for frequently used encryption instances
• Use appropriate payload sizes (recommended < 10MB)

📋 Version Compatibility

| Node.js Version | Package Version | Status | | --------------- | --------------- | ---------------- | | 16.x | 1.0.0+ | ✅ Supported | | 18.x | 1.0.0+ | ✅ Supported | | 20.x | 1.0.0+ | ✅ Supported | | 14.x | - | ❌ Not supported |

🤝 Contributing

See the main repository README.md for contribution guidelines.

📄 License

MIT License Copyright © 2025 Duong Tran Quang. All rights reserved.

See LICENSE for full license terms.

👥 Authors

Author: Duong Tran Quang Email: [email protected] GitHub: https://github.com/DTDucas

🆘 Support

For technical support:

1. Check the documentation and examples above
2. Review test files for additional usage patterns
3. Create an issue on GitHub or email [email protected]
4. Ensure you're using the latest version

🔗 Related Packages

• C# Package: WH.Encryption - NuGet package for .NET applications
• Main Repository: wh-encrypt-api

Note: This package is open source and available for use in any project under the MIT license.