Dcoderz Encryption Javascript 🔒

A cross-platform encryption library with JavaScript and Python compatibility. Features custom cipher algorithms with character substitution, matrix transformations, and integrity verification.

✨ Features

• 🔐 Proprietary Encryption Algorithm - Multi-layered security with 6 transformation steps
• 🌐 Cross-Platform Compatible - Works identically with Python implementation
• 🛡️ Integrity Verification - Built-in checksums detect tampering
• 🎯 Deterministic - Same input always produces same output
• 🚀 High Performance - Optimized for speed and memory usage
• 📦 Zero Dependencies - No external dependencies required
• 🔧 CLI Tool - Command-line interface included
• 📚 TypeScript Support - Full TypeScript definitions included

🚀 Installation

npm install dcoderz-encryption

📖 Quick Start

const { encrypt, decrypt, generateKey } = require('dcoderz-encryption');

// Basic encryption/decryption
const plaintext = 'Hello, World!';
const key = 'my-secret-key';

const encrypted = encrypt(plaintext, key);
console.log('Encrypted:', encrypted);

const decrypted = decrypt(encrypted, key);
console.log('Decrypted:', decrypted);

// Generate a random key
const randomKey = generateKey();
console.log('Generated key:', randomKey);

🔧 API Reference

Functions

encrypt(plaintext, key)

Encrypts plaintext using the specified key.

Parameters:

• plaintext (string) - The text to encrypt
• key (string) - The encryption key

Returns: string - The encrypted text

Example:

const encrypted = encrypt('Hello World!', 'my-key');

decrypt(ciphertext, key)

Decrypts ciphertext using the specified key.

Parameters:

• ciphertext (string) - The encrypted text to decrypt
• key (string) - The decryption key

Returns: string - The decrypted text

Example:

const decrypted = decrypt(encrypted, 'my-key');

generateKey(length)

Generates a random encryption key.

Parameters:

• length (number, optional) - Key length (default: 32)

Returns: string - A random key

Example:

const key = generateKey(16); // 16-character key

isValidCiphertext(ciphertext)

Validates if a string is properly formatted encrypted text.

Parameters:

• ciphertext (string) - The text to validate

Returns: boolean - True if valid, false otherwise

Example:

const isValid = isValidCiphertext(encrypted);

Classes

CipherEngine

Advanced encryption engine for reusable instances.

Constructor:

const cipher = new CipherEngine('my-key');

Methods:

• encrypt(plaintext) - Encrypt text
• decrypt(ciphertext) - Decrypt text

Example:

const cipher = new CipherEngine('my-key');
const encrypted = cipher.encrypt('Hello World!');
const decrypted = cipher.decrypt(encrypted);

🖥️ CLI Usage

The library includes a command-line interface:

# Interactive mode
npx dcoderz-encrypt

# Direct commands
npx dcoderz-encrypt encrypt "Hello World!" "my-key"
npx dcoderz-encrypt decrypt "encrypted-text" "my-key"
npx dcoderz-encrypt generate-key 32
npx dcoderz-encrypt test

🌐 Cross-Platform Compatibility

This library is fully compatible with the Python implementation. You can encrypt data in JavaScript and decrypt it in Python, or vice versa.

JavaScript Example:

const { encrypt } = require('dcoderz-encryption');
const encrypted = encrypt('Hello World!', 'test123');
console.log(encrypted); // 's[f|0+o)5KW[lKafq(B0f%MBC

Python Example:

from dcoderz_encryption import decrypt
decrypted = decrypt("'s[f|0+o)5KW[lKafq(B0f%MBC", "test123")
print(decrypted)  # Hello World!

🔒 Security Features

The encryption algorithm combines multiple security layers:

1. Character Substitution - Dynamic cipher wheel based on key
2. Matrix Transformation - Row/column scrambling
3. Position-based XOR - Key-dependent bit manipulation
4. Position Scrambling - Deterministic character reordering
5. Integrity Checksum - MD5 hash for tampering detection
6. Custom Encoding - Base-94 encoding for safe transport

🧪 Testing

Run the test suite:

npm test

Run examples:

npm run example

📚 TypeScript Support

The library includes full TypeScript definitions with complete type safety:

import { encrypt, decrypt, CipherEngine, generateKey } from 'dcoderz-encryption';

// All functions are fully typed
const plaintext: string = 'Hello World!';
const key: string = 'my-secret-key';

const encrypted: string = encrypt(plaintext, key);
const decrypted: string = decrypt(encrypted, key);

// CipherEngine class with full typing
const cipher: CipherEngine = new CipherEngine('my-key');
const result: string = cipher.encrypt('TypeScript message');

// Key generation with optional length parameter
const randomKey: string = generateKey(32);
const shortKey: string = generateKey(16);

// Type-safe error handling
try {
    const result = decrypt('invalid-data', 'wrong-key');
} catch (error: unknown) {
    if (error instanceof Error) {
        console.log('Decryption failed:', error.message);
    }
}

