Table of Contents

Interface ISecretsProvider

Namespace
Invex.Atom.Build.Secrets
Assembly
Invex.Atom.Build.dll

Defines a contract for retrieving sensitive configuration values (secrets) from a secure storage provider.

public interface ISecretsProvider

Examples

// 1. Implement the interface
public class MySecretsProvider : ISecretsProvider
{
    public async ValueTask<string?> GetSecretAsync(string key, CancellationToken cancellationToken) =>
        await MySecureStore.GetAsync(key, cancellationToken);
}
// 2. Register the provider from your partial build class
static partial void OnConfigureHostBuilder(IHostApplicationBuilder builder) =>
    builder.Services.AddSingleton<ISecretsProvider, MySecretsProvider>();
// 3. Use a secret parameter in a target
[SecretDefinition("my-api-key", "An API key.")]
string MyApiKey => GetParam(() => MyApiKey);

Remarks

This interface is the core of the Atom framework's secret management system, enabling secure retrieval of sensitive data like API keys and connection strings. Implementations can integrate with various backends such as Azure Key Vault or .NET User Secrets.

The framework automatically discovers and queries registered providers when resolving parameters marked with SecretDefinitionAttribute. Providers are queried in descending Priority order (ties preserve registration order), creating a fallback chain (e.g., from a cloud provider to local user secrets).

Before a build executes its targets, Atom asynchronously prefetches the secret parameters used by the targets that will run, passing the build's cancellation token (which is signalled when the host stops). Parameter property getters (GetParam(() => MySecret)) are synchronous, so a secret that was not prefetched (for example, one read by name from a provider or a target that is not part of the run) is resolved by blocking on GetSecretAsync(string, CancellationToken) with System.Threading.CancellationToken.None. Atom runs as a console application without a System.Threading.SynchronizationContext, so this does not deadlock, but implementations should still enforce their own timeouts for network calls.

Properties

Priority

Gets the resolution priority of the secrets provider.

int Priority { get; }

Property Value

int

Remarks

Providers with a higher priority value are queried first when resolving secrets among multiple providers; providers with equal priority are queried in registration order. The default value is 0.

Methods

GetSecretAsync(string, CancellationToken)

Asynchronously retrieves a secret value by its key.

ValueTask<string?> GetSecretAsync(string key, CancellationToken cancellationToken)

Parameters

key string

The unique identifier for the secret to retrieve (the parameter's argument name).

cancellationToken CancellationToken

A token that is cancelled when the build is cancelled or the host is stopping. It is System.Threading.CancellationToken.None when the secret is resolved synchronously outside the prefetch phase.

Returns

ValueTask<string>

The secret value associated with the key, or null if the secret is not found in this provider.

Remarks

Implementations should return null rather than throwing an exception if a key is not found, allowing the framework to query other registered providers. Results are not cached by the provider contract; Atom caches resolved values in IParamService.

See Also