funkz-crypto

A lightweight, dependency-free encryption module built on the Web Crypto API (window.crypto.subtle), designed for secure AES-GCM encryption, decryption, and SHA-256 hashing in TypeScript or JavaScript projects.

Features

• 🔑 AES-GCM encryption and decryption
• 🧮 SHA-256 hashing (sha256Hex)
• 🎲 Secure random IV and key generation
• 🧰 Fully typed (ICrypto interface)
• 🌐 Works in modern browsers with window.crypto

Installation

npm i funkz-crypto

Example Usage

import Crypto, { sha256Hex, generateKeyData } from "funkz-crypto";

// Generate a random 16-byte IV
const iv = generateKeyData(16);

// Create a crypto instance with a secret key and IV
const cryptoInstance = new Crypto("my-secret-key", iv);

// Encrypt a message
const encrypted = await cryptoInstance.encrypt("Hello World!");
console.log("Encrypted (ArrayBuffer):", encrypted);

// Decrypt the message
const decrypted = await cryptoInstance.decrypt(encrypted);
console.log("Decrypted:", decrypted); // "Hello World!"

// Generate a SHA-256 hash
const hash = await sha256Hex("Hello World!");
console.log("SHA-256 Hash:", hash);

// Generate random bytes (for keys or IVs)
const randomBytes = generateKeyData(32);
console.log("Random bytes:", randomBytes);

Functions & Class Overview

Crypto class

Implements AES-GCM symmetric encryption using a UTF-8 encoded secret.

| Method | Description | | ---------------------------------- | ------------------------------------------------------- | | encrypt(message: string) | Encrypts a string using AES-GCM. Returns ArrayBuffer. | | decrypt(cipherText: ArrayBuffer) | Decrypts AES-GCM ciphertext. Returns plaintext string. |

Constructor

constructor(secret: string, iv?: Uint8Array)

• secret: A UTF-8 string used as the encryption key.
• iv: Optional initialization vector (IV). If not provided, one is auto-generated via generateKeyData().

Utility Functions

• generateKeyData(len?: number): Uint8Array Generates a secure random byte array using crypto.getRandomValues().
• sha256Hex(data: string): Promise Creates a SHA-256 hash in hexadecimal format.

Security Notes

IV reuse: Avoid reusing the same IV (_iv) with the same secret key for multiple encryptions. For better security, generate a new IV per message and store/transmit it alongside the ciphertext.

Key strength: AES-GCM supports 128, 192, and 256-bit keys. Ensure your secret string is long enough (e.g., 16+ characters for AES-128).

Environment: This module uses window.crypto.subtle. It is supported in all modern browsers and recent versions of Node.js (v20+ with Web Crypto).

Example — Encrypt/Decrypt with Dynamic IV

const iv = generateKeyData(12); // 96-bit IV (recommended for AES-GCM)
const cryptoInstance = new Crypto("super-secret-key", iv);

const ciphertext = await cryptoInstance.encrypt("Sensitive Data");
const plaintext = await cryptoInstance.decrypt(ciphertext);

console.log("Plaintext:", plaintext);

License

MIT © 2025 Ariel Francis Fernando Gacilo