feat: Azure Key Vault vault provider

[pirminf]

Problem

In Azure-based repos, secrets are currently stored using local_encryption as a fallback. There is no native Azure vault backend, so ${{ vault.get(azure-kv, MY_SECRET) }} cannot resolve against Azure Key Vault. This blocks production use of swamp in Azure environments where secrets must live in Azure Key Vault for compliance and operational reasons.

Current workaround: The azure vault in this repo uses local_encryption as its backend (type: local_encryption), which defeats the purpose of having a named Azure vault.

Proposed Solution

Implement an azure vault provider that resolves secrets from Azure Key Vault, following the same VaultProvider interface pattern used by the existing aws provider.

Config schema

id: <uuid>
name: azure-kv
type: azure
config:
  vault_url: https://<vault>.vault.azure.net/
  tenant_id: <tenantId>
  client_id: <clientId>
  client_secret: <clientSecret>
  secret_prefix: swamp/   # optional — namespace all swamp secrets

Authentication

Client credentials flow to https://vault.azure.net/.default — the same OAuth2 pattern already used in the Azure extension models in this ecosystem (@azure/workload, etc.).

API operations needed

swamp operation	Azure Key Vault REST call
get(key)	GET https://{vault}.vault.azure.net/secrets/{prefix}{key}?api-version=7.4
put(key, value)	PUT https://{vault}.vault.azure.net/secrets/{prefix}{key}?api-version=7.4
list()	GET https://{vault}.vault.azure.net/secrets?api-version=7.4 (follow nextLink for pagination)

CLI usage (once implemented)

# Store a secret
swamp vault put azure-kv MY_SECRET <value>

# Resolve in a workflow/model
${{ vault.get(azure-kv, MY_SECRET) }}

Reference

The design/vaults.md doc in the swamp repo already contains an Azure provider skeleton and the exact config example above — the implementation should follow that spec. The aws provider is the reference implementation pattern to follow.

Alternatives Considered

• Use local_encryption: Works locally but secrets are not stored in Azure Key Vault, defeating compliance requirements.
• Wrap AZ CLI in a shell command: Violates the swamp model for vault integration; not reusable across repos.

Additional Context

• swamp version: 20260221.201206.0-sha.878e8dec
• The azure vault in this repo currently uses local_encryption as a temporary workaround. Once this provider ships, the plan is to migrate existing secrets and switch type: azure.

Post-ship migration checklist

1. Create a new vault definition with type: azure
2. swamp vault put azure-kv MY_SECRET <value> → secret stored in Azure Key Vault
3. Reference in a model: ${{ vault.get(azure-kv, MY_SECRET) }} → resolves correctly
4. Migrate existing local_encryption/azure vault secrets to the new Azure KV vault

[github-actions]

Hi @pirminf, thanks for opening this issue!

We appreciate you taking the time to report it. A maintainer will review it as soon as possible.

In the meantime, please make sure you've included all relevant details (steps to reproduce, expected vs actual behaviour, swamp version, etc.) to help us triage it quickly.

[johnrwatson]

/plan

[github-actions]

Implementation Plan

Summary

Implement an Azure Key Vault vault provider that integrates with Azure Key Vault for secret storage and retrieval. This follows the existing VaultProvider interface pattern established by the AWS Secrets Manager provider, using the Azure SDK for JavaScript (@azure/identity and @azure/keyvault-secrets).

DDD Analysis

Following the DDD patterns in .claude/skills/ddd/SKILL.md:

Concept	Type	Rationale
AzureVaultProvider	Domain Service	Stateless service for external integration with Azure Key Vault; follows existing VaultProvider interface
AzureVaultConfig	Value Object	Immutable configuration for Azure vault (vault_url, tenant_id, etc.) - equality by value
VaultTypeInfo for "azure"	Value Object	Metadata describing the Azure vault type

The Azure provider is a Domain Service because:

• It performs operations spanning external systems (Azure Key Vault API)
• It's stateless (credentials loaded at instantiation, no internal state mutations)
• It implements the VaultProvider interface contract

