{"_id":"@aion2hub/vault-client","name":"@aion2hub/vault-client","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aion2hub/vault-client","version":"1.0.0","description":"HashiCorp Vault client library for Aion2Hub services","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","watch":"tsc --watch","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"keywords":["vault","secrets","hashicorp","aion2hub","vault-client","secrets-management"],"author":{"name":"Aion2Hub Team"},"license":"MIT","dependencies":{"node-vault":"^0.10.2"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0"},"engines":{"node":">=20.0.0"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/WhileTureDev/Aion2Hub.git","directory":"packages/vault-client"},"_id":"@aion2hub/vault-client@1.0.0","gitHead":"aaaada05ac21b98ba20a9657cc2b6ad0f80cbada","bugs":{"url":"https://github.com/WhileTureDev/Aion2Hub/issues"},"homepage":"https://github.com/WhileTureDev/Aion2Hub#readme","_nodeVersion":"22.19.0","_npmVersion":"11.6.0","dist":{"integrity":"sha512-8OXSq0JkETpsaf3uZ6xZ/7wn6pjcjrXYkziRGN2M5QGqIpRurTJy/EcpR+HGXgmnccOJ93fesJPDP6mO7B1NiQ==","shasum":"ee403a4e3b2d4926c033c3615e736134dfd7eb5a","tarball":"https://registry.npmjs.org/@aion2hub/vault-client/-/vault-client-1.0.0.tgz","fileCount":6,"unpackedSize":17152,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHTcCRyTZgTsNIWSBbjS0mmiy9I93Y+6MqKuofgyGeB5AiEAhNwVjbqBmnXLGVDqUfuSeNXVWkVZ0NpfBCLph/kvX4s="}]},"_npmUser":{"name":"constantinradulescu","email":"constatin.r@gmail.com"},"directories":{},"maintainers":[{"name":"constantinradulescu","email":"constatin.r@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vault-client_1.0.0_1759269257775_0.9967113977543036"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-30T21:54:17.693Z","1.0.0":"2025-09-30T21:54:17.962Z","modified":"2025-09-30T21:54:18.254Z"},"maintainers":[{"name":"constantinradulescu","email":"constatin.r@gmail.com"}],"description":"HashiCorp Vault client library for Aion2Hub services","homepage":"https://github.com/WhileTureDev/Aion2Hub#readme","keywords":["vault","secrets","hashicorp","aion2hub","vault-client","secrets-management"],"repository":{"type":"git","url":"git+https://github.com/WhileTureDev/Aion2Hub.git","directory":"packages/vault-client"},"author":{"name":"Aion2Hub Team"},"bugs":{"url":"https://github.com/WhileTureDev/Aion2Hub/issues"},"license":"MIT","readme":"# @aion2hub/vault-client\n\nHashiCorp Vault client library for Aion2Hub microservices.\n\n## Features\n\n- ✅ **AppRole Authentication**: Secure service-to-service authentication\n- ✅ **Automatic Token Renewal**: Handles token expiration automatically\n- ✅ **Retry Logic**: Exponential backoff for failed requests\n- ✅ **Fallback Support**: Falls back to environment variables if Vault is unavailable\n- ✅ **TypeScript**: Full TypeScript support with type definitions\n- ✅ **Connection Pooling**: Efficient connection management\n- ✅ **Error Handling**: Comprehensive error handling and logging\n\n## Installation\n\n```bash\nnpm install @aion2hub/vault-client\n```\n\n## Usage\n\n### Basic Usage\n\n```typescript\nimport { VaultClient } from '@aion2hub/vault-client';\n\nconst client = new VaultClient({\n  vaultAddr: 'http://vault:8200',\n  roleId: process.env.VAULT_ROLE_ID,\n  secretId: process.env.VAULT_SECRET_ID,\n  enableFallback: true,\n});\n\nawait client.initialize();\n\n// Get a secret\nconst dbSecret = await client.getSecret('aion2hub/data/shared/database');\nconsole.log(dbSecret.password);\n\n// Get a specific field\nconst jwtSecret = await client.getSecretField('aion2hub/data/shared/jwt', 'secret');\n\n// Get database URL\nconst dbUrl = await client.getDatabaseUrl('aion2hub_users');\n```\n\n### Using Environment Variables\n\n```typescript\nimport { createVaultClientFromEnv } from '@aion2hub/vault-client';\n\nconst client = createVaultClientFromEnv();\nawait client.initialize();\n\nconst secrets = await client.getSecret('aion2hub/data/services/user-service');\n```\n\n### Development Mode (with root token)\n\n```typescript\nconst client = new VaultClient({\n  vaultAddr: 'http://vault:8200',\n  token: 'dev-root-token',\n});\n\nawait client.initialize();\n```\n\n## Configuration\n\n### VaultClientConfig\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `vaultAddr` | string | required | Vault server address |\n| `roleId` | string | optional | AppRole role_id |\n| `secretId` | string | optional | AppRole secret_id |\n| `token` | string | optional | Root token (dev only) |\n| `enableFallback` | boolean | `true` | Enable fallback to env vars |\n| `maxRetries` | number | `3` | Maximum retry attempts |\n| `retryDelay` | number | `1000` | Initial retry delay (ms) |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `VAULT_ADDR` | Vault server address |\n| `VAULT_ROLE_ID` | AppRole role_id |\n| `VAULT_SECRET_ID` | AppRole secret_id |\n| `VAULT_TOKEN` | Root token (dev only) |\n| `VAULT_ENABLE_FALLBACK` | Enable fallback (`true`/`false`) |\n\n## API Reference\n\n### `VaultClient`\n\n#### `initialize(): Promise<void>`\nInitialize the client and authenticate with Vault.\n\n#### `getSecret(path: string): Promise<SecretData>`\nGet a secret from Vault.\n\n```typescript\nconst secret = await client.getSecret('aion2hub/data/shared/database');\n// { host: 'postgres', port: '5432', user: 'aion2hub', password: '...' }\n```\n\n#### `getSecrets(paths: string[]): Promise<Record<string, SecretData>>`\nGet multiple secrets at once.\n\n```typescript\nconst secrets = await client.getSecrets([\n  'aion2hub/data/shared/database',\n  'aion2hub/data/shared/jwt',\n]);\n```\n\n#### `getSecretField(path: string, field: string, defaultValue?: string): Promise<string>`\nGet a specific field from a secret.\n\n```typescript\nconst password = await client.getSecretField(\n  'aion2hub/data/shared/database',\n  'password',\n  'default-password'\n);\n```\n\n#### `getDatabaseUrl(dbName: string): Promise<string>`\nBuild a PostgreSQL connection URL from Vault secrets.\n\n```typescript\nconst dbUrl = await client.getDatabaseUrl('aion2hub_users');\n// postgresql://aion2hub:password123@postgres:5432/aion2hub_users\n```\n\n#### `healthCheck(): Promise<boolean>`\nCheck if Vault is healthy and unsealed.\n\n```typescript\nconst isHealthy = await client.healthCheck();\n```\n\n#### `isAuthenticated(): boolean`\nCheck if the client is authenticated.\n\n```typescript\nif (client.isAuthenticated()) {\n  console.log('Client is authenticated');\n}\n```\n\n## Error Handling\n\nThe client includes comprehensive error handling:\n\n```typescript\ntry {\n  const secret = await client.getSecret('aion2hub/data/shared/database');\n} catch (error) {\n  console.error('Failed to retrieve secret:', error);\n  // Fallback to environment variables if enabled\n}\n```\n\n## Retry Logic\n\nFailed requests are automatically retried with exponential backoff:\n\n- Attempt 1: Immediate\n- Attempt 2: 1 second delay\n- Attempt 3: 2 second delay\n- Attempt 4: 4 second delay (if maxRetries > 3)\n\n## Fallback Mode\n\nWhen `enableFallback` is true (default), the client will return empty objects instead of throwing errors if Vault is unavailable. This allows services to fall back to environment variables.\n\n```typescript\nconst client = new VaultClient({\n  vaultAddr: 'http://vault:8200',\n  roleId: process.env.VAULT_ROLE_ID,\n  secretId: process.env.VAULT_SECRET_ID,\n  enableFallback: true, // Enable fallback\n});\n\n// If Vault is down, this returns {} instead of throwing\nconst secret = await client.getSecret('aion2hub/data/shared/database');\n\n// Use fallback values\nconst dbPassword = secret.password || process.env.DB_PASSWORD;\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Watch mode\nnpm run watch\n\n# Clean\nnpm run clean\n```\n\n## License\n\nMIT\n\n","readmeFilename":"README.md","_rev":"1-2fd176b44e4e53a6213fdf40839400bb"}