LocalSecretVault.Client 0.2.0

LocalSecretVault.Client -- Usage Guide

LocalSecretVault.Client is a NuGet package for reading secrets from a running LocalSecretVault daemon. Add it to any .NET project that needs secrets instead of .env files.

REQUIREMENTS

• LocalSecretVault daemon must be installed and running on the same machine.
• The full path of your executable must be listed under Allowed Callers for the vault (configured via the Admin UI).
• .NET Standard 2.0 compatible -- works with .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5+.

INSTALLATION

Install via NuGet:

dotnet add package LocalSecretVault.Client

Or in your .csproj:

<PackageReference Include="LocalSecretVault.Client" Version="0.1.0" />

MANUAL DLL REFERENCE (without NuGet)

If you cannot use NuGet, add a direct reference in your .csproj:

<ItemGroup>
  <Reference Include="LocalSecretVault.Client">
    <HintPath>path\to\LocalSecretVault.Client.dll</HintPath>
  </Reference>
</ItemGroup>

And add System.Text.Json if not already present:

dotnet add package System.Text.Json

BASIC USAGE

using LocalSecretVault;
using System.Collections.Generic;

// Open the vault and read all secrets in one call.
// The daemon verifies that this executable's path is in Allowed Callers.
Dictionary<string, string> secrets = LocalSecretVaultManager.Open("my-vault");

string baseUrl  = secrets["API_BASE_URL"];
string clientId = secrets["API_CLIENT_ID"];
string secret   = secrets["API_CLIENT_SECRET"];

// Use immediately -- do not store 'secrets' in a static field or log its contents.

USAGE WITH Microsoft.Extensions.Configuration

The recommended pattern is to load secrets at startup directly into your configuration builder, then let the dictionary go out of scope:

using LocalSecretVault;
using Microsoft.Extensions.Configuration;

var builder = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: false);

var secrets = LocalSecretVaultManager.Open("my-vault");
builder.AddInMemoryCollection(secrets);

IConfiguration config = builder.Build();

string baseUrl = config["API_BASE_URL"];

USAGE WITH IHostBuilder / Generic Host (.NET 6+)

using LocalSecretVault;
using Microsoft.Extensions.Hosting;

var host = Host.CreateApplicationBuilder(args);

var secrets = LocalSecretVaultManager.Open("my-vault");
host.Configuration.AddInMemoryCollection(secrets);

// IConfiguration, IOptions<T>, etc. all see the vault values
host.Services.Configure<MyOptions>(host.Configuration.GetSection("MySection"));

await host.Build().RunAsync();

USAGE WITH ASP.NET Core (Program.cs / WebApplication)

using LocalSecretVault;

var builder = WebApplication.CreateBuilder(args);

var secrets = LocalSecretVaultManager.Open("my-vault");
builder.Configuration.AddInMemoryCollection(secrets);

builder.Services.AddControllers();
// ... rest of setup

var app = builder.Build();
app.MapControllers();
app.Run();

ERROR HANDLING

All exceptions derive from LocalSecretVaultException.

using LocalSecretVault;

try
{
    var secrets = LocalSecretVaultManager.Open("my-vault");
    // use secrets...
}
catch (VaultConnectionException ex)
{
    // Daemon not running, pipe not found, or connection timed out.
    // Appropriate to retry with backoff, or fail fast at startup.
    Console.Error.WriteLine($"Vault service unavailable: {ex.Message}");
    throw;
}
catch (VaultAccessDeniedException ex)
{
    // This executable's path is not in Allowed Callers for the vault.
    // Fix: open the Admin UI, select the vault, add this exe under Allowed Callers.
    // Retrying will not help -- this is a configuration issue.
    Console.Error.WriteLine($"Access denied: {ex.Message}");
    throw;
}
catch (VaultNotFoundException ex)
{
    // The vault name does not exist. Check spelling or create it in the Admin UI.
    Console.Error.WriteLine($"Vault not found: {ex.VaultName}");
    throw;
}
catch (VaultServiceException ex)
{
    // Unexpected daemon error. Check the service logs at:
    // %LOCALAPPDATA%\LocalSecretVault\logs\daemon-YYYY-MM-DD.log
    Console.Error.WriteLine($"Vault service error: {ex.Message}");
    throw;
}

RETRY WITH BACKOFF (optional)

VaultConnectionException is the only retriable error (e.g. daemon still starting up):

using LocalSecretVault;

static Dictionary<string, string> OpenWithRetry(string vaultName, int maxAttempts = 3)
{
    int delayMs = 500;
    for (int attempt = 1; attempt <= maxAttempts; attempt++)
    {
        try
        {
            return LocalSecretVaultManager.Open(vaultName);
        }
        catch (VaultConnectionException) when (attempt < maxAttempts)
        {
            Thread.Sleep(delayMs);
            delayMs *= 2;
        }
    }
    return LocalSecretVaultManager.Open(vaultName); // final attempt, let exceptions propagate
}

SECURITY NOTES

• No caching. Every Open() call makes a fresh pipe connection. The library never stores secrets between calls.

• ZeroMemory. The raw response bytes are zeroed immediately after deserialization.

• Caller verification. The daemon resolves the calling process's executable path via Win32 QueryFullProcessImageName and compares it against Allowed Callers. Symlinks and junctions in the path are rejected by the daemon.

• Do not log the dictionary. Structured loggers (Serilog, NLog, etc.) may serialize objects passed to log statements. Never pass the secrets dictionary to any logger.

• Do not store in static fields. Assign values to your DI container or configuration builder and let the dictionary go out of scope immediately.