npm package: @kevboutin/azure-middy-keyvault-secrets
Description: Azure Key Vault Secrets middleware for the azure-middy framework
Author: Azure-Middy contributors
Latest version: 0.2.14

# azure-middy-keyvault-secrets

Azure Key Vault Secrets middleware for the azure-middy framework, the Node.js middleware engine for Azure functions.

## Install

To install the this middleware, you can use NPM:

```bash
npm install --save @kevboutin/azure-middy-keyvault-secrets
```

## Prerequisites

- Node.js >= 18
- An Azure Function App
- An Azure Key Vault instance
- Proper Azure credentials configured (using DefaultAzureCredential)

## Usage

The middleware provides Azure Key Vault secrets management for your Azure Functions.

### JavaScript (CommonJS)

```javascript
const { app } = require("@azure/functions");
const middy = require("@kevboutin/azure-middy-core");
const {
    keyvaultSecretsMiddleware,
} = require("@kevboutin/azure-middy-keyvault-secrets");

// Your handler
const baseHandler = async (req, context) => {
    // Your business logic here
    // Secrets are available in req.internal
    return {
        body: JSON.stringify({ message: "Success" }),
    };
};

// Wrap handler with middy
const handler = middy(baseHandler).use(
    keyvaultSecretsMiddleware({
        vaultUrl: "https://your-vault.vault.azure.net",
        fetchData: {
            apiKey: "api-key-secret-name",
            dbPassword: "db-password-secret-name",
        },
        cacheKey: "my-secrets",
    }),
);

module.exports = { handler };

app.http("yourFunction", {
    route: "your-route",
    methods: ["GET"],
    authLevel: "anonymous",
    handler: handler,
});
```

### TypeScript

```typescript
import { app } from "@azure/functions";
import middy from "@kevboutin/azure-middy-core";
import {
    keyvaultSecretsMiddleware,
    KeyVaultSecretsOptions,
} from "@kevboutin/azure-middy-keyvault-secrets";
import type { AzureFunctionRequest } from "@kevboutin/azure-middy-types";

// Your handler
const baseHandler = async (req: AzureFunctionRequest, context: any) => {
    // Access secrets from the request internal object
    const apiKey = req.internal?.["apiKey"];
    const dbPassword = req.internal?.["dbPassword"];

    console.log("Retrieved secrets:", {
        hasApiKey: !!apiKey,
        hasDbPassword: !!dbPassword,
    });

    return {
        body: JSON.stringify({ message: "Success" }),
    };
};

// Configure Key Vault options with TypeScript
const keyVaultOptions: KeyVaultSecretsOptions = {
    vaultUrl: "https://your-vault.vault.azure.net",
    fetchData: {
        apiKey: "api-key-secret-name",
        dbPassword: "db-password-secret-name",
        jwtSecret: "jwt-signing-key",
    },
    cacheKey: "my-secrets",
};

// Wrap handler with middy
const handler = middy(baseHandler).use(
    keyvaultSecretsMiddleware(keyVaultOptions),
);

export { handler };

app.http("yourFunction", {
    route: "your-route",
    methods: ["GET"],
    authLevel: "anonymous",
    handler: handler,
});
```

## TypeScript Support

This package includes full TypeScript support with:

- **Type Definitions**: Complete type definitions for all Key Vault interfaces and functions
- **Type Safety**: Full type checking for middleware options and request objects
- **IntelliSense**: Enhanced IDE support with autocomplete and type hints

### Available Types

```typescript
import {
    KeyVaultSecretsOptions,
    AzureFunctionRequest,
    KeyVaultSecretsMiddleware,
    CachedValues,
    FetchedValues,
} from "@kevboutin/azure-middy-keyvault-secrets";
```

### TypeScript Configuration

To use TypeScript with this package, ensure your `tsconfig.json` includes:

```json
{
    "compilerOptions": {
        "esModuleInterop": true,
        "moduleResolution": "node"
    }
}
```

## API

### keyvaultSecretsMiddleware(opts = {})

Creates a middleware instance with the following options:

- `opts.vaultUrl` (required): The URL of your Azure Key Vault (e.g., "https://your-vault.vault.azure.net")
- `opts.fetchData` (required): Object mapping of local names to Key Vault secret names
- `opts.cacheKey` (optional): Custom cache key for storing secrets (default: "secrets")

## Authentication

The middleware uses `DefaultAzureCredential` from `@azure/identity` which supports multiple authentication methods:

1. Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
2. Managed Identity
3. Visual Studio Code credentials
4. Azure CLI credentials
5. Interactive browser login

For production, we recommend using Managed Identity or service principal credentials.

## Caching

The middleware supports caching of secrets to reduce Key Vault API calls:

- Set `cacheExpiry` to the number of milliseconds to cache secrets
- Use `cacheKey` to specify a custom cache key if needed
- Cache is automatically invalidated after expiry
- Set `cacheExpiry: 0` to disable caching

## Security Considerations

1. Always use RBAC or Access Policies to limit Key Vault access
2. Consider enabling Key Vault soft-delete and purge protection
3. Monitor Key Vault access using Azure Monitor
4. Regularly rotate secrets
5. Use Managed Identity when possible

## Documentation and examples

For more documentation and examples, refer to the main [Azure-middy monorepo on GitHub](https://github.com/kevboutin/azure-middy).

## Contributing

Everyone is very welcome to contribute to this repository. Feel free to [raise issues](https://github.com/kevboutin/azure-middy/issues) or to [submit Pull Requests](https://github.com/kevboutin/azure-middy/pulls).

## License

Licensed under [MIT License](LICENSE). Copyright (c) 2024 Kevin Boutin and the [Azure-Middy team](https://github.com/kevboutin/azure-middy/graphs/contributors).