LocalSecretVault.Client 0.4.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.4.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
}

HUMAN APPROVED REQUESTS (Debug only)

OpenHumanApproved() is a debug-only API that lets a human operator select which vault to open at runtime via a popup in the Admin UI. This eliminates the need to change vault names in code when switching between environments (dev, staging, local mock) during development.

This method does NOT exist in Release builds -- the #if DEBUG guard ensures it is never accidentally used in production.

SETUP REQUIREMENTS:

• Admin UI must be running (configured to start with Windows via the autostart setting).
• This executable's path must be added to the Human Approvals allowed callers list in the Admin UI (Human Approvals tab).

HOW IT WORKS:

1. Your app calls OpenHumanApproved("hint describing what you need").
2. The request is queued in the daemon.
3. The Admin UI detects the pending request and shows a Gate Prompt popup.
4. If the Admin UI has no active login session, the Gate Prompt will prompt for the master password or Windows Hello before showing the vault selector -- no pre-auth required.
5. The operator selects a vault and clicks Approve (or Deny / closes the window).
6. The secrets from the approved vault are returned to your app.

TYPICAL USAGE:

#if DEBUG
var secrets = LocalSecretVaultManager.OpenHumanApproved("SQL credentials for local dev");
builder.Configuration.AddInMemoryCollection(secrets);
#else
var secrets = LocalSecretVaultManager.Open("production-vault");
builder.Configuration.AddInMemoryCollection(secrets);
#endif

ERROR HANDLING FOR OpenHumanApproved:

try
{
    var secrets = LocalSecretVaultManager.OpenHumanApproved("vault type hint");
    // use secrets...
}
catch (VaultConnectionException)
{
    // Daemon not running or pipe not found.
}
catch (VaultAccessDeniedException)
{
    // This exe is not in the Human Approvals allowed callers list.
    // Fix: open the Admin UI, go to Human Approvals tab, add this exe path.
}
catch (HumanApprovedRequestDeniedException)
{
    // Operator clicked Deny or closed the popup.
}
catch (HumanApprovedRequestTimeoutException)
{
    // No response within the configured timeout (default 60s). Operator stepped away.
}
catch (HumanApprovedRequestAdminUnavailableException)
{
    // Admin UI is not running or has not registered as the approval handler.
    // Fix: start the Admin UI (enable autostart in Settings for convenience).
}
catch (HumanApprovedQueueFullException)
{
    // 10 requests already pending. Retry with backoff.
}
catch (VaultNotFoundException)
{
    // The vault the operator selected no longer exists.
}

EXCEPTION TAXONOMY FOR OpenHumanApproved:

Exception                                   Retry?   Cause
------------------------------------------  -------  ----------------------------------------
VaultConnectionException                    Yes      Daemon not running / pipe timeout
VaultAccessDeniedException                  No       Exe not on allowed callers list
HumanApprovedRequestDeniedException         No       Operator denied or closed the prompt
HumanApprovedRequestTimeoutException        No       No response within timeout
HumanApprovedRequestAdminUnavailableException No     Admin UI not running / not registered
HumanApprovedQueueFullException             Yes      10 requests already queued
VaultNotFoundException                      No       Selected vault was deleted
VaultServiceException                       Escalate Unexpected daemon error

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.

• OpenHumanApproved is debug-only. The #if DEBUG guard prevents it from compiling in Release builds. Never use it in production -- use Open() with a named vault instead.