🛡️ Safe Crypto

Production-ready AES-256-GCM encryption with built-in safety rails.

A lightweight, zero-dependency TypeScript wrapper around Node's crypto module. Designed with the Safe Result Pattern to eliminate unhandled runtime exceptions.

✨ Features

• 🔒 AES-256-GCM: Industry-standard authenticated encryption.
• 🚦 Safe Result Pattern: No more try/catch blocks. Functions return a status object.
• 🛡️ Tamper Proof: Built-in "Auth Tag" validation (GCM magic).
• 🗜️ Small & Fast: Zero external dependencies (uses node:crypto).
• 💪 Fully Typed: Written in TypeScript for excellent IDE support.

📦 Installation

npm install @chizalam/safe-crypto

🚀 Quick Start
1. Initialize the EngineYou need a 64-character hex string (32 bytes) as your encryption key.

import { AesGcm } from '@chizalam/safe-crypto';

const crypto = new AesGcm({
  encryptionKey: 'your-64-character-hex-string-goes-here'
});

2. Encrypting (Safe Pattern)
The safeEncrypt method handles errors internally and returns a descriptive object.

const result = crypto.safeEncrypt("Hello Secret World");

if (result.success) {
  console.log(result.data); // Output: "iv:tag:ciphertext"
} else {
  console.error("Encryption failed:", result.error);
}
3. Decrypting (Safe Pattern)
The safeDecrypt method ensures the data is valid before returning it.
const result = crypto.safeDecrypt("iv:tag:ciphertext");

if (result.success) {
  // TypeScript knows 'data' is a string here
  console.log("Decrypted value:", result.data);
} else {
  // Handles tampered data, invalid formats, or wrong keys
  console.error("Decryption failed:", result.error);
}
🛠️ Utility 
FunctionsisEncrypted(value)
Check if a string matches the iv:tag:ciphertext format before attempting decryption.

if (crypto.isEncrypted(inputValue)) {
  const result = crypto.safeDecrypt(inputValue);
}
⚙️ Configuration 
Key64 Hex Chars (Must be a valid 256-bit key in hexadecimal).
Node Version16.x or higher (Uses node:crypto built-ins).
IV Length 12Bytes (Fixed to NIST-recommended GCM standard.)

🧪 Testing
We use Vitest for all unit tests.
npm test


📜 LicenseMIT © 2026 Chizalam