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

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './config.errors';
 export * from './config.model';
 export * from './json-schema.validator';
 export * from './environment.service';
+export * from './vault';

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

@@ -0,0 +1,226 @@
+/**
+ * Vault Integration Tests
+ * These tests require a local Vault instance and are skipped in CI.
+ * To run locally:
+ *   docker compose -f docker-compose.vault.yml up -d
+ *   bash scripts/vault-setup.sh
+ *   VAULT_INTEGRATION_TESTS=true npm test
+ */
+
+import { IsString } from 'class-validator';
+
+import { VaultKey, VaultPath } from '../decorators';
+import { IVaultConfigOptions } from '../types';
+import { VaultIntegration } from '../vault-integration';
+
+import 'reflect-metadata';
+
+// Skip these tests unless explicitly enabled (requires running Vault)
+const SKIP_VAULT_TESTS = !process.env.VAULT_INTEGRATION_TESTS;
+
+/**
+ * Test configuration class with Vault secrets
+ * Note: VaultPath should use logical paths (without engine-specific prefix)
+ * The engine prefix (secret/data/ for kv-v2) is added automatically
+ */
+class TestVaultConfig {
+  @VaultPath('configit/api')
+  @VaultKey('api_key')
+  @IsString()
+    API_KEY!: string;
+
+  @VaultPath('configit/api')
+  @VaultKey('api_secret')
+  @IsString()
+    API_SECRET!: string;
+
+  @VaultPath('configit/database')
+  @VaultKey('host')
+  @IsString()
+    DB_HOST!: string;
+
+  @VaultPath('configit/database')
+  @VaultKey('port')
+  @IsString()
+    DB_PORT!: string;
+
+  @VaultPath('configit/database')
+  @VaultKey('username')
+  @IsString()
+    DB_USERNAME!: string;
+
+  @VaultPath('configit/database')
+  @VaultKey('password')
+  @IsString()
+    DB_PASSWORD!: string;
+
+  @VaultPath('configit/features')
+  @VaultKey('enable_beta')
+  @IsString()
+    ENABLE_BETA!: string;
+
+  @VaultPath('configit/features')
+  @VaultKey('max_connections')
+  @IsString()
+    MAX_CONNECTIONS!: string;
+}
+
+const VAULT_CONFIG: IVaultConfigOptions = {
+  endpoint: 'http://127.0.0.1:8200',
+  auth: {
+    methods: [
+      {
+        type: 'token',
+        config: {
+          token: process.env.VAULT_TOKEN || 'configit-dev-token'
+        }
+      }
+    ]
+  },
+  tls: {
+    enabled: false,
+    verifyCertificate: false
+  }
+};
+
+// Use describe.skip when Vault is not available
+const describeVault = SKIP_VAULT_TESTS ? describe.skip : describe;
+
+describeVault('VaultIntegration (requires running Vault)', () => {
+  let vaultIntegration: VaultIntegration;
+
+  afterEach(() => {
+    if (vaultIntegration) {
+      vaultIntegration.shutdown();
+    }
+  });
+
+  describe('when Vault is available', () => {
+    beforeEach(() => {
+      vaultIntegration = new VaultIntegration(VAULT_CONFIG);
+    });
+
+    it('should initialize successfully', async () => {
+      await vaultIntegration.initialize();
+      expect(vaultIntegration.isInitialized()).toBe(true);
+    });
+
+    it('should load secrets for a config class', async () => {
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(TestVaultConfig);
+
+      // Verify secrets are cached
+      expect(vaultIntegration.getSecret('API_KEY')).toBe('test-api-key-123');
+      expect(vaultIntegration.getSecret('API_SECRET')).toBe('test-api-secret-xyz');
+      expect(vaultIntegration.getSecret('DB_HOST')).toBe('localhost');
+      expect(vaultIntegration.getSecret('DB_PORT')).toBe('5432');
+      expect(vaultIntegration.getSecret('DB_USERNAME')).toBe('testuser');
+      expect(vaultIntegration.getSecret('DB_PASSWORD')).toBe('testpassword');
+      expect(vaultIntegration.getSecret('ENABLE_BETA')).toBe('true');
+      expect(vaultIntegration.getSecret('MAX_CONNECTIONS')).toBe('100');
+    });
+
+    it('should report healthy status after initialization', async () => {
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(TestVaultConfig);
+
+      const health = vaultIntegration.getHealth();
+      expect(health.connected).toBe(true);
+      expect(health.authenticated).toBe(true);
+      expect(health.cacheSize).toBeGreaterThan(0);
+    });
+
+    it('should invalidate cache entries', async () => {
+      await vaultIntegration.initialize();
+      await vaultIntegration.loadSecrets(TestVaultConfig);
+
+      // Verify secret is cached
+      expect(vaultIntegration.getSecret('API_KEY')).toBe('test-api-key-123');
+
+      // Invalidate
+      vaultIntegration.invalidateProperty('API_KEY');
+
+      // Should be null after invalidation
+      expect(vaultIntegration.getSecret('API_KEY')).toBeNull();
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw error when not initialized', async () => {
+      vaultIntegration = new VaultIntegration(VAULT_CONFIG);
+
+      await expect(vaultIntegration.loadSecrets(TestVaultConfig))
+        .rejects
+        .toThrow('VaultIntegration not initialized');
+    });
+
+    it('should throw error with invalid token', async () => {
+      const invalidConfig: IVaultConfigOptions = {
+        ...VAULT_CONFIG,
+        auth: {
+          methods: [
+            {
+              type: 'token',
+              config: {
+                token: 'invalid-token'
+              }
+            }
+          ]
+        }
+      };
+
+      vaultIntegration = new VaultIntegration(invalidConfig);
+
+      await expect(vaultIntegration.initialize())
+        .rejects
+        .toThrow(/authentication.*failed/i);
+    });
+  });
+});
+
+/**
+ * Run this file directly to test Vault integration:
+ *   npx ts-node src/vault/__tests__/vault-integration.test.ts
+ */
+if (require.main === module) {
+  (async () => {
+    console.log('Testing Vault Integration...\n');
+
+    const integration = new VaultIntegration(VAULT_CONFIG);
+
+    try {
+      console.log('1. Initializing...');
+      await integration.initialize();
+      console.log('   ✓ Initialized\n');
+
+      console.log('2. Loading secrets...');
+      await integration.loadSecrets(TestVaultConfig);
+      console.log('   ✓ Secrets loaded\n');
+
+      console.log('3. Reading secrets:');
+      console.log(`   API_KEY: ${ integration.getSecret('API_KEY') }`);
+      console.log(`   API_SECRET: ${ integration.getSecret('API_SECRET') }`);
+      console.log(`   DB_HOST: ${ integration.getSecret('DB_HOST') }`);
+      console.log(`   DB_PORT: ${ integration.getSecret('DB_PORT') }`);
+      console.log(`   DB_USERNAME: ${ integration.getSecret('DB_USERNAME') }`);
+      console.log(`   DB_PASSWORD: ${ integration.getSecret('DB_PASSWORD') }`);
+      console.log(`   ENABLE_BETA: ${ integration.getSecret('ENABLE_BETA') }`);
+      console.log(`   MAX_CONNECTIONS: ${ integration.getSecret('MAX_CONNECTIONS') }\n`);
+
+      console.log('4. Health status:');
+      const health = integration.getHealth();
+      console.log(`   Connected: ${ health.connected }`);
+      console.log(`   Authenticated: ${ health.authenticated }`);
+      console.log(`   Cache size: ${ health.cacheSize }`);
+      console.log(`   Errors: ${ health.errors.length }\n`);
+
+      console.log('✓ All tests passed!\n');
+    } catch (error) {
+      console.error('✗ Test failed:', error);
+      process.exit(1);
+    } finally {
+      integration.shutdown();
+    }
+  })();
+}
+

