Better Cipher

A secure encryption library with browser and Node.js support using AES-256-GCM.

Features

• 🔒 AES-256-GCM encryption
• 🌐 Works in both Node.js and browser environments
• 🔄 Key rotation support
• 📦 Zero dependencies (uses platform native crypto APIs)
• 🎯 TypeScript support
• ✨ Simple API

Installation

npm install better-cipher
# or
yarn add better-cipher
# or
pnpm add better-cipher

Usage

Node.js

import { Cipher } from "better-cipher";

// Create a cipher instance with a 32-byte (64 hex characters) key
const cipher = new Cipher(
  "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
);

// Encrypt
const encrypted = await cipher.encrypt("Hello, World!");
// {
//   iv: '...',        // 24 characters (12 bytes in hex)
//   content: '...',   // encrypted data in hex
//   authTag: '...'    // authentication tag in hex
// }

// Decrypt
const decrypted = await cipher.decrypt(encrypted);
// 'Hello, World!'

Browser

import { Cipher } from "better-cipher";

// Same API as Node.js!
const cipher = new Cipher(
  "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
);

const encrypted = await cipher.encrypt("Hello, World!");
const decrypted = await cipher.decrypt(encrypted);

Key Rotation

import { Cipher } from 'better-cipher';

const oldKey = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
const newKey = 'fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210';

// Create a rotator function
const rotator = Cipher.createRotator(oldKey, newKey);

// Re-encrypt data with new key
const oldEncrypted = /* ... previously encrypted data ... */;
const newEncrypted = await rotator(oldEncrypted);

API Documentation

class Cipher

Constructor

constructor(secretKeyHex: string)

Creates a new Cipher instance.

• secretKeyHex: A 32-byte (64 hex characters) key in hexadecimal format.
• Throws if key is invalid (wrong length or non-hex characters).

Methods

encrypt(text: string): Promise<Encrypted>

Encrypts a string using AES-256-GCM.

• text: The string to encrypt (can be empty).
• Returns: Promise resolving to an Encrypted object.

decrypt(encrypted: Encrypted): Promise<string>

Decrypts previously encrypted data.

• encrypted: An Encrypted object from the encrypt method.
• Returns: Promise resolving to the original string.

static createRotator(oldSecretKey: string, newSecretKey: string): (encrypted: Encrypted) => Promise<Encrypted>

Creates a key rotation function.

• oldSecretKey: The current encryption key.
• newSecretKey: The new encryption key.
• Returns: A function that takes old encrypted data and returns newly encrypted data.

Types

interface Encrypted {
  iv: string; // Initialization vector (hex)
  content: string; // Encrypted content (hex)
  authTag: string; // Authentication tag (hex, Node.js only)
}

Requirements

• Node.js >= 20.0.0
• Modern browsers with Web Crypto API support

License

MIT