@kibibit/configit 1.0.0-beta.25 → 1.0.0-beta.27

package/src/vault/vault-cache.ts

@@ -0,0 +1,240 @@
+/**
+ * VaultCache
+ * In-memory cache for Vault secrets with TTL management
+ */
+
+import nconf from 'nconf';
+
+import { IVaultSecret, VaultCacheEntry, VaultPropertyMetadata } from './types';
+
+/**
+ * VaultCache - Manages in-memory cache of Vault secrets
+ */
+export class VaultCache {
+  private cache: Map<string, VaultCacheEntry> = new Map();
+  private propertyToPath: Map<string, string> = new Map();
+  private pathToProperties: Map<string, Set<string>> = new Map();
+
+  /**
+   * Get cached value for a property
+   * @returns The cached value or null if not found/expired
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  get(propertyName: string): any | null {
+    const entry = this.cache.get(propertyName);
+    if (!entry) {
+      return null;
+    }
+
+    // Check if expired
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(propertyName);
+      return null;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Set cached value for a property
+   */
+  set(
+    propertyName: string,
+    vaultPath: string,
+    secret: IVaultSecret,
+    metadata: VaultPropertyMetadata
+  ): void {
+    // Extract value based on engine type
+    const value = this.extractValue(secret, metadata);
+
+    // Calculate expiration times
+    const now = Date.now();
+    const leaseDurationMs = secret.leaseDuration * 1000;
+    // Default 1 hour if no TTL
+    const expiresAt = secret.leaseDuration > 0 ? now + leaseDurationMs : now + 3600000;
+
+    // Calculate refresh time (refresh buffer)
+    // metadata.refreshBuffer is in SECONDS, we need milliseconds
+    // Default: min(10% of TTL, 5 minutes)
+    const defaultBufferMs = Math.min(leaseDurationMs * 0.1, 300000);
+    const refreshBufferMs = metadata.refreshBuffer ? metadata.refreshBuffer * 1000 : defaultBufferMs;
+    const refreshAt = secret.leaseDuration > 0 ? expiresAt - refreshBufferMs : expiresAt;
+
+    const entry: VaultCacheEntry = {
+      value,
+      secret,
+      cachedAt: now,
+      expiresAt,
+      refreshAt,
+      propertyName,
+      vaultPath
+    };
+
+    this.cache.set(propertyName, entry);
+
+    // Update mappings
+    this.propertyToPath.set(propertyName, vaultPath);
+
+    const properties = this.pathToProperties.get(vaultPath) || new Set();
+    properties.add(propertyName);
+    this.pathToProperties.set(vaultPath, properties);
+
+    // Inject into nconf overrides (highest priority)
+    // Merge with existing overrides to avoid overwriting other secrets
+    // Access the overrides store directly to get current values
+    const overridesStore = (nconf as any).stores?.overrides;
+    const existingOverrides = overridesStore?.store || {};
+
+    // Merge and set all overrides at once
+    nconf.overrides({
+      ...existingOverrides,
+      [propertyName]: value
+    });
+  }
+
+  /**
+   * Extract value from secret based on engine type and metadata
+   */
+  private extractValue(secret: IVaultSecret, metadata: VaultPropertyMetadata): any {
+    const { engine, key } = metadata;
+
+    switch (engine) {
+      case 'kv-v1':
+        // KV v1: data is flat
+        return key ? secret.data[key] : secret.data;
+
+      case 'kv-v2':
+        // KV v2: data is nested under 'data' key
+        const kv2Data = secret.data?.data || secret.data;
+        return key ? kv2Data[key] : kv2Data;
+
+      case 'database':
+      case 'aws':
+      case 'azure':
+      case 'gcp':
+        // Dynamic secrets: data contains credentials
+        return key ? secret.data[key] : secret.data;
+
+      default:
+        // Default: try to extract by key, fallback to entire data
+        return key ? secret.data[key] : secret.data;
+    }
+  }
+
+  /**
+   * Invalidate cache entry by path
+   */
+  invalidate(vaultPath: string): void {
+    const properties = this.pathToProperties.get(vaultPath);
+    if (!properties) {
+      return;
+    }
+
+    for (const propertyName of properties) {
+      this.cache.delete(propertyName);
+      this.propertyToPath.delete(propertyName);
+      // Remove from nconf overrides
+      nconf.remove(propertyName);
+    }
+
+    this.pathToProperties.delete(vaultPath);
+  }
+
+  /**
+   * Invalidate cache entry by property name
+   */
+  invalidateProperty(propertyName: string): void {
+    const vaultPath = this.propertyToPath.get(propertyName);
+    if (vaultPath) {
+      this.invalidate(vaultPath);
+    } else {
+      // Just remove this property
+      this.cache.delete(propertyName);
+      nconf.remove(propertyName);
+    }
+  }
+
+  /**
+   * Get cache entry for a property
+   */
+  getEntry(propertyName: string): VaultCacheEntry | undefined {
+    return this.cache.get(propertyName);
+  }
+
+  /**
+   * Get all properties for a Vault path
+   */
+  getPropertiesForPath(vaultPath: string): string[] {
+    const properties = this.pathToProperties.get(vaultPath);
+    return properties ? Array.from(properties) : [];
+  }
+
+  /**
+   * Get Vault path for a property
+   */
+  getPathForProperty(propertyName: string): string | undefined {
+    return this.propertyToPath.get(propertyName);
+  }
+
+  /**
+   * Check if cache entry exists and is valid
+   */
+  has(propertyName: string): boolean {
+    const entry = this.cache.get(propertyName);
+    if (!entry) {
+      return false;
+    }
+
+    // Check if expired
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(propertyName);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get all cache entries that need refresh
+   */
+  getEntriesNeedingRefresh(): VaultCacheEntry[] {
+    const now = Date.now();
+    const entries: VaultCacheEntry[] = [];
+
+    for (const entry of this.cache.values()) {
+      if (entry.refreshAt <= now && entry.expiresAt > now) {
+        entries.push(entry);
+      }
+    }
+
+    return entries;
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear(): void {
+    // Remove all from nconf overrides
+    for (const propertyName of this.cache.keys()) {
+      nconf.remove(propertyName);
+    }
+
+    this.cache.clear();
+    this.propertyToPath.clear();
+    this.pathToProperties.clear();
+  }
+
+  /**
+   * Get cache size
+   */
+  size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Get all cached property names
+   */
+  getCachedProperties(): string[] {
+    return Array.from(this.cache.keys());
+  }
+}

package/src/vault/vault-integration.ts

@@ -0,0 +1,332 @@
+/**
+ * VaultIntegration
+ * High-level integration class for Vault secrets management
+ */
+
+import { getAllVaultMetadata } from './decorators';
+import { SecretRefreshManager } from './secret-refresh-manager';
+import {
+  IVaultConfigOptions,
+  IVaultHealthDetails,
+  VaultHealth,
+  VaultPropertyMetadata
+} from './types';
+import { VaultCache } from './vault-cache';
+import { VaultProvider } from './vault-provider';
+
+/**
+ * VaultIntegration - High-level API for Vault secrets integration
+ */
+export class VaultIntegration {
+  private provider: VaultProvider;
+  private cache: VaultCache;
+  private refreshManager: SecretRefreshManager;
+  private initialized = false;
+  private config: IVaultConfigOptions;
+  private errors: Array<{ timestamp: number; path: string; error: string; retryable: boolean }> = [];
+
+  constructor(config: IVaultConfigOptions) {
+    this.config = config;
+    this.provider = new VaultProvider(config);
+    this.cache = new VaultCache();
+    const refreshBuffer = config.refreshBuffer || 300; // Default 5 minutes
+    this.refreshManager = new SecretRefreshManager(this.provider, this.cache, refreshBuffer);
+  }
+
+  /**
+   * Initialize Vault connection and authenticate
+   * Must be called before using Vault integration
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return; // Already initialized
+    }
+
+    try {
+      await this.provider.initialize();
+      this.initialized = true;
+    } catch (error: any) {
+      const errorMessage = error?.message || 'Unknown error';
+      this.recordError('', this.sanitizeError(errorMessage), false);
+      throw error;
+    }
+  }
+
+  /**
+   * Load secrets for a config class or instance
+   * Scans for @VaultPath decorators and loads secrets
+   */
+  async loadSecrets<T extends object>(configOrClass: T | (new () => T)): Promise<void> {
+    if (!this.initialized) {
+      throw new Error('VaultIntegration not initialized. Call initialize() first.');
+    }
+
+    // Determine if we got a class or instance
+    const isClass = typeof configOrClass === 'function';
+    const targetClass = isClass ? configOrClass : (configOrClass.constructor as new () => T);
+    const targetInstance = isClass ? null : configOrClass;
+
+    // Get all Vault metadata from decorators
+    const vaultMetadata = getAllVaultMetadata(targetClass);
+
+    if (Object.keys(vaultMetadata).length === 0) {
+      return; // No Vault properties
+    }
+
+    // Group properties by full Vault path (including engine prefix)
+    const pathGroups = this.groupByFullPath(vaultMetadata);
+
+    // Load secrets for each path
+    for (const [ fullPath, properties ] of pathGroups.entries()) {
+      try {
+        const secret = await this.provider.read(fullPath);
+
+        // Cache secret for each property
+        for (const property of properties) {
+          // Merge global refreshBuffer config with property metadata
+          const propertyWithDefaults = {
+            ...property,
+            // Use property-specific refreshBuffer, fall back to global config
+            refreshBuffer: property.refreshBuffer ?? this.config.refreshBuffer
+          };
+
+          this.cache.set(property.propertyName, fullPath, secret, propertyWithDefaults);
+
+          // Extract and set the specific key value to the instance
+          if (targetInstance) {
+            const key = property.key || property.propertyName;
+            const value = secret.data[key];
+            (targetInstance as any)[property.propertyName] = value;
+          }
+
+          // Schedule refresh if secret has TTL
+          if (secret.leaseDuration > 0) {
+            this.refreshManager.scheduleRefresh(property.propertyName, propertyWithDefaults, targetInstance);
+          }
+        }
+      } catch (error: any) {
+        const errorMessage = error?.message || 'Unknown error';
+        const sanitizedError = this.sanitizeError(errorMessage);
+        this.recordError(fullPath, sanitizedError, this.isRetryableError(error));
+
+        // Handle fallback strategy
+        const fallback = this.config.fallback;
+        if (fallback?.required !== false) {
+          // Required secret - throw error
+          throw new Error(`Failed to load required secret from ${ this.sanitizePath(fullPath) }: ${ sanitizedError }`);
+        }
+
+        // Optional secret - log warning and continue
+        console.warn(`Failed to load optional secret from ${ this.sanitizePath(fullPath) }: ${ sanitizedError }`);
+      }
+    }
+  }
+
+  /**
+   * Get secret value synchronously from cache
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  getSecret(propertyName: string): any | null {
+    return this.cache.get(propertyName);
+  }
+
+  /**
+   * Check if Vault integration is initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /**
+   * Get Vault health status
+   */
+  getHealth(): VaultHealth {
+    const refreshStatus = this.refreshManager.getRefreshStatus();
+    const lastRefreshTime = refreshStatus.length > 0 ?
+      Math.max(...refreshStatus.map((s) => s.lastRefresh)) :
+      0;
+
+    return {
+      connected: this.initialized && this.provider.isAuthenticated(),
+      authenticated: this.provider.isAuthenticated(),
+      cacheSize: this.cache.size(),
+      refreshQueueSize: refreshStatus.filter((s) => s.scheduled).length,
+      lastRefreshTime,
+      errors: this.errors.slice(-10) // Last 10 errors
+    };
+  }
+
+  /**
+   * Get detailed health information
+   */
+  getHealthDetails(): IVaultHealthDetails {
+    const refreshStatus = this.refreshManager.getRefreshStatus();
+
+    return {
+      connected: this.initialized && this.provider.isAuthenticated(),
+      authenticated: this.provider.isAuthenticated(),
+      cacheSize: this.cache.size(),
+      refreshQueueSize: refreshStatus.filter((s) => s.scheduled).length,
+      lastRefreshTime: refreshStatus.length > 0 ?
+        Math.max(...refreshStatus.map((s) => s.lastRefresh)) :
+        0,
+      errors: this.errors.slice(-10), // Last 10 errors
+      refreshStatus
+    };
+  }
+
+  /**
+   * Invalidate cache for a Vault path
+   */
+  invalidateCache(vaultPath: string): void {
+    this.cache.invalidate(vaultPath);
+    // Cancel refresh for properties using this path
+    const properties = this.cache.getPropertiesForPath(vaultPath);
+    for (const propertyName of properties) {
+      this.refreshManager.cancelRefresh(propertyName);
+    }
+  }
+
+  /**
+   * Invalidate cache for a property
+   */
+  invalidateProperty(propertyName: string): void {
+    this.cache.invalidateProperty(propertyName);
+    this.refreshManager.cancelRefresh(propertyName);
+  }
+
+  /**
+   * Shutdown gracefully - stop all refresh workers
+   */
+  shutdown(): void {
+    this.refreshManager.shutdown();
+    this.cache.clear();
+    this.initialized = false;
+  }
+
+  /**
+   * Group properties by Vault path
+   */
+  private groupByPath(metadata: Record<string, VaultPropertyMetadata>): Map<string, VaultPropertyMetadata[]> {
+    const groups = new Map<string, VaultPropertyMetadata[]>();
+
+    for (const property of Object.values(metadata)) {
+      const path = property.path;
+      if (!groups.has(path)) {
+        groups.set(path, []);
+      }
+      groups.get(path)!.push(property);
+    }
+
+    return groups;
+  }
+
+  /**
+   * Group properties by full Vault path (including engine prefix)
+   */
+  private groupByFullPath(metadata: Record<string, VaultPropertyMetadata>): Map<string, VaultPropertyMetadata[]> {
+    const groups = new Map<string, VaultPropertyMetadata[]>();
+
+    for (const property of Object.values(metadata)) {
+      const fullPath = this.constructFullPath(property.path, property.engine);
+      if (!groups.has(fullPath)) {
+        groups.set(fullPath, []);
+      }
+      groups.get(fullPath)!.push(property);
+    }
+
+    return groups;
+  }
+
+  /**
+   * Construct full Vault path based on engine type
+   */
+  private constructFullPath(path: string, engine: string): string {
+    switch (engine) {
+      case 'kv1':
+      case 'kv-v1':
+        return `secret/${ path }`;
+      case 'kv2':
+      case 'kv-v2':
+        return `secret/data/${ path }`;
+      case 'database':
+        return path.startsWith('database/') ? path : `database/${ path }`;
+      default:
+        return path;
+    }
+  }
+
+  /**
+   * Record error for health monitoring
+   */
+  private recordError(path: string, error: string, retryable: boolean): void {
+    this.errors.push({
+      timestamp: Date.now(),
+      path: this.sanitizePath(path),
+      error,
+      retryable
+    });
+
+    // Keep only last 100 errors
+    if (this.errors.length > 100) {
+      this.errors.shift();
+    }
+  }
+
+  /**
+   * Check if error is retryable
+   */
+  private isRetryableError(error: any): boolean {
+    const errorMessage = error?.message || '';
+    const errorCode = error?.code || '';
+    const statusCode = error?.statusCode || error?.response?.statusCode;
+
+    const retryablePatterns = [ 'ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND', '5xx' ];
+
+    for (const pattern of retryablePatterns) {
+      if (pattern.includes('xx') && statusCode) {
+        const codePrefix = parseInt(pattern[0]);
+        const statusPrefix = Math.floor(statusCode / 100);
+        if (statusPrefix === codePrefix) {
+          return true;
+        }
+      } else if (errorMessage.includes(pattern) || errorCode.includes(pattern)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Sanitize error message
+   */
+  private sanitizeError(message: string): string {
+    const sensitivePatterns = [ /password/i, /secret/i, /key/i, /token/i, /credential/i ];
+    let sanitized = message;
+
+    sensitivePatterns.forEach((pattern) => {
+      sanitized = sanitized.replace(
+        new RegExp(`${ pattern.source }[:=]\\s*[^\\s,}]+`, 'gi'),
+        `${ pattern.source }: ***`
+      );
+    });
+
+    return sanitized;
+  }
+
+  /**
+   * Sanitize path for logging
+   */
+  private sanitizePath(path: string): string {
+    const segments = path.split('/');
+    if (segments.length > 0) {
+      const lastSegment = segments[segments.length - 1];
+      const sensitivePatterns = [ /password/i, /secret/i, /key/i, /token/i, /credential/i ];
+      if (sensitivePatterns.some((pattern) => pattern.test(lastSegment))) {
+        segments[segments.length - 1] = '***';
+      }
+    }
+    return segments.join('/');
+  }
+}