A robust, cross-platform TypeScript/JavaScript library for encrypting and decrypting data and files using AES-GCM with PBKDF2 key derivation. Works seamlessly in both Node.js and browser environments with built-in CLI support.

• Features
• Installation
• Quick Start
• CLI Usage
  • CLI Installation
  • Help
  • Available Commands
  • Basic CLI Text Operations
  • CLI File Operations
  • Advanced CLI Options
  • Examples with Advanced Options
  • Piping Support
• API Reference
  • Piping Support
• Compressing Data
• Custom Options
• Usage
  • Browser Usage
    • With Bundlers (Webpack, Vite, etc.)
    • Direct Script Tag
  • Node.js Usage
    • CommonJS
    • ES Modules
• Security Considerations
  • Best Practices
  • Default Security Parameters
  • Performance
  • Limitations
• Contributing
• License

• Secure Encryption: AES-GCM with PBKDF2 key derivation
• Built-in CLI: Command-line interface for encrypting/decrypting files
• Cross-Platform: Works in Node.js and modern browsers
• Zero Dependencies: Uses native Web Crypto API
• Type Safe: Written in TypeScript with full type definitions
• Compression Support: Built-in GZIP compression to reduce file size
• Self-Decrypting HTML: Generate standalone HTML files unlockable in any browser
• Configurable: Customizable encryption parameters
• File Support: Encrypt/decrypt binary file data
• Simple API: Easy-to-use static methods

npm install data-crypt

or

yarn add data-crypt

// Import DataCrypt
import { DataCrypt } from 'data-crypt';

// Encrypt a string
const encrypted = await DataCrypt.encrypt('Secret message', 'my-password');
console.log('Encrypted:', encrypted);

// Decrypt the data
const decrypted = await DataCrypt.decrypt(encrypted, 'my-password');
console.log('Decrypted:', decrypted); // 'Secret message'

DataCrypt provides a convenient command-line interface for quick encryption/decryption operations.

npm install -g data-crypt

dc --help
dc -h

You can use any of these command names:

• dc (recommended, short and fast)
• datacrypt (full name)
• data-crypt (hyphenated)

Encrypt Text

dc encrypt "your secret message" "password"

Decrypt Text

dc decrypt "ENCRYPTED_BASE64_DATA" "password"

Encrypt Text

dc encrypt -f input.txt -o encrypted.txt "password"

Decrypt Text

dc decrypt -f encrypted.txt -o decrypted.txt "password"

# Encrypt with custom parameters
dc encrypt "text" -i 1000000 --hash SHA-512 "password"

# Encrypt file with advanced options
dc encrypt -f document.pdf -o secure.pdf -i 500000 --hash SHA-384 "password"

Create a standalone .html file that anyone can decrypt in their browser without installing any software.

# Encrypt file into a self-unlocking HTML page
dc encrypt -f secret.pdf -o unlock.html --html "password"

⚠️ Important Note for Chrome/Edge Users:

Modern browsers like Chrome and Edge restrict the Web Crypto API on file:// URLs for security reasons. If you double-click the generated HTML file to open it, decryption might fail.

Solutions:

1. Open the file in Firefox (it works locally).
2. Use a local server (e.g., npx serve .).
3. Upload the file to any website (HTTPS) or localhost.

Reduce file size by compressing data before encryption (uses GZIP).

# Compress and encrypt a large log file
dc encrypt -f server.log -o server.enc -z "password"

When decrypting files that were compressed using the -z flag, decompression is automatic. You do not need to pass a compression flag during decryption. DataCrypt detects the compression headers inside the encrypted data and handles it for you.

# Just run the standard decrypt command
dc decrypt -f server.enc -o server.log "password"

You can also pipe data through the CLI:

# Encrypt piped data
echo "secret data" | dc encrypt "password"

# Encrypt file content
cat file.txt | dc encrypt -f "password" > encrypted.txt

Syntax

encrypt(
  text: string | Uint8Array,
  password: string,
  opts?: DeriveOptions
): Promise<string>

Parameters

• text: String or Uint8Array to encrypt
• password: Password for encryption
• opts: Optional derivation options

Returns: Base64-encoded encrypted data (salt + iv + ciphertext)

Example

const encrypted = await DataCrypt.encrypt('Hello World', 'password');

Syntax

decrypt(
  base64: string,
  password: string,
  opts?: DeriveOptions
): Promise<string | null>

Parameters

• base64: Base64-encoded encrypted data
• password: Password used for encryption
• opts: Optional derivation options (must match encryption options, if used)

Returns: Decrypted string or null if decryption fails.

Example

const decrypted = await DataCrypt.decrypt(encryptedData, 'password');

Syntax

encryptFile(
  fileData: Uint8Array,
  password: string,
  opts?: DeriveOptions
): Promise<string>

Parameters

• fileData: Uint8Array containing file data
• password: Password used for encryption
• opts: Optional derivation options

Returns: Base64-encoded encrypted file data.

Example