Advanced TypeScript Features

Create strongly-typed wrappers for object encryption:

import { CipherEngine } from 'dcoderz-encryption';

// Create a strongly-typed wrapper
class TypedCipherEngine<T> extends CipherEngine {
    encryptObject(obj: T): string {
        return this.encrypt(JSON.stringify(obj));
    }

    decryptObject(ciphertext: string): T {
        const decrypted = this.decrypt(ciphertext);
        return JSON.parse(decrypted) as T;
    }
}

// Usage with type safety
interface UserData {
    id: number;
    name: string;
    email: string;
}

const cipher = new TypedCipherEngine<UserData>('user-key');
const userData: UserData = { id: 1, name: 'John', email: 'john@example.com' };

const encrypted = cipher.encryptObject(userData);
const decrypted: UserData = cipher.decryptObject(encrypted);

⚛️ React/JSX Support

Perfect for React applications with full component examples:

Basic React Component

import React, { useState } from 'react';
import { encrypt, decrypt, generateKey } from 'dcoderz-encryption';

function EncryptionComponent() {
    const [message, setMessage] = useState('');
    const [key, setKey] = useState('');
    const [encrypted, setEncrypted] = useState('');
    const [decrypted, setDecrypted] = useState('');

    const handleEncrypt = () => {
        try {
            const result = encrypt(message, key);
            setEncrypted(result);
        } catch (error) {
            alert(`Encryption failed: ${error.message}`);
        }
    };

    const handleDecrypt = () => {
        try {
            const result = decrypt(encrypted, key);
            setDecrypted(result);
        } catch (error) {
            alert(`Decryption failed: ${error.message}`);
        }
    };

    const handleGenerateKey = () => {
        const newKey = generateKey();
        setKey(newKey);
    };

    return (
        <div className="encryption-tool">
            <h2>🔒 Dcoderz Encryption Tool</h2>
            
            <div className="form-group">
                <label>Message:</label>
                <textarea 
                    value={message}
                    onChange={(e) => setMessage(e.target.value)}
                    placeholder="Enter message to encrypt"
                />
            </div>

            <div className="form-group">
                <label>Key:</label>
                <input 
                    type="text"
                    value={key}
                    onChange={(e) => setKey(e.target.value)}
                    placeholder="Enter encryption key"
                />
                <button onClick={handleGenerateKey}>Generate Random Key</button>
            </div>

            <div className="buttons">
                <button onClick={handleEncrypt} disabled={!message || !key}>
                    Encrypt
                </button>
                <button onClick={handleDecrypt} disabled={!encrypted || !key}>
                    Decrypt
                </button>
            </div>

            {encrypted && (
                <div className="result">
                    <label>Encrypted:</label>
                    <textarea value={encrypted} readOnly />
                </div>
            )}

            {decrypted && (
                <div className="result">
                    <label>Decrypted:</label>
                    <textarea value={decrypted} readOnly />
                </div>
            )}
        </div>
    );
}

export default EncryptionComponent;

React Hook for Encryption

import { useState, useCallback } from 'react';
import { encrypt, decrypt, CipherEngine } from 'dcoderz-encryption';

export function useEncryption(persistentKey) {
    const [cipher] = useState(() => 
        persistentKey ? new CipherEngine(persistentKey) : null
    );

    const encryptText = useCallback((text, key) => {
        try {
            return cipher ? cipher.encrypt(text) : encrypt(text, key);
        } catch (error) {
            throw new Error(`Encryption failed: ${error.message}`);
        }
    }, [cipher]);

    const decryptText = useCallback((ciphertext, key) => {
        try {
            return cipher ? cipher.decrypt(ciphertext) : decrypt(ciphertext, key);
        } catch (error) {
            throw new Error(`Decryption failed: ${error.message}`);
        }
    }, [cipher]);

    return { encryptText, decryptText };
}

// Usage in component:
function MyComponent() {
    const { encryptText, decryptText } = useEncryption('my-app-key');
    
    const handleSaveData = (data) => {
        const encrypted = encryptText(JSON.stringify(data));
        localStorage.setItem('userData', encrypted);
    };

    const handleLoadData = () => {
        const encrypted = localStorage.getItem('userData');
        if (encrypted) {
            const decrypted = decryptText(encrypted);
            return JSON.parse(decrypted);
        }
    };
    
    // ... rest of component
}

TypeScript + React

import React, { useState, FC } from 'react';
import { encrypt, decrypt, generateKey } from 'dcoderz-encryption';

interface EncryptionFormProps {
    onEncrypted?: (encrypted: string) => void;
    onDecrypted?: (decrypted: string) => void;
}

