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

package/src/vault/secret-refresh-manager.ts

@@ -0,0 +1,241 @@
+/**
+ * SecretRefreshManager
+ * Manages background refresh of Vault secrets based on TTL
+ */
+
+import { IRefreshStatus, VaultPropertyMetadata } from './types';
+import { VaultCache } from './vault-cache';
+import { VaultProvider } from './vault-provider';
+
+interface IRefreshContext {
+  metadata: VaultPropertyMetadata;
+  targetInstance?: object;
+  fullPath: string;
+}
+
+/**
+ * SecretRefreshManager - Handles TTL-based secret refresh scheduling
+ */
+export class SecretRefreshManager {
+  private refreshTimers: Map<string, NodeJS.Timeout> = new Map();
+  private refreshLocks: Map<string, Promise<void>> = new Map();
+  private refreshCounts: Map<string, number> = new Map();
+  private lastRefreshTimes: Map<string, number> = new Map();
+  private refreshContexts: Map<string, IRefreshContext> = new Map();
+  private vaultProvider: VaultProvider;
+  private cache: VaultCache;
+  private refreshBuffer: number; // Default refresh buffer in seconds
+
+  constructor(provider: VaultProvider, cache: VaultCache, refreshBuffer?: number) {
+    this.vaultProvider = provider;
+    this.cache = cache;
+    // Default: min(10% of TTL, 300s) - but we'll use a fixed buffer per secret
+    this.refreshBuffer = refreshBuffer || 300; // 5 minutes default
+  }
+
+  /**
+   * Schedule refresh for a secret based on TTL
+   */
+  scheduleRefresh(propertyName: string, metadata: VaultPropertyMetadata, targetInstance?: object): void {
+    const entry = this.cache.getEntry(propertyName);
+    if (!entry) {
+      return; // No cache entry to refresh
+    }
+
+    // Store context for refresh
+    this.refreshContexts.set(propertyName, {
+      metadata,
+      targetInstance,
+      fullPath: entry.vaultPath
+    });
+
+    // Cancel existing refresh if any
+    this.cancelRefresh(propertyName);
+
+    // Calculate refresh time
+    const now = Date.now();
+    const timeUntilRefresh = Math.max(0, entry.refreshAt - now);
+
+    if (timeUntilRefresh <= 0) {
+      // Already past refresh time, refresh immediately
+      this.executeRefresh(propertyName);
+      return;
+    }
+
+    // Schedule refresh
+    const timer = setTimeout(() => {
+      this.executeRefresh(propertyName);
+    }, timeUntilRefresh);
+
+    this.refreshTimers.set(propertyName, timer);
+  }
+
+  /**
+   * Cancel scheduled refresh for a property
+   */
+  cancelRefresh(propertyName: string): void {
+    const timer = this.refreshTimers.get(propertyName);
+    if (timer) {
+      clearTimeout(timer);
+      this.refreshTimers.delete(propertyName);
+    }
+  }
+
+  /**
+   * Execute refresh for a secret (with locking to prevent concurrent refreshes)
+   */
+  private async executeRefresh(propertyName: string): Promise<void> {
+    // Check if refresh is already in progress
+    const existingLock = this.refreshLocks.get(propertyName);
+    if (existingLock) {
+      await existingLock;
+      return; // Refresh already completed
+    }
+
+    // Create refresh lock
+    const refreshPromise = this.performRefresh(propertyName)
+      .finally(() => {
+        this.refreshLocks.delete(propertyName);
+        this.refreshTimers.delete(propertyName);
+      });
+
+    this.refreshLocks.set(propertyName, refreshPromise);
+    await refreshPromise;
+  }
+
+  /**
+   * Perform the actual refresh operation
+   */
+  private async performRefresh(propertyName: string): Promise<void> {
+    const context = this.refreshContexts.get(propertyName);
+    if (!context) {
+      console.error(`No refresh context for ${ propertyName }`);
+      return;
+    }
+
+    const { metadata, targetInstance, fullPath } = context;
+    const refreshCount = (this.refreshCounts.get(propertyName) || 0) + 1;
+    this.refreshCounts.set(propertyName, refreshCount);
+
+    try {
+      // Read fresh secret from Vault (using full path)
+      const secret = await this.vaultProvider.read(fullPath);
+
+      // Update cache
+      this.cache.set(propertyName, fullPath, secret, metadata);
+
+      // Update target instance if provided
+      if (targetInstance) {
+        const key = metadata.key || metadata.propertyName;
+        const value = secret.data[key];
+        (targetInstance as any)[propertyName] = value;
+      }
+
+      // Record refresh time
+      this.lastRefreshTimes.set(propertyName, Date.now());
+
+      // Reschedule next refresh
+      this.scheduleRefresh(propertyName, metadata, targetInstance);
+    } catch (error: any) {
+      // Log error (sanitized)
+      const errorMessage = error?.message || 'Unknown error';
+      console.error(`Failed to refresh secret for ${ propertyName }: ${ this.sanitizeError(errorMessage) }`);
+
+      // Retry with exponential backoff
+      const retryDelay = Math.min(1000 * Math.pow(2, refreshCount - 1), 30000); // Max 30s
+      setTimeout(() => {
+        this.scheduleRefresh(propertyName, metadata, targetInstance);
+      }, retryDelay);
+    }
+  }
+
+  /**
+   * Get refresh status for all secrets
+   */
+  getRefreshStatus(): IRefreshStatus[] {
+    const statuses: IRefreshStatus[] = [];
+    const cachedProperties = this.cache.getCachedProperties();
+
+    for (const propertyName of cachedProperties) {
+      const entry = this.cache.getEntry(propertyName);
+      if (!entry) {
+        continue;
+      }
+
+      const timer = this.refreshTimers.get(propertyName);
+      const now = Date.now();
+      const refreshAt = entry.refreshAt;
+      const timeUntilRefresh = Math.max(0, refreshAt - now);
+
+      statuses.push({
+        propertyName,
+        vaultPath: entry.vaultPath,
+        scheduled: timer !== undefined,
+        refreshAt,
+        timeUntilRefresh,
+        lastRefresh: this.lastRefreshTimes.get(propertyName) || entry.cachedAt,
+        refreshCount: this.refreshCounts.get(propertyName) || 0
+      });
+    }
+
+    return statuses;
+  }
+
+  /**
+   * Get refresh status for a specific property
+   */
+  getRefreshStatusForProperty(propertyName: string): IRefreshStatus | null {
+    const entry = this.cache.getEntry(propertyName);
+    if (!entry) {
+      return null;
+    }
+
+    const timer = this.refreshTimers.get(propertyName);
+    const now = Date.now();
+    const refreshAt = entry.refreshAt;
+    const timeUntilRefresh = Math.max(0, refreshAt - now);
+
+    return {
+      propertyName,
+      vaultPath: entry.vaultPath,
+      scheduled: timer !== undefined,
+      refreshAt,
+      timeUntilRefresh,
+      lastRefresh: this.lastRefreshTimes.get(propertyName) || entry.cachedAt,
+      refreshCount: this.refreshCounts.get(propertyName) || 0
+    };
+  }
+
+  /**
+   * Stop all refresh workers
+   */
+  shutdown(): void {
+    // Cancel all timers
+    for (const [ propertyName, timer ] of this.refreshTimers.entries()) {
+      clearTimeout(timer);
+    }
+
+    this.refreshTimers.clear();
+    this.refreshLocks.clear();
+    this.refreshCounts.clear();
+    this.lastRefreshTimes.clear();
+  }
+
+  /**
+   * Sanitize error message (remove potential secret values)
+   */
+  private sanitizeError(message: string): string {
+    // Remove potential secret values from error messages
+    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;
+  }
+}

