@kibibit/configit 2.12.2 → 2.13.0

package/src/vault/__tests__/vault-integration.test.ts

@@ -9,8 +9,9 @@
 
 import { IsString } from 'class-validator';
 
-import { VaultKey, VaultPath } from '../decorators';
-import { IVaultConfigOptions } from '../types';
+import { VaultEngine, VaultKey, VaultPath } from '../decorators';
+import { buildVaultConfigFromEnv } from '../build-vault-config';
+import { IVaultConfigOptions, SecretRefreshEvent } from '../types';
 import { VaultIntegration } from '../vault-integration';
 
 import 'reflect-metadata';
@@ -176,6 +177,177 @@ describeVault('VaultIntegration (requires running Vault)', () => {
         .toThrow(/authentication.*failed/i);
     });
   });
+
+  describe('onSecretRefreshed callback', () => {
+    it('should fire callback with correct event when configured via constructor', async () => {
+      const events: SecretRefreshEvent[] = [];
+      const configWithCallback: IVaultConfigOptions = {
+        ...VAULT_CONFIG,
+        onSecretRefreshed: (event) => { events.push(event); }
+      };
+
+      vaultIntegration = new VaultIntegration(configWithCallback);
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(TestVaultConfig);
+
+      expect(events).toHaveLength(0);
+    });
+
+    it('should fire callback via runtime registration', async () => {
+      const events: SecretRefreshEvent[] = [];
+
+      vaultIntegration = new VaultIntegration(VAULT_CONFIG);
+      vaultIntegration.onSecretRefreshed((event) => { events.push(event); });
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(TestVaultConfig);
+
+      expect(events).toHaveLength(0);
+    });
+  });
+
+  describe('dynamic secrets with TTL-based refresh', () => {
+    /**
+     * Config class using the database engine with dynamic credentials.
+     * database/creds/configit-readonly has a 60s TTL in the test Vault setup.
+     */
+    class DynamicConfig {
+      @VaultPath('creds/configit-readonly')
+      @VaultKey('username')
+      @VaultEngine('database')
+      @IsString()
+        DB_USERNAME!: string;
+
+      @VaultPath('creds/configit-readonly')
+      @VaultKey('password')
+      @VaultEngine('database')
+      @IsString()
+        DB_PASSWORD!: string;
+    }
+
+    it('should load dynamic database credentials', async () => {
+      vaultIntegration = new VaultIntegration({
+        ...VAULT_CONFIG,
+        refreshBuffer: 30
+      });
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(DynamicConfig);
+
+      const username = vaultIntegration.getSecret('DB_USERNAME');
+      const password = vaultIntegration.getSecret('DB_PASSWORD');
+
+      expect(username).toBeDefined();
+      expect(username).toMatch(/^v-token-/);
+      expect(password).toBeDefined();
+      expect(password!.length).toBeGreaterThan(0);
+    });
+
+    it('should schedule refresh for dynamic secrets', async () => {
+      vaultIntegration = new VaultIntegration({
+        ...VAULT_CONFIG,
+        refreshBuffer: 30
+      });
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(DynamicConfig);
+
+      const health = vaultIntegration.getHealthDetails();
+      expect(health.refreshQueueSize).toBeGreaterThanOrEqual(1);
+
+      const dbUserStatus = health.refreshStatus.find((s) => s.propertyName === 'DB_USERNAME');
+      expect(dbUserStatus).toBeDefined();
+      expect(dbUserStatus!.scheduled).toBe(true);
+      expect(dbUserStatus!.timeUntilRefresh).toBeLessThanOrEqual(60000);
+    });
+
+    it('should perform path-level atomic refresh and fire callback', async () => {
+      const events: SecretRefreshEvent[] = [];
+
+      vaultIntegration = new VaultIntegration({
+        ...VAULT_CONFIG,
+        refreshBuffer: 55, // 60s TTL minus 55s buffer = refresh after ~5s
+        onSecretRefreshed: (event) => { events.push(event); }
+      });
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(DynamicConfig);
+
+      const initialUser = vaultIntegration.getSecret('DB_USERNAME');
+      const initialPass = vaultIntegration.getSecret('DB_PASSWORD');
+
+      // Wait for the refresh to trigger (~5s + some margin)
+      await new Promise((resolve) => setTimeout(resolve, 10000));
+
+      const refreshedUser = vaultIntegration.getSecret('DB_USERNAME');
+      const refreshedPass = vaultIntegration.getSecret('DB_PASSWORD');
+
+      // Credentials should have changed
+      expect(refreshedUser).not.toBe(initialUser);
+      expect(refreshedPass).not.toBe(initialPass);
+
+      // Exactly one callback event for the path
+      expect(events.length).toBeGreaterThanOrEqual(1);
+      const dbEvent = events.find((e) => e.engine === 'database');
+      expect(dbEvent).toBeDefined();
+      expect(dbEvent!.properties).toContain('DB_USERNAME');
+      expect(dbEvent!.properties).toContain('DB_PASSWORD');
+      expect(dbEvent!.vaultPath).toContain('configit-readonly');
+      expect(dbEvent!.refreshCount).toBeGreaterThanOrEqual(1);
+    }, 20000);
+  });
+
+  describe('buildVaultConfigFromEnv end-to-end', () => {
+    const savedEnv: Record<string, string | undefined> = {};
+
+    beforeEach(() => {
+      savedEnv.VAULT_ADDR = process.env.VAULT_ADDR;
+      savedEnv.VAULT_TOKEN = process.env.VAULT_TOKEN;
+      savedEnv.VAULT_GCP_ROLE = process.env.VAULT_GCP_ROLE;
+    });
+
+    afterEach(() => {
+      for (const [key, val] of Object.entries(savedEnv)) {
+        if (val !== undefined) {
+          process.env[key] = val;
+        } else {
+          delete process.env[key];
+        }
+      }
+    });
+
+    it('should produce a config that VaultIntegration can use', async () => {
+      process.env.VAULT_ADDR = 'http://127.0.0.1:8200';
+      process.env.VAULT_TOKEN = 'configit-dev-token';
+      delete process.env.VAULT_GCP_ROLE;
+
+      const config = buildVaultConfigFromEnv();
+      expect(config).toBeDefined();
+
+      vaultIntegration = new VaultIntegration(config!);
+      await vaultIntegration.initialize();
+      expect(vaultIntegration.isInitialized()).toBe(true);
+
+      await vaultIntegration.loadSecrets(TestVaultConfig);
+      expect(vaultIntegration.getSecret('API_KEY')).toBe('test-api-key-123');
+    });
+
+    it('should wire onSecretRefreshed callback through to VaultIntegration', async () => {
+      process.env.VAULT_ADDR = 'http://127.0.0.1:8200';
+      process.env.VAULT_TOKEN = 'configit-dev-token';
+      delete process.env.VAULT_GCP_ROLE;
+
+      const events: SecretRefreshEvent[] = [];
+      const config = buildVaultConfigFromEnv({
+        onSecretRefreshed: (event) => { events.push(event); }
+      });
+      expect(config).toBeDefined();
+      expect(config!.onSecretRefreshed).toBeDefined();
+
+      vaultIntegration = new VaultIntegration(config!);
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(TestVaultConfig);
+
+      // No events yet (KV secrets have no TTL-based refresh in this setup)
+      expect(events).toHaveLength(0);
+    });
+  });
 });
 
 /**

package/src/vault/build-vault-config.ts

@@ -0,0 +1,73 @@
+/**
+ * buildVaultConfigFromEnv
+ *
+ * Builds IVaultConfigOptions from standard environment variables.
+ * Returns undefined when Vault is not configured, causing configit
+ * to fall back to env vars / config files.
+ *
+ * Supported auth flows (checked in order):
+ *   1. VAULT_TOKEN         → Token auth (local development)
+ *   2. VAULT_GCP_ROLE      → GCP IAM auth (production / GKE)
+ *
+ * Common env vars:
+ *   VAULT_ADDR             → Vault server URL (required)
+ */
+
+import { IVaultConfigOptions, IVaultFallbackConfig, SecretRefreshCallback } from './types';
+
+export interface IBuildVaultConfigOptions {
+  /** Seconds before expiry to trigger refresh. Default: 10 (token) / 60 (GCP) */
+  refreshBuffer?: number;
+
+  /** Fallback behavior when Vault is unavailable */
+  fallback?: IVaultFallbackConfig;
+
+  /** Callback fired when secrets are refreshed */
+  onSecretRefreshed?: SecretRefreshCallback;
+}
+
+const DEFAULT_FALLBACK: IVaultFallbackConfig = {
+  required: false,
+  useCacheOnFailure: true,
+  maxCacheAge: 3600000,
+  failFast: false
+};
+
+export function buildVaultConfigFromEnv(
+  options?: IBuildVaultConfigOptions
+): IVaultConfigOptions | undefined {
+  const vaultAddr = process.env.VAULT_ADDR;
+  const vaultToken = process.env.VAULT_TOKEN;
+  const vaultRole = process.env.VAULT_GCP_ROLE;
+
+  if (!vaultAddr) {
+    // eslint-disable-next-line no-undefined
+    return undefined;
+  }
+
+  const fallback = options?.fallback ?? DEFAULT_FALLBACK;
+  const onSecretRefreshed = options?.onSecretRefreshed;
+
+  if (vaultToken) {
+    return {
+      endpoint: vaultAddr,
+      auth: { method: 'token' as const, token: vaultToken },
+      refreshBuffer: options?.refreshBuffer ?? 10,
+      fallback,
+      onSecretRefreshed
+    };
+  }
+
+  if (vaultRole) {
+    return {
+      endpoint: vaultAddr,
+      auth: { method: 'gcp' as const, role: vaultRole },
+      refreshBuffer: options?.refreshBuffer ?? 60,
+      fallback,
+      onSecretRefreshed
+    };
+  }
+
+  // eslint-disable-next-line no-undefined
+  return undefined;
+}