package/src/vault/decorators.ts

@@ -0,0 +1,228 @@
+/**
+ * Vault Decorators
+ * Composable decorators for marking configuration properties as Vault secrets
+ */
+
+import { kebabCase } from 'lodash';
+
+import { VaultEngineType, VaultPropertyMetadata } from './types';
+
+import 'reflect-metadata';
+
+/**
+ * Symbols for storing individual decorator metadata
+ */
+const VAULT_PATH_SYMBOL = Symbol('configit:vault:path');
+const VAULT_ENGINE_SYMBOL = Symbol('configit:vault:engine');
+const VAULT_KEY_SYMBOL = Symbol('configit:vault:key');
+const VAULT_REFRESH_BUFFER_SYMBOL = Symbol('configit:vault:refreshBuffer');
+const VAULT_OPTIONAL_SYMBOL = Symbol('configit:vault:optional');
+const VAULT_PROPERTIES_SYMBOL = Symbol('configit:vault:properties');
+
+/**
+ * Register a property as having Vault metadata (for discovery)
+ */
+function registerVaultProperty(target: unknown, propertyKey: string): void {
+  const constructor = (target as object).constructor;
+  const existingProperties: string[] = Reflect.getMetadata(VAULT_PROPERTIES_SYMBOL, constructor) || [];
+  if (!existingProperties.includes(propertyKey)) {
+    Reflect.defineMetadata(VAULT_PROPERTIES_SYMBOL, [ ...existingProperties, propertyKey ], constructor);
+  }
+}
+
+/**
+ * Get all registered Vault property names for a class
+ */
+export function getVaultPropertyNames(target: unknown): string[] {
+  const constructor = typeof target === 'function' ? target : (target as object).constructor;
+  return Reflect.getMetadata(VAULT_PROPERTIES_SYMBOL, constructor) || [];
+}
+
+/**
+ * Specifies the Vault path for a property (required for Vault secrets)
+ * @param path Full Vault path (e.g., 'secret/data/myapp/db_password' or 'database/creds/my-role')
+ */
+export function VaultPath(path: string): PropertyDecorator {
+  return function(target: unknown, propertyKey: string | symbol) {
+    const key = String(propertyKey);
+    Reflect.defineMetadata(VAULT_PATH_SYMBOL, path, target, key);
+    // Register this property for discovery
+    registerVaultProperty(target, key);
+  };
+}
+
+/**
+ * Specifies the Vault secrets engine type (optional, auto-detected from path)
+ * @param engine Engine type
+ */
+export function VaultEngine(engine: VaultEngineType): PropertyDecorator {
+  return function(target: unknown, propertyKey: string | symbol) {
+    const key = String(propertyKey);
+    Reflect.defineMetadata(VAULT_ENGINE_SYMBOL, engine, target, key);
+  };
+}
+
+/**
+ * Specifies the key name within the secret (optional, defaults to property name in kebab-case)
+ * Only used for KV v1/v2 engines
+ * @param key Key name
+ */
+export function VaultKey(key: string): PropertyDecorator {
+  return function(target: unknown, propertyKey: string | symbol) {
+    const keyName = String(propertyKey);
+    Reflect.defineMetadata(VAULT_KEY_SYMBOL, key, target, keyName);
+  };
+}
+
+/**
+ * Override default refresh buffer (optional)
+ * @param seconds Refresh buffer in seconds (default: 300s or 10% of TTL, whichever is smaller)
+ */
+export function VaultRefreshBuffer(seconds: number): PropertyDecorator {
+  return function(target: unknown, propertyKey: string | symbol) {
+    const key = String(propertyKey);
+    Reflect.defineMetadata(VAULT_REFRESH_BUFFER_SYMBOL, seconds, target, key);
+  };
+}
+
+/**
+ * Mark secret as optional - fallback to environment variable if Vault unavailable
+ * Without this decorator, Vault secrets are required by default
+ */
+export function VaultOptional(): PropertyDecorator {
+  return function(target: unknown, propertyKey: string | symbol) {
+    const key = String(propertyKey);
+    Reflect.defineMetadata(VAULT_OPTIONAL_SYMBOL, true, target, key);
+  };
+}
+
+/**
+ * Get Vault path for a property
+ */
+export function getVaultPath(target: any, propertyKey: string): string | undefined {
+  return Reflect.getMetadata(VAULT_PATH_SYMBOL, target, propertyKey);
+}
+
+/**
+ * Get Vault engine for a property
+ */
+export function getVaultEngine(target: any, propertyKey: string): VaultEngineType | undefined {
+  return Reflect.getMetadata(VAULT_ENGINE_SYMBOL, target, propertyKey);
+}
+
+/**
+ * Get Vault key for a property
+ */
+export function getVaultKey(target: any, propertyKey: string): string | undefined {
+  return Reflect.getMetadata(VAULT_KEY_SYMBOL, target, propertyKey);
+}
+
+/**
+ * Get Vault refresh buffer for a property
+ */
+export function getVaultRefreshBuffer(target: any, propertyKey: string): number | undefined {
+  return Reflect.getMetadata(VAULT_REFRESH_BUFFER_SYMBOL, target, propertyKey);
+}
+
+/**
+ * Check if Vault secret is optional for a property
+ */
+export function isVaultOptional(target: any, propertyKey: string): boolean {
+  return Reflect.getMetadata(VAULT_OPTIONAL_SYMBOL, target, propertyKey) === true;
+}
+
+/**
+ * Detect engine type from Vault path
+ */
+export function detectEngineFromPath(path: string): VaultEngineType {
+  // Common path patterns
+  if (path.startsWith('secret/data/')) {
+    return 'kv-v2';
+  }
+  if (path.startsWith('secret/') && !path.includes('/data/')) {
+    return 'kv-v1';
+  }
+  if (path.startsWith('database/creds/')) {
+    return 'database';
+  }
+  if (path.startsWith('aws/creds/')) {
+    return 'aws';
+  }
+  if (path.startsWith('azure/creds/')) {
+    return 'azure';
+  }
+  if (path.startsWith('gcp/')) {
+    return 'gcp';
+  }
+  if (path.startsWith('transit/')) {
+    return 'transit';
+  }
+  if (path.startsWith('pki/')) {
+    return 'pki';
+  }
+
+  // Default to kv-v2 (most common)
+  return 'kv-v2';
+}
+
+/**
+ * Get property type from metadata (basic implementation)
+ */
+function getPropertyType(target: any, propertyKey: string): string {
+  // Try to get type from reflect-metadata
+  const type = Reflect.getMetadata('design:type', target, propertyKey);
+  if (type) {
+    return type.name || 'unknown';
+  }
+  return 'unknown';
+}
+
+/**
+ * Build complete Vault metadata for a property from individual decorators
+ */
+export function buildVaultMetadata(
+  target: any,
+  propertyKey: string
+): VaultPropertyMetadata | undefined {
+  const path = getVaultPath(target, propertyKey);
+  if (!path) {
+    return undefined; // Not a Vault property
+  }
+
+  const engine = getVaultEngine(target, propertyKey) || detectEngineFromPath(path);
+  const key = getVaultKey(target, propertyKey) || kebabCase(propertyKey);
+  const refreshBuffer = getVaultRefreshBuffer(target, propertyKey);
+  const optional = isVaultOptional(target, propertyKey);
+  const propertyType = getPropertyType(target, propertyKey);
+
+  return {
+    path,
+    engine,
+    key,
+    refreshBuffer,
+    required: !optional,
+    propertyName: propertyKey,
+    propertyType
+  };
+}
+
+/**
+ * Get all Vault metadata for a class
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getAllVaultMetadata(target: any): Record<string, VaultPropertyMetadata> {
+  const metadata: Record<string, VaultPropertyMetadata> = {};
+
+  // Get registered Vault properties
+  const propertyKeys = getVaultPropertyNames(target);
+  const prototype = target.prototype || target;
+
+  for (const key of propertyKeys) {
+    const vaultMetadata = buildVaultMetadata(prototype, key);
+    if (vaultMetadata) {
+      metadata[key] = vaultMetadata;
+    }
+  }
+
+  return metadata;
+}

package/src/vault/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Vault Integration Module
+ * Exports for HashiCorp Vault integration
+ */
+
+// Types
+export * from './types';
+
+// Decorators
+export {
+  VaultPath,
+  VaultEngine,
+  VaultKey,
+  VaultRefreshBuffer,
+  VaultOptional,
+  getVaultPath,
+  getVaultEngine,
+  getVaultKey,
+  getVaultRefreshBuffer,
+  isVaultOptional,
+  detectEngineFromPath,
+  buildVaultMetadata,
+  getAllVaultMetadata,
+  getVaultPropertyNames
+} from './decorators';
+
+// Components
+export { VaultProvider } from './vault-provider';
+export { VaultCache } from './vault-cache';
+export { SecretRefreshManager } from './secret-refresh-manager';
+export { VaultIntegration } from './vault-integration';