Unified Key-Value secrets engine interface for HashiCorp Vault.

This module provides a unified interface for both KV v1 and KV v2 engines, automatically detecting the engine version and delegating operations to the appropriate implementation. It offers a seamless experience for working with KV secrets regardless of the underlying engine version.

Features

• Automatic Version Detection: Detects KV v1 vs v2 automatically
• Unified API: Same interface works with both versions
• Version-Specific Features: Advanced features available when supported
• Graceful Degradation: Unsupported operations return clear errors
• Performance Optimized: Caches version detection results
• Convenience Functions: Additional utility functions for common operations

Supported Operations

Core Operations (Both v1 and v2)

• read/2 - Read secrets from any path
• write/3 - Write secrets to any path
• delete/2 - Delete secrets (soft delete in v2)
• list/2 - List secret keys at a path

KV v2 Specific Operations

• read_metadata/2 - Read secret metadata and version history
• write_metadata/3 - Update secret metadata without creating new version
• delete_metadata/2 - Permanently delete all versions and metadata
• undelete/2 - Restore soft-deleted versions
• destroy/2 - Permanently destroy specific versions
• list_versions/2 - List all versions of a secret

Convenience Functions

• read_version/3 - Read specific version of a secret
• write_cas/4 - Write with Check-And-Set (CAS) support
• delete_versions/3 - Delete specific versions
• exists?/2 - Check if a secret exists
• keys/2 - Get field names from a secret
• get_field/3 - Get specific field value
• update_field/4 - Update single field preserving others

Usage Examples

# Basic operations (work with both v1 and v2)
{:ok, secret} = Vaultx.Secrets.KV.read("myapp/config", mount_path: "secret")
{:ok, result} = Vaultx.Secrets.KV.write("myapp/config", %{"key" => "value"}, mount_path: "secret")
:ok = Vaultx.Secrets.KV.delete("myapp/config", mount_path: "secret")
{:ok, keys} = Vaultx.Secrets.KV.list("myapp/", mount_path: "secret")

# KV v2 specific operations (gracefully fail on v1)
{:ok, secret} = Vaultx.Secrets.KV.read_version("myapp/config", 2, mount_path: "secret")
{:ok, result} = Vaultx.Secrets.KV.write_cas("myapp/config", %{"key" => "value"}, 1, mount_path: "secret")
:ok = Vaultx.Secrets.KV.undelete("myapp/config", versions: [1, 2], mount_path: "secret")

# Metadata operations (KV v2 only)
{:ok, metadata} = Vaultx.Secrets.KV.read_metadata("myapp/config", mount_path: "secret")
:ok = Vaultx.Secrets.KV.write_metadata("myapp/config", %{"max_versions" => 5}, mount_path: "secret")

# Convenience functions
true = Vaultx.Secrets.KV.exists?("myapp/config", mount_path: "secret")
{:ok, ["username", "password"]} = Vaultx.Secrets.KV.keys("myapp/config", mount_path: "secret")
{:ok, "admin"} = Vaultx.Secrets.KV.get_field("myapp/config", "username", mount_path: "secret")

Version Detection

The module automatically detects the KV engine version by:

1. Checking engine mount information via /sys/mounts
2. Caching the result for subsequent operations
3. Falling back to API behavior analysis if needed

API Compliance

This implementation fully complies with HashiCorp Vault's official KV API:

• KV v1: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v1
• KV v2: https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2

Configuration

# KV v1 engine
vault secrets enable -version=1 -path=kv-v1 kv

# KV v2 engine (default for new installations)
vault secrets enable -version=2 -path=secret kv

Error Handling

Operations return standardized errors with clear messages:

{:error, %Vaultx.Base.Error{
  type: :unsupported_operation,
  message: "KV v1 does not support versioning",
  details: %{operation: :read, version: 2}
}}

Performance Considerations

• Version detection results are cached per mount path
• Cache can be cleared with clear_version_cache/1
• First operation per mount may be slightly slower due to detection