WH.Encryption 1.0.0

WH Encrypt API

A comprehensive cross-platform encryption library providing consistent AES-256-GCM encryption across Node.js and C# environments.

🏗️ Project Structure

wh-encrypt-api/
├── nodejs/                    # Node.js/Browser implementation
│   ├── src/
│   │   ├── index.js          # Main encryption library
│   │   └── index.d.ts        # TypeScript definitions
│   ├── test-compatibility.js # Cross-platform tests
│   └── package.json          # Node.js package config
├── csharp/                   # C# implementation
│   └── csharp/
│       ├── EncryptionService.cs      # Main encryption service
│       ├── EncryptionConstants.cs    # Shared constants
│       ├── EncryptionException.cs    # Exception handling
│       ├── EncryptedResponse.cs      # Response wrapper
│       ├── TestProgram.cs            # Cross-platform tests
│       └── csharp.csproj            # C# project config
├── .github/
│   └── workflows/            # CI/CD pipelines
├── LICENSE                   # License information
├── .gitignore               # Git ignore rules
├── CHANGELOG.md             # Version history
└── README.md                # This file

🚀 Features

• AES-256-GCM Encryption: Industry-standard authenticated encryption with integrity verification
• Cross-Platform Compatible: Full compatibility between Node.js and C# implementations
• PBKDF2 Key Derivation: Secure key derivation with 100,000 iterations and SHA-256
• TypeScript Support: Complete type definitions for Node.js/TypeScript projects
• Browser Support: Web Crypto API compatibility for frontend applications
• Multi-Framework: Supports .NET 6.0+ and .NET 8.0+ with conditional compilation
• Comprehensive Testing: Extensive test suites with cross-platform validation
• Security Validated: Tampering detection, key separation, and format validation
• CI/CD Ready: Automated testing, building, and deployment workflows

📦 Packages

Node.js Package

• Package Name: wh-encrypt-api
• Location: nodejs/
• Environments: Node.js servers, Browser clients
• Entry Points:
  • createEncryption() - Node.js crypto module
  • createBrowserEncryption() - Web Crypto API

C# Package

• Package Name: WH.Encryption
• Location: csharp/csharp/
• Environments: .NET 6.0+, .NET 8.0+
• Main Class: EncryptionService
• Compatible: Full interoperability with Node.js implementation

🔧 Installation

Node.js/JavaScript

npm install wh-encrypt-api

C# (.NET)

dotnet add package WH.Encryption

💻 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 }

C# (.NET)

using WH.Encryption;

// Initialize encryption service
using var encryption = new EncryptionService("your-secret-key");

// Encrypt data (any object that can be JSON serialized)
var userData = new { id = 123, name = "John Doe", active = true };
string encrypted = encryption.EncryptData(userData);

// Decrypt data with generic type
var decrypted = encryption.DecryptData<dynamic>(encrypted);
Console.WriteLine(decrypted); // { "id": 123, "name": "John Doe", "active": true }

// Or decrypt to specific type
var typedData = encryption.DecryptData<UserData>(encrypted);

Cross-Platform Data Exchange

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

// Send encrypted to C# service...

// C#: Decrypt the same data
using var csharpEncryption = new EncryptionService("shared-secret");
var decrypted = csharpEncryption.DecryptData<dynamic>(encryptedFromNodejs);
// Successfully decrypts Node.js encrypted 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]

Security Features

• Authenticated Encryption: Prevents tampering and ensures data integrity
• Random IV: Each encryption operation uses a cryptographically random IV
• Key Separation: Different secret keys cannot decrypt each other's data
• Format Validation: Strict validation of encrypted data structure
• Cross-Platform Consistency: Identical security properties across all implementations

🧪 Testing & Validation

Run Tests

Node.js:

cd nodejs
npm test                    # Run unit tests
npm run test:coverage      # Generate coverage report
node test-compatibility.js # Cross-platform validation

C#:

cd csharp/csharp
dotnet run                 # Run test program with cross-platform vectors
dotnet test               # Run unit tests (if available)

Cross-Platform Compatibility Testing

The library includes comprehensive compatibility tests that verify:

• Data encrypted by Node.js can be decrypted by C#
• Data encrypted by C# can be decrypted by Node.js
• Security features work consistently across platforms
• Performance characteristics are acceptable

Example output:

🔄 Testing C# ↔ Node.js Compatibility
=====================================
✅ All compatibility tests PASSED!
✅ Cross-platform data exchange is working correctly
✅ Security features are functioning properly
🚀 Ready for production use!

📈 Performance

Typical performance characteristics:

• Node.js: ~20-30 operations/second for 1KB payloads
• C#: ~40-50 operations/second for 1KB payloads
• Browser: ~15-25 operations/second for 1KB payloads
• Memory: Minimal memory footprint with proper disposal

🔄 CI/CD Workflows

The repository includes comprehensive GitHub Actions workflows:

Node.js CI (nodejs-ci.yml)

• Multi-version testing: Node.js 16, 18, 20
• Security auditing: npm audit with vulnerability checks
• Cross-platform: Windows, macOS, Linux
• Automated publishing: NPM package deployment
• Coverage reporting: Code coverage analysis

C# CI (csharp-ci.yml)

• Multi-framework: .NET 6.0, .NET 8.0
• Cross-platform: Windows, macOS, Linux
• NuGet publishing: Automated package deployment
• Security scanning: Vulnerability assessment
• Compatibility testing: Cross-platform validation

🤝 Contributing

Development Guidelines

1. Maintain Compatibility: Ensure changes don't break cross-platform compatibility
2. Add Tests: Include comprehensive tests for new features
3. Follow Patterns: Use established code patterns in each language
4. Security First: Follow security best practices
5. Documentation: Update documentation for API changes

Testing Workflow

1. Make changes in one implementation
2. Run local tests: npm test or dotnet run
3. Run cross-platform tests: node test-compatibility.js
4. Verify CI passes for both platforms
5. Update documentation if needed

Code Style

• Node.js: Follow existing JavaScript patterns, use TypeScript definitions
• C#: Follow Microsoft C# coding conventions, use XML documentation
• Both: Comprehensive error handling and input validation

📋 Version History

See CHANGELOG.md for detailed version history and migration guides.

📄 License

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

👥 Authors & Maintainers

Author: Duong Tran Quang Email: baymax.contact@gmail.com GitHub: https://github.com/DTDucas

🆘 Support

For technical support, bug reports, or feature requests:

1. Check existing documentation and examples
2. Review the test files for usage patterns
3. Create an issue on GitHub or email baymax.contact@gmail.com
4. Ensure you're using the latest version

🔗 Related Projects

This encryption library is designed to work seamlessly with:

• API services requiring secure data exchange
• Frontend applications needing client-side encryption
• Mobile applications with encryption requirements
• Any application requiring cross-platform encryption

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