VaultaX 1.1.2

VaultaX

HashiCorp Vault Integration for .NET 10+

VaultaX is a comprehensive .NET library for seamless HashiCorp Vault integration. It provides transparent secret management where Vault secrets automatically overlay your appsettings.json values, automatic token renewal, and support for multiple secret engines including KV, Transit (for signing/encryption), and PKI.

Built exclusively for .NET 10 with C# 14, VaultaX leverages modern language features and offers a clean, fluent API that integrates naturally with ASP.NET Core and the Microsoft.Extensions ecosystem.

💖 Support the Project

VaultaX is a passion project, driven by the desire to provide a truly modern Vault integration for the .NET community. Maintaining this library requires significant effort: staying current with each .NET release, addressing issues promptly, implementing new features, keeping documentation up to date, and ensuring compatibility with HashiCorp Vault updates.

If VaultaX has helped you build better applications or saved you development time, I would be incredibly grateful for your support. Your contribution—no matter the size—helps me dedicate time to respond to issues quickly, implement improvements, and keep the library evolving alongside the .NET platform.

I'm also looking for sponsors who believe in this project's mission. Sponsorship helps ensure VaultaX remains actively maintained and continues to serve the .NET community for years to come.

Of course, there's absolutely no obligation. If you prefer, simply starring the repository or sharing VaultaX with fellow developers is equally appreciated!

• ⭐ Star the repository on GitHub to raise its visibility

• 💬 Share VaultaX with your team or community

• ☕ Support via Donations:

  • 
  • 

✨ Features

• Transparent Configuration: Vault secrets automatically overlay appsettings.json
• Multiple Authentication Methods: Token, AppRole, Kubernetes, LDAP, JWT, AWS, Azure, and more
• Secret Engines: KV v1/v2, Transit (signing & encryption), PKI (certificates)
• Automatic Token Renewal: Background service keeps tokens fresh
• Hot Reload: Configuration updates without restart via IOptionsMonitor
• Health Checks: Built-in ASP.NET Core health check integration
• Configuration Options: appsettings.json or Fluent API
• Environment Variables: Use env:VARIABLE_NAME for sensitive values

🎉 What's New in 1.1.0

• Transit certificate chain support — associate X.509 certificate chains with Transit signing keys and retrieve the end-entity serial at signing time. Designed for regulatory signing flows (e.g., STP/Banxico) that require the cert serial to travel alongside the Vault-produced signature.
  • ITransitEngine.SetCertificateChainAsync(keyName, pem, keyVersion?)
  • ITransitEngine.GetCertificateChainAsync(keyName, version?) → PEM string or null
  • ITransitEngine.GetCertificateSerialAsync(keyName, version?, SerialFormat.Decimal | SerialFormat.Hex)
  • TransitKeyInfo.CertificateChain — populated automatically by GetKeyInfoAsync
• Raw HTTP escape hatch — IVaultClient.SendRawRequestAsync<TResponse>(method, relativePath, body?) for Vault endpoints not covered by VaultSharp. 404 → null; other non-success → VaultOperationException.

See the full changelog for details.

🚀 Getting Started

Integrating VaultaX into your .NET 10+ application is straightforward.

1. Install the NuGet Package:

dotnet add package VaultaX

2. Configure appsettings.json:

{
  "VaultaX": {
    "Enabled": true,
    "Address": "https://vault.example.com:8200",
    "MountPoint": "secret",
    "BasePath": "production",
    "Authentication": {
      "Method": "AppRole",
      "RoleId": "env:VAULT_ROLE_ID",
      "SecretId": "env:VAULT_SECRET_ID"
    },
    "Mappings": [
      {
        "SecretPath": "database",
        "Bindings": {
          "connectionString": "ConnectionStrings:DefaultConnection"
        }
      }
    ]
  }
}

3. Register in Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Add Vault as configuration source (secrets override appsettings)
builder.Configuration.AddVaultaX();

