@syldel/crypto-utils 1.0.3 → 1.1.0

package/LICENSE.MD

@@ -1,5 +1,5 @@
-Copyright (c) 2026, Syl-Studio Inc. c/o Syl. D.
-
-Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
-
+Copyright (c) 2026, Syl-Studio Inc. c/o Syl. D.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -30,7 +30,8 @@ const encrypted = AesGcmUtil.encrypt(message, keyHex);
 try {
   const original = AesGcmUtil.decrypt(encrypted, keyHex);
 } catch (error) {
-  // Throws "Decryption failed" if data is tampered or key is wrong
+  // "Invalid key: …" if the key is missing, not hex or not 32 bytes (a config error)
+  // "Decryption failed" for anything wrong with the payload, or the wrong key
 }
 ```
 
@@ -58,10 +59,20 @@ try {
 
 - **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.
+- **Side-Channel Protection**: JWT signatures are compared with `crypto.timingSafeEqual`, in constant time.
 
 - **GCM Integrity**: Unlike AES-CTR or CBC, AES-GCM ensures that any single-bit modification to the encrypted data will be detected during decryption.
 
+### ⚠️ What is refused, and why
+
+- `AesGcmUtil.decrypt` requires a full 16-byte tag and a 12-byte IV. Without this, Node accepts tags down to 4 bytes, and a random forged tag would pass with a 1 in 2^32 chance instead of 2^128.
+- Every hex input (key, data, IV, tag) is decoded strictly: a stray character fails instead of being silently cut off.
+- `decrypt` refuses a ciphertext above `AesGcmUtil.MAX_CIPHERTEXT_BYTES` (1 MiB) before decoding it.
+- A missing, non-hex or wrongly sized key throws `Invalid key: …`, never `Decryption failed`: it is a configuration error, and blaming the payload sent the search the wrong way. The message never quotes the key. Everything wrong with the payload stays a single generic `Decryption failed`, so an attacker learns nothing about which check failed.
+- `PureJwtUtil.verify` only accepts `alg: "HS256"`, a JSON object payload, a numeric `exp`, and the canonical base64url spelling of the signature.
+- Both `sign` and `verify` refuse an empty or missing secret: HMAC happily signs with an empty key, which anyone can guess.
+- `nbf`, `iat`, `aud` and `iss` are **not** checked: callers that rely on them must check them themselves.
+
 
 ## 🧪 Testing
 

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

@@ -5,7 +5,29 @@ export interface EncryptedData {
 }
 export declare class AesGcmUtil {
     private static readonly ALGORITHM;
+    private static readonly KEY_BYTES;
+    private static readonly IV_BYTES;
+    private static readonly TAG_BYTES;
+    /**
+     * Largest ciphertext `decrypt` accepts, in bytes (1 MiB). Checked on the hex
+     * string before any decoding: without it, a payload of hundreds of MB was
+     * decoded in full before GCM refused it. Our largest real payload is an
+     * agent key, 66 characters.
+     */
+    static readonly MAX_CIPHERTEXT_BYTES: number;
+    /**
+     * Une clé invalide est une erreur de configuration de l'appelant, pas une
+     * entrée d'attaquant : elle se nomme au lieu de se fondre dans « Decryption
+     * failed », qui accusait le chiffré quand le secret manquait dans l'env.
+     * Le message ne cite jamais la clé.
+     */
     private static validateKey;
+    /**
+     * Strict hex decoding. Buffer.from(hex) stops at the first invalid character
+     * without a word: a damaged field was read half-way, and a key followed by
+     * junk ("<64 hex>zz") was accepted as its first 32 bytes.
+     */
+    private static hexToBuffer;
     /**
      * Encrypts text using native Node.js crypto (AES-256-GCM)
      */

package/dist/aes-gcm.util.js

@@ -36,21 +36,53 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AesGcmUtil = void 0;
 const crypto = __importStar(require("crypto"));
 class AesGcmUtil {
+    /**
+     * Une clé invalide est une erreur de configuration de l'appelant, pas une
+     * entrée d'attaquant : elle se nomme au lieu de se fondre dans « Decryption
+     * failed », qui accusait le chiffré quand le secret manquait dans l'env.
+     * Le message ne cite jamais la clé.
+     */
     static validateKey(key) {
-        const encryptionKey = typeof key === 'string' ? Buffer.from(key, 'hex') : key;
-        if (encryptionKey.length !== 32) {
-            throw new Error('Invalid Key: Key must be 32 bytes (64 hex characters)');
+        if (key === undefined || key === null || key.length === 0) {
+            throw new Error('Invalid key: missing or empty (is the secret configured?)');
+        }
+        let encryptionKey;
+        try {
+            encryptionKey = typeof key === 'string' ? this.hexToBuffer(key) : key;
+        }
+        catch {
+            throw new Error('Invalid key: not a hex string');
+        }
+        if (!Buffer.isBuffer(encryptionKey) || encryptionKey.length !== this.KEY_BYTES) {
+            throw new Error('Invalid key: must be 32 bytes (64 hex characters)');
         }
         return encryptionKey;
     }
+    /**
+     * Strict hex decoding. Buffer.from(hex) stops at the first invalid character
+     * without a word: a damaged field was read half-way, and a key followed by
+     * junk ("<64 hex>zz") was accepted as its first 32 bytes.
+     */
+    static hexToBuffer(hex, expectedBytes) {
+        if (typeof hex !== 'string' || hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) {
+            throw new Error('Invalid hex string');
+        }
+        const buffer = Buffer.from(hex, 'hex');
+        if (expectedBytes !== undefined && buffer.length !== expectedBytes) {
+            throw new Error(`Expected ${expectedBytes} bytes, got ${buffer.length}`);
+        }
+        return buffer;
+    }
     /**
      * Encrypts text using native Node.js crypto (AES-256-GCM)
      */
     static encrypt(text, key) {
+        const encryptionKey = this.validateKey(key);
         try {
-            const encryptionKey = this.validateKey(key);
-            const iv = crypto.randomBytes(12);
-            const cipher = crypto.createCipheriv(this.ALGORITHM, encryptionKey, iv);
+            const iv = crypto.randomBytes(this.IV_BYTES);
+            const cipher = crypto.createCipheriv(this.ALGORITHM, encryptionKey, iv, {
+                authTagLength: this.TAG_BYTES,
+            });
             let encrypted = cipher.update(text, 'utf8', 'hex');
             encrypted += cipher.final('hex');
             return {
@@ -67,11 +99,22 @@ class AesGcmUtil {
      * Decrypts a payload using native Node.js crypto (AES-256-GCM)
      */
     static decrypt(payload, key) {
+        const encryptionKey = this.validateKey(key);
         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');
+            if (typeof payload.data !== 'string' || payload.data.length > 2 * this.MAX_CIPHERTEXT_BYTES) {
+                throw new Error('Ciphertext missing or above the size limit');
+            }
+            const iv = this.hexToBuffer(payload.iv, this.IV_BYTES);
+            const tag = this.hexToBuffer(payload.tag, this.TAG_BYTES);
+            const data = this.hexToBuffer(payload.data);
+            // Sans `authTagLength`, Node accepte un tag de 4 à 16 octets : mesuré sur
+            // la 1.0.3, un tag tronqué à 4 octets déchiffrait, et un tag forgé au
+            // hasard passait avec une chance sur 2^32 au lieu de 2^128.
+            const decipher = crypto.createDecipheriv(this.ALGORITHM, encryptionKey, iv, {
+                authTagLength: this.TAG_BYTES,
+            });
+            decipher.setAuthTag(tag);
+            let decrypted = decipher.update(data, undefined, 'utf8');
             decrypted += decipher.final('utf8');
             return decrypted;
         }
@@ -82,3 +125,13 @@ class AesGcmUtil {
 }
 exports.AesGcmUtil = AesGcmUtil;
 AesGcmUtil.ALGORITHM = 'aes-256-gcm';
+AesGcmUtil.KEY_BYTES = 32;
+AesGcmUtil.IV_BYTES = 12;
+AesGcmUtil.TAG_BYTES = 16;
+/**
+ * Largest ciphertext `decrypt` accepts, in bytes (1 MiB). Checked on the hex
+ * string before any decoding: without it, a payload of hundreds of MB was
+ * decoded in full before GCM refused it. Our largest real payload is an
+ * agent key, 66 characters.
+ */
+AesGcmUtil.MAX_CIPHERTEXT_BYTES = 1024 * 1024;

package/dist/jwt.util.js

@@ -40,22 +40,37 @@ class PureJwtUtil {
      * Verifies a JWT's signature and expiration, then returns the decoded payload.
      */
     static verify(token, secret) {
+        assertSecret(secret);
         const parts = token.split('.');
         if (parts.length !== 3)
             throw new Error('Invalid token format');
         const [headerB64, payloadB64, signatureB64] = parts;
         const dataToVerify = `${headerB64}.${payloadB64}`;
-        const expectedSignature = crypto
-            .createHmac('sha256', secret)
-            .update(dataToVerify)
-            .digest('base64url');
-        if (signatureB64 !== expectedSignature) {
+        const expected = crypto.createHmac('sha256', secret).update(dataToVerify).digest();
+        const received = Buffer.from(signatureB64, 'base64url');
+        // Comparaison en temps constant : `!==` s'arrête au premier caractère
+        // différent, et le temps de réponse renseigne sur la signature attendue.
+        // timingSafeEqual lance sur deux longueurs différentes, d'où le test avant.
+        // Le décodage base64url est tolérant : plusieurs écritures donnent les mêmes
+        // octets. Seule la forme canonique est admise, comme avec l'ancien `!==`.
+        if (received.toString('base64url') !== signatureB64 ||
+            received.length !== expected.length ||
+            !crypto.timingSafeEqual(received, expected)) {
             throw new Error('Invalid signature');
         }
-        const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
-        const payloadRecord = payload;
-        if (typeof payloadRecord.exp === 'number') {
-            if (Date.now() >= payloadRecord.exp * 1000) {
+        // L'en-tête n'était jamais lu : un jeton annonçant « none » ou un autre
+        // algorithme passait du moment que sa signature HS256 était juste.
+        const header = parseJsonObject(headerB64, 'Invalid token header');
+        if (header.alg !== 'HS256') {
+            throw new Error('Unsupported algorithm');
+        }
+        const payload = parseJsonObject(payloadB64, 'Invalid token payload');
+        // Un `exp` non numérique était ignoré : le jeton n'expirait jamais.
+        if (payload.exp !== undefined) {
+            if (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp)) {
+                throw new Error('Invalid token payload');
+            }
+            if (Date.now() >= payload.exp * 1000) {
                 throw new Error('Token expired');
             }
         }
@@ -65,6 +80,7 @@ class PureJwtUtil {
      * Signs a payload and returns a compact JWT string.
      */
     static sign(payload, secret) {
+        assertSecret(secret);
         const header = { alg: 'HS256', typ: 'JWT' };
         const encode = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
         const encodedHeader = encode(header);
@@ -77,3 +93,25 @@ class PureJwtUtil {
     }
 }
 exports.PureJwtUtil = PureJwtUtil;
+/**
+ * createHmac signe avec une chaîne vide (mesuré sur le bot le 2026-10-06) : la
+ * signature attendue devient calculable par quiconque devine le secret vide.
+ */
+function assertSecret(secret) {
+    if (typeof secret !== 'string' || secret.length === 0) {
+        throw new Error('Invalid secret: a non-empty string is required');
+    }
+}
+function parseJsonObject(segment, error) {
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error(error);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(error);
+    }
+    return value;
+}

package/package.json

@@ -1,49 +1,58 @@
-{
-  "name": "@syldel/crypto-utils",
-  "version": "1.0.3",
-  "description": "Lightweight JWT and AES-256-GCM utilities",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "clean": "rm -rf dist",
-    "build": "npm run lint && npm run clean && tsc -p tsconfig.json",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "prepublishOnly": "npm run build",
-    "release": "npm run build && npm version patch && npm publish"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "jwt",
-    "aes",
-    "crypto",
-    "security",
-    "nestjs"
-  ],
-  "author": "Syl. D.",
-  "license": "ISC",
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/jest": "^30.0.0",
-    "eslint": "^10.0.1",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsonc": "^3.0.0",
-    "eslint-plugin-prettier": "^5.5.5",
-    "jest": "^30.2.0",
-    "jsonc-eslint-parser": "^3.1.0",
-    "prettier": "^3.8.1",
-    "ts-jest": "^29.4.6",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.0"
-  },
-  "overrides": {
-    "minimatch": "^10.2.1"
-  }
-}
+{
+  "name": "@syldel/crypto-utils",
+  "version": "1.1.0",
+  "description": "Lightweight JWT and AES-256-GCM utilities",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syldel/crypto-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Syldel/crypto-utils/issues"
+  },
+  "homepage": "https://github.com/Syldel/crypto-utils#readme",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "clean": "rm -rf dist",
+    "build": "npm run lint && npm run clean && tsc -p tsconfig.json",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "npm run build",
+    "release": "npm run build && npm version patch && npm publish"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "jwt",
+    "aes",
+    "crypto",
+    "security",
+    "nestjs"
+  ],
+  "author": "Syl. D.",
+  "license": "ISC",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.19.43",
+    "eslint": "^10.0.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsonc": "^3.0.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "jest": "^30.2.0",
+    "jsonc-eslint-parser": "^3.1.0",
+    "prettier": "^3.8.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0"
+  },
+  "overrides": {
+    "minimatch": "^10.2.1"
+  }
+}