ez-web-crypto

A lightweight, type-safe wrapper around the Web Crypto API, providing easy-to-use cryptographic operations for both browser and Node.js environments.

Features

• 🔐 AES-GCM encryption/decryption
• 🔑 ECDH key exchange and encryption
• ✍️ ECDSA digital signatures
• 🔒 Password-based encryption
• 🌐 HKDF key derivation
• #️⃣ HMAC operations
• 🧮 Cryptographic hashing (SHA-1, SHA-256, SHA-384, SHA-512)
• 📱 Cross-platform compatibility (Browser + Node.js)
• 📘 Full TypeScript support
• 🔄 Flexible key format handling

Installation

npm install @justinwwolcott/ez-web-crypto

Usage Examples

AES Encryption

import { AESMakeKey, AESEncrypt, AESDecrypt } from '@justinwwolcott/ez-web-crypto'

// Generate a new AES key
const key = await AESMakeKey()

// Encrypt data
const encrypted = await AESEncrypt(key, btoa('Hello, World!'))

// Decrypt data
const decrypted = await AESDecrypt(key, encrypted.iv, encrypted.ciphertext, true)
console.log(decrypted) // 'Hello, World!'

ECDH Key Exchange and Encryption

import { EcMakeCryptKeys, EcEncrypt, EcDecrypt } from '@justinwwolcott/ez-web-crypto'

// Generate key pairs for both parties
const aliceKeys = await EcMakeCryptKeys()
const bobKeys = await EcMakeCryptKeys()

// Alice encrypts message for Bob
const encrypted = await EcEncrypt(aliceKeys.privateKey, bobKeys.publicKey, btoa('Secret message'))

// Bob decrypts message from Alice
const decrypted = await EcDecrypt(bobKeys.privateKey, aliceKeys.publicKey, encrypted.iv, encrypted.ciphertext, true)

Digital Signatures (ECDSA)

import { EcMakeSigKeys, EcSignData, EcVerifySig } from '@justinwwolcott/ez-web-crypto'

// Generate signing keys
const keys = await EcMakeSigKeys()

// Sign data
const signature = await EcSignData(keys.privateKey, btoa('Sign this message'))

// Verify signature
const isValid = await EcVerifySig(keys.publicKey, signature, btoa('Sign this message'))

Password-Based Encryption

import { PASSWORD_ENCRYPT, PASSWORD_DECRYPT } from '@justinwwolcott/ez-web-crypto'

// Encrypt with password
const encrypted = await PASSWORD_ENCRYPT('myPassword', btoa('Secret data'))

// Decrypt with password
const decrypted = await PASSWORD_DECRYPT('myPassword', encrypted)

HKDF Encryption

import { EcMakeCryptKeys, HKDFEncrypt, HKDFDecrypt } from '@justinwwolcott/ez-web-crypto'

// Generate keys
const aliceKeys = await EcMakeCryptKeys()
const bobKeys = await EcMakeCryptKeys()

// Encrypt using HKDF
const encrypted = await HKDFEncrypt(aliceKeys.privateKey, bobKeys.publicKey, btoa('Secret data'))

// Decrypt using HKDF
const decrypted = await HKDFDecrypt(
  bobKeys.privateKey,
  aliceKeys.publicKey,
  encrypted.salt,
  encrypted.iv,
  encrypted.ciphertext,
  true
)

Hashing and HMAC

import { HASH, HMAC } from '@justinwwolcott/ez-web-crypto'

// Generate hash
const hash = await HASH('SHA-256', 'Hash this text')

// Generate HMAC
const hmac = await HMAC('secret-key', 'Message to authenticate')

API Reference

AES Operations

• AESMakeKey(exportable?: boolean): Promise<Base64String | CryptoKey>

  • Generates a new AES-GCM key
  • exportable: Whether the key should be exportable (default: true)

• AESEncrypt(key: Base64String | CryptoKey, data: Base64String, nonce?: Base64String): Promise<AESEncryptResult>

  • Encrypts data using AES-GCM
  • Returns ciphertext and IV

• AESDecrypt(key: Base64String | CryptoKey, nonce: Base64String, data: Base64String, returnText?: boolean): Promise<string | ArrayBuffer>

  • Decrypts AES-GCM encrypted data
  • Optional text return format

ECDH Operations

• EcMakeCryptKeys(exportable?: boolean): Promise<ECKeyPair>

  • Generates ECDH key pair for encryption
  • Returns public/private keys in multiple formats

• EcEncrypt(privateKey: Base64String | CryptoKey, publicKey: Base64String | CryptoKey, data: Base64String): Promise<AESEncryptResult>

  • Encrypts data using ECDH key exchange
  • Returns encrypted data and IV

• EcDecrypt(privateKey: Base64String | CryptoKey, publicKey: Base64String | CryptoKey, nonce: Base64String, data: Base64String, returnText?: boolean): Promise<string | ArrayBuffer>

  • Decrypts ECDH encrypted data

ECDSA Digital Signatures

• EcMakeSigKeys(exportable?: boolean): Promise<ECSignatureKeyPair>
  • Generates ECDSA signing key pair
• EcSignData(privateKey: Base64String | CryptoKey, data: Base64String): Promise<Base64String>
  • Signs data using ECDSA
• EcVerifySig(publicKey: Base64String | CryptoKey, signature: Base64String, data: Base64String): Promise<boolean>
  • Verifies ECDSA signature

HKDF Operations

• HKDFEncrypt(privateKey: Base64String | CryptoKey, publicKey: Base64String | CryptoKey, data: Base64String, ivLength?: number, saltLength?: number): Promise<HKDFEncryptResult>
  • Encrypts data using HKDF key derivation
• HKDFDecrypt(privateKey: Base64String | CryptoKey, publicKey: Base64String | CryptoKey, salt: Base64String, iv: Base64String, data: Base64String, returnText?: boolean): Promise<string | ArrayBuffer>
  • Decrypts HKDF encrypted data

Password Operations

• PASSWORD_ENCRYPT(password: string, data: Base64String): Promise<Base64String>
  • Encrypts data using password-based encryption
• PASSWORD_DECRYPT(password: string, data: Base64String): Promise<string>
  • Decrypts password-protected data

Hashing Operations

• HASH(algorithm: HashAlgorithm, data: string, length?: number): Promise<Base64String>
  • Generates cryptographic hash
  • Supports SHA-1, SHA-256, SHA-384, SHA-512
• HMAC(secret: string, data: string): Promise<HexString>
  • Generates HMAC using SHA-256

Type Definitions

type Base64String = string
type HexString = string
type HashAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512'

interface AESEncryptResult {
  ciphertext: Base64String
  iv: Base64String
}

interface HKDFEncryptResult {
  ciphertext: Base64String
  salt: Base64String
  iv: Base64String
}

interface ECKeyPair {
  publicKey: Base64String
  privateKey: Base64String | CryptoKey
  rawPublicKey: Base64String
  rawPublicKeyLite: Base64String
  jwkPublicKey?: JsonWebKey
  jwkPrivateKey?: JsonWebKey
}

Environment Support

• Node.js ≥ 14.0.0
• Modern browsers with Web Crypto API support
• Full TypeScript support included

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Security Notes

• All cryptographic operations use standard Web Crypto API implementations
• Keys can be handled in both exportable and non-exportable formats
• Password-based encryption uses multiple rounds of hashing for key strengthening
• All operations are async and type-safe

License

This project is licensed under the ISC License - see the LICENSE file for details.

Author

Justin W. Wolcott

Support

If you encounter any problems or have questions, please open an issue on GitHub.