const EncryptionForm: FC<EncryptionFormProps> = ({ onEncrypted, onDecrypted }) => {
    const [message, setMessage] = useState<string>('');
    const [key, setKey] = useState<string>('');
    const [loading, setLoading] = useState<boolean>(false);

    const handleEncrypt = async (): Promise<void> => {
        setLoading(true);
        try {
            const encrypted: string = encrypt(message, key);
            onEncrypted?.(encrypted);
        } catch (error) {
            console.error('Encryption error:', error);
        } finally {
            setLoading(false);
        }
    };

    const handleGenerateKey = (): void => {
        const newKey: string = generateKey(32);
        setKey(newKey);
    };

    return (
        <form onSubmit={(e) => { e.preventDefault(); handleEncrypt(); }}>
            <input 
                type="text"
                value={message}
                onChange={(e: React.ChangeEvent<HTMLInputElement>) => setMessage(e.target.value)}
                placeholder="Enter message"
            />
            <input 
                type="text"
                value={key}
                onChange={(e: React.ChangeEvent<HTMLInputElement>) => setKey(e.target.value)}
                placeholder="Enter key"
            />
            <button type="button" onClick={handleGenerateKey}>
                Generate Key
            </button>
            <button type="submit" disabled={loading || !message || !key}>
                {loading ? 'Encrypting...' : 'Encrypt'}
            </button>
        </form>
    );
};

export default EncryptionForm;

Next.js Usage

Perfect for Next.js applications:

// pages/encryption.js
import { useState } from 'react';
import { encrypt, decrypt, generateKey } from 'dcoderz-encryption';

export default function EncryptionPage() {
    const [result, setResult] = useState('');

    const handleEncrypt = () => {
        const encrypted = encrypt('Hello Next.js!', 'next-key');
        setResult(encrypted);
    };

    return (
        <div>
            <h1>Encryption in Next.js</h1>
            <button onClick={handleEncrypt}>Encrypt</button>
            {result && <p>Encrypted: {result}</p>}
        </div>
    );
}

🛠️ Framework Compatibility

• ✅ TypeScript: Full type definitions included
• ✅ React/JSX: Works perfectly in React components
• ✅ Next.js: Compatible with SSR and client-side
• ✅ Vue.js: Works in Vue applications
• ✅ Angular: Compatible with Angular projects
• ✅ Node.js: Server-side usage
• ✅ Browser: Client-side usage
• ✅ Webpack: Module bundler compatible
• ✅ Vite: Modern build tool compatible

📋 Examples

Basic Usage

const { encrypt, decrypt } = require('dcoderz-encryption');

const message = 'Secret message';
const key = 'my-secret-key';

const encrypted = encrypt(message, key);
const decrypted = decrypt(encrypted, key);

console.log(message === decrypted); // true

Using CipherEngine Class

const { CipherEngine } = require('dcoderz-encryption');

const cipher = new CipherEngine('persistent-key');

// Encrypt multiple messages with same key
const msg1 = cipher.encrypt('First message');
const msg2 = cipher.encrypt('Second message');

// Decrypt them back
console.log(cipher.decrypt(msg1)); // First message
console.log(cipher.decrypt(msg2)); // Second message

Error Handling

const { encrypt, decrypt } = require('dcoderz-encryption');

try {
    const encrypted = encrypt('Hello', 'key');
    const decrypted = decrypt(encrypted, 'wrong-key');
} catch (error) {
    console.log('Decryption failed:', error.message);
}

JSON Data Encryption

const { encrypt, decrypt } = require('dcoderz-encryption');

const data = { user: 'john', age: 30, active: true };
const jsonString = JSON.stringify(data);

const encrypted = encrypt(jsonString, 'json-key');
const decrypted = decrypt(encrypted, 'json-key');

const parsedData = JSON.parse(decrypted);
console.log(parsedData); // { user: 'john', age: 30, active: true }

🎯 Performance

• Encryption Speed: ~1MB/s on typical hardware
• Memory Usage: Minimal overhead
• Key Generation: Cryptographically secure random keys
• Deterministic: Same input always produces same output

🛡️ Security Considerations

• Key Management: Store keys securely, never hardcode in production
• Key Strength: Use strong, unique keys for each application
• Transport Security: Use HTTPS for transmitting encrypted data
• Key Rotation: Regularly rotate encryption keys
• Backup: Securely backup keys to prevent data loss

📦 Package Contents

dcoderz-encryption/
├── lib/
│   └── index.js          # Main library
├── bin/
│   └── cli.js            # Command-line interface
├── types/
│   └── index.d.ts        # TypeScript definitions
├── test/
│   └── test.js           # Test suite
├── examples/
│   └── basic-usage.js    # Usage examples
├── README.md             # This file
└── package.json          # Package configuration

🔄 Changelog

v1.0.0

• Initial release
• Cross-platform compatibility with Python
• CLI tool
• TypeScript support
• Comprehensive test suite

🤝 Contributing

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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

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

🏢 About Dcoderz

Dcoderz is a software development company specializing in security solutions and cross-platform applications.

• Website: https://www.facebook.com/dcoderzphilippines
• Email: m4kuguren@gmail.com

🆘 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Contact us at m4kuguren@gmail.com

🙏 Acknowledgments

• Thanks to the cryptography community for inspiration
• Special thanks to all contributors and testers