@cemiar/keyvault-sdk

A TypeScript SDK for managing Azure Key Vault secrets with support for both single and multiple vault connections.

Installation

npm install @cemiar/keyvault-sdk

Features

• KeyVaultManager: Singleton pattern for single Key Vault connection
• KeyVaultFactory: Factory pattern for managing multiple Key Vault connections
• Support for local development using Azure CLI credentials
• Support for service principal authentication in production

Usage

Single Key Vault (KeyVaultManager)

Use KeyVaultManager when your application only needs to connect to one Key Vault.

import { KeyVaultManager } from '@cemiar/keyvault-sdk';

// Initialize once at application startup

// Option 1: Local development (uses Azure CLI credentials)
KeyVaultManager.initialize({
    keyVaultUrl: 'https://my-vault.vault.azure.net',
    useDefaultCred: true,
});

// Option 2: Production with service principal
KeyVaultManager.initialize({
    keyVaultUrl: 'https://my-vault.vault.azure.net',
    tenantId: 'your-tenant-id',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
});

// Use anywhere in your application
const manager = KeyVaultManager.getInstance();
const secret = await manager.loadSecret('my-secret');

Multiple Key Vaults (KeyVaultFactory)

Use KeyVaultFactory when your application needs to connect to multiple Key Vaults simultaneously.

import { KeyVaultFactory } from '@cemiar/keyvault-sdk';

const factory = new KeyVaultFactory();

// Register multiple vaults
factory.registerVault({
    name: 'primary',
    keyVaultUrl: 'https://primary-vault.vault.azure.net',
    useDefaultCred: true,
    makeDefault: true,
});

factory.registerVault({
    name: 'secondary',
    keyVaultUrl: 'https://secondary-vault.vault.azure.net',
    tenantId: 'your-tenant-id',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
});

// Load secrets from specific vaults
const primarySecret = await factory.loadSecretFromVault('primary', 'my-secret');
const secondarySecret = await factory.loadSecretFromVault('secondary', 'other-secret');

// Or use the default vault
const secret = await factory.loadSecret('my-secret');

// Create secrets
await factory.createSecretInVault('primary', 'new-secret', 'secret-value');

// List registered vaults
const vaults = factory.listRegisteredVaults(); // ['primary', 'secondary']

// Change default vault
factory.setDefaultVault('secondary');

// Unregister a vault
factory.unregisterVault('secondary');

Authentication Options

Local Development

For local development, set useDefaultCred: true to use Azure CLI credentials:

{
    keyVaultUrl: 'https://my-vault.vault.azure.net',
    useDefaultCred: true
}

Make sure you're logged in via Azure CLI:

az login

Service Principal (Production)

For production environments, use service principal credentials:

{
    keyVaultUrl: 'https://my-vault.vault.azure.net',
    tenantId: 'your-tenant-id',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret'
}

API Reference

KeyVaultManager

| Method | Description | | --------------------------------------- | ------------------------------------- | | initialize(options) | Initialize the singleton instance | | getInstance() | Get the singleton instance | | loadSecret(secretName) | Load a secret from the vault | | createSecret(secretName, secretValue) | Create a new secret | | getSecretClient() | Get the underlying Azure SecretClient | | getOptions() | Get the current connection options |

KeyVaultFactory

| Method | Description | | --------------------------------------------------------- | ------------------------------------------------ | | registerVault(options) | Register a new Key Vault connection | | unregisterVault(name) | Remove a vault from the registry | | setDefaultVault(name) | Set the default vault | | getSecretClient(name?) | Get SecretClient for a specific or default vault | | loadSecret(secretName) | Load a secret from the default vault | | loadSecretFromVault(vaultName, secretName) | Load a secret from a specific vault | | createSecret(secretName, secretValue) | Create a secret in the default vault | | createSecretInVault(vaultName, secretName, secretValue) | Create a secret in a specific vault | | listRegisteredVaults() | List all registered vault names | | getDefaultVaultName() | Get the name of the default vault |

Types

interface KeyVaultAuthOptions {
    useDefaultCred?: boolean;
    tenantId?: string;
    clientId?: string;
    clientSecret?: string;
}

interface KeyVaultConnectionOptions extends KeyVaultAuthOptions {
    keyVaultUrl: string;
}

interface VaultRegistrationOptions extends KeyVaultConnectionOptions {
    name: string;
    makeDefault?: boolean;
}

Requirements

• Node.js >= 18.16.0
• npm >= 9.5.1

License

ISC