@rytass/secret-adapter-vault-nestjs 0.3.3 → 0.4.1

package/README.md

@@ -1,30 +1,482 @@
-# Rytass Utils - Secret Manager Nestjs Module (Vault)
+# Rytass Utils - Secret Adapter Vault NestJS
 
-### Getting Started
+NestJS module for HashiCorp Vault integration, providing secure secret management with automatic fallback to environment variables. Seamlessly integrates with NestJS dependency injection and configuration system.
 
-This module will get vault config from env with @nestjs/common, please set following env before use.
+## Features
 
-- VAULT_HOST (Vault service base url)
-- VAULT_ACCOUNT
-- VAULT_PASSWORD
-- VAULT_PATH (Vault secret path from root)
+- [x] HashiCorp Vault integration for NestJS
+- [x] Automatic fallback to environment variables
+- [x] Global module support
+- [x] TypeScript support with generics
+- [x] Asynchronous secret retrieval
+- [x] Secret writing and deletion
+- [x] Online/offline sync support
+- [x] Connection state management
+- [x] Error handling with graceful degradation
+
+## Installation
+
+```bash
+npm install @rytass/secret-adapter-vault-nestjs @rytass/secret-adapter-vault
+# or
+yarn add @rytass/secret-adapter-vault-nestjs @rytass/secret-adapter-vault
+```
+
+## Environment Configuration
+
+Configure the following environment variables for Vault connection:
+
+```bash
+# Required for Vault connection
+VAULT_HOST=https://vault.example.com:8200  # Vault service base URL
+VAULT_ACCOUNT=your-username                # Vault username
+VAULT_PASSWORD=your-password               # Vault password
+
+# Optional - defaults to root path if not specified
+VAULT_PATH=/secret/data/myapp             # Vault secret path from root
+```
+
+## Basic Usage
+
+### Module Setup
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { VaultService, VaultModule } from '@rytass/secret-adapter-vault-nestjs';
+import { VaultModule } from '@rytass/secret-adapter-vault-nestjs';
+
+@Module({
+  imports: [
+    VaultModule.forRoot({
+      path: '/secret/data/myapp',  // Vault path for secrets
+      fallbackFile: '.env',         // Optional: fallback env file
+    })
+  ],
+})
+export class AppModule {}
+```
+
+### Global Module Configuration
+
+Make the VaultService available throughout your application:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { VaultModule } from '@rytass/secret-adapter-vault-nestjs';
+
+@Module({
+  imports: [
+    VaultModule.forRoot({
+      path: '/secret/data/myapp',
+      fallbackFile: '.env'
+    })
+  ],
+})
+export class AppModule {}
+```
+
+### Using VaultService
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { VaultService } from '@rytass/secret-adapter-vault-nestjs';
 
 @Injectable()
