# @eqxjs/azure-manage-identity

A TypeScript library for managing Azure Key Vault secrets and cryptographic operations using Azure Managed Identity.

Node: `>=22`

## Description

This library provides a simple interface to interact with Azure Key Vault for secret management, JWT token verification/signing, and data encryption/decryption operations. It uses Azure's DefaultAzureCredential for seamless authentication with managed identities.

## Installation

```bash
npm install @eqxjs/azure-manage-identity
```

## Features

- **Secret Management**: Get, set, list, and remove Azure Key Vault secrets
- **JWT Operations**: Verify and sign JWT tokens using Azure Key Vault keys
- **Data Encryption**: Encrypt and decrypt data using Azure Key Vault keys
- **Managed Identity**: Automatic authentication using Azure Managed Identity

## Functions

### Secret Management

#### `getSecret(keyvaultURL: string, secretName: string, secretOpt?: GetSecretOptions)`

Retrieves a secret from Azure Key Vault.

**Parameters:**

- `keyvaultURL` - The URL of the Azure Key Vault (e.g., `https://your-keyvault.vault.azure.net/`)
- `secretName` - The name of the secret to retrieve
- `secretOpt` - Optional settings for getting the secret

**Returns:** `Promise<KeyVaultSecret>`

**Example:**

```typescript
import { getSecret } from '@eqxjs/azure-manage-identity';

const secret = await getSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);
console.log(secret.value);
```

---

#### `setSecret(keyvaultURL: string, secretName: string, secretValue: string, secretOpt?: SetSecretOptions)`

Creates or updates a secret in Azure Key Vault.

**Parameters:**

- `keyvaultURL` - The URL of the Azure Key Vault
- `secretName` - The name of the secret to set
- `secretValue` - The value to store in the secret
- `secretOpt` - Optional settings for setting the secret

**Returns:** `Promise<KeyVaultSecret>`

**Example:**

```typescript
import { setSecret } from '@eqxjs/azure-manage-identity';

const secret = await setSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
  'my-secret-value',
);
```

---

#### `listSecretVersion(keyvaultURL: string, secretName: string, secretOpt?: ListPropertiesOfSecretVersionsOptions)`

Lists all versions of a specific secret.

**Parameters:**

- `keyvaultURL` - The URL of the Azure Key Vault
- `secretName` - The name of the secret
- `secretOpt` - Optional settings for listing secret versions

**Returns:** `PagedAsyncIterableIterator<SecretProperties>`

**Example:**

```typescript
import { listSecretVersion } from '@eqxjs/azure-manage-identity';

const versions = await listSecretVersion(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);

for await (const version of versions) {
  console.log(version.version);
}
```

---

#### `removeSecret(keyvaultURL: string, secretName: string, secretOpt?: BeginDeleteSecretOptions, clientOptions?: SecretClientOptions)`

Removes a secret from Azure Key Vault and waits until the deletion is complete.

**Parameters:**

- `keyvaultURL` - The URL of the Azure Key Vault
- `secretName` - The name of the secret to remove
- `secretOpt` - Optional settings for the delete operation
- `clientOptions` - Optional configuration for the Secret client

**Returns:** `Promise<DeletedSecret>`

**Example:**

```typescript
import { removeSecret } from '@eqxjs/azure-manage-identity';

const deleted = await removeSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);
console.log(deleted.deletedOn);
```

---

### JWT Token Operations

#### `verifyJWTToken(keyURL: string, keyName: string, algorithm: string, jwtToken: string)`

Verifies a JWT token using an Azure Key Vault cryptographic key.

**Parameters:**

- `keyURL` - The URL of the Azure Key Vault
- `keyName` - The name of the key to use for verification
- `algorithm` - The signing algorithm (e.g., 'RS256')
- `jwtToken` - The JWT token to verify

**Returns:** `Promise<VerifyResult>`

**Example:**

```typescript
import { verifyJWTToken } from '@eqxjs/azure-manage-identity';

const result = await verifyJWTToken(
  'https://your-keyvault.vault.azure.net/',
  'my-key',
  'RS256',
  'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
);
console.log(result.result); // true or false
```

