key-rotation-manager 1.0.11 → 1.1.2

package/README.md

@@ -4,6 +4,8 @@
 
 A production-ready library for generating, storing, rotating, and retrieving cryptographic keys with support for expiration, versioning, merge strategies, custom storage logic, and lifecycle hooks.
 
+**Key Rotation Manager** is a comprehensive Node.js library for secure cryptographic key management. It provides automatic key rotation, expiration handling, versioning, and flexible storage options. Perfect for API key management, token rotation, secret management, and credential handling in production applications.
+
 [![npm version](https://img.shields.io/npm/v/key-rotation-manager)](https://www.npmjs.com/package/key-rotation-manager)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -44,6 +46,8 @@ A production-ready library for generating, storing, rotating, and retrieving cry
 - 📡 **Event-Driven** - Lifecycle hooks for key events
 - 📁 **Git Integration** - Automatic `.gitignore` management
 - 🎯 **TypeScript** - Full TypeScript support with comprehensive types
+- ⚡ **Zero Dependencies** - Uses native Node.js crypto module
+- 🚀 **Production Ready** - Battle-tested for enterprise applications
 
 ---
 
@@ -55,6 +59,8 @@ npm install key-rotation-manager
 
 **Requirements:** Node.js >= 18.0.0
 
+**Package:** [npmjs.com/package/key-rotation-manager](https://www.npmjs.com/package/key-rotation-manager)
+
 ---
 
 ## 🚀 Quick Start
@@ -562,6 +568,7 @@ Retrieves a key by path and version.
 - `options`: `TGetKeyOptions`
   - `path`: `string` - Storage path
   - `version`: `string` - Key version
+  - `disableHooks?`: `boolean` - Skip hook execution (default: `false`)
   - `onRotate?`: Rotation options (if key is expired and rotatable)
 
 **Returns:** `Promise<TGetKey>`
@@ -577,8 +584,45 @@ const result = await keyManager.getKey({
     rotate: true,
   },
 });
+
+// With disabled hooks for performance
+const result = await keyManager.getKey({
+  path: '/keys/api',
+  version: 'v1',
+  disableHooks: true,
+});
+```
+
+### `verifyKey(hashedKey, path, version, disableGetKeyHooks?)`
+
+Verifies a hashed key against a stored key.
+
+**Parameters:**
+- `hashedKey`: `string` - The hashed key to verify
+- `path`: `string` - Storage path
+- `version`: `string | number` - Key version
+- `disableGetKeyHooks?`: `boolean` - Disable hooks in getKey call (default: `true`)
+
+**Returns:** `Promise<boolean>`
+
+**Example:**
+```typescript
+const isValid = await keyManager.verifyKey(hashedKey, '/keys/api', 'v1');
+if (isValid) {
+  console.log('Key is valid!');
+} else {
+  console.log('Key is invalid!');
+}
+
+// Verification with hooks enabled
+const isValid = await keyManager.verifyKey(hashedKey, '/keys/api', 'v1', false);
 ```
 
+**Notes:**
+- Uses PBKDF2 verification if the key has a `secret` field
+- Falls back to direct hash comparison otherwise
+- Verifies against expired keys if no ready key is available
+
 ### `useHooks(hooks)`
 
 Sets multiple hooks at once.
@@ -602,12 +646,16 @@ Sets a single hook.
 
 ## 🎯 Use Cases
 
-- **API Key Management** - Secure storage and rotation of API keys
-- **Token Rotation** - Automatic credential rotation for services
-- **Secret Management** - File-based secret storage with expiration
-- **Multi-Version Keys** - Support for multiple key versions simultaneously
-- **Custom Persistence** - Integrate with databases or cloud storage
-- **Backend Services** - Production-ready key management for Node.js applications
+- **API Key Management** - Secure storage and rotation of API keys for third-party services
+- **Token Rotation** - Automatic credential rotation for OAuth tokens, JWT secrets, and access tokens
+- **Secret Management** - File-based secret storage with expiration for application secrets
+- **Multi-Version Keys** - Support for multiple key versions simultaneously during rotation periods
+- **Custom Persistence** - Integrate with databases, cloud storage, or key management services
+- **Backend Services** - Production-ready key management for Node.js applications and microservices
+- **Encryption Keys** - Manage encryption keys for data protection with automatic rotation
+- **Session Keys** - Rotate session encryption keys periodically for enhanced security
+- **Database Credentials** - Rotate database passwords and connection strings securely
+- **Service-to-Service Authentication** - Manage keys for inter-service communication
 
 ---
 
@@ -615,7 +663,9 @@ Sets a single hook.
 
 See the full changelog for each version:
 
-- **[v1.0.10](./changelogs/1.0.10.md)** - Hooks system, enhanced gitIgnore configuration
+- **[v1.1.2](https://github.com/DucAnh2611/key-rotation-manager/tree/master/changelogs/1.1.2.md)** - Key verification, hook control, enhanced documentation
+- **[v1.1.1](https://github.com/DucAnh2611/key-rotation-manager/tree/master/changelogs/1.1.1.md)** - Native crypto, zero dependencies, bug fixes
+- **[v1.0.10](https://github.com/DucAnh2611/key-rotation-manager/tree/master/changelogs/1.0.10.md)** - Hooks system, enhanced gitIgnore configuration
 
 ---
 
@@ -648,7 +698,27 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/DucAnh2611/key-rotation-manager/blob/master/LICENSE) file for details.
+
+---
+
+## 🔍 Search Keywords
+
+This package is optimized for searches related to:
+- key rotation
+- key management
+- cryptographic key storage
+- API key rotation
+- secret rotation
+- credential management
+- token rotation
+- key versioning
+- automatic key rotation
+- secure key storage
+- Node.js key management
+- TypeScript key management
+- production key rotation
+- enterprise key management
 
 ---
 

package/dist/index.cjs

@@ -2,12 +2,11 @@
 
 var promises = require('fs/promises');
 var path = require('path');
-var CryptoJS = require('crypto-js');
+var crypto = require('crypto');
 var EventEmitter = require('events');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
-var CryptoJS__default = /*#__PURE__*/_interopDefault(CryptoJS);
 var EventEmitter__default = /*#__PURE__*/_interopDefault(EventEmitter);
 
 // src/constants/default.constant.ts
@@ -185,10 +184,13 @@ var isType = (data) => {
   return {
     number: typeof data === "number" && !Number.isNaN(Number(data)),
     string: typeof data === "string",
-    stringNumber: typeof data === "string" && !Number.isNaN(Number(data)) || typeof data === "number",
+    stringNumber: typeof data === "string" || typeof data === "number",
     boolean: typeof data === "boolean",
     null: data === null,
-    undefined: data === void 0
+    undefined: data === void 0,
+    optionalNumber: typeof data === "undefined" || typeof data === "number" && !Number.isNaN(Number(data)),
+    optionalString: typeof data === "undefined" || typeof data === "string",
+    optionalStringNumber: typeof data === "undefined" || typeof data === "string" || typeof data === "number"
   };
 };
 var CryptoService = class {
@@ -196,97 +198,77 @@ var CryptoService = class {
   constructor(options = {}) {
     this.options = { ...DEFAULT_CRYPTO_OPTIONS, ...options };
   }
-  generateRandomWordArray(length) {
-    return CryptoJS__default.default.lib.WordArray.random(length);
-  }
+  /**
+   * Generate random bytes and encode them
+   */
   generateRandom(length = 32) {
-    const wordArray = this.generateRandomWordArray(length);
-    return this.encode(wordArray);
+    const buffer = crypto.randomBytes(length);
+    return this.encodeBuffer(buffer);
   }
-  /*
+  /**
    * Generate a random key
-   * @param length Length of the key
+   * @param length Length of the key in bytes
    * @default cryptoOptions.keyLength
-   * @returns { key: string, length: number }
    */
   generateKey(length = this.options.keyLength) {
     return { key: this.generateRandom(length), length };
   }
-  /*
+  /**
    * Generate a random salt
-   * @param length Length of the salt
+   * @param length Length of the salt in bytes
    * @default cryptoOptions.saltLength
-   * @returns { salt: string, length: number }
    */
   generateSalt(length = this.options.saltLength) {
     return { salt: this.generateRandom(length), length };
   }
-  /*
+  /**
    * Generate a random IV
-   * @param length Length of the IV
+   * @param length Length of the IV in bytes
    * @default cryptoOptions.ivLength
-   * @returns { iv: string, length: number }
    */
   generateIV(length = this.options.ivLength) {
     return { iv: this.generateRandom(length), length };
   }
-  encode(wordArray) {
+  encodeBuffer(buffer) {
     switch (this.options.encoding) {
       case "hex":
-        return wordArray.toString(CryptoJS__default.default.enc.Hex);
+        return buffer.toString("hex");
       case "base64url":
-        return wordArray.toString(CryptoJS__default.default.enc.Base64).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+        return buffer.toString("base64url");
       case "base64":
       default:
-        return wordArray.toString(CryptoJS__default.default.enc.Base64);
+        return buffer.toString("base64");
     }
   }
-  decode(encoded) {
+  decodeToBuffer(encoded) {
     switch (this.options.encoding) {
       case "hex":
-        return CryptoJS__default.default.enc.Hex.parse(encoded);
+        return Buffer.from(encoded, "hex");
       case "base64url":
-        const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
-        const padding = "=".repeat((4 - base64.length % 4) % 4);
-        return CryptoJS__default.default.enc.Base64.parse(base64 + padding);
+        return Buffer.from(encoded, "base64url");
       case "base64":
       default:
-        return CryptoJS__default.default.enc.Base64.parse(encoded);
+        return Buffer.from(encoded, "base64");
     }
   }
   deriveKey(password, salt, keyLength) {
     if (this.options.kdf === "none") {
-      return CryptoJS__default.default.enc.Hex.parse(password);
+      return Buffer.from(password, "hex");
     }
     const actualKeyLength = keyLength ?? this.options.keyLength;
-    const keySize = actualKeyLength / 4;
-    return CryptoJS__default.default.PBKDF2(password, salt, {
-      keySize,
-      iterations: this.options.iterations,
-      hasher: this.getHasher()
-    });
-  }
-  getHasher() {
-    switch (this.options.hashAlgorithm) {
-      case "sha512":
-        return CryptoJS__default.default.algo.SHA512;
-      case "sha384":
-        return CryptoJS__default.default.algo.SHA384;
-      case "sha256":
-      default:
-        return CryptoJS__default.default.algo.SHA256;
-    }
-  }
-  getAESMode() {
-    return CryptoJS__default.default.mode.CBC;
-  }
-  getPadding() {
-    return CryptoJS__default.default.pad.Pkcs7;
+    return crypto.pbkdf2Sync(
+      password,
+      salt,
+      this.options.iterations,
+      actualKeyLength,
+      this.options.hashAlgorithm
+    );
   }
   /**
-   * Encrypt data
+   * Encrypt data using AES-CBC
    * @param plainText Text to encrypt
-   * @param secret Secret key for encryption Key length, salt, and IV will be randomly generated within configured range
+   * @param secret Secret key for encryption
+   * @param options Optional lengths for key, salt, and IV
    */
   encrypt(plainText, secret, {
     keyLength,
@@ -296,61 +278,48 @@ var CryptoService = class {
     keyLength = keyLength ?? this.options.keyLength;
     saltLength = saltLength ?? this.options.saltLength;
     ivLength = ivLength ?? this.options.ivLength;
-    const salt = this.options.kdf !== "none" ? this.generateRandomWordArray(saltLength) : CryptoJS__default.default.lib.WordArray.create();
-    const iv = this.generateRandomWordArray(ivLength);
+    const salt = this.options.kdf !== "none" ? crypto.randomBytes(saltLength) : Buffer.alloc(0);
+    const iv = crypto.randomBytes(ivLength);
     const key = this.deriveKey(secret, salt, keyLength);
-    const encrypted = CryptoJS__default.default.AES.encrypt(plainText, key, {
-      iv,
-      mode: this.getAESMode(),
-      padding: this.getPadding()
-    });
-    const actualSaltLength = salt.sigBytes;
-    const keyLengthHex = keyLength.toString(16).padStart(4, "0");
-    const saltLengthHex = actualSaltLength.toString(16).padStart(4, "0");
-    const ivLengthHex = ivLength.toString(16).padStart(4, "0");
-    const saltHex = salt.toString(CryptoJS__default.default.enc.Hex);
-    const ivHex = iv.toString(CryptoJS__default.default.enc.Hex);
-    const encryptedHex = encrypted.ciphertext.toString(CryptoJS__default.default.enc.Hex);
-    const combined = keyLengthHex + saltLengthHex + ivLengthHex + saltHex + ivHex + encryptedHex;
-    return this.encode(CryptoJS__default.default.enc.Hex.parse(combined));
+    const cipher = crypto.createCipheriv(this.options.algorithm, key, iv);
+    const encrypted = Buffer.concat([cipher.update(plainText, "utf8"), cipher.final()]);
+    const keyLengthBuf = Buffer.alloc(2);
+    keyLengthBuf.writeUInt16BE(keyLength);
+    const saltLengthBuf = Buffer.alloc(2);
+    saltLengthBuf.writeUInt16BE(salt.length);
+    const ivLengthBuf = Buffer.alloc(2);
+    ivLengthBuf.writeUInt16BE(ivLength);
+    const combined = Buffer.concat([keyLengthBuf, saltLengthBuf, ivLengthBuf, salt, iv, encrypted]);
+    return this.encodeBuffer(combined);
   }
   /**
    * Decrypt data
    * @param encryptedData Encrypted data to decrypt
    * @param secret Secret key for decryption
+   * @returns Decrypted string, or empty string if decryption fails (wrong password/corrupted data)
    */
   decrypt(encryptedData, secret) {
-    const combined = this.decode(encryptedData);
-    const combinedHex = combined.toString(CryptoJS__default.default.enc.Hex);
-    let offset = 0;
-    const keyLengthHex = combinedHex.substring(offset, offset + 4);
-    offset += 4;
-    const saltLengthHex = combinedHex.substring(offset, offset + 4);
-    offset += 4;
-    const ivLengthHex = combinedHex.substring(offset, offset + 4);
-    offset += 4;
-    const keyLength = parseInt(keyLengthHex, 16);
-    const saltLength = parseInt(saltLengthHex, 16);
-    const ivLength = parseInt(ivLengthHex, 16);
-    const saltHexLength = saltLength * 2;
-    const ivHexLength = ivLength * 2;
-    const saltHex = saltHexLength > 0 ? combinedHex.substring(offset, offset + saltHexLength) : "";
-    offset += saltHexLength;
-    const ivHex = combinedHex.substring(offset, offset + ivHexLength);
-    offset += ivHexLength;
-    const encryptedHex = combinedHex.substring(offset);
-    const salt = saltHex ? CryptoJS__default.default.enc.Hex.parse(saltHex) : CryptoJS__default.default.lib.WordArray.create();
-    const iv = CryptoJS__default.default.enc.Hex.parse(ivHex);
-    const encrypted = CryptoJS__default.default.lib.CipherParams.create({
-      ciphertext: CryptoJS__default.default.enc.Hex.parse(encryptedHex)
-    });
-    const key = this.deriveKey(secret, salt, keyLength);
-    const decrypted = CryptoJS__default.default.AES.decrypt(encrypted, key, {
-      iv,
-      mode: this.getAESMode(),
-      padding: this.getPadding()
-    });
-    return decrypted.toString(CryptoJS__default.default.enc.Utf8);
+    try {
+      const combined = this.decodeToBuffer(encryptedData);
+      let offset = 0;
+      const keyLength = combined.readUInt16BE(offset);
+      offset += 2;
+      const saltLength = combined.readUInt16BE(offset);
+      offset += 2;
+      const ivLength = combined.readUInt16BE(offset);
+      offset += 2;
+      const salt = combined.subarray(offset, offset + saltLength);
+      offset += saltLength;
+      const iv = combined.subarray(offset, offset + ivLength);
+      offset += ivLength;
+      const encrypted = combined.subarray(offset);
+      const key = this.deriveKey(secret, salt, keyLength);
+      const decipher = crypto.createDecipheriv(this.options.algorithm, key, iv);
+      const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+      return decrypted.toString("utf8");
+    } catch {
+      return "";
+    }
   }
   /**
    * Hash data (one-way)
@@ -359,19 +328,17 @@ var CryptoService = class {
    * @param salt Optional encoded salt string for deterministic hashing
    */
   hash(data, secret, salt) {
-    const secretWordArray = CryptoJS__default.default.enc.Utf8.parse(secret);
-    const hasher = this.getHasher();
-    let saltWordArray;
+    let saltBuffer;
     let saltStr;
     if (salt) {
-      saltWordArray = this.decode(salt);
+      saltBuffer = this.decodeToBuffer(salt);
       saltStr = salt;
     } else {
-      saltWordArray = this.generateRandomWordArray(this.options.saltLength);
-      saltStr = this.encode(saltWordArray);
+      saltBuffer = crypto.randomBytes(this.options.saltLength);
+      saltStr = this.encodeBuffer(saltBuffer);
     }
-    const hash = hasher.create().update(data).update(secretWordArray).update(saltWordArray).finalize();
-    const hashStr = this.encode(hash);
+    const hash = crypto.createHash(this.options.hashAlgorithm).update(data).update(secret).update(saltBuffer).digest();
+    const hashStr = this.encodeBuffer(hash);
     return `${saltStr}:${hashStr}`;
   }
   /**
@@ -385,11 +352,9 @@ var CryptoService = class {
     if (!saltStr || !expectedHashStr) {
       return false;
     }
-    const salt = this.decode(saltStr);
-    const secretWordArray = CryptoJS__default.default.enc.Utf8.parse(secret);
-    const hasher = this.getHasher();
-    const hash = hasher.create().update(data).update(secretWordArray).update(salt).finalize();
-    const hashStr = this.encode(hash);
+    const saltBuffer = this.decodeToBuffer(saltStr);
+    const hash = crypto.createHash(this.options.hashAlgorithm).update(data).update(secret).update(saltBuffer).digest();
+    const hashStr = this.encodeBuffer(hash);
     return hashStr === expectedHashStr;
   }
 };
@@ -676,33 +641,33 @@ var KeyManager = class extends Store {
     const { path, version } = options;
     const key = await this.getKeyByStore(path, String(version));
     if (!key) {
-      this.runKeyHook("onKeyNotFound", path, version);
+      if (!options.disableHooks) this.runKeyHook("onKeyNotFound", path, version);
       this.sysLog(`Key not found!`, { path, version });
       return { expired: null, ready: null };
     }
     const { ok, message, isExpired, isRenewable, errorOn } = this.validateKey(key);
     if (!ok && isExpired && isRenewable && key) {
       if (!options.onRotate) {
-        this.runKeyHook("onKeyMissingRotateOption", key, options);
+        if (!options.disableHooks) this.runKeyHook("onKeyMissingRotateOption", key, options);
         this.sysLog(`Key missing rotate option!`, { path, version });
-        return { expired: null, ready: null };
+        return { expired: key, ready: null };
       }
       const renew = await this.newKey({
         type: key.type,
         ...options.onRotate
       });
       const resGetKey = { expired: key, ready: renew.key };
-      this.runKeyHook("onKeyRenewed", resGetKey, options);
+      if (!options.disableHooks) this.runKeyHook("onKeyRenewed", resGetKey, options);
       this.sysLog(`Key renewed!`, { path, version });
       return resGetKey;
     }
     if (!ok && isExpired && !isRenewable && key) {
-      this.runKeyHook("onKeyExpired", path, key);
+      if (!options.disableHooks) this.runKeyHook("onKeyExpired", path, key);
       this.sysLog(`Key expired!`, { path, version });
       return { expired: key, ready: null };
     }
     if (!ok) {
-      this.runKeyHook("onKeyInvalid", key, message, errorOn);
+      if (!options.disableHooks) this.runKeyHook("onKeyInvalid", key, message, errorOn);
       this.sysLog(`Key invalid!`, { path, version });
       return { expired: null, ready: null };
     }
@@ -748,15 +713,16 @@ var KeyManager = class extends Store {
   async newKey(options, variables = {}) {
     const { rotate, duration, type, unit, merge, keyLength } = options;
     const { key, length: kLength } = this.cryptoService.generateKey(keyLength);
-    const { salt } = this.cryptoService.generateSalt();
+    const { salt: secret } = this.cryptoService.generateSalt();
     this.sysLog(`Key generated
 Options:`, options);
-    const hashedKey = this.cryptoService.hash(key, salt);
+    const hashedKey = this.cryptoService.hash(key, secret);
     const now = /* @__PURE__ */ new Date();
     const keyGenerated = {
       from: now.toISOString(),
       to: duration && unit ? addDuration(now, duration, unit).toISOString() : "NON_EXPIRED",
       key,
+      secret,
       hashed: hashedKey,
       hashedBytes: kLength,
       type,
@@ -771,6 +737,49 @@ Options:`, options);
     });
     return { key: keyGenerated, path };
   }