Files to Modify

1. src/domain/vaults/vault_types.ts (lines 36-49)

Purpose: Add Azure vault type to the VAULT_TYPES registry

Changes:

• Add new entry to VAULT_TYPES array:

  {
    type: "azure",
    name: "Azure Key Vault",
    description: "Store and retrieve secrets using Azure Key Vault. Requires vault URL and service principal credentials (tenant_id, client_id, client_secret).",
  },

2. src/domain/vaults/vault_service.ts (lines 78-102)

Purpose: Register Azure vault provider in the factory switch statement

Changes:

• Add import for AzureVaultProvider and AzureVaultConfig
• Add case for "azure" type in registerVault() switch statement (around line 97):

  case "azure":
    provider = new AzureVaultProvider(
      config.name,
      config.config as AzureVaultConfig,
    );
    break;

• Update error messages to include "azure" in available vault types list (lines 116-117, 148)

3. src/cli/commands/vault_create.ts (lines 40-58)

Purpose: Add default configuration for Azure vault type

Changes:

• Add case for "azure" in getDefaultConfig() function:

  case "azure":
    return {
      vault_url: "",  // Required: https://<vault-name>.vault.azure.net/
      tenant_id: "",  // Required: Azure AD tenant ID
      client_id: "",  // Required: Service principal client ID
      client_secret: "", // Required: Service principal client secret
      secret_prefix: "", // Optional: prefix for all secret names
    };

4. deno.json (imports section, lines 32-35)

Purpose: Add Azure SDK dependencies

Changes:

• Add Azure SDK imports:

  "@azure/identity": "npm:@azure/identity@^4.8.0",
  "@azure/keyvault-secrets": "npm:@azure/keyvault-secrets@^4.9.0"

5. .claude/skills/swamp-vault/SKILL.md (lines 37-61)

Purpose: Document the new Azure vault type

Changes:

• Add "azure" to the vault types section with configuration example

6. .claude/skills/swamp-vault/references/providers.md (lines 59-98)

Purpose: Add detailed Azure provider documentation

Changes:

• Add new section "## Azure Key Vault Provider" with configuration options, authentication details, and security considerations

Files to Create

1. src/domain/vaults/azure_vault_provider.ts

Purpose: Azure Key Vault vault provider implementation

Contents:

// AGPLv3 license header

import { ClientSecretCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";
import type { VaultProvider } from "./vault_provider.ts";

/**
 * Configuration options for Azure Key Vault provider.
 */
export interface AzureVaultConfig {
  /** Azure Key Vault URL (e.g., https://myvault.vault.azure.net/) */
  vault_url: string;
  /** Azure AD tenant ID */
  tenant_id: string;
  /** Service principal client ID */
  client_id: string;
  /** Service principal client secret */
  client_secret: string;
  /** Optional prefix for all secret names */
  secret_prefix?: string;
}

/**
 * Azure Key Vault vault provider.
 */
export class AzureVaultProvider implements VaultProvider {
  private readonly client: SecretClient;
  private readonly name: string;
  private readonly secretPrefix: string;

  constructor(name: string, config: AzureVaultConfig) {
    // Validate required config fields
    // Create ClientSecretCredential with tenant_id, client_id, client_secret
    // Create SecretClient with vault_url and credential
    // Store secretPrefix for key prefixing
  }

  async get(secretKey: string): Promise<string> {
    // Apply prefix to key
    // Call client.getSecret()
    // Return secret value or throw descriptive error
  }

  async put(secretKey: string, secretValue: string): Promise<void> {
    // Apply prefix to key
    // Call client.setSecret()
    // Handle errors appropriately
  }

  getName(): string {
    return this.name;
  }

  async list(): Promise<string[]> {
    // Use client.listPropertiesOfSecrets()
    // Handle pagination via async iteration
    // Strip prefix from returned keys if present
    // Return sorted array of key names
  }
}

2. src/domain/vaults/azure_vault_provider_test.ts

Purpose: Unit tests for Azure vault provider

Test cases:

• Constructor and configuration tests (similar to aws_vault_provider_test.ts:23-56)
  • Should store and return vault name via getName
  • Should accept config with all required fields
  • Should throw error when required config fields are missing
  • Should handle various vault name formats
• Secret prefix behavior tests
  • Should apply prefix when getting secrets
  • Should apply prefix when putting secrets
  • Should strip prefix when listing secrets
  • Should handle empty prefix
• Error handling tests
  • Should throw descriptive error when secret not found
  • Should throw descriptive error for authentication failures
  • Should validate vault URL format

Implementation Steps

Phase 1: Core Provider Implementation

1. Add Azure SDK dependencies to deno.json
2. Create azure_vault_provider.ts with the AzureVaultConfig interface and AzureVaultProvider class
3. Implement the constructor with credential and client initialization
4. Implement get(), put(), list(), and getName() methods
5. Add proper error handling with descriptive messages

Phase 2: Integration with VaultService

6. Add Azure vault type to VAULT_TYPES in vault_types.ts
7. Update vault_service.ts to import and register AzureVaultProvider
8. Add Azure default config to vault_create.ts
9. Update error messages to include "azure" in available types

Phase 3: Testing

10. Create azure_vault_provider_test.ts with unit tests
11. Update vault_types_test.ts to include Azure type checks
12. Update vault_service_test.ts to verify Azure provider registration

Phase 4: Documentation

13. Update swamp-vault/SKILL.md with Azure vault type documentation
14. Update swamp-vault/references/providers.md with detailed Azure provider docs

Phase 5: Verification

15. Run deno check - Type checking
16. Run deno lint - Linting
17. Run deno fmt - Formatting
18. Run deno run test - Tests
19. Run deno run license-headers - Ensure license headers on new files
20. Run deno run compile - Recompile the binary

Testing Strategy

Unit Tests (in azure_vault_provider_test.ts):

• Test constructor configuration handling (required fields, optional prefix)
• Test getName() returns the configured vault name
• Test error messages for missing config fields
• Test secret prefix application logic

Integration with existing tests:

• Update vault_types_test.ts:23-29 to verify Azure type is in VAULT_TYPES
• Update vault_service_test.ts:225-239 to test Azure provider registration

Manual integration testing (documented, not automated):

• Create Azure Key Vault and service principal
• Configure vault with credentials
• Test get/put/list operations

Code Style Checklist

• TypeScript strict mode - no any types (except existing deno-lint-ignore in vault_create.ts)
• Named exports, not default exports
• AGPLv3 license header on new files
• AzureVaultConfig interface with explicit types (no unknown)
• Comprehensive JSDoc comments matching existing patterns
• Error messages include vault name and key for debugging

Potential Challenges

1. Azure SDK compatibility with Deno: The Azure SDK packages are designed for Node.js. Need to verify they work correctly with Deno's npm compatibility. The AWS SDK works fine, so Azure SDK should too.

2. Secret name character restrictions: Azure Key Vault secret names have specific requirements (alphanumeric and dashes only). May need validation in put() to provide helpful error messages.

3. Pagination handling: Azure's listPropertiesOfSecrets() returns an async pageable. Need to properly iterate through all pages.

4. Rate limiting: Azure Key Vault has throttling limits. Error handling should provide clear messages for 429 responses.

5. Secret versions: Azure Key Vault supports secret versions. The implementation should always get the latest version (default behavior of getSecret).

6. Credential refresh: ClientSecretCredential handles token refresh automatically, but need to ensure the credential doesn't expire during long-running workflows.

Dependencies

New npm dependencies to add to deno.json:

• @azure/identity@^4.8.0 - For ClientSecretCredential
• @azure/keyvault-secrets@^4.9.0 - For SecretClient

These packages depend on @azure/core-* packages which will be automatically installed.

Configuration Example

# .swamp/vault/azure/{id}.yaml
id: abc-123
name: azure-kv
type: azure
config:
  vault_url: https://mycompany-swamp.vault.azure.net/
  tenant_id: 12345678-1234-1234-1234-123456789012
  client_id: abcdefgh-abcd-abcd-abcd-abcdefghijkl
  client_secret: "my-client-secret"
  secret_prefix: swamp/
createdAt: 2026-02-23T12:00:00.000Z

Usage After Implementation

# Create Azure vault
swamp vault create azure azure-kv

# Edit configuration to add credentials
swamp vault edit azure-kv

# Store a secret
swamp vault put azure-kv MY_SECRET=my-value

# Use in workflow
# attributes:
#   apiKey: ${{ vault.get(azure-kv, MY_SECRET) }}

[johnrwatson]

Updated Implementation Plan (v2)

This plan covers two changes:

1. New azure-kv vault provider for Azure Key Vault
2. Rename aws → aws-sm for consistency (breaking change, acceptable in alpha)

Design Decisions

No credentials in config. The original plan proposed storing Azure credentials in the vault config YAML. This breaks the pattern established by the AWS provider, which uses the SDK's default credential chain. The Azure provider will use DefaultAzureCredential instead.

Provider config resolved at creation time. Provider-specific options (e.g., --vault-url for Azure, --region for AWS) are resolved once during swamp vault create and written into the config file. This keeps configs self-documenting and stable — two vaults in the same repo can point at different backends without env var conflicts. Each flag falls back to the standard env var (AZURE_KEYVAULT_URL, AWS_REGION) if not provided explicitly, and errors if neither is set. No silent defaults. When a value is picked up from an environment variable, the CLI must log a message to the user (e.g., Using vault URL from AZURE_KEYVAULT_URL environment variable) so there's no hidden magic.

Hyphenated type names. Vault types use hyphens (azure-kv, aws-sm) consistent with vault name validation (/^[a-z][a-z0-9-]*$/).

Authentication: DefaultAzureCredential

Uses DefaultAzureCredential from @azure/identity, which automatically tries (in order):

1. Environment variables (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)
2. Workload Identity (for Azure-hosted workloads)
3. Managed Identity (for Azure VMs, App Service, etc.)
4. Azure CLI credentials (az login)
5. Azure PowerShell credentials
6. Azure Developer CLI credentials

This mirrors how the AWS provider uses the default AWS credential chain.

Config Schema

id: <uuid>
name: my-azure-vault
type: azure-kv
config:
  vault_url: https://<vault>.vault.azure.net/   # resolved at creation time
  secret_prefix: swamp/                          # optional — namespace all swamp secrets

No credentials in config. The vault_url is resolved once at swamp vault create time:

1. --vault-url flag (explicit)
2. AZURE_KEYVAULT_URL environment variable (fallback)
3. Error if neither is set

---

DDD Analysis

Concept	Type	Rationale
AzureKvVaultProvider	Domain Service	Stateless service for external integration with Azure Key Vault; follows existing VaultProvider interface
AzureKvVaultConfig	Value Object	Immutable configuration — vault_url and optional secret_prefix
VaultTypeInfo for azure-kv	Value Object	Metadata describing the Azure Key Vault type

---

Part 1: New azure-kv Provider

Files to Create

1. src/domain/vaults/azure_kv_vault_provider.ts

export interface AzureKvVaultConfig {
  /** Azure Key Vault URL (e.g., https://myvault.vault.azure.net/) */
  vault_url: string;
  /** Optional prefix for all secret names */
  secret_prefix?: string;
}

export class AzureKvVaultProvider implements VaultProvider {
  private readonly client: SecretClient;
  private readonly name: string;
  private readonly secretPrefix: string;

  constructor(name: string, config: AzureKvVaultConfig) {
    // Validate vault_url is provided (already resolved at create time)
    // Create DefaultAzureCredential (SDK default credential chain)
    // Create SecretClient with vault_url and credential
    // Store secretPrefix (default "")
  }

  async get(secretKey: string): Promise<string>
  // Apply prefix, call client.getSecret(), return value

  async put(secretKey: string, secretValue: string): Promise<void>
  // Apply prefix, call client.setSecret()

  getName(): string

  async list(): Promise<string[]>
  // Use client.listPropertiesOfSecrets() with async iteration
  // Strip prefix from returned keys
  // Return sorted array
}

2. src/domain/vaults/azure_kv_vault_provider_test.ts

Test cases following the aws_vault_provider_test.ts pattern:

• Constructor stores and returns vault name via getName()
• Constructor validates vault_url is required (already resolved, so must be present)
• Constructor handles optional secret_prefix
• Secret prefix logic (apply on get/put, strip on list, handle empty prefix)

Files to Modify

1. deno.json (imports section)

Add Azure SDK dependencies:

"@azure/identity": "npm:@azure/identity@^4.8.0",
"@azure/keyvault-secrets": "npm:@azure/keyvault-secrets@^4.9.0"

2. src/domain/vaults/vault_types.ts (lines 36-49)

Add to VAULT_TYPES array:

{
  type: "azure-kv",
  name: "Azure Key Vault",
  description:
    "Store and retrieve secrets using Azure Key Vault. Requires vault URL and Azure credentials via environment variables, managed identity, or Azure CLI.",
},

3. src/domain/vaults/vault_service.ts

• Add import for AzureKvVaultProvider and AzureKvVaultConfig
• Add case in registerVault() switch:

  case "azure-kv":
    provider = new AzureKvVaultProvider(
      config.name,
      config.config as AzureKvVaultConfig,
    );
    break;

• Update "Available vault types" error messages to include azure-kv

4. src/cli/commands/vault_create.ts

• Add --vault-url and --region options to the command definition
• Add case in getDefaultConfig() for azure-kv that resolves the vault URL:

  case "azure-kv": {
    const vaultUrl = options?.vaultUrl || Deno.env.get("AZURE_KEYVAULT_URL");
    if (!vaultUrl) {
      throw new UserError(
        "Azure Key Vault URL is required. Provide --vault-url or set AZURE_KEYVAULT_URL environment variable.",
      );
    }
    if (!options?.vaultUrl) {
      logger.info`Using vault URL from AZURE_KEYVAULT_URL environment variable: ${vaultUrl}`;
    }
    return {
      vault_url: vaultUrl,
    };
  }

• Update aws-sm case to resolve region from flag/env:

  case "aws-sm": {
    const region = options?.region || Deno.env.get("AWS_REGION");
    if (!region) {
      throw new UserError(
        "AWS region is required. Provide --region or set AWS_REGION environment variable.",
      );
    }
    if (!options?.region) {
      logger.info`Using region from AWS_REGION environment variable: ${region}`;
    }
    return {
      region,
    };
  }

5. .claude/skills/swamp-vault/SKILL.md

Add azure-kv vault type documentation section.

6. .claude/skills/swamp-vault/references/providers.md

Add Azure Key Vault provider section with configuration, authentication, and usage details.

---

Part 2: Rename aws → aws-sm (Breaking Change)

Since swamp is in alpha, this is an acceptable breaking change. Existing vault configs with type: aws will need to be updated to type: aws-sm.

Files to Modify

1. src/domain/vaults/vault_types.ts — Change type: "aws" to type: "aws-sm", update name to "AWS Secrets Manager"
2. src/domain/vaults/vault_service.ts — Change case "aws": to case "aws-sm": in the switch, update all "Available vault types" error messages, update ensureDefaultVaults() to use aws-sm
3. src/cli/commands/vault_create.ts — Change case "aws": to case "aws-sm": in getDefaultConfig(), update to resolve region from --region flag / AWS_REGION env var / us-east-1 default
4. src/domain/vaults/aws_vault_provider.ts — Remove the us-east-1 default and AWS_REGION env var fallback from the constructor (region is now always resolved at create time and provided via config). Make region required in the config type.
5. src/domain/vaults/vault_types_test.ts — Update test expectations from "aws" to "aws-sm"
6. src/domain/vaults/vault_service_test.ts — Update test expectations from "aws" to "aws-sm"
7. src/domain/vaults/aws_vault_provider_test.ts — No changes needed (tests the class, not the type string)
8. .claude/skills/swamp-vault/SKILL.md — Update aws references to aws-sm
9. .claude/skills/swamp-vault/references/providers.md — Update aws references to aws-sm

---

Existing Tests to Update

• vault_types_test.ts: Update "aws" → "aws-sm", add "azure-kv" assertions
• vault_service_test.ts: Update "aws" → "aws-sm", test azure-kv provider registration

Implementation Phases

1. Rename aws → aws-sm — Update type string across all files and tests
2. Core Azure Provider — Add Azure SDK deps, create AzureKvVaultProvider with DefaultAzureCredential
3. Integration — Register azure-kv in vault types, service factory, create command with --vault-url flag
4. Testing — Unit tests for new provider + update existing vault type/service tests
5. Documentation — Update skill docs and provider reference
6. Verification — deno check, deno lint, deno fmt, deno run test, deno run license-headers, deno run compile

Key Differences from Original Plan

Aspect	Original Plan	This Plan
Type name	azure	azure-kv (specific to Key Vault)
AWS type name	aws (unchanged)	aws-sm (renamed for consistency)
Authentication	ClientSecretCredential with creds in config	DefaultAzureCredential (SDK default chain)
Config fields	vault_url, tenant_id, client_id, client_secret, secret_prefix	vault_url, secret_prefix only
Config resolution	Runtime resolution from config or env var	Resolved once at vault create time, persisted in config
Create command	No provider flags	--vault-url (Azure), --region (AWS) flags with env var fallbacks
Security	Creds could be committed to repo	No creds in repo — mirrors AWS pattern

Usage After Implementation

# Set up Azure credentials (one of these methods):
export AZURE_TENANT_ID=...
export AZURE_CLIENT_ID=...
export AZURE_CLIENT_SECRET=...
# OR: az login
# OR: use managed identity on Azure-hosted workloads

# Create Azure vault with explicit URL
swamp vault create azure-kv my-azure-vault --vault-url https://mycompany.vault.azure.net/

# Or with env var
export AZURE_KEYVAULT_URL=https://mycompany.vault.azure.net/
swamp vault create azure-kv my-azure-vault

# Store a secret
swamp vault put my-azure-vault MY_SECRET=my-value

# Use in workflow
# attributes:
#   apiKey: ${{ vault.get(my-azure-vault, MY_SECRET) }}

# AWS vaults now use aws-sm type
swamp vault create aws-sm my-aws-vault --region eu-west-1

# Or pick up region from env var
export AWS_REGION=eu-west-1
swamp vault create aws-sm my-aws-vault

[johnrwatson]

Hey @pirminf - Thanks for the excellent idea. This is now in the stable build of swamp - just run swamp update then you can see the new vault type available:

swamp vault type search --json
{
  "query": "",
  "results": [
    {
      "type": "aws-sm",
      "name": "AWS Secrets Manager",
      "description": "Store and retrieve secrets using AWS Secrets Manager. Requires AWS credentials via IAM roles, environment variables, or AWS profiles."
    },
    {
      "type": "azure-kv",
      "name": "Azure Key Vault",
      "description": "Store and retrieve secrets using Azure Key Vault. Requires vault URL and Azure credentials via environment variables, managed identity, or Azure CLI."
    },
    {
      "type": "local_encryption",
      "name": "Local Encryption",
      "description": "Store encrypted secrets in local files using AES-GCM encryption. Uses SSH private key or auto-generated key for encryption."
    }
  ]
}

To use it simply create the vault via swamp vault create azure-kv azure-secrets --vault-url https://<your-vault>.vault.azure.net/ & off you go with putting values in it & referencing them in workflows etc.

It uses the same primitive for authentication as the existing AWS vault - i.e. the standard credential chain to Azure e.g.

• Env Vars
• az login output, etc

Let me know how you get on!