key-rotation-manager 1.0.7 → 1.0.10

package/README.md

@@ -1,99 +1,107 @@
-# Rotate Key
+# 🔐 Key Rotation Manager
 
-Flexible, file-based key management for Node.js.  
-It helps you **generate, store, rotate, and retrieve cryptographic keys** with support for expiration, versioning, merge strategies, custom storage logic, and lifecycle events.
+> **Flexible, file-based cryptographic key management for Node.js**
 
-This library is designed for backend systems that need safe, extensible, and transparent key handling.
+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.
 
----
+[![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)
 
-## Issues & Bug Reports
+---
 
-Found a bug or have a feature request?
-
-**[🐛 Report an Issue](https://github.com/DucAnh2611/key-rotation-manager/issues/new)**
-
-Please include:
-- A clear description of the issue
-- Steps to reproduce
-- Expected vs actual behavior
-- Your environment (Node.js version, OS, package version)
-- Code samples if applicable
+## 📋 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Configuration](#-configuration)
+- [Core Concepts](#-core-concepts)
+  - [Creating Keys](#creating-keys)
+  - [Retrieving Keys](#retrieving-keys)
+  - [Key Rotation](#key-rotation)
+- [Advanced Usage](#-advanced-usage)
+  - [Custom Storage Logic](#custom-storage-logic)
+  - [Custom Path & File Naming](#custom-path--file-naming)
+  - [Hooks & Lifecycle Events](#hooks--lifecycle-events)
+  - [Logging](#logging)
+  - [Instance Cloning](#instance-cloning)
+- [API Reference](#-api-reference)
+- [Use Cases](#-use-cases)
+- [Changelog](#-changelog)
+- [Contributing](#-contributing)
+- [License](#-license)
 
 ---
 
-## Features
+## ✨ Features
 
-- 🔐 Secure key generation (AES-256-GCM by default)
-- 🔄 Key expiration & rotation
-- 🗂 File-based storage with configurable structure
-- 🧩 Merge & non-merge key strategies
-- 🔧 Custom save & get hooks
-- 📡 Event-driven lifecycle
-- 📁 Automatic `.gitignore` integration
+- 🔐 **Secure Key Generation** - AES-256-CBC encryption with PBKDF2 key derivation
+- 🔄 **Automatic Rotation** - Built-in expiration and rotation support
+- 🗂 **Flexible Storage** - File-based storage with configurable structure
+- 🧩 **Merge Strategies** - Support for single-file or multi-file key storage
+- 🔧 **Extensible** - Custom save/get hooks and storage logic
+- 📡 **Event-Driven** - Lifecycle hooks for key events
+- 📁 **Git Integration** - Automatic `.gitignore` management
+- 🎯 **TypeScript** - Full TypeScript support with comprehensive types
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install key-rotation-manager
 ```
 
+**Requirements:** Node.js >= 18.0.0
+
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
 ```typescript
-import { create, km } from 'key-rotation-manager';
+import { create } from 'key-rotation-manager';
 
-const keyManager = create({});
-// or 
-const keyManager = km({});
+// Initialize key manager
+const keyManager = create();
 
+// Generate a new key
 const { key, path } = await keyManager.newKey({
   type: 'api',
-  ...options
+  duration: 30,
+  unit: 'days',
+  rotate: true,
 });
-```
-
-This will:
-- Create a `keys/` directory base on `{{path}}/{{filename}}.{{fileExt}}`
-- Generate a new key
-- Save it using default storage rules
-
----
 
-## Basic Usage
+console.log('Key generated:', key.key);
+console.log('Storage path:', path);
 
-### Initialize KeyManager
-
-```typescript
-import { create, km } from 'key-rotation-manager';
-
-const keyManager = create();
-// or 
-const keyManager = km();
+// Retrieve the key
+const result = await keyManager.getKey({
+  path,
+  version: key.version,
+});
 ```
 
-On initialization:
-- The key storage folder is created
-- `.gitignore` is updated (if enabled)
-- A store initialization event is emitted
+---
+
+## ⚙️ Configuration
 
-### Default Configuration
+### Default Options
 
 ```typescript
 {
-  path: ['keys'],
-  file: ['{{type}}', 'v', '{{version}}'],
-  fileSplitor: '_',
-  fileExt: 'json',
-  gitIgnore: true, // add resolved path to .gitignore
-
+  // Storage configuration
+  path: ['keys', '{{type}}'],        // Directory structure (supports variables)
+  file: ['v', '{{version}}'],        // File naming pattern
+  fileSplitor: '_',                  // File name separator
+  fileExt: 'json',                   // File extension
+  gitIgnore: true,          // Auto-update .gitignore (boolean | string | string[])
+
+  // Cryptographic settings
   crypto: {
-    algorithm: 'aes-256-gcm',
-    kdf: 'scrypt',
+    algorithm: 'aes-256-cbc',
+    kdf: 'pbkdf2',
     hashAlgorithm: 'sha256',
     keyLength: 32,
     ivLength: 16,
@@ -103,6 +111,7 @@ On initialization:
     encoding: 'base64',
   },
 
+  // Version generation
   versionGenerator: () => Date.now().toString()
 }
 ```
@@ -113,222 +122,534 @@ With default settings, keys are stored as:
 
 ```
 keys/
-└── api_v_1700000000000.json
+└── {{type}}/
+    └── v_{{version}}.json
+```
+
+**Example:** `keys/api/v_1704067200000.json`
+
+### Git Ignore Configuration
+
+The `gitIgnore` option controls how the key storage folder is added to `.gitignore`.
+
+**Type:** `boolean | string | string[]`
+
+| Value | Behavior |
+|-------|----------|
+| `false` | Disable auto-update `.gitignore` |
+| `true` | Uses `path + file + fileExt` pattern |
+| `string \| string[]` | Uses custom path pattern |
+
+**Default:** `true` → adds `path + file + fileExt` to `.gitignore`
+
+**Variable Replacement:** Any `{{variable}}` in the path will be replaced with `*` in `.gitignore`.
+
+**Wildcard Support:** You can use `'*'` directly in the path array for explicit wildcard matching.
+
+**Examples:**
+
+```typescript
+// Disable gitignore management
+const km1 = create({ gitIgnore: false });
+
+// Use full path pattern (path + file + fileExt)
+const km2 = create({ gitIgnore: true });
+// .gitignore: keys/{{type}}/v_{{version}}.json → keys/*/v_*.json
+
+// Custom folder with wildcard (default)
+const km3 = create({ gitIgnore: ['keys', '*'] });
+// .gitignore: keys/*
+
+// Custom path with variables
+const km4 = create({ gitIgnore: ['secrets', '{{env}}', 'keys'] });
+// .gitignore: secrets/*/keys
+
+// Custom path with explicit wildcard
+const km5 = create({ gitIgnore: ['keys', '{{type}}', '*'] });
+// .gitignore: keys/*/*
+
+// Simple string
+const km6 = create({ gitIgnore: 'keys' });
+// .gitignore: keys
 ```
 
 ---
 
-## Creating Keys
+## 📚 Core Concepts
+
+### Creating Keys
 
-### 1. Non-expiring Key
+#### 1. Non-Expiring Key
 
 ```typescript
-const { key } = await km.newKey({
+const { key, path } = await keyManager.newKey({
   type: 'service',
 });
 ```
 
-### 2. Expiring / Rotating Key
+#### 2. Expiring Key with Rotation
 
 ```typescript
-const { key } = await km.newKey({
-  type: 'service',
+const { key, path } = await keyManager.newKey({
+  type: 'api',
   duration: 30,
-  unit: 'seconds',
-  rotate: true,
+  unit: 'days',      // 'seconds' | 'minutes' | 'hours' | 'days'
+  rotate: true,      // Enable automatic rotation
 });
 ```
 
-The key expires after 30 seconds and requires rotation.
+#### 3. Merge Strategy (Single File)
 
-### 3. Merge Strategy
-
-Merge mode stores multiple key versions in a single file.
+Store multiple key versions in a single file:
 
 ```typescript
-const { key } = await keyManager.newKey({
+const { key, path } = await keyManager.newKey({
   type: 'service',
-  duration: 30,
-  unit: 'seconds',
+  merge: true,       // Store all versions in one file
+  duration: 7,
+  unit: 'days',
   rotate: true,
-  merge: true, // Merge into 1 file {{path}}/{filename}
 });
 ```
 
----
+### Retrieving Keys
 
-## Custom Path & File Naming
+#### Basic Retrieval
 
 ```typescript
-import { create } from 'key-rotation-manager';
+const result = await keyManager.getKey({
+  path: '/path/to/key/file',
+  version: 'v1',
+});
 
-const keyManager = create({
-  path: ['keys', 'custom'],
-  file: '{{type}}',
-  fileExt: 'txt',
-  ...options,
+// Result structure
+{
+  ready: TKeyGenerated | null,    // Valid, usable key
+  expired: TKeyGenerated | null   // Expired key (if rotation occurred)
+}
+```
+
+#### Key Rotation
+
+When a key is expired and rotatable, provide rotation options:
+
+```typescript
+const result = await keyManager.getKey({
+  path: '/path/to/key/file',
+  version: 'v1',
+  onRotate: {
+    duration: 30,
+    unit: 'days',
+    rotate: true,
+    merge: true,      // Optional: merge strategy for new key
+  },
 });
+
+if (result.expired) {
+  console.log('Key was rotated');
+  console.log('Old version:', result.expired.version);
+  console.log('New version:', result.ready?.version);
+}
 ```
 
-Resulting structure:
+#### Handling Missing Keys
 
+```typescript
+const result = await keyManager.getKey({
+  path: '/path/to/key/file',
+  version: 'v1',
+});
+
+if (!result.ready) {
+  // Key not found or invalid
+  console.log('Key unavailable');
+}
 ```
-keys/custom/service.txt
 
->> .gitignore
-keys/custom/*
+### Key Rotation
+
+Key rotation occurs automatically when:
+
+1. A key is expired (`to` date has passed)
+2. The key has `rotate: true`
+3. `onRotate` options are provided in `getKey()`
+
+**Rotation Flow:**
+
+```
+Expired Key → Check rotate flag → Generate new key → Return both keys
 ```
 
 ---
 
-## Custom Save Logic
+## 🔧 Advanced Usage
 
-Override how and where keys are saved:
+### Custom Storage Logic
+
+#### Custom Get Logic
+
+Override how keys are retrieved:
 
 ```typescript
-keyManager.useSaveKey(async () => {
-  return '/absolute/custom/path/key.json';
+keyManager.useGetKey(async (path, version) => {
+  // Your custom retrieval logic
+  const data = await fetchFromDatabase(path, version);
+  
+  if (!data) return null;
+  
+  return {
+    from: data.createdAt,
+    to: data.expiresAt,
+    key: data.rawKey,
+    hashed: data.hashedKey,
+    hashedBytes: 32,
+    type: data.type,
+    version: data.version,
+    rotate: data.rotate,
+  };
 });
 ```
 
-The returned value becomes `key.path`.
+#### Custom Save Logic
 
----
+Override how keys are saved:
+
+```typescript
+keyManager.useSaveKey(async (keyData, options) => {
+  // Your custom save logic
+  const savedPath = await saveToDatabase(keyData);
+  return savedPath; // This becomes key.path
+});
+```
 
-## Retrieving Keys
+### Custom Path & File Naming
 
-### Rotate Key (Valid)
+Use variables in path and file names:
 
 ```typescript
-const result = await keyManager.getKey({
-  path: 'keys/service_merge.json',
-  version: 'rotate',
-  onRotate: {
-    duration: 30,
-    unit: 'seconds',
-    rotate: true,
-    merge: true,
+const keyManager = create({
+  path: ['keys', '{{type}}', '{{env}}'],
+  file: ['{{version}}', '{{region}}'],
+  fileExt: 'json',
+});
+
+const { key, path } = await keyManager.newKey(
+  {
+    type: 'api',
+  },
+  {
+    env: 'production',
+    region: 'us-east-1',
+  }
+);
+
+// Result: keys/api/production/1704067200000_us-east-1.json
+```
+
+**Available Variables:**
+- `{{type}}` - Key type
+- `{{version}}` - Key version
+- Any custom variables passed to `newKey()`
+
+### Hooks & Lifecycle Events
+
+> **Available since v1.0.10**
+
+Hooks allow you to execute custom logic when specific key lifecycle events occur.
+
+#### Available Hooks
+
+**Key Manager Hooks:**
+
+| Hook | Description | Parameters |
+|------|-------------|------------|
+| `onKeyNotFound` | Fires when key file is not found or version doesn't exist | `(path: string, version: string \| number)` |
+| `onKeyInvalid` | Fires when key validation fails | `(key: TKeyGenerated, message: string, errorOn?: keyof TKeyGenerated)` |
+| `onKeyMissingRotateOption` | Fires when expired key needs rotation but options are missing | `(key: TKeyGenerated, options: TGetKeyOptions)` |
+| `onKeyRenewed` | Fires when a key is successfully rotated | `(getKey: TGetKey, options: TGetKeyOptions)` |
+| `onKeyExpired` | Fires when a key expires but is not renewable | `(path: string, key: TKeyGenerated)` |
+
+**Base Hooks:**
+
+| Hook | Description | Parameters |
+|------|-------------|------------|
+| `onHookNotFound` | Fires when a hook is called but not registered | `(name: string)` |
+| `onHookOverriding` | Fires when a hook is being overridden | `(name: string)` |
+
+#### Setting Hooks
+
+**Set Multiple Hooks:**
+
+```typescript
+keyManager.useHooks({
+  onKeyNotFound: (path, version) => {
+    console.log(`Key not found: ${path}@${version}`);
+  },
+  onKeyInvalid: (key, message, errorOn) => {
+    console.error(`Invalid key: ${message}`, { errorOn, key });
+  },
+  onKeyRenewed: (getKey, options) => {
+    console.log('Key renewed:', {
+      expired: getKey.expired?.version,
+      ready: getKey.ready?.version,
+    });
   },
 });
 ```
 
-Returned structure:
+**Set Single Hook:**
 
 ```typescript
-{
-  ready: Key | null,
-  expired: Key | null
-}
+keyManager.setHook('onKeyRenewed', (getKey, options) => {
+  console.log('Key was renewed successfully');
+});
 ```
 
-- `ready` → usable key
-- `expired` → expired key (if rotation occurred)
+**Async Hooks:**
+
+```typescript
+keyManager.setHook('onKeyRenewed', async (getKey, options) => {
+  await sendNotification({
+    message: 'Key was rotated',
+    expiredVersion: getKey.expired?.version,
+    newVersion: getKey.ready?.version,
+  });
+});
 
-### Rotate Key (Invalid – Missing Options)
+keyManager.setHook('onKeyInvalid', async (key, message, errorOn) => {
+  await logToDatabase({
+    event: 'key_invalid',
+    message,
+    errorOn,
+    keyVersion: key.version,
+  });
+});
+```
+
+#### Complete Hook Example
 
 ```typescript
-await keyManager.getKey({
-  path: 'keys/service_merge.json',
-  version: 'rotate-invalid',
+import { create } from 'key-rotation-manager';
+
+const keyManager = create({
+  versionGenerator: () => 'v1',
+});
+
+// Configure all hooks
+keyManager.useHooks({
+  onKeyNotFound: (path, version) => {
+    console.log(`[Hook] Key not found: ${path}@${version}`);
+  },
+  onKeyInvalid: (key, message, errorOn) => {
+    console.error(`[Hook] Invalid key: ${message}`, {
+      version: key.version,
+      errorOn,
+    });
+  },
+  onKeyRenewed: async (getKey, options) => {
+    console.log('[Hook] Key renewed:', {
+      from: getKey.expired?.version,
+      to: getKey.ready?.version,
+    });
+    // Perform async operations (notifications, logging, etc.)
+  },
+  onKeyMissingRotateOption: (key, options) => {
+    console.warn(`[Hook] Missing rotate option for key: ${key.version}`);
+  },
+  onKeyExpired: (path, key) => {
+    console.log(`[Hook] Key expired: ${path}@${key.version}`);
+  },
+});
+
+// Use the key manager
+const result = await keyManager.getKey({
+  path: '/keys/api',
+  version: 'v1',
 });
 ```
 
-Throws:
+### Logging
+
+#### Custom Logger
 
+```typescript
+// Synchronous logger
+keyManager.setLogger((...args) => {
+  console.log('[KeyManager]', ...args);
+});
+
+// Async logger
+keyManager.setLogger(async (...args) => {
+  await logToService(...args);
+});
 ```
-Expired rotate options not provided
+
+#### System Logging
+
+```typescript
+await keyManager.sysLog('Key operation completed');
 ```
 
-### Non-Rotating Key
+#### Custom Logging
 
 ```typescript
-const result = await keyManager.getKey({
-  path: 'path (full path return from km.newKey)',
-  version: 'version',
+await keyManager.customLog(async (...args) => {
+  await customLoggingService.log(...args);
+}, 'Log message');
+```
+
+### Instance Cloning
+
+Create a new instance with shared configuration:
+
+```typescript
+const original = create({ versionGenerator: () => 'v1' });
+
+// Clone with additional options
+const cloned = original.clone({
+  path: ['custom', 'keys'],
 });
+
+// Cloned instance includes:
+// - Custom save/get hooks
+// - Store path configuration
+// - Logger settings
+// - Hooks settings
 ```
 
 ---
 
-## Custom Get Logic
+## 📖 API Reference
 
-Override how keys are retrieved:
+### `create(options?, only?)`
+
+Creates a new KeyManager instance.
+
+**Parameters:**
+- `options` (optional): Partial `TModuleOptions`
+- `only` (optional): `boolean` - If `false`, returns a singleton instance
+
+**Returns:** `KM` instance
 
+**Example:**
 ```typescript
-keyManager.useGetKey(async () => {
-  return {
-    from: '2025-12-29T01:23:27.882Z',
-    to: '2099-12-29T01:23:57.882Z',
-    key: '...',
-    hashed: '...',
-    type: 'service',
-    version: 'version',
+const km = create({ versionGenerator: () => 'v1' });
+// or
+const km = create({}, false); // Singleton instance
+```
+
+### `newKey(options, variables?)`
+
+Generates a new cryptographic key.
+
+**Parameters:**
+- `options`: `TGenerateKeyOptions`
+  - `type`: `string` - Key type identifier
+  - `duration?`: `number` - Expiration duration
+  - `unit?`: `'seconds' | 'minutes' | 'hours' | 'days'` - Time unit
+  - `rotate?`: `boolean` - Enable rotation
+  - `merge?`: `boolean` - Merge strategy
+  - `keyLength?`: `number` - Key length in bytes
+- `variables?`: `TKeyVariables` - Custom variables for path/file naming
+
+**Returns:** `Promise<{ key: TKeyGenerated, path: string }>`
+
+### `getKey(options)`
+
+Retrieves a key by path and version.
+
+**Parameters:**
+- `options`: `TGetKeyOptions`
+  - `path`: `string` - Storage path
+  - `version`: `string` - Key version
+  - `onRotate?`: Rotation options (if key is expired and rotatable)
+
+**Returns:** `Promise<TGetKey>`
+
+**Example:**
+```typescript
+const result = await keyManager.getKey({
+  path: '/keys/api',
+  version: 'v1',
+  onRotate: {
+    duration: 30,
+    unit: 'days',
     rotate: true,
-  };
+  },
 });
 ```
 
-Return `null` to indicate an invalid or missing key.
+### `useHooks(hooks)`
 
-## Custom logger
+Sets multiple hooks at once.
 
-Override how logger work
+**Parameters:**
+- `hooks`: `Partial<TModuleHooks>`
 
-```typescript 
-km.setLogger((...args: unknown[]) => console.log(...args))
-// or Async
-km.setLogger(async (...args: unknown[]) => console.log(...args))
+**Returns:** `this` (chainable)
 
-km.sysLog(...args);
-km.customLog(async (...args: unknown[]) => console.log(...args))
-```
+### `setHook(name, handler)`
 
-## Clone instance
+Sets a single hook.
 
-Clone instance to new instance include custom saveKey, getKey and storePath
+**Parameters:**
+- `name`: `keyof TModuleHooks`
+- `handler`: `TModuleHooks[K]`
 
-```typescript 
-const k = km();
-const k2 = k.clone(options);
-```
+**Returns:** `this` (chainable)
 
 ---
 
-## Events
+## 🎯 Use Cases
 
-KeyManager emits lifecycle events.
+- **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
 
-### Store Initialization Event
+---
 
-```typescript
-import { create, types } from 'rotate-key';
-const { EEvent } = types;
-const keyManager = create({});
+## 📝 Changelog
 
-keyManager.once(EEvent.STORE_INIT_FOLDER, ({ storePath }) => {
-  console.log('Key store initialized at:', storePath);
-});
-```
+See the full changelog for each version:
+
+- **[v1.0.10](./changelogs/1.0.10.md)** - Hooks system, enhanced gitIgnore configuration
 
 ---
 
-## Use Cases
+## 🐛 Issues & Bug Reports
 
-- API key management
-- Token & credential rotation
-- Secure file-based secrets
-- Multi-version key handling
-- Custom persistence strategies
-- Backend Node.js services
+Found a bug or have a feature request?
+
+**[🐛 Report an Issue](https://github.com/DucAnh2611/key-rotation-manager/issues/new)**
+
+Please include:
+- Clear description of the issue
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details (Node.js version, OS, package version)
+- Code samples if applicable
 
 ---
 
-## Contributing
+## 🤝 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
 ---
 
-## License
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
 
-MIT
+**Made with ❤️ for secure key management**