@chizalam/safe-crypto 1.0.0

package/README.md

@@ -0,0 +1,69 @@
+# 🛡️ 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
+
+```bash
+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

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/** * Represents a successful or failed crypto operation.
+ */
+export type CryptoResult<T> = {
+    success: true;
+    data: T;
+    error: null;
+} | {
+    success: false;
+    data: null;
+    error: string;
+};
+/** * Formatted as hex strings: `iv:tag:ciphertext`
+ */
+export type EncryptedString = `${string}:${string}:${string}`;
+export interface CryptoConfig {
+    /** A 64-character hex string (256-bit key) */
+    encryptionKey: string;
+}
+/**
+ * A production-ready AES-256-GCM encryption engine.
+ */
+export declare class AesGcm {
+    private readonly algorithm;
+    private readonly ivLength;
+    private readonly secretKey;
+    constructor(config: CryptoConfig);
+    /**
+     * Encrypts a string and returns a status object.
+     */
+    safeEncrypt(plaintext: string): CryptoResult<EncryptedString>;
+    /**
+     * Decrypts a string and returns a status object.
+     */
+    safeDecrypt(payload: EncryptedString): CryptoResult<string>;
+    private encrypt;
+    private decrypt;
+    isEncrypted(value: any): value is EncryptedString;
+}

package/dist/index.js

@@ -0,0 +1,60 @@
+import { randomBytes, createCipheriv, createDecipheriv, createSecretKey } from "node:crypto";
+/**
+ * A production-ready AES-256-GCM encryption engine.
+ */
+export class AesGcm {
+    algorithm = "aes-256-gcm";
+    ivLength = 12;
+    secretKey;
+    constructor(config) {
+        if (!/^[0-9A-Fa-f]{64}$/.test(config.encryptionKey)) {
+            throw new Error("Encryption key must be a 64-character hex string.");
+        }
+        this.secretKey = createSecretKey(Buffer.from(config.encryptionKey, "hex"));
+    }
+    /**
+     * Encrypts a string and returns a status object.
+     */
+    safeEncrypt(plaintext) {
+        try {
+            const data = this.encrypt(plaintext);
+            return { success: true, data, error: null };
+        }
+        catch (e) {
+            return { success: false, data: null, error: e instanceof Error ? e.message : "Encryption failed" };
+        }
+    }
+    /**
+     * Decrypts a string and returns a status object.
+     */
+    safeDecrypt(payload) {
+        try {
+            const data = this.decrypt(payload);
+            return { success: true, data, error: null };
+        }
+        catch (e) {
+            return { success: false, data: null, error: e instanceof Error ? e.message : "Decryption failed" };
+        }
+    }
+    encrypt(plaintext) {
+        const iv = randomBytes(this.ivLength);
+        const cipher = createCipheriv(this.algorithm, this.secretKey, iv);
+        const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return `${iv.toString("hex")}:${tag.toString("hex")}:${ciphertext.toString("hex")}`;
+    }
+    decrypt(payload) {
+        const [ivHex, tagHex, ctHex] = payload.split(":");
+        if (!ivHex || !tagHex || !ctHex)
+            throw new Error("Invalid format");
+        const decipher = createDecipheriv(this.algorithm, this.secretKey, Buffer.from(ivHex, "hex"));
+        decipher.setAuthTag(Buffer.from(tagHex, "hex"));
+        return Buffer.concat([decipher.update(Buffer.from(ctHex, "hex")), decipher.final()]).toString("utf8");
+    }
+    isEncrypted(value) {
+        if (typeof value !== "string")
+            return false;
+        const parts = value.split(":");
+        return parts.length === 3 && parts.every(p => /^[0-9A-Fa-f]+$/.test(p));
+    }
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { AesGcm } from './index.js';
+describe('AesGcm Engine', () => {
+    const key = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+    const engine = new AesGcm({ encryptionKey: key });
+    it('should handle safe decryption of invalid data without crashing', () => {
+        const result = engine.safeDecrypt('bad:format:data');
+        expect(result.success).toBe(false);
+        expect(result.error).toBeTypeOf('string');
+    });
+    it('should successfully encrypt and decrypt', () => {
+        const original = "Top Secret";
+        const encrypted = engine.safeEncrypt(original);
+        if (encrypted.success) {
+            const decrypted = engine.safeDecrypt(encrypted.data);
+            expect(decrypted.success).toBe(true);
+            expect(decrypted.data).toBe(original);
+        }
+    });
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@chizalam/safe-crypto",
+  "version": "1.0.0",
+  "description": "A production-ready AES-256-GCM encryption engine with safe result handling.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "crypto",
+    "aes-256-gcm",
+    "encryption",
+    "safe-result",
+    "typescript"
+  ],
+  "author": "Chizalam",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cemuchay/safe-crypto.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cemuchay/safe-crypto/issues"
+  },
+  "homepage": "https://github.com/cemuchay/safe-crypto#readme",
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.3"
+  }
+}