Raycynix.Extensions.Secrets 2.2.0

Raycynix.Extensions.Secrets

Raycynix.Extensions.Secrets provides a unified secret-resolution layer for Raycynix applications.

It allows application code to ask for secrets through ISecretResolver while the actual values can come from the standard configuration pipeline or environment-specific fallback providers.

What it contains

• AddRaycynixSecrets(...)
• SecretOptions
• ISecretProvider registrations
• ISecretResolver
• ISecretDiagnosticsResolver
• GetRequiredSecretAsync(...)
• ResolveWithSourceAsync(...)
• ExplainSecretResolutionAsync(...)
• configuration, environment, GitHub Actions, and TeamCity-style secret providers

What it does not contain

• cloud-specific secret storage integrations
• UI or interactive secret management
• a custom secret file format

Why use it

IConfiguration is still the place where configuration is assembled, but Raycynix.Extensions.Secrets gives applications a separate API for secret access.

That separation is useful when you want to:

• consume secrets through a dedicated abstraction instead of injecting raw IConfiguration
• support multiple secret sources without changing application code
• keep CI/CD-oriented environment variable resolution as a fallback when configuration does not contain a value

Usage

var builder = Host.CreateApplicationBuilder(args);

builder.Configuration.UseRaycynixConfigurationSources(options =>
{
    options.BaseFileName = "appsettings";
    options.EnvironmentName = builder.Environment.EnvironmentName;
    options.IncludeUserSecrets = builder.Environment.IsDevelopment();
});

builder.Services.AddRaycynixSecrets();

public sealed class GitHubTokenLoader(ISecretResolver secrets)
{
    public async Task<string?> LoadAsync(CancellationToken cancellationToken)
    {
        return await secrets.GetSecretAsync("GitHub:Token", cancellationToken);
    }
}

See the runnable example in examples/Raycynix.Extensions.Secrets.Example/Program.cs for a complete walkthrough of:

• default provider precedence
• custom provider precedence through SecretOptions
• required-secret resolution
• provider-aware resolution results
• explain output that shows the evaluated provider chain

The package resolves secrets through a provider chain and returns the first available value.

By default, the provider chain checks sources in this order:

1. IConfiguration
2. exact environment variable key
3. GitHub Actions-style normalized environment variable
4. TeamCity-style normalized environment variable

This allows applications to keep using the standard configuration pipeline, including .NET User Secrets, while still consuming secrets through a dedicated ISecretResolver.

You can customize the provider order when the default precedence is not appropriate:

builder.Services.AddRaycynixSecrets(options =>
{
    options.ProviderOrder.Clear();
    options.ProviderOrder.Add(typeof(GitHubSecretProvider));
    options.ProviderOrder.Add(typeof(ConfigurationSecretProvider));
    options.ProviderOrder.Add(typeof(EnvironmentSecretProvider));
    options.ProviderOrder.Add(typeof(TeamCitySecretProvider));
});

Providers not listed in SecretOptions.ProviderOrder are still evaluated afterward in their registration order.

Logging

The package uses optional Microsoft ILogger<T> diagnostics when logging is registered in the application. No Raycynix logging provider is required.

Diagnostics cover provider chain initialization, provider attempts, successful provider selection, and missing-secret outcomes. Secret keys, normalized keys, secret values, configuration values, and environment variable values are not logged.

Examples:

• ConnectionStrings:Main can be resolved from IConfiguration["ConnectionStrings:Main"]
• or from the exact environment variable ConnectionStrings:Main
• or from CONNECTIONSTRINGS_MAIN in GitHub Actions-style environments
• or from env.ConnectionStrings.Main in TeamCity-style environments

You can also use the convenience APIs for required secrets and diagnostics:

var token = await secrets.GetRequiredSecretAsync("Api:Token", cancellationToken);

var resolved = await secrets.ResolveWithSourceAsync("ConnectionStrings:Main", cancellationToken);
Console.WriteLine(resolved.ProviderName);

var attempts = await secrets.ExplainSecretResolutionAsync("ConnectionStrings:Main", cancellationToken);
foreach (var attempt in attempts)
{
    Console.WriteLine($"{attempt.ProviderName}: {attempt.Succeeded}");
}

Typical output looks like this:

Default provider order
Configuration -> Environment -> GitHub -> TeamCity
GetSecretAsync: Server=config;Database=main;
ResolveWithSourceAsync.ProviderName: ConfigurationSecretProvider
GetRequiredSecretAsync(Api:Token): config-token
ExplainSecretResolutionAsync:
- ConfigurationSecretProvider: True

Custom provider order
GitHub -> Configuration -> Environment -> TeamCity
ResolveWithSourceAsync.Value: Server=github;Database=main;
ResolveWithSourceAsync.ProviderName: GitHubSecretProvider
ExplainSecretResolutionAsync:
- GitHubSecretProvider: True