@syldel/crypto-utils 1.0.1 → 1.0.3

package/README.md

@@ -1,8 +1,75 @@
 # @syldel/crypto-utils
 
-Lightweight JWT and AES-256-GCM utilities
+A robust, high-performance cryptographic toolkit for Node.js and NestJS applications. This package prioritizes security by leveraging Node's native crypto module (OpenSSL) for maximum protection of sensitive data and private keys.
 
----
+## 🚀 Key Features
+- **Native Security**: Built on top of Node.js crypto (OpenSSL) for hardware-accelerated encryption.
+
+- **AES-256-GCM**: Industry-standard authenticated encryption (AEAD) to ensure both confidentiality and data integrity.
+
+- **Lightweight JWT**: Pure implementation for signing and verifying tokens without heavy dependencies.
+
+- **Standardized Error Handling**: Harmonized error messages ("Decryption failed") for better security and predictable testing.
+
+## 🛠 Usage
+
+### AES-256-GCM (Authenticated Encryption)
+Designed for high-security environments. It automatically handles Initialization Vectors (IV) and Authentication Tags.
+
+```ts
+import { AesGcmUtil } from '@syldel/crypto-utils';
+
+const keyHex = "0123456789abcdef..."; // 64 hex characters (32 bytes)
+const message = "Sensitive data";
+
+// Encrypt
+const encrypted = AesGcmUtil.encrypt(message, keyHex);
+// Returns: { data: '...', iv: '...', tag: '...' }
+
+// Decrypt
+try {
+  const original = AesGcmUtil.decrypt(encrypted, keyHex);
+} catch (error) {
+  // Throws "Decryption failed" if data is tampered or key is wrong
+}
+```
+
+### Pure JWT Utilities
+A lightweight way to handle JWTs in your NestJS guards or services.
+
+```ts
+import { PureJwtUtil } from '@syldel/crypto-utils';
+
+const secret = "your-secure-secret";
+const payload = { sub: "user_123", role: "admin" };
+
+// Sign a token
+const token = PureJwtUtil.sign(payload, secret);
+
+// Verify and decode
+try {
+  const decoded = PureJwtUtil.verify<MyUserType>(token, secret);
+} catch (err) {
+  // Handles "Token expired" or "Invalid signature"
+}
+```
+
+## 🔒 Security & Performance
+
+- **Zero External Crypto Libs**: By using native Node.js APIs, this package minimizes the attack surface and dependency supply chain risks.
+
+- **Side-Channel Protection**: Leverages OpenSSL's C++ implementation to protect against timing attacks.
+
+- **GCM Integrity**: Unlike AES-CTR or CBC, AES-GCM ensures that any single-bit modification to the encrypted data will be detected during decryption.
+
+
+## 🧪 Testing
+
+Full test suite with 100% coverage on core crypto logic.
+
+```bash
+npm run test
+```
 
 ## 👨‍💻 Développement
 
@@ -24,8 +91,6 @@ Le projet utilise **ESLint** pour la logique et **Prettier** pour le formatage.
 npx eslint .
 ```
 
----
-
 ## 🔗 Utilisation en local (Development Workflow)
 
 Pour utiliser ce package dans tes autres projets sans le publier sur NPM :
@@ -39,8 +104,6 @@ Pour utiliser ce package dans tes autres projets sans le publier sur NPM :
     npm link @syldel/crypto-utils
     ```
 
----
-
 ## 📦 Publication
 
 Le projet utilise des **Granular Access Tokens** pour la publication afin de contourner la double authentification (2FA) manuelle tout en maintenant une sécurité maximale.

package/dist/aes-gcm.util.d.ts

@@ -4,7 +4,14 @@ export interface EncryptedData {
     tag: string;
 }
 export declare class AesGcmUtil {
+    private static readonly ALGORITHM;
     private static validateKey;
+    /**
+     * Encrypts text using native Node.js crypto (AES-256-GCM)
+     */
     static encrypt(text: string, key: Buffer | string): EncryptedData;
+    /**
+     * Decrypts a payload using native Node.js crypto (AES-256-GCM)
+     */
     static decrypt(payload: EncryptedData, key: Buffer | string): string;
 }