package/src/vault/index.ts

@@ -29,3 +29,7 @@ export { VaultProvider } from './vault-provider';
 export { VaultCache } from './vault-cache';
 export { SecretRefreshManager } from './secret-refresh-manager';
 export { VaultIntegration } from './vault-integration';
+
+// Helpers
+export { buildVaultConfigFromEnv } from './build-vault-config';
+export type { IBuildVaultConfigOptions } from './build-vault-config';

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

@@ -1,9 +1,19 @@
 /**
  * SecretRefreshManager
- * Manages background refresh of Vault secrets based on TTL
+ * Manages background refresh of Vault secrets based on TTL.
+ *
+ * Refreshes are path-aware: when a secret at a given Vault path is refreshed,
+ * ALL properties sharing that path are updated from the same Vault read.
+ * This prevents credential mismatch (e.g. username from one read, password
+ * from another) for engines like `database` where each read generates new creds.
  */
 
-import { IRefreshStatus, VaultPropertyMetadata } from './types';
+import {
+  IRefreshStatus,
+  SecretRefreshCallback,
+  SecretRefreshEvent,
+  VaultPropertyMetadata
+} from './types';
 import { VaultCache } from './vault-cache';
 import { VaultProvider } from './vault-provider';
 
@@ -13,9 +23,6 @@ interface IRefreshContext {
   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();
@@ -24,45 +31,45 @@ export class SecretRefreshManager {
   private refreshContexts: Map<string, IRefreshContext> = new Map();
   private vaultProvider: VaultProvider;
   private cache: VaultCache;
-  private refreshBuffer: number; // Default refresh buffer in seconds
+  private refreshBuffer: number;
+  private onRefreshCallbacks: SecretRefreshCallback[] = [];
 
   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
+    this.refreshBuffer = refreshBuffer || 300;
   }
 
   /**
-   * Schedule refresh for a secret based on TTL
+   * Register a callback to be invoked after secrets are refreshed.
+   * Multiple callbacks can be registered.
    */
+  onSecretRefreshed(callback: SecretRefreshCallback): void {
+    this.onRefreshCallbacks.push(callback);
+  }
+
   scheduleRefresh(propertyName: string, metadata: VaultPropertyMetadata, targetInstance?: object): void {
     const entry = this.cache.getEntry(propertyName);
     if (!entry) {
-      return; // No cache entry to refresh
+      return;
     }
 
-    // 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);
@@ -70,9 +77,6 @@ export class SecretRefreshManager {
     this.refreshTimers.set(propertyName, timer);
   }
 
-  /**
-   * Cancel scheduled refresh for a property
-   */
   cancelRefresh(propertyName: string): void {
     const timer = this.refreshTimers.get(propertyName);
     if (timer) {
@@ -81,77 +85,123 @@ export class SecretRefreshManager {
     }
   }
 
-  /**
-   * 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);
+    const context = this.refreshContexts.get(propertyName);
+    if (!context) {
+      return;
+    }
+
+    // Lock by path so sibling properties don't trigger duplicate reads
+    const lockKey = `path:${ context.fullPath }`;
+    const existingLock = this.refreshLocks.get(lockKey);
     if (existingLock) {
       await existingLock;
-      return; // Refresh already completed
+      return;
     }
 
-    // Create refresh lock
-    const refreshPromise = this.performRefresh(propertyName)
+    const refreshPromise = this.performPathRefresh(context.fullPath)
       .finally(() => {
-        this.refreshLocks.delete(propertyName);
-        this.refreshTimers.delete(propertyName);
+        this.refreshLocks.delete(lockKey);
       });
 
-    this.refreshLocks.set(propertyName, refreshPromise);
+    this.refreshLocks.set(lockKey, refreshPromise);
     await refreshPromise;
   }
 
   /**
-   * Perform the actual refresh operation
+   * Refresh ALL properties that share the given Vault path in a single read.
    */
-  private async performRefresh(propertyName: string): Promise<void> {
-    const context = this.refreshContexts.get(propertyName);
-    if (!context) {
-      console.error(`No refresh context for ${ propertyName }`);
+  private async performPathRefresh(fullPath: string): Promise<void> {
+    const siblingProperties = this.getSiblingsForPath(fullPath);
+    if (siblingProperties.length === 0) {
       return;
     }
 
-    const { metadata, targetInstance, fullPath } = context;
-    const refreshCount = (this.refreshCounts.get(propertyName) || 0) + 1;
-    this.refreshCounts.set(propertyName, refreshCount);
+    const pathRefreshCount = (this.refreshCounts.get(fullPath) || 0) + 1;
+    this.refreshCounts.set(fullPath, pathRefreshCount);
 
     try {
-      // Read fresh secret from Vault (using full path)
       const secret = await this.vaultProvider.read(fullPath);
+      const updatedProperties: string[] = [];
+      let engine = siblingProperties[0].metadata.engine;
+
+      for (const { propertyName, metadata, targetInstance } of siblingProperties) {
+        this.cache.set(propertyName, fullPath, secret, metadata);
 
-      // Update cache
-      this.cache.set(propertyName, fullPath, secret, metadata);
+        if (targetInstance) {
+          const key = metadata.key || metadata.propertyName;
+          const value = secret.data[key];
+          (targetInstance as any)[propertyName] = value;
+        }
 
-      // Update target instance if provided
-      if (targetInstance) {
-        const key = metadata.key || metadata.propertyName;
-        const value = secret.data[key];
-        (targetInstance as any)[propertyName] = value;
+        updatedProperties.push(propertyName);
+        engine = metadata.engine;
+
+        this.cancelRefresh(propertyName);
+        this.refreshTimers.delete(propertyName);
       }
 
-      // Record refresh time
-      this.lastRefreshTimes.set(propertyName, Date.now());
+      const now = Date.now();
+      this.lastRefreshTimes.set(fullPath, now);
+
+      // Reschedule all sibling properties
+      for (const { propertyName, metadata, targetInstance } of siblingProperties) {
+        this.scheduleRefresh(propertyName, metadata, targetInstance);
+      }
 
-      // Reschedule next refresh
-      this.scheduleRefresh(propertyName, metadata, targetInstance);
+      // Fire callbacks once per path
+      const event: SecretRefreshEvent = {
+        vaultPath: fullPath,
+        properties: updatedProperties,
+        engine,
+        timestamp: new Date(now).toISOString(),
+        refreshCount: pathRefreshCount
+      };
+
+      for (const callback of this.onRefreshCallbacks) {
+        try {
+          const result = callback(event);
+          if (result && typeof (result as Promise<void>).catch === 'function') {
+            (result as Promise<void>).catch((err) => {
+              console.error(`Secret refresh callback error for ${ fullPath }: ${ this.sanitizeError(err?.message || 'Unknown') }`);
+            });
+          }
+        } catch (err: any) {
+          console.error(`Secret refresh callback error for ${ fullPath }: ${ this.sanitizeError(err?.message || 'Unknown') }`);
+        }
+      }
     } catch (error: any) {
-      // Log error (sanitized)
       const errorMessage = error?.message || 'Unknown error';
-      console.error(`Failed to refresh secret for ${ propertyName }: ${ this.sanitizeError(errorMessage) }`);
+      console.error(`Failed to refresh secrets for path ${ this.sanitizePath(fullPath) }: ${ this.sanitizeError(errorMessage) }`);
 
-      // Retry with exponential backoff
-      const retryDelay = Math.min(1000 * Math.pow(2, refreshCount - 1), 30000); // Max 30s
+      const retryDelay = Math.min(1000 * Math.pow(2, pathRefreshCount - 1), 30000);
       setTimeout(() => {
-        this.scheduleRefresh(propertyName, metadata, targetInstance);
+        for (const { propertyName, metadata, targetInstance } of siblingProperties) {
+          this.scheduleRefresh(propertyName, metadata, targetInstance);
+        }
       }, retryDelay);
     }
   }
 
   /**
-   * Get refresh status for all secrets
+   * Find all properties that share the given Vault path.
    */
+  private getSiblingsForPath(fullPath: string): Array<{ propertyName: string; metadata: VaultPropertyMetadata; targetInstance?: object }> {
+    const siblings: Array<{ propertyName: string; metadata: VaultPropertyMetadata; targetInstance?: object }> = [];
+
+    for (const [ propertyName, context ] of this.refreshContexts.entries()) {
+      if (context.fullPath === fullPath) {
+        siblings.push({
+          propertyName,
+          metadata: context.metadata,
+          targetInstance: context.targetInstance
+        });
+      }
+    }
+
+    return siblings;
+  }
+
   getRefreshStatus(): IRefreshStatus[] {
     const statuses: IRefreshStatus[] = [];
     const cachedProperties = this.cache.getCachedProperties();
@@ -173,17 +223,14 @@ export class SecretRefreshManager {
         scheduled: timer !== undefined,
         refreshAt,
         timeUntilRefresh,
-        lastRefresh: this.lastRefreshTimes.get(propertyName) || entry.cachedAt,
-        refreshCount: this.refreshCounts.get(propertyName) || 0
+        lastRefresh: this.lastRefreshTimes.get(entry.vaultPath) || entry.cachedAt,
+        refreshCount: this.refreshCounts.get(entry.vaultPath) || 0
       });
     }
 
     return statuses;
   }
 
-  /**
-   * Get refresh status for a specific property
-   */
   getRefreshStatusForProperty(propertyName: string): IRefreshStatus | null {
     const entry = this.cache.getEntry(propertyName);
     if (!entry) {
@@ -201,17 +248,13 @@ export class SecretRefreshManager {
       scheduled: timer !== undefined,
       refreshAt,
       timeUntilRefresh,
-      lastRefresh: this.lastRefreshTimes.get(propertyName) || entry.cachedAt,
-      refreshCount: this.refreshCounts.get(propertyName) || 0
+      lastRefresh: this.lastRefreshTimes.get(entry.vaultPath) || entry.cachedAt,
+      refreshCount: this.refreshCounts.get(entry.vaultPath) || 0
     };
   }
 
-  /**
-   * Stop all refresh workers
-   */
   shutdown(): void {
-    // Cancel all timers
-    for (const [ propertyName, timer ] of this.refreshTimers.entries()) {
+    for (const [ , timer ] of this.refreshTimers.entries()) {
       clearTimeout(timer);
     }
 
@@ -219,13 +262,10 @@ export class SecretRefreshManager {
     this.refreshLocks.clear();
     this.refreshCounts.clear();
     this.lastRefreshTimes.clear();
+    this.onRefreshCallbacks = [];
   }
 
-  /**
-   * 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;
 
@@ -238,4 +278,16 @@ export class SecretRefreshManager {
 
     return sanitized;
   }
+
+  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('/');
+  }
 }

package/src/vault/types.ts

@@ -68,6 +68,14 @@ export interface IVaultConfigOptions {
    * Circuit breaker configuration
    */
   circuitBreaker?: ICircuitBreakerConfig;
+
+  /**
+   * Callback invoked when a secret is refreshed.
+   * Fired once per Vault path after all properties from that path are updated.
+   * Config values are already set when this fires, so consumers can
+   * safely read the new values from the config instance.
+   */
+  onSecretRefreshed?: SecretRefreshCallback;
 }
 
 /**
@@ -225,6 +233,36 @@ export interface IRetryPolicy {
   retryableErrors: string[];
 }
 
+/**
+ * Event emitted when a Vault secret is refreshed.
+ * Fired once per Vault path (not per property), so consumers
+ * can react to credential rotation (e.g., reconnect a database pool).
+ *
+ * Secret values are intentionally excluded for security.
+ */
+export interface SecretRefreshEvent {
+  /** The Vault path that was refreshed (e.g. 'database/creds/my-role') */
+  vaultPath: string;
+
+  /** Config property names updated from this path (e.g. ['DB_USERNAME', 'DB_PASSWORD']) */
+  properties: string[];
+
+  /** Vault engine type */
+  engine: VaultEngineType;
+
+  /** ISO timestamp of the refresh */
+  timestamp: string;
+
+  /** Number of times this path has been refreshed (1-based) */
+  refreshCount: number;
+}
+
+/**
+ * Callback invoked when Vault secrets are refreshed.
+ * Config values are already updated when this fires.
+ */
+export type SecretRefreshCallback = (event: SecretRefreshEvent) => void | Promise<void>;
+
 /**
  * Circuit breaker configuration
  */

package/src/vault/vault-integration.ts

@@ -8,6 +8,7 @@ import { SecretRefreshManager } from './secret-refresh-manager';
 import {
   IVaultConfigOptions,
   IVaultHealthDetails,
+  SecretRefreshCallback,
   VaultHealth,
   VaultPropertyMetadata
 } from './types';
@@ -31,8 +32,12 @@ export class VaultIntegration {
     this.config = config;
     this.provider = new VaultProvider(config);
     this.cache = new VaultCache();
-    const refreshBuffer = config.refreshBuffer || 300; // Default 5 minutes
+    const refreshBuffer = config.refreshBuffer || 300;
     this.refreshManager = new SecretRefreshManager(this.provider, this.cache, refreshBuffer);
+
+    if (config.onSecretRefreshed) {
+      this.refreshManager.onSecretRefreshed(config.onSecretRefreshed);
+    }
   }
 
   /**
@@ -171,6 +176,14 @@ export class VaultIntegration {
     }
   }
 
+  /**
+   * Register a callback for secret refresh events.
+   * Can be called before or after initialization.
+   */
+  onSecretRefreshed(callback: SecretRefreshCallback): void {
+    this.refreshManager.onSecretRefreshed(callback);
+  }
+
   /**
    * Get Vault health status
    */