Deneblab.StashLock.Client 0.3.121

Deneblab.StashLock.Client

Async-first .NET secrets management client for StashLock vault.

Installation

dotnet add package Deneblab.StashLock.Client

Quick Start

using Deneblab.StashLock.Client;

// From environment variable STASHLOCK_VAULT_KEY
var store = await StashLock.CreateClient()
    .FromEnvironment()
    .OpenAsync();

var dbPassword = store["Database:Password"];

Fluent API

All access starts with StashLock.CreateClient() which returns a fluent builder.

Connection string

The simplest way to configure StashLock — a single string with all connection parameters:

// Explicit connection string
var store = await StashLock.CreateClient()
    .WithConnectionString("Url=https://vault.example.com;ApiKey=slk_xxx;PrivateKey=base64key;Box=myapp;Tag=prod")
    .OpenAsync();

// From STASHLOCK_CONNECTION_STRING env var
var store = await StashLock.CreateClient()
    .FromConnectionString()
    .OpenAsync();

// Zero-config: auto-reads STASHLOCK_CONNECTION_STRING when no source is configured
var store = await StashLock.CreateClient()
    .OpenAsync();

// Partial override: CS provides defaults, fluent calls override specific values
var store = await StashLock.CreateClient()
    .WithBox("myapp", "staging")   // overrides Box+Tag from CS env var
    .OpenAsync();

Connection string keys: Url, ApiKey, PrivateKey, Box, Tag. Supports optional base64 wrapping for safe transport.

Remote sealed-box (X25519)

var store = await StashLock.CreateClient()
    .WithBox("myapp", "prod")
    .WithPrivateKey(key)              // optional, falls back to env var
    .OpenAsync();

Sealed-box with offline cache

var store = await StashLock.CreateClient()
    .WithBox("myapp", "prod")
    .WithPrivateKey(key)
    .WithCache(ttl: TimeSpan.FromHours(2))
    .OpenAsync();

// With custom cache directory
var store = await StashLock.CreateClient()
    .WithBox("myapp", "prod")
    .WithCache(cacheDir: "/app/cache", ttl: TimeSpan.FromHours(4))
    .OpenAsync();

Cache-first strategy

By default, the client tries the server first and falls back to cache. Use CacheFirst to prioritize cached secrets (useful for low-latency startup or unreliable networks):

var store = await StashLock.CreateClient()
    .WithBox("myapp", "prod")
    .WithCache(
        ttl: TimeSpan.FromHours(2),
        strategy: CacheStrategy.CacheFirst,      // use cache if valid, refresh in background
        serverTimeout: TimeSpan.FromSeconds(5))   // timeout for server requests (default: 10s)
    .OpenAsync();

Request timeout

var store = await StashLock.CreateClient()
    .WithBox("myapp", "prod")
    .WithTimeout(TimeSpan.FromSeconds(15))   // default: 30s (or 10s when cache is enabled)
    .OpenAsync();

Local files

// Plain JSON file (development)
var store = await StashLock.CreateClient()
    .FromDevFile()                    // auto-discovers dev/secrets/secrets.json
    .OpenAsync();

// Explicit plain JSON file
var store = await StashLock.CreateClient()
    .FromFile("./secrets.json")
    .OpenAsync();

// Local encrypted file (SOPS or whole-file mode)
var store = await StashLock.CreateClient()
    .FromEncryptedFile("./stashlock.enc.prod.secrets.json")
    .WithPrivateKey(key)
    .OpenAsync();

Configuration validation

var result = await StashLock.CreateClient()
    .WithBox("myapp", "prod")
    .ValidateAsync();

if (!result.IsValid)
    foreach (var issue in result.Issues)
        Console.WriteLine($"ERROR: {issue}");

Builder options

Reading Secrets

// Indexer (synchronous — secrets are pre-loaded)
string value = store["Database:Password"];

// Async
string value = await store.GetAsync("Database:Password");

// TryGet (no exception on missing key)
if (store.TryGet("OptionalKey", out var value))
{
    // use value
}

// Section as dictionary
var dbConfig = await store.GetSectionAsDictionaryAsync("Database");
// Returns: { "Host": "localhost", "Password": "secret", ... }

// Typed section (deserializes into a POCO)
var dbConfig = store.GetSection<DatabaseConfig>("Database");

IConfiguration Integration

Single AddStashLock extension method with the same fluent builder:

using Deneblab.StashLock.Client.Configuration;

var builder = WebApplication.CreateBuilder(args);

// Remote sealed-box vault with cache
builder.Configuration.AddStashLock(cfg => cfg
    .WithBox("myapp", "prod")
    .WithCache(cacheDir: "/app/cache", ttl: TimeSpan.FromHours(4))
);

var app = builder.Build();

// Access secrets via standard IConfiguration
var connString = app.Configuration["Database:ConnectionString"];
var apiKey = app.Configuration["ExternalService:ApiKey"];

Dev/prod branching

builder.ConfigureAppConfiguration((ctx, config) =>
{
    if (ctx.HostingEnvironment.IsDevelopment())
    {
        config.AddStashLock(cfg => cfg
            .FromDevFile("dev/secrets/secrets.json")
        );
    }
    else
    {
        config.AddStashLock(cfg => cfg
            .WithBox("myapp", ctx.HostingEnvironment.EnvironmentName.ToLower())
            .WithCache(ttl: TimeSpan.FromHours(2))
        );
    }
});

Encrypted local file

builder.Configuration.AddStashLock(cfg => cfg
    .FromEncryptedFile("secrets.enc.json")
    .WithPrivateKey(key)
);

Dependency Injection

Register ISecretsStore as a singleton in your DI container:

using Deneblab.StashLock.Client.Configuration;

builder.Services.AddStashLock(cfg => cfg
    .WithBox("myapp", "prod")
    .WithCache(ttl: TimeSpan.FromHours(2))
);

// Inject anywhere
public class MyService(ISecretsStore secrets)
{
    public string GetDbPassword() => secrets["Database:Password"];
}

Environment Variables

Error Handling

try
{
    var store = await StashLock.CreateClient()
        .FromEnvironment()
        .OpenAsync();
}
catch (VaultConfigurationException ex)
{
    // Missing or invalid configuration (env var, key format)
}
catch (VaultNotFoundException ex)
{
    // Vault entry not found on server
}
catch (DecryptionException ex)
{
    // Decryption failed — wrong password or key
}

Development Secrets File

Create a secrets.json in dev/secrets/ under your project root:

{
  "Database:ConnectionString": "Server=localhost;Database=dev",
  "Database:Password": "dev-password",
  "ExternalApi:Key": "dev-api-key"
}

FromDevFile() (without a path) auto-discovers this file when running in Dev or Test mode.

License

MIT License - see LICENSE file for details

Links

• NuGet Package
• Repository
• Issues