// Register VaultaX services
builder.Services.AddVaultaX(builder.Configuration);

// Add health checks
builder.Services.AddHealthChecks()
    .AddVaultaX();

var app = builder.Build();
app.MapHealthChecks("/health");
app.Run();

4. Use Secrets Transparently:

public class MyService(IConfiguration configuration)
{
    // This value comes from Vault if configured, otherwise from appsettings.json
    private readonly string _connectionString = configuration.GetConnectionString("DefaultConnection");
}

🔐 Secret Engines

Key-Value Engine

public class SecretService(IKeyValueEngine kvEngine)
{
    public async Task<string> GetApiKeyAsync()
    {
        var secrets = await kvEngine.GetSecretAsync("api-keys");
        return secrets["apiKey"]?.ToString();
    }
}

Transit Engine (Signing & Encryption)

The Transit engine keeps private keys secure in Vault:

public class DocumentSigningService(ITransitEngine transitEngine)
{
    public async Task<string> SignDocumentAsync(byte[] documentHash)
    {
        var response = await transitEngine.SignAsync(new TransitSignRequest
        {
            KeyName = "document-signing-key",
            Data = documentHash,
            HashAlgorithm = TransitHashAlgorithm.Sha256,
            Prehashed = true
        });
        return response.Signature;
    }

    public async Task<string> EncryptAsync(string plaintext)
    {
        var data = Encoding.UTF8.GetBytes(plaintext);
        return await transitEngine.EncryptAsync("encryption-key", data);
    }
}

Certificate Chain Support (v1.1.0+)

When your signing flow needs to expose the X.509 serial of the cert associated with the Transit key (e.g., Banxico/STP requires the serial alongside every signed payment), associate the PEM chain once and read the serial at signing time:

// Associate the cert chain with the key (one-time setup, or after each key rotation)
await transitEngine.SetCertificateChainAsync(
    keyName: "document-signing-key",
    pemCertificateChain: pemChain);

// At signing time — resolve the serial dynamically
var signResponse = await transitEngine.SignAsync(signRequest);
var certSerial = await transitEngine.GetCertificateSerialAsync(
    keyName: "document-signing-key",
    version: signResponse.KeyVersion,
    format: SerialFormat.Decimal); // "Hex" also available

Returns null if no certificate has been associated with the key (or Vault is older than 1.16). Consider caching the serial per (keyName, keyVersion) — it only changes when the key is rotated.

PKI Engine (Certificates)

public class CertificateService(IPkiEngine pkiEngine)
{
    public async Task<PkiCertificateResponse> IssueCertificateAsync(string commonName)
    {
        return await pkiEngine.IssueCertificateAsync(new PkiCertificateRequest
        {
            RoleName = "web-server",
            CommonName = commonName,
            Ttl = "720h"
        });
    }
}

📅 Versioning & .NET Support Policy

VaultaX follows a clear versioning strategy aligned with .NET's release cadence:

Version History

Future Support Policy

VaultaX will always support the current LTS version plus the next standard release:

📚 Documentation

Comprehensive guides to help you master VaultaX:

Getting Started

• Getting Started - Installation, basic setup, and first configuration
• Configuration - Complete configuration reference

Core Features

• Authentication - All authentication methods explained
• Secret Engines - KV, Transit, and PKI engines
• Signing - Document signing with Transit engine

Advanced Topics

• Hot Reload - Automatic configuration updates
• Health Checks - Monitoring and health endpoints
• Migration - Migrating from other Vault libraries
• Troubleshooting - Common issues and solutions

Examples

Check out the samples folder for complete working examples.

Tools

• Terraform Configuration - Infrastructure as Code for provisioning Vault secrets

🙏 Acknowledgments

VaultaX is built on top of VaultSharp, an excellent low-level Vault client for .NET. VaultaX provides a higher-level abstraction focused on configuration integration and modern .NET patterns.

VaultSharp Project: VaultSharp on GitHub