Deneblab.StashLock.Client 0.2.76

Deneblab.StashLock.Client

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

Installation

dotnet add package Deneblab.StashLock.Client

Two Ways to Use

1. Standalone (VaultKey + SecretsStoreAsync)

Load secrets directly in code — useful for early initialization before the host builder, console apps, or anywhere you need explicit control.

using Deneblab.StashLock.Client;

// From environment variable STASHLOCK_VAULT_KEY
var vaultKey = VaultKey.FromEnvironment();
var store = await SecretsStoreAsync.OpenRemoteAsync(vaultKey);

var dbPassword = await store.GetAsync("Database:Password");
var apiKey = await store.GetAsync("ExternalApi:Key");

2. IConfiguration Integration

Plug secrets into the standard .NET configuration pipeline — secrets appear alongside appsettings.json, env vars, etc.

using Deneblab.StashLock.Client.Configuration;

var builder = WebApplication.CreateBuilder(args);

// Remote vault (production)
builder.Configuration.AddStashLockRemote(
    box: "myapp",
    tag: "prod",
    version: "v1");

// Then access secrets via IConfiguration
var app = builder.Build();
var dbConn = app.Configuration["Database:ConnectionString"];

Standalone API

VaultKey — Configure access

// From environment variable STASHLOCK_VAULT_KEY
var vaultKey = VaultKey.FromEnvironment();

// From file
var vaultKey = VaultKey.FromFile("/path/to/vault.key");

// Direct string
var vaultKey = VaultKey.FromString("box.tag.version.password");

Vault key format: box.tag.version.password (4 dot-separated segments)

SecretsStoreAsync — Open and read secrets

// Remote encrypted vault (production)
var store = await SecretsStoreAsync.OpenRemoteAsync(vaultKey);

// Remote sealed-box encrypted vault (X25519)
var store = await SecretsStoreAsync.OpenRemoteSealedAsync(
    box: "myapp", tag: "prod", version: "v1");

// Local encrypted file (stashlock.enc.*.json)
var store = await SecretsStoreAsync.OpenEncryptedFileAsync("./stashlock.enc.prod.secrets.json");

// Plain JSON file (development)
var store = await SecretsStoreAsync.OpenFileAsync("./secrets.json");

// Auto-discover dev file (looks for dev/secrets/secrets.json)
var store = await SecretsStoreAsync.TryOpenDevFileAsync();

Read secrets

// Single secret
string value = await store.GetAsync("SecretKey");

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

Early initialization pattern

Load secrets before the host builder is created:

var vaultKey = VaultKey.FromEnvironment();
var store = await SecretsStoreAsync.OpenRemoteAsync(vaultKey);

var builder = WebApplication.CreateBuilder(args);

var dbConn = await store.GetAsync("Database:ConnectionString");
builder.Services.AddDbContext<MyContext>(o => o.UseSqlServer(dbConn));

IConfiguration Integration API

Three extension methods on IConfigurationBuilder:

AddStashLockRemote — Remote vault

Fetches encrypted secrets from a StashLock server, decrypts with X25519 private key, and loads into IConfiguration.

builder.Configuration.AddStashLockRemote(
    box: "myapp",
    tag: "prod",
    version: "v1",
    privateKeyBase64: null,  // falls back to STASHLOCK_PRIVATE_KEY env var
    apiUrl: null,            // falls back to STASHLOCK_API_URL env var
    apiKey: null);           // falls back to STASHLOCK_API_KEY env var

AddStashLockFile — Local encrypted file

Reads a stashlock.enc.*.json file, auto-detects SOPS or whole-file encryption, decrypts with X25519 private key.

builder.Configuration.AddStashLockFile(
    filePath: "./stashlock.enc.prod.secrets.json",
    privateKeyBase64: null);  // falls back to STASHLOCK_PRIVATE_KEY env var

AddStashLockDevFile — Plain JSON (development)

Reads an unencrypted JSON file. Nested objects are flattened with colon separators (e.g., Database:Host).

builder.Configuration.AddStashLockDevFile(
    filePath: "./dev-secrets.json");

Full IConfiguration example

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    builder.Configuration.AddStashLockDevFile("./dev-secrets.json");
}
else
{
    builder.Configuration.AddStashLockRemote(
        box: "myapp",
        tag: "prod",
        version: "v1");
}

var app = builder.Build();

// Access secrets like any other configuration source
var dbConn = app.Configuration["Database:ConnectionString"];
var apiKey = app.Configuration["ExternalApi:Key"];

Environment Variables

Error Handling

try
{
    var vaultKey = VaultKey.FromEnvironment();
    var store = await SecretsStoreAsync.OpenRemoteAsync(vaultKey);
}
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"
}

TryOpenDevFileAsync() auto-discovers this file when running in Dev or Test mode.

License

MIT License - see LICENSE file for details

Links

• NuGet Package
• Repository
• Issues