-class TestService {
+export class ConfigurationService {
   constructor(private readonly vault: VaultService) {}
 
-  async getValue() {
-    return vault.get<string>('key');
+  async getDatabaseConfig() {
+    const host = await this.vault.get<string>('DB_HOST');
+    const port = await this.vault.get<number>('DB_PORT');
+    const username = await this.vault.get<string>('DB_USERNAME');
+    const password = await this.vault.get<string>('DB_PASSWORD');
+
+    return {
+      host,
+      port,
+      username,
+      password
+    };
+  }
+
+  async getApiKey(): Promise<string> {
+    return this.vault.get<string>('API_KEY');
+  }
+
+  async updateApiKey(newKey: string): Promise<void> {
+    // Update locally and sync to Vault
+    await this.vault.set('API_KEY', newKey, true);
+  }
+}
+```
+
+## Advanced Usage
+
+### Type-Safe Secret Retrieval
+
+```typescript
+interface DatabaseConfig {
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  ssl: boolean;
+}
+
+@Injectable()
+export class DatabaseService {
+  constructor(private readonly vault: VaultService) {}
+
+  async getConfig(): Promise<DatabaseConfig> {
+    // Retrieve complex objects
+    return this.vault.get<DatabaseConfig>('database');
+  }
+
+  async getConnectionString(): Promise<string> {
+    const config = await this.getConfig();
+    return `postgresql://${config.username}:${config.password}@${config.host}:${config.port}/mydb`;
   }
 }
+```
+
+### Managing Secrets
+
+```typescript
+@Injectable()
+export class SecretManagementService {
+  constructor(private readonly vault: VaultService) {}
+
+  // Create or update a secret
+  async createSecret(key: string, value: any): Promise<void> {
+    // Save locally only
+    await this.vault.set(key, value, false);
+  }
+
+  // Create and sync to Vault immediately
+  async createAndSyncSecret(key: string, value: any): Promise<void> {
+    await this.vault.set(key, value, true);
+  }
+
+  // Delete a secret
+  async removeSecret(key: string): Promise<void> {
+    // Delete locally only
+    await this.vault.delete(key, false);
+  }
+
+  // Delete and sync removal to Vault
+  async removeAndSyncSecret(key: string): Promise<void> {
+    await this.vault.delete(key, true);
+  }
+}
+```
+
+### Fallback Mechanism
+
+When Vault is unavailable, the service automatically falls back to environment variables:
+
+```typescript
+@Injectable()
+export class ResilientConfigService {
+  constructor(private readonly vault: VaultService) {}
+
+  async getConfig() {
+    // If Vault is unavailable, this will read from process.env
+    const apiUrl = await this.vault.get<string>('API_URL');
+    const apiKey = await this.vault.get<string>('API_KEY');
+
+    return {
+      apiUrl,
+      apiKey
+    };
+  }
+}
+```
+
+### Environment File Configuration
+
+Specify a fallback environment file for when Vault is unavailable:
+
+```typescript
+// app.module.ts
+@Module({
+  imports: [
+    VaultModule.forRoot({
+      path: '/secret/data/production',
+      fallbackFile: '.env.production'  // Fallback to .env.production file
+    })
+  ],
+})
+export class AppModule {}
+```
+
+## Integration Examples
+
+### With TypeORM
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { VaultModule, VaultService } from '@rytass/secret-adapter-vault-nestjs';
 
 @Module({
-  imports: [VaultModule.forRoot({ path: '/', isGlobal: true })],
-  providers: [TestService],
+  imports: [
+    VaultModule.forRoot({
+      path: '/secret/data/database'
+    }),
+    TypeOrmModule.forRootAsync({
+      imports: [VaultModule],
+      inject: [VaultService],
+      useFactory: async (vault: VaultService) => ({
+        type: 'postgres',
+        host: await vault.get<string>('DB_HOST'),
+        port: await vault.get<number>('DB_PORT'),
+        username: await vault.get<string>('DB_USERNAME'),
+        password: await vault.get<string>('DB_PASSWORD'),
+        database: await vault.get<string>('DB_NAME'),
+        synchronize: false,
+        logging: true,
+      })
+    })
+  ],
 })
-class TestModule {};
+export class DatabaseModule {}
 ```
+
+### With JWT Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { JwtModule } from '@nestjs/jwt';
+import { VaultModule, VaultService } from '@rytass/secret-adapter-vault-nestjs';
+
+@Module({
+  imports: [
+    VaultModule.forRoot({
+      path: '/secret/data/auth'
+    }),
+    JwtModule.registerAsync({
+      imports: [VaultModule],
+      inject: [VaultService],
+      useFactory: async (vault: VaultService) => ({
+        secret: await vault.get<string>('JWT_SECRET'),
+        signOptions: {
+          expiresIn: await vault.get<string>('JWT_EXPIRY') || '1h'
+        }
+      })
+    })
+  ],
+})
+export class AuthModule {}
+```
+
+### With Microservices
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { Transport } from '@nestjs/microservices';
+import { VaultService } from '@rytass/secret-adapter-vault-nestjs';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  const vault = app.get(VaultService);
+
+  const microservice = await NestFactory.createMicroservice({
+    transport: Transport.REDIS,
+    options: {
+      host: await vault.get<string>('REDIS_HOST'),
+      port: await vault.get<number>('REDIS_PORT'),
+      password: await vault.get<string>('REDIS_PASSWORD'),
+    }
+  });
+
+  await app.startAllMicroservices();
+  await app.listen(3000);
+}
+```
+
+## Error Handling
+
+```typescript
+@Injectable()
+export class SafeConfigService {
+  constructor(private readonly vault: VaultService) {}
+
+  async getSensitiveConfig() {
+    try {
+      const secret = await this.vault.get<string>('SENSITIVE_KEY');
+      
+      if (!secret) {
+        throw new Error('Sensitive key not found');
+      }
+
+      return secret;
+    } catch (error) {
+      // When Vault is down, it falls back to env vars automatically
+      console.error('Failed to retrieve secret:', error);
+      
+      // You can implement additional fallback logic
+      return process.env.FALLBACK_SENSITIVE_KEY || 'default-value';
+    }
+  }
+
+  async trySaveSecret(key: string, value: string): Promise<boolean> {
+    try {
+      await this.vault.set(key, value, true);
+      return true;
+    } catch (error) {
+      // Cannot save when in fallback mode
+      console.error('Failed to save secret:', error.message);
+      return false;
+    }
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Use Type Parameters
+
+```typescript
+// Good - Type-safe
+const port = await vault.get<number>('PORT');
+const config = await vault.get<DatabaseConfig>('db_config');
+
+// Avoid - Returns any
+const value = await vault.get('SOME_KEY');
+```
+
+### 2. Handle Fallback Scenarios
+
+```typescript
+@Injectable()
+export class ConfigService {
+  constructor(private readonly vault: VaultService) {}
+
+  async initialize() {
+    try {
+      // Try to save a test value to check if Vault is writable
+      await this.vault.set('health_check', 'ok', true);
+      console.log('Vault is connected and writable');
+    } catch (error) {
+      console.warn('Running in read-only mode with environment variables');
+    }
+  }
+}
+```
+
+### 3. Organize Secrets by Path
+
+```typescript
+// auth.module.ts
+VaultModule.forRoot({ path: '/secret/data/auth' })
+
+// database.module.ts  
+VaultModule.forRoot({ path: '/secret/data/database' })
+
+// api.module.ts
+VaultModule.forRoot({ path: '/secret/data/external-apis' })
+```
+
+### 4. Use Environment-Specific Paths
+
+```typescript
+const environment = process.env.NODE_ENV || 'development';
+
+@Module({
+  imports: [
+    VaultModule.forRoot({
+      path: `/secret/data/${environment}`,
+      fallbackFile: `.env.${environment}`
+    })
+  ],
+})
+export class AppModule {}
+```
+
+## API Reference
+
+### VaultModule
+
+#### `forRoot(options: VaultModuleOptions): DynamicModule`
+
+Configure the Vault module.
+
+**Options:**
+- `path` (string, required): Vault secret path from root
+- `fallbackFile` (string, optional): Path to fallback environment file
+
+### VaultService
+
+#### `get<T>(key: string): Promise<T>`
+
+Retrieve a secret value.
+
+**Parameters:**
+- `key`: Secret key name
+
+**Returns:** Promise resolving to the secret value
+
+#### `set<T>(key: string, value: T, syncToOnline?: boolean): Promise<void>`
+
+Store a secret value.
+
+**Parameters:**
+- `key`: Secret key name
+- `value`: Value to store
+- `syncToOnline`: Whether to sync immediately to Vault (default: false)
+
+#### `delete(key: string, syncToOnline?: boolean): Promise<void>`
+
+Delete a secret.
+
+**Parameters:**
+- `key`: Secret key name
+- `syncToOnline`: Whether to sync deletion to Vault (default: false)
+
+## Migration from ConfigService
+
+```typescript
+// Before - Using ConfigService
+@Injectable()
+export class OldService {
+  constructor(private config: ConfigService) {}
+  
+  getValue() {
+    return this.config.get('MY_KEY');
+  }
+}
+
+// After - Using VaultService
+@Injectable()
+export class NewService {
+  constructor(private vault: VaultService) {}
+  
+  async getValue() {
+    return this.vault.get<string>('MY_KEY');
+  }
+}
+```
+
+## Troubleshooting
+
+### Vault Connection Issues
+
+If you see fallback warnings:
+1. Check `VAULT_HOST` is accessible
+2. Verify `VAULT_ACCOUNT` and `VAULT_PASSWORD` are correct
+3. Ensure `VAULT_PATH` exists in Vault
+4. Check network connectivity to Vault server
+
+### Type Safety
+
+Always specify type parameters for better TypeScript support:
+
+```typescript
+// Explicit types prevent runtime errors
+const port = await vault.get<number>('PORT');
+const features = await vault.get<string[]>('FEATURE_FLAGS');
+const config = await vault.get<AppConfig>('APP_CONFIG');
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/secret-adapter-vault-nestjs",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Rytass Sceret Vault nestjs adapter",
   "keywords": [
     "rytass",
@@ -24,7 +24,7 @@
     "reflect-metadata": "*"
   },
   "dependencies": {
-    "@rytass/secret-adapter-vault": "^0.3.2",
+    "@rytass/secret-adapter-vault": "^0.4.1",
     "regenerator-runtime": "^0.14.1"
   },
   "main": "./index.cjs.js",