package/src/vault/types.ts

@@ -0,0 +1,487 @@
+/**
+ * Vault Integration Types
+ * TypeScript interfaces and types for HashiCorp Vault integration
+ */
+
+import 'reflect-metadata';
+
+/**
+ * Vault secrets engine types
+ * - kv1/kv-v1: Key-Value v1 (simple)
+ * - kv2/kv-v2: Key-Value v2 (versioned, default)
+ * - database: Database secrets engine (dynamic credentials)
+ * - aws: AWS secrets engine
+ * - azure: Azure secrets engine
+ * - gcp: GCP secrets engine
+ * - transit: Transit secrets engine (encryption)
+ * - pki: PKI secrets engine
+ * - custom: Custom engine (requires custom extraction logic)
+ */
+export type VaultEngineType =
+  | 'kv1'
+  | 'kv-v1'
+  | 'kv2'
+  | 'kv-v2'
+  | 'database'
+  | 'aws'
+  | 'azure'
+  | 'gcp'
+  | 'transit'
+  | 'pki'
+  | 'custom';
+
+/**
+ * Vault configuration options for ConfigService
+ */
+export interface IVaultConfigOptions {
+  /**
+   * Vault server endpoint (must be HTTPS in production)
+   */
+  endpoint: string;
+
+  /**
+   * Authentication configuration
+   */
+  auth: IVaultAuthConfig;
+
+  /**
+   * TLS configuration
+   */
+  tls?: IVaultTLSConfig;
+
+  /**
+   * Refresh buffer (seconds) - default: min(10% of TTL, 300s)
+   */
+  refreshBuffer?: number;
+
+  /**
+   * Fallback configuration
+   */
+  fallback?: IVaultFallbackConfig;
+
+  /**
+   * Retry configuration
+   */
+  retry?: IRetryPolicy;
+
+  /**
+   * Circuit breaker configuration
+   */
+  circuitBreaker?: ICircuitBreakerConfig;
+}
+
+/**
+ * Authentication configuration with priority
+ * Supports both simple single-method and array-based multi-method configs
+ */
+export type IVaultAuthConfig = IVaultAuthConfigSimple | IVaultAuthConfigMethods;
+
+/**
+ * Simple single-method auth config (for convenience)
+ */
+export type IVaultAuthConfigSimple =
+  | ({ method: 'gcp' } & IGCPAuthConfig)
+  | ({ method: 'aws' } & IAWSAuthConfig)
+  | ({ method: 'approle' } & IAppRoleAuthConfig)
+  | ({ method: 'token' } & ITokenAuthConfig);
+
+/**
+ * Multi-method auth config (for fallback chains)
+ */
+export interface IVaultAuthConfigMethods {
+  /**
+   * Authentication methods in priority order
+   * Tried sequentially until one succeeds
+   */
+  methods: IVaultAuthMethod[];
+}
+
+/**
+ * Individual authentication method
+ */
+export interface IVaultAuthMethod {
+  type: 'gcp' | 'aws' | 'approle' | 'token';
+  config: IGCPAuthConfig | IAWSAuthConfig | IAppRoleAuthConfig | ITokenAuthConfig;
+}
+
+/**
+ * GCP IAM authentication
+ */
+export interface IGCPAuthConfig {
+  type?: 'gcp';
+  /** Vault role name configured for GCP auth */
+  role: string;
+  /** Path to service account key file (JSON). If not provided, uses ADC */
+  serviceAccountKeyFile?: string;
+  /** Service account email. If not provided, derived from key file or metadata */
+  serviceAccountEmail?: string;
+  /** JWT expiration in seconds (default: 900 = 15 minutes) */
+  jwtExpiration?: number;
+}
+
+/**
+ * AWS IAM authentication
+ */
+export interface IAWSAuthConfig {
+  type?: 'aws';
+  role: string;
+  // Uses instance profile or environment credentials
+}
+
+/**
+ * AppRole authentication
+ */
+export interface IAppRoleAuthConfig {
+  type?: 'approle';
+  /** Can be in config */
+  roleId: string;
+  /** MUST come from secure source */
+  secretId: string;
+  /** Default: 'approle' */
+  mountPath?: string;
+}
+
+/**
+ * Token authentication (dev only)
+ */
+export interface ITokenAuthConfig {
+  type?: 'token';
+  /** MUST come from secure source */
+  token: string;
+}
+
+/**
+ * TLS configuration
+ */
+export interface IVaultTLSConfig {
+  /**
+   * Require TLS (default: true, cannot be disabled)
+   */
+  enabled: boolean;
+
+  /**
+   * Verify server certificate (default: true)
+   */
+  verifyCertificate: boolean;
+
+  /**
+   * Certificate fingerprint for pinning (optional)
+   */
+  certificateFingerprint?: string;
+
+  /**
+   * Custom CA certificate (optional)
+   */
+  caCert?: string | Buffer;
+
+  /**
+   * Minimum TLS version (default: 'TLSv1.2')
+   */
+  minVersion?: 'TLSv1.2' | 'TLSv1.3';
+}
+
+/**
+ * Fallback configuration
+ */
+export interface IVaultFallbackConfig {
+  /**
+   * Whether Vault is required (default: true)
+   * If false, falls back to env/file on initialization failure
+   */
+  required: boolean;
+
+  /**
+   * Use cached secrets on failure (default: true)
+   */
+  useCacheOnFailure: boolean;
+
+  /**
+   * Maximum cache age for fallback (ms) - default: TTL or 1 hour
+   */
+  maxCacheAge: number;
+
+  /**
+   * Fail fast on refresh failure (default: true for required secrets)
+   */
+  failFast: boolean;
+}
+
+/**
+ * Retry policy
+ */
+export interface IRetryPolicy {
+  /** Default: 3 */
+  maxAttempts: number;
+  backoff: {
+    strategy: 'exponential' | 'linear' | 'fixed';
+    /** Default: 1000ms */
+    initial: number;
+    /** Default: 10000ms */
+    max: number;
+    /** Default: 2 */
+    multiplier: number;
+  };
+  /** Default: ['ECONNREFUSED', 'ETIMEDOUT', '5xx'] */
+  retryableErrors: string[];
+}
+
+/**
+ * Circuit breaker configuration
+ */
+export interface ICircuitBreakerConfig {
+  /** Default: true */
+  enabled: boolean;
+  /** Default: 5 */
+  failureThreshold: number;
+  /** Default: 60000ms */
+  resetTimeout: number;
+  /** Default: 1 */
+  halfOpenMaxRequests: number;
+}
+
+/**
+ * Vault secret response structure
+ */
+export interface IVaultSecretResponse {
+  /**
+   * Secret data (structure varies by engine)
+   */
+  data: Record<string, any>;
+
+  /**
+   * Lease ID (for dynamic secrets)
+   */
+  lease_id?: string;
+
+  /**
+   * Lease duration in seconds (for dynamic secrets)
+   */
+  lease_duration?: number;
+
+  /**
+   * Whether the lease can be renewed
+   */
+  renewable?: boolean;
+
+  /**
+   * Request ID for tracing
+   */
+  request_id?: string;
+}
+
+/**
+ * Normalized Vault secret (internal representation)
+ */
+export interface IVaultSecret {
+  /**
+   * Secret data (engine-specific structure)
+   */
+  data: Record<string, any>;
+
+  /**
+   * Lease ID (for dynamic secrets)
+   */
+  leaseId?: string;
+
+  /**
+   * Lease duration in seconds
+   */
+  leaseDuration: number;
+
+  /**
+   * Whether lease is renewable
+   */
+  renewable: boolean;
+
+  /**
+   * Metadata (for KV v2)
+   */
+  metadata?: {
+    createdTime: string;
+    deletionTime: string;
+    destroyed: boolean;
+    version: number;
+  };
+}
+
+/**
+ * Vault property metadata (from decorators)
+ */
+export interface VaultPropertyMetadata {
+  /**
+   * Vault path (from @VaultPath decorator)
+   */
+  path: string;
+
+  /**
+   * Engine type (from @VaultEngine decorator, or auto-detected)
+   */
+  engine: VaultEngineType;
+
+  /**
+   * Key name (from @VaultKey decorator, or defaults to property name)
+   */
+  key?: string;
+
+  /**
+   * Refresh buffer override (from @VaultRefreshBuffer decorator)
+   */
+  refreshBuffer?: number;
+
+  /**
+   * Whether required (from @VaultOptional decorator - false if present, true otherwise)
+   */
+  required: boolean;
+
+  /**
+   * Property name
+   */
+  propertyName: string;
+
+  /**
+   * Property type (for validation)
+   */
+  propertyType: string;
+}
+
+/**
+ * Vault cache entry
+ */
+export interface VaultCacheEntry {
+  /**
+   * The secret value (extracted from Vault response)
+   */
+  value: any;
+
+  /**
+   * Original Vault secret
+   */
+  secret: IVaultSecret;
+
+  /**
+   * When this secret was cached
+   */
+  cachedAt: number;
+
+  /**
+   * When this secret expires (timestamp)
+   */
+  expiresAt: number;
+
+  /**
+   * When to refresh this secret (timestamp)
+   */
+  refreshAt: number;
+
+  /**
+   * Property name this secret is mapped to
+   */
+  propertyName: string;
+
+  /**
+   * Vault path
+   */
+  vaultPath: string;
+}
+
+/**
+ * Vault health status
+ */
+export interface VaultHealth {
+  connected: boolean;
+  authenticated: boolean;
+  cacheSize: number;
+  refreshQueueSize: number;
+  lastRefreshTime: number;
+  errors: VaultError[];
+}
+
+/**
+ * Vault error (sanitized)
+ */
+export interface VaultError {
+  timestamp: number;
+  path: string;
+  error: string; // Sanitized
+  retryable: boolean;
+}
+
+/**
+ * Refresh status for a secret
+ */
+export interface IRefreshStatus {
+  /**
+   * Property name
+   */
+  propertyName: string;
+
+  /**
+   * Vault path
+   */
+  vaultPath: string;
+
+  /**
+   * Whether refresh is scheduled
+   */
+  scheduled: boolean;
+
+  /**
+   * When refresh is scheduled (timestamp)
+   */
+  refreshAt: number;
+
+  /**
+   * Time until refresh (ms)
+   */
+  timeUntilRefresh: number;
+
+  /**
+   * Last refresh time (timestamp)
+   */
+  lastRefresh: number;
+
+  /**
+   * Number of refresh attempts
+   */
+  refreshCount: number;
+}
+
+/**
+ * Detailed Vault health information
+ */
+export interface IVaultHealthDetails {
+  /**
+   * Whether connected to Vault
+   */
+  connected: boolean;
+
+  /**
+   * Whether authenticated
+   */
+  authenticated: boolean;
+
+  /**
+   * Cache size (number of cached secrets)
+   */
+  cacheSize: number;
+
+  /**
+   * Refresh queue size (number of scheduled refreshes)
+   */
+  refreshQueueSize: number;
+
+  /**
+   * Last refresh time (timestamp)
+   */
+  lastRefreshTime: number;
+
+  /**
+   * Recent errors
+   */
+  errors: VaultError[];
+
+  /**
+   * Refresh status for all secrets
+   */
+  refreshStatus: IRefreshStatus[];
+}