Custom secret provider
How do you use Envilder with a secret store it does not support, or test your startup code without a cloud account? In the SDKs, pass your own provider to the fluent builder. The map file, contract validation and injection work exactly as with AWS SSM or Azure Key Vault.
When to use it
A custom provider replaces the AWS or Azure client that the SDK would build from $config. Two common reasons:
- Your secrets live in a store Envilder does not support yet (HashiCorp Vault, 1Password, a database, an internal API).
- You want to test your startup code against an in-memory fake: no cloud account, no emulator, no environment variables.
Only the runtime SDKs (1.2+) accept a custom provider. The CLI and the GitHub Action support AWS SSM and Azure Key Vault.
How it works
A provider implements one interface, and optionally a second one for contract validation:
| Interface | Method (Node.js · Python · .NET) | Used for |
|---|---|---|
ISecretProvider | getSecrets · get_secret · GetSecret | Resolving the values to inject. Missing secrets are left out, not raised. |
ISecretExistenceChecker | checkSecretsExist · check_secrets_exist · CheckSecretsExistAsync | Optional. Contract validation: answering exists or missing for each key without reading any value. |
Pass the instance with withSecretProvider() (with_secret_provider() in Python, WithSecretProvider() in .NET). The SDK no longer builds a provider from $config, but it still validates the map file, so a mistake in the file your app uses in production also fails in tests that use a fake.
Example
An in-memory provider that implements both interfaces, plugged into a load with contract validation:
import {
Envilder,
type ISecretExistenceChecker,
type ISecretProvider,
} from '@envilder/sdk';
const fakeSecrets = new Map([['/app/db-url', 'postgres://localhost/test']]);
class InMemoryProvider implements ISecretProvider, ISecretExistenceChecker {
async getSecrets(names: string[]) {
return new Map(
names.flatMap((name) => {
const value = fakeSecrets.get(name);
return value === undefined ? [] : [[name, value] as const];
}),
);
}
async checkSecretsExist(names: readonly string[]) {
return new Map(
names.map((name) => [
name,
{ status: fakeSecrets.has(name) ? 'exists' : 'missing' } as const,
]),
);
}
}
await Envilder.fromMapFile('envilder.json')
.withSecretProvider(new InMemoryProvider())
.withContractValidation()
.inject();from envilder import (
Envilder,
ISecretExistenceChecker,
ISecretProvider,
SecretExistence,
SecretExistenceStatus,
)
FAKE_SECRETS = {'/app/db-url': 'postgres://localhost/test'}
class InMemoryProvider(ISecretProvider, ISecretExistenceChecker):
def get_secret(self, name):
return FAKE_SECRETS.get(name)
def check_secrets_exist(self, names):
return {
name: SecretExistence(
SecretExistenceStatus.EXISTS
if name in FAKE_SECRETS
else SecretExistenceStatus.MISSING
)
for name in names
}
(
Envilder.from_map_file('envilder.json')
.with_secret_provider(InMemoryProvider())
.with_contract_validation()
.inject()
)using Envilder;
using Envilder.Domain.Ports;
await Env.FromMapFile("envilder.json")
.WithSecretProvider(new InMemoryProvider())
.WithContractValidation()
.InjectAsync();
public sealed class InMemoryProvider : ISecretProvider, ISecretExistenceChecker
{
private readonly Dictionary<string, string> _secrets = new()
{
["/app/db-url"] = "Server=localhost;Database=test",
};
public string? GetSecret(string name) => _secrets.GetValueOrDefault(name);
public Task<string?> GetSecretAsync(string name, CancellationToken ct = default)
=> Task.FromResult(GetSecret(name));
public Task<IReadOnlyDictionary<string, SecretExistence>> CheckSecretsExistAsync(
IReadOnlyCollection<string> names, CancellationToken ct)
=> Task.FromResult<IReadOnlyDictionary<string, SecretExistence>>(names.ToDictionary(
name => name,
name => new SecretExistence(_secrets.ContainsKey(name)
? SecretExistenceStatus.Exists
: SecretExistenceStatus.Missing)));
}Contract validation with a custom provider
- If the provider implements ISecretExistenceChecker, validateContract() and withContractValidation() check every key with it, as with the built-in providers.
- If it does not, every key is reported as provider_error ("The provider cannot check whether a secret exists."), so a load with contract validation fails instead of passing silently.
- The provider field of each key keeps the configured type: the withProvider() override, then $config.provider, then aws.
Runnable examples
envilder-examples has one example per SDK: a provider over a local file encrypted with AES-256-GCM, with tests for loading, failing at startup on a missing secret, and validating the contract without decrypting anything.