@encryptedclipboard/crypto

A professional-grade, unified end-to-end (E2E) encryption logic library built for the Encrypted Clipboard Manager ecosystem.

This package is the core encryption engine of the Encrypted Clipboard Manager extension, created and maintained by Nowshad Hossain Rahat and the encryptedclipboard organization.

• Website: encryptedclipboard.app
• X/Twitter: @EncryptedClip
• Maintainers: Nowshad Hossain Rahat, encryptedclipboard

🚀 Features

• Standardized Encryption: Uses industry-standard AES-256-GCM for high-performance authenticated encryption.
• Robust Key Derivation: Implements PBKDF2 with a default of 400,000 iterations (to have a balance between speed and security), customizable based on security vs. performance needs.
• Hybrid API: Seamless support for both static utility methods and pre-configured class instances.
• Zero Dependencies: Built entirely on top of the native Web Crypto API, ensuring maximum security and a tiny footprint.
• Unified Logic: Shared between the server, client (web), and browser extension for consistent E2E stability.
• Security Utilities: Includes password strength validation, SHA-256 hashing with pepper support, and PIN-based encryption.

📦 Installation

This package is intended to be used within the Encrypted Clipboard Manager workspace.

bun install @encryptedclipboard/crypto

🛠 Usage

This package supports both ES Modules (ESM) and CommonJS (CJS).

1. Modern ESM / TypeScript (Recommended)

Works in modern Node.js, Vite, Nuxt, React, Svelte, etc.

import { CryptoEngine } from "@encryptedclipboard/crypto";

const masterPassword = "your-strong-master-password";
const sensibleData = { secret: "This is a secret message" };

Static Approach (One-off)

// Encrypt
const encrypted = await CryptoEngine.encryptData(sensibleData, masterPassword);

// Decrypt
const decrypted = await CryptoEngine.decryptData(encrypted, masterPassword);

Instance Approach (Pre-configured)

const crypto = new CryptoEngine({ iterations: 100000 });

// No need to pass iterations every time
const encrypted = await crypto.encryptData(sensibleData, masterPassword);
const decrypted = await crypto.decryptData(encrypted, masterPassword);

2. Node.js CommonJS

Works in older Node.js environments or projects using require.

Static Approach

const { CryptoEngine } = require("@encryptedclipboard/crypto");

// Usage is the same (Async/Await)
(async () => {
  const encrypted = await CryptoEngine.encryptData({ msg: "Hi" }, "pass");
  console.log(encrypted);
})();

Instance Approach

const { CryptoEngine } = require("@encryptedclipboard/crypto");

(async () => {
  const crypto = new CryptoEngine({ iterations: 100000 });
  const encrypted = await crypto.encryptData({ msg: "Hi" }, "pass");
  console.log(encrypted);
})();

3. Direct Browser (via CDN)

Since this library has zero dependencies and uses the native Web Crypto API, you can use it directly in the browser without a build step.

Static Approach

<script type="module">
  import { CryptoEngine } from "https://esm.sh/@encryptedclipboard/crypto";

  const encrypted = await CryptoEngine.encryptData(
    "Hello world",
    "my-password"
  );

  console.log("Encrypted:", encrypted);
</script>

Instance Approach

<script type="module">
  import { CryptoEngine } from "https://esm.sh/@encryptedclipboard/crypto";

  const crypto = new CryptoEngine({ iterations: 100000 });

  const encrypted = await crypto.encryptData("Hello world", "my-password");

  console.log("Encrypted:", encrypted);
</script>

Password Strength Validation

const assessment = CryptoEngine.validatePasswordStrength("MyP@ssw0rd");
console.log(assessment.isStrong); // boolean
console.log(assessment.feedback); // Array of suggestions

High-Performance Batch Processing

When encrypting or decrypting multiple items, use the batch methods. They automatically cache the derived key (salt) for the entire batch and use a builtin concurrency controller, drastically improving performance compared to a simple Promise.all.

Static Approach

const items = [{ id: 1 }, { id: 2 }, { id: 3 }];