const fileData = new TextEncoder().encode('File content');
const encryptedFile = await DataCrypt.encryptFile(fileData, 'password');

Syntax

decryptFile(
  base64: string,
  password: string,
  opts?: DeriveOptions
): Promise<Uint8Array | null>

Parameters

• base64: Uint8Array containing file data
• password: Password used for encryption
• opts: Optional derivation options (must match encryption options)

Returns: Decrypted Uint8Array or null if decryption fails.

Example

const decryptedFile = await DataCrypt.decryptFile(encryptedFile, 'password');

Syntax

isEncrypted(data: string): boolean

Example

const isValid = DataCrypt.isEncrypted(encryptedData);
console.log('Is encrypted?', isValid); // true or false

Syntax

generateSelfDecryptingHTML(
  encryptedBase64: string, 
  filename: string, 
  opts?: DeriveOptions
): string

Example

const html = DataCrypt.generateSelfDecryptingHTML(encryptedData, 'doc.pdf');

Parameters

• encryptedBase64: The Base64 string returned by encrypt() or encryptFile().
• filename: The default filename used when the user downloads the decrypted file (e.g., 'secret.pdf').
• opts: Optional derivation options (must match encryption options)

Returns: A string containing the full HTML document.

Syntax

downloadFile(
  content: string | Uint8Array,
  filename: string,
  mimeType: string = 'application/octet-stream'
): void

Example

const html = DataCrypt.generateSelfDecryptingHTML(encryptedData, 'doc.pdf');
DataCrypt.downloadFile(html, 'secret.html', 'text/html');

Parameters

• content: The data to download (string or binary).
• filename: The name of the file to save (e.g., 'secret.html').
• mimeType: (Optional) The MIME type (default: 'application/octet-stream').

Syntax

generateRandomBytes(length: number): Uint8Array

Example

const randomBytes = DataCrypt.generateRandomBytes(32);

Syntax

clearCache(): void

Example

DataCrypt.clearCache();

Syntax

getCacheSize(): number

Example

console.log('Cached keys: ', DataCrypt.getCacheSize());

DataCrypt includes built-in GZIP compression to reduce the size of your encrypted data. This is especially useful for large text files, logs, or JSON data.

When you enable compression, the data is first compressed using GZIP and then encrypted. This results in significantly smaller output files for compressible data.

CLI Usage

Use the -z or --compress flag during encryption:

# Encrypt and compress a large log file
dc encrypt -f app.log -o app.log.enc -z "password"

API Usage

Pass { compress: true } in the options object:

const bigData = JSON.stringify(largeObject);
const encrypted = await DataCrypt.encrypt(bigData, 'password', { compress: true });

Decompression is automatic. You do not need to specify any special flags or options when decrypting. DataCrypt automatically detects the GZIP compression headers inside the encrypted payload and decompresses the data transparently.

CLI Usage

# Just run the standard command; DataCrypt handles the rest
dc decrypt -f app.log.enc -o restored.log "password"

API Usage

// No options needed; automatic detection
const decrypted = await DataCrypt.decrypt(encrypted, 'password');

Customize the key derivation process:

Interface

interface DeriveOptions {
  iterations?: number;
  hash?: HashAlgorithm;
  length?: KeyLength;
  saltLength?: number;
  compress?: boolean;
}

import { DataCrypt } from 'data-crypt';
// NOw use as normal Javascript

You can use the same API in a browser environment.

<script type="module">
  import { DataCrypt } from 'https://cdn.skypack.dev/data-crypt';

  const text = 'Hello from Browser!';
  const password = 'browser-key';

  const encrypted = await DataCrypt.encrypt(text, password);
  const decrypted = await DataCrypt.decrypt(encrypted, password);

  console.log({ encrypted, decrypted });
</script>

const { DataCrypt } = require('data-crypt');

async function main() {
  const encrypted = await DataCrypt.encrypt('Node.js data', 'password');
  const decrypted = await DataCrypt.decrypt(encrypted, 'password');
  console.log(decrypted);
}

main().catch(console.error);

import { DataCrypt } from 'data-crypt';
// Use as shown in browser examples

1. Use Strong Passwords: The security depends on password strength.
2. Increase Iterations: Use higher PBKDF2 iterations for sensitive data.
3. Unique Salts: Each encryption uses a random salt (automatically handled).
4. Secure Storage: Store encrypted data securely, separate from keys.

• PBKDF2 Iterations: 600,000 (OWASP recommended minimum)
• Hash Algorithm: SHA-256
• Key Length: 256-bit
• Encryption: AES-GCM with 12-byte IV
• Salt Length: 16 bytes

The library is optimized for performance with:

• Key Caching: Derived keys are cached for same parameters
• Native Crypto: Uses platform's native Web Crypto API
• Efficient Encoding: Minimal data copying and encoding

For large files, consider streaming encryption in chunks (not currently supported).

• Password Strength: Security depends entirely on password strength
• No Key Management: This library doesn't handle key storage/management
• Memory: Large files are loaded entirely into memory

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

MIT © 2025 [M B Parvez]