+  /**
+   * Verify a key by hashed key and path and version
+   * @param hashedKey Hashed key to verify
+   * @param path Path to the key
+   * @param version Version of the key
+   * @param disableGetKeyHooks Disable getKey method hooks, should not use hooks in this method
+   * @returns True if the key is valid, false otherwise
+   * 
+   * @example
+   * ```ts
+   * const isValid = await keyManager.verifyKey(hashedKey, path, version);
+   * if (isValid) {
+   *   console.log('Key is valid!');
+   * } else {
+   *   console.log('Key is invalid!');
+   * }
+   * ```
+   * 
+   * @note
+   * 1. This use getKey method to get key, so disableGetKeyHooks option is set to true, if disableGetKeyHooks is not provided, it will be set to true 
+   * 
+   * 2. Get key from store
+   * - If the key is expired, the expired key will be used to verify the key
+   * - If the key is not expired, the ready key will be used to verify the key
+   * 
+   * 3. If the key is not found, the function will return false
+   * 
+   * 4. Verify key strategy
+   * - If the key is found and secret is provided, compare original key with hashed key using secret
+   * - If the key is found and secret is not provided, compare original key with hashed key
+   * 
+   */
+  async verifyKey(hashedKey, path, version, disableGetKeyHooks = true) {
+    const { ready, expired } = await this.getKey({ path, version: String(version), disableHooks: disableGetKeyHooks });
+    if (!ready && !expired) {
+      this.sysLog(`Key not found to verify!`, { path, version });
+      return false;
+    }
+    const key = expired ?? ready;
+    this.sysLog("Verifying key...", { hashedKey, path, version, validateMethod: key.secret ? "verifyHash(key, hashedKey, secret)" : "hashedKey === key.hashed" });
+    if (key.secret) return this.cryptoService.verifyHash(key.key, hashedKey, key.secret);
+    return hashedKey === key.hashed;
+  }
   async getKeyByStore(path, version) {
     if (this.getKeyFn) {
       return this.getKeyFn(path, version);
@@ -795,7 +804,8 @@ Options:`, options);
       rotate: "boolean",
       type: "string",
       version: "stringNumber",
-      hashedBytes: "number"
+      hashedBytes: "number",
+      secret: "optionalString"
     };
     for (const [field, type] of Object.entries(typeChecks)) {
       if (!isType(requiredKeyGenerated[field])[type])