cross-env-crypto v1.0.1

cross-env-crypto

A lightweight, cross-environment encryption/decryption library that works seamlessly between browser frontend and Node.js backend applications. Written in TypeScript with full type definitions, but compatible with both TypeScript and JavaScript projects.

Features

• Same encryption/decryption behavior in both browser and Node.js environments
• Full TypeScript support with type definitions included
• Uses native crypto APIs (Node.js crypto and Web Crypto API)
• AES-256-CBC encryption
• Handles IV (Initialization Vector) properly across environments
• Simple API with minimal configuration
• Zero runtime dependencies

Installation

npm install cross-env-crypto

Usage

In TypeScript

import CrossEnvCrypto, { EncryptedData } from "cross-env-crypto";

// Create an instance with your secret key (must be 32 characters)
const crypto = new CrossEnvCrypto("12345678901234567890123456789012");

// Node.js (sync)
const encrypted: EncryptedData = crypto.encrypt(
  "Hello, World!"
) as EncryptedData;
const decrypted: string = crypto.decrypt(encrypted) as string;

// Browser (async)
async function browserExample() {
  const encrypted = await crypto.encrypt("Hello, World!");
  const decrypted = await crypto.decrypt(encrypted);
  console.log(decrypted); // 'Hello, World!'
}

In JavaScript (Node.js - CommonJS)

const CrossEnvCrypto = require("cross-env-crypto");

// Create an instance with your secret key (must be 32 characters)
const crypto = new CrossEnvCrypto("12345678901234567890123456789012");

// Encrypt data
const encrypted = crypto.encrypt("Hello, World!");
console.log("Encrypted:", encrypted);
// Output: { iv: '...', encryptedData: '...' }

// Decrypt data
const decrypted = crypto.decrypt(encrypted);
console.log("Decrypted:", decrypted);
// Output: 'Hello, World!'

In JavaScript (Browser - ESM)

import CrossEnvCrypto from "cross-env-crypto";

// Use the same key as in your backend
const crypto = new CrossEnvCrypto("12345678901234567890123456789012");

// Since browser encryption uses the Web Crypto API which is async:
async function testEncryption() {
  // Encrypt data
  const encrypted = await crypto.encrypt("Hello from the browser!");
  console.log("Encrypted:", encrypted);

  // Decrypt data (including data from backend)
  const decrypted = await crypto.decrypt(encrypted);
  console.log("Decrypted:", decrypted);

  // You can also decrypt data that was encrypted by the backend
  const dataFromBackend = {
    iv: "1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
    encryptedData: "7q8r9s0t1u2v3w4x5y6z7a8b9c0d1e2f",
  };
  const decryptedFromBackend = await crypto.decrypt(dataFromBackend);
  console.log("Decrypted from backend:", decryptedFromBackend);
}

testEncryption();

Using the Same IV (Important for Cross-Environment Compatibility)

For two different environments to decrypt each other's encrypted data, they must use the same key AND IV:

// In environment A (e.g., backend)
const cryptoA = new CrossEnvCrypto("12345678901234567890123456789012");
const iv = "fedcba9876543210fedcba9876543210"; // Must be 32 hex chars (16 bytes)
const encryptedA = cryptoA.encrypt("Secret message", iv);

// In environment B (e.g., frontend)
const cryptoB = new CrossEnvCrypto("12345678901234567890123456789012");
// Use the exact same IV
const decryptedB = await cryptoB.decrypt(encryptedA);
// decryptedB will be 'Secret message'

Generating a Secure Key

const secureKey = CrossEnvCrypto.generateKey();
console.log("Generated key:", secureKey);

Security Considerations

1. Always use a strong, random 32-character key
2. For production use, never hardcode your key - use environment variables or secure key management
3. The IV is automatically included in the encrypted output, which is secure but makes the encrypted text longer
4. This library uses AES-256-CBC, which is a widely accepted encryption standard

Building from Source

# Install dependencies
npm install

# Build the package
npm run build

License

MIT