---

#### `verifyJWTTokenBySecret(keyURL: string, secretName: string, jwtToken: string)`

Verifies a JWT token using a public key stored as a secret in Azure Key Vault. Supports JWKS (JSON Web Key Set) format.

**Parameters:**

- `keyURL` - The URL of the Azure Key Vault
- `secretName` - The name of the secret containing the public key/JWKS
- `jwtToken` - The JWT token to verify

**Returns:** `Promise<VerifyResult>`

**Example:**

```typescript
import { verifyJWTTokenBySecret } from '@eqxjs/azure-manage-identity';

const result = await verifyJWTTokenBySecret(
  'https://your-keyvault.vault.azure.net/',
  'jwks-secret',
  'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
);
```

---

#### `signJWTToken(keyURL: string, keyName: string, algorithm: string, payload: string)`

Signs a JWT payload using an Azure Key Vault cryptographic key.

**Parameters:**

- `keyURL` - The URL of the Azure Key Vault
- `keyName` - The name of the key to use for signing
- `algorithm` - The signing algorithm (e.g., 'RS256')
- `payload` - The payload to sign

**Returns:** `Promise<string>` - Base64URL-encoded signature

**Example:**

```typescript
import { signJWTToken } from '@eqxjs/azure-manage-identity';

const signature = await signJWTToken(
  'https://your-keyvault.vault.azure.net/',
  'my-key',
  'RS256',
  'header.payload',
);
```

---

### Data Encryption/Decryption

#### `encryptData(keyURL: string, keyName: string, payload: string, ivSecretName: string)`

Encrypts data using AES-256-CBC encryption with an Azure Key Vault key.

**Parameters:**

- `keyURL` - The URL of the Azure Key Vault
- `keyName` - The name of the key to use for encryption
- `payload` - The data to encrypt
- `ivSecretName` - The name of the secret containing the initialization vector (IV)

**Returns:** `Promise<string>` - Base64URL-encoded encrypted data

**Example:**

```typescript
import { encryptData } from '@eqxjs/azure-manage-identity';

const encrypted = await encryptData(
  'https://your-keyvault.vault.azure.net/',
  'encryption-key',
  'sensitive data',
  'iv-secret',
);
```

---

#### `decryptData(keyURL: string, keyName: string, payloadBase64: string, ivSecretName: string)`

Decrypts data that was encrypted using AES-256-CBC encryption.

**Parameters:**

- `keyURL` - The URL of the Azure Key Vault
- `keyName` - The name of the key to use for decryption
- `payloadBase64` - The Base64URL-encoded encrypted data
- `ivSecretName` - The name of the secret containing the initialization vector (IV)

**Returns:** `Promise<string>` - Decrypted plaintext data

**Example:**

```typescript
import { decryptData } from '@eqxjs/azure-manage-identity';

const decrypted = await decryptData(
  'https://your-keyvault.vault.azure.net/',
  'encryption-key',
  'base64url-encoded-ciphertext',
  'iv-secret',
);
```

---

## Authentication

This library uses Azure's `DefaultAzureCredential` for authentication, which automatically handles:

- Managed Identity (for Azure-hosted applications)
- Azure CLI credentials
- Environment variables
- Visual Studio Code credentials
- And other Azure authentication methods

Ensure your application has the appropriate permissions to access the Azure Key Vault resources.

## Required Azure Key Vault Permissions

Your managed identity or service principal needs the following permissions:

### For Secret Operations:

- `Get` - To read secrets
- `Set` - To create/update secrets
- `List` - To list secret versions
- `Delete` - To remove secrets

### For Key Operations:

- `Get` - To retrieve keys
- `Sign` - To sign data/JWT tokens
- `Verify` - To verify signatures
- `Encrypt` - To encrypt data
- `Decrypt` - To decrypt data

## Dependencies

This library depends on:

- `@azure/identity` - Azure authentication
- `@azure/keyvault-keys` - Key Vault key operations
- `@azure/keyvault-secrets` - Key Vault secret operations
- `jsonwebtoken` - JWT operations
- `base64url` - Base64URL encoding/decoding

## License

ISC

## Author

Equinox