// Encrypt multiple items iteratively with a concurrency limit and progress tracking
const encryptedBatch = await CryptoEngine.encryptBatch(
  items,
  "master-password",
  400000,
  {
    concurrency: 5,
    onProgress: (processed, total) => {
      console.log(`Encrypted ${processed} of ${total} items`);
    }
  }
);

// Decrypt the batch
const decryptedBatch = await CryptoEngine.decryptBatch(
  encryptedBatch,
  "master-password",
  {
    concurrency: 5,
    disableCache: false, // disableCache is false by default
    onProgress: (processed, total) => {
      console.log(`Decrypted ${processed} of ${total} items`);
    }
  }
);

Disabling Salt Caching

By default, batch operations generate a single salt/key for the entire batch to maximize performance. If you need each item to have its own unique salt, set disableCache: true.

const encryptedBatch = await CryptoEngine.encryptBatch(
  items,
  "master-password",
  400000,
  { disableCache: true }
);

Instance Approach

const crypto = new CryptoEngine({
  iterations: 100000,
  concurrency: 5
});

const items = [{ id: 1 }, { id: 2 }, { id: 3 }];

const encryptedBatch = await crypto.encryptBatch(items, "master-password", {
  onProgress: (processed, total) => console.log(`Encrypting: ${processed}/${total}`)
});

const decryptedBatch = await crypto.decryptBatch(encryptedBatch, "master-password", {
  onProgress: (processed, total) => console.log(`Decrypting: ${processed}/${total}`)
});

PIN-based Encryption

Useful for local sessions where you want to lock data with a short PIN without re-entering the main password.

Static Approach

const encryptedPassword = await CryptoEngine.encryptPasswordWithPin(
  "master-password",
  "1234"
);

const originalPassword = await CryptoEngine.decryptPasswordWithPin(
  encryptedPassword,
  "1234"
);

Instance Approach

const crypto = new CryptoEngine({ iterations: 50000 });

const encryptedPassword = await crypto.encryptPasswordWithPin("master-password", "1234");
const originalPassword = await crypto.decryptPasswordWithPin(encryptedPassword, "1234");

Raw Key Support

For high-performance scenarios (e.g., Web Workers or repeated operations), you can derive the raw PBKDF2 key once and reuse it for multiple encryption/decryption operations. This avoids the overhead of repeated key derivation.

Derived Raw Key Usage

const salt = crypto.getRandomValues(new Uint8Array(32));
const iterations = 400000;

// 1. Generate the raw key buffer (Uint8Array/ArrayBuffer)
const rawKey = await CryptoEngine.generateRawKey(masterPassword, salt, iterations);

// 2. Encrypt using the raw key
const encrypted = await CryptoEngine.encryptWithRawKey(data, rawKey, salt, iterations);

// 3. Decrypt using the raw key
const decrypted = await CryptoEngine.decryptWithRawKey(encrypted, rawKey);

Instance Approach

const crypto = new CryptoEngine({ iterations: 400000 });
const salt = crypto.getRandomValues(new Uint8Array(32));

const rawKey = await CryptoEngine.generateRawKey(masterPassword, salt);

// Iterations are handled by the instance
const encrypted = await crypto.encryptWithRawKey(data, rawKey, salt);
const decrypted = await crypto.decryptWithRawKey(encrypted, rawKey);

🔐 Security Specifications

• Algorithm: AES-GCM (Advanced Encryption Standard - Galois/Counter Mode)
• Key Length: 256 bits
• KDF: PBKDF2 (Password-Based Key Derivation Function 2)
• Hash: SHA-256
• Iterations: 400,000 (Default, Customizable)
• Salt Length: 256 bits (32 bytes)
• IV Length: 96 bits (12 bytes)

🛠 Development

If you want to contribute or verify the library logic locally:

1. Clone the repo:

   git clone https://github.com/encryptedclipboard/crypto.git

2. Install dependencies:

   bun install

3. Run tests:

   bun test

📜 License

This project is licensed under the Apache License 2.0.