package/dist/aes-gcm.util.js

@@ -43,25 +43,42 @@ class AesGcmUtil {
         }
         return encryptionKey;
     }
+    /**
+     * Encrypts text using native Node.js crypto (AES-256-GCM)
+     */
     static encrypt(text, key) {
-        const encryptionKey = this.validateKey(key);
-        const iv = crypto.randomBytes(12);
-        const cipher = crypto.createCipheriv('aes-256-gcm', encryptionKey, iv);
-        let encrypted = cipher.update(text, 'utf8', 'hex');
-        encrypted += cipher.final('hex');
-        return {
-            data: encrypted,
-            iv: iv.toString('hex'),
-            tag: cipher.getAuthTag().toString('hex'),
-        };
+        try {
+            const encryptionKey = this.validateKey(key);
+            const iv = crypto.randomBytes(12);
+            const cipher = crypto.createCipheriv(this.ALGORITHM, encryptionKey, iv);
+            let encrypted = cipher.update(text, 'utf8', 'hex');
+            encrypted += cipher.final('hex');
+            return {
+                data: encrypted,
+                iv: iv.toString('hex'),
+                tag: cipher.getAuthTag().toString('hex'),
+            };
+        }
+        catch {
+            throw new Error('Encryption failed');
+        }
     }
+    /**
+     * Decrypts a payload using native Node.js crypto (AES-256-GCM)
+     */
     static decrypt(payload, key) {
-        const encryptionKey = this.validateKey(key);
-        const decipher = crypto.createDecipheriv('aes-256-gcm', encryptionKey, Buffer.from(payload.iv, 'hex'));
-        decipher.setAuthTag(Buffer.from(payload.tag, 'hex'));
-        let decrypted = decipher.update(payload.data, 'hex', 'utf8');
-        decrypted += decipher.final('utf8');
-        return decrypted;
+        try {
+            const encryptionKey = this.validateKey(key);
+            const decipher = crypto.createDecipheriv(this.ALGORITHM, encryptionKey, Buffer.from(payload.iv, 'hex'));
+            decipher.setAuthTag(Buffer.from(payload.tag, 'hex'));
+            let decrypted = decipher.update(payload.data, 'hex', 'utf8');
+            decrypted += decipher.final('utf8');
+            return decrypted;
+        }
+        catch {
+            throw new Error('Decryption failed');
+        }
     }
 }
 exports.AesGcmUtil = AesGcmUtil;
+AesGcmUtil.ALGORITHM = 'aes-256-gcm';

package/dist/jwt.util.d.ts

@@ -1,4 +1,10 @@
 export declare class PureJwtUtil {
+    /**
+     * Verifies a JWT's signature and expiration, then returns the decoded payload.
+     */
     static verify<T extends object>(token: string, secret: string): T;
+    /**
+     * Signs a payload and returns a compact JWT string.
+     */
     static sign(payload: Record<string, any>, secret: string): string;
 }

package/dist/jwt.util.js

@@ -36,6 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PureJwtUtil = void 0;
 const crypto = __importStar(require("crypto"));
 class PureJwtUtil {
+    /**
+     * Verifies a JWT's signature and expiration, then returns the decoded payload.
+     */
     static verify(token, secret) {
         const parts = token.split('.');
         if (parts.length !== 3)
@@ -58,6 +61,9 @@ class PureJwtUtil {
         }
         return payload;
     }
+    /**
+     * Signs a payload and returns a compact JWT string.
+     */
     static sign(payload, secret) {
         const header = { alg: 'HS256', typ: 'JWT' };
         const encode = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syldel/crypto-utils",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Lightweight JWT and AES-256-GCM utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",