Tooark.Secrets 4.7.0

Tooark.Secrets

Library with the Tooark family's secrets and parameters abstractions. The store feeds IConfiguration, so the packages that already read their options from configuration (Storage, Securities, OpenId, Observability) receive the store's values without any change. For what is only known at runtime, there is the ISecretService, with cache.

The package has no cloud SDK: each store lives in its own package.

🌍 Languages: 🇺🇸 English (this file) · 🇧🇷 Português

📑 Contents

• Overview
• Installation
• Configuration
• From store names to keys
• Runtime reads
• Usage Examples
• Dependencies
• Best Practices
• Error Codes and Solutions
• Contributing
• Help & Security
• Support
• License

📖 Overview

• Configuration source — the store enters IConfiguration like any other source, and wins over the earlier ones (appsettings.json, environment variables). Storage:SecretKey, Jwt:Secret or OpenId:Entra:ClientSecret come from the store, and the AddTooark* calls keep reading and validating the options as always.
• ISecretService — reads a secret by name at runtime, such as a tenant's API key, with cache. It reads secrets only: parameters are configuration and come through the source.
• Read at startup — the source reads the store once, when the configuration is built. Tooark packages validate and keep their options at startup, so rotating a secret they use takes a restart or a new deploy. The ISecretService reads again when the cache expires.
• The store credential comes from the environment — AWS role, Google Application Default Credentials, or Kubernetes/AppRole auth in Vault. A store access key kept in appsettings.json would only move the secret around.
• Fails at startup — an unreachable store, a missing permission or a timeout keeps the application from starting, unless Optional.

🔧 Installation

Install the store package, which brings this one:

dotnet add package Tooark.Secrets.Aws
# or
dotnet add package Tooark.Secrets.Gcp
# or
dotnet add package Tooark.Secrets.Vault

The Tooark aggregator brings only this package, with the abstractions, and no provider.

⚙️ Configuration

appsettings.json

The options live in the Secrets section, together with the store's own (AWS, Google Cloud, Vault):

{
  "Secrets": {
    "SecretsPrefix": "arkuest/prod",
    "TimeoutSeconds": 30,
    "CacheMinutes": 5
  }
}

Program.cs

The source goes on the IConfigurationBuilder, after the other sources and before the AddTooark* calls that read the options:

using Tooark.Secrets.Aws.Injections;

var builder = WebApplication.CreateBuilder(args);

// The store goes on top of appsettings.json and environment variables
builder.Configuration.AddTooarkSecretsAws();

// Storage, Securities and the others already receive the store's values
builder.Services.AddTooarkStorageAws(builder.Configuration);

// Optional: runtime reads, with cache
builder.Services.AddTooarkSecretsAws(builder.Configuration);

The source's options come from the Secrets section of the sources already added, and the code adjustment applies on top: AddTooarkSecretsAws(options => options.SecretsPrefix = "arkuest/prod").

SecretsOptions properties

🔑 From store names to keys

Each secret or parameter under the configured prefix becomes a key. The name loses the prefix, and / and __ become ::

• The prefix respects the level boundary: arkuest/prod does not take arkuest/production.
• Google does not accept / or : in names, so levels there use __, as in environment variables.
• In Vault, each field of a secret is a key, and the fields of the secret at the path itself sit at the root.
• With the same name in a secret and a parameter, the secret wins.

ExpandJson

Off, the default, the value stays as text, even when it is JSON. That fits one secret per key, including a Google service account key in Storage:CredentialsJson.

On, a value that is a JSON object becomes child keys. That fits one document with many keys, such as the Secrets Manager "key/value" secret:

{ "Jwt": { "Secret": "..." }, "Storage__SecretKey": "...", "OpenId": { "Entra": { "ClientSecret": "..." } } }

Kept in the secret arkuest/prod, the prefix itself, it becomes Jwt:Secret, Storage:SecretKey and OpenId:Entra:ClientSecret. Text inside the document is never parsed as JSON again, so a service account key kept there as text stays whole. The expansion applies to every value of the source: with one secret per key, leave it off.

What the Tooark packages read from the store

Any configuration key can come from the store. The family's sensitive ones:

🔍 Runtime reads

ISecretService reads a secret by its name in the store. The value stays cached for CacheMinutes; a missing secret is not cached, so it is read as soon as it is created.

In Vault, the value is the JSON object with the secret's fields, and GetFieldAsync reads one of them. Parameters do not go through the service: they are configuration.

using Tooark.Secrets.Interfaces;

public sealed class TenantService(ISecretService secrets)
{
  public Task<string?> ApiKey(string tenant, CancellationToken cancellationToken) =>
    secrets.GetFieldAsync($"arkuest/tenants/{tenant}", "ApiKey", cancellationToken);
}

📝 Usage Examples

One document with every key (AWS)

{ "Secrets": { "SecretsPrefix": "arkuest/prod", "ExpandJson": true } }

The secret arkuest/prod holds the JSON document, and each field becomes a key.

One secret per key (Google Cloud)

{ "Secrets": { "ProjectId": "arkuest", "SecretsPrefix": "arkuest-prod" } }

The secrets arkuest-prod__Jwt__Secret and arkuest-prod__Storage__CredentialsJson become Jwt:Secret and Storage:CredentialsJson.

Optional source in development

builder.Configuration.AddTooarkSecretsVault(options => options.Optional = builder.Environment.IsDevelopment());

📋 Dependencies

The package runs on the base .NET runtime, without ASP.NET Core and without any cloud SDK.

🎯 Best Practices

1. Nothing sensitive in appsettings.json — with the store, the versioned file keeps only what is not secret: region, bucket, prefix.
2. Environment identity for the store — role, service account or Kubernetes auth; the store credential cannot come from the store.
3. One prefix per environment — arkuest/prod, arkuest/staging: the application's permission stays scoped to its own.
4. Rotation with a restart — Tooark packages read their options at startup; change the secret and deploy again or restart the instances.
5. Optional only where it makes sense — in production, starting without the secrets is usually worse than not starting.

⚠️ Error Codes and Solutions

Each store's own errors are in its README.

🤝 Contributing

Contributions are welcome! Start with CONTRIBUTING.md — it covers the development workflow, the coding and commit conventions and the pull request checklist. Bugs and feature requests go through the issue templates of the Tooark repository.

By participating you agree to the Code of Conduct.

🆘 Help & Security

• ❓ Questions, bugs, feature ideas — see SUPPORT.md for the right channel
• 🔒 Security vulnerabilities — do not open a public issue; follow SECURITY.md

💖 Support

If Tooark helps your projects, consider supporting its development:

• 💙 GitHub Sponsors
• ☕ Ko-fi

Every contribution helps keep the project maintained and improving. Thank you! 🙏

📄 License

This project is licensed under the BSD 3-Clause License.