secrets

secrets

A Go library for reading secrets from multiple providers using struct tags.

type Config struct {
    DBHost string              `secret:"awssm://prod/db#host"`
    DBPort int                 `secret:"awssm://prod/db#port"`
    DBPass string              `secret:"awssm://prod/db#password"`
    APIKey string              `secret:"env://API_KEY"`
    Debug  bool                `secret:"debug,optional"`
    Cert   []byte              `secret:"file:///etc/tls/cert.pem"`
    EncKey secrets.Versioned[[]byte] `secret:"awssm://prod/enc-key"`
}

Declare secrets as struct fields, resolve them from any combination of providers, and watch for changes at runtime.

Install

go get github.com/brwse/go-secrets

Usage

r := secrets.NewResolver(
    secrets.WithDefault(awssm.New(awssm.WithRegion("us-west-2"))),
    secrets.WithProvider("env", env.New()),
    secrets.WithProvider("file", file.New()),
)
defer r.Close()

var cfg Config
if err := r.Resolve(ctx, &cfg); err != nil {
    log.Fatal(err)
}

Cloud providers return (*Provider, error) from New():

sm, err := awssm.New(awssm.WithRegion("us-west-2"))
if err != nil {
    log.Fatal(err)
}
r := secrets.NewResolver(secrets.WithDefault(sm))

Tag format

secret:"[scheme://]key[#fragment][,option...]"

Bare keys (no scheme) route to the default provider. Keys with a scheme route to the provider registered for that scheme. The #fragment extracts a field from JSON-encoded secrets. Nested fragments like #db.host are supported.

Supported field types

string, []byte, bool, int/int8-int64, uint/uint8-uint64, float32, float64, time.Duration, pointer variants (*string, etc.), encoding.TextUnmarshaler implementations, Versioned[T], and nested/embedded structs.

Providers

Each provider accepts a WithClient option to inject a custom or pre-configured client implementation.

Key rotation

Use Versioned[T] to fetch both current and previous values. The provider must implement VersionedProvider.

type Config struct {
    EncKey secrets.Versioned[[]byte] `secret:"awssm://prod/enc-key"`
}

// cfg.EncKey.Current  — active key
// cfg.EncKey.Previous — previous key for re-encryption

Use version= to fetch a specific version:

type Config struct {
    OldKey string `secret:"key,version=previous"`
}

Watching for changes

w, err := r.Watch(ctx, &cfg, secrets.WatchInterval(5*time.Minute))
if err != nil {
    log.Fatal(err)
}
defer w.Stop()

go func() {
    for event := range w.Changes() {
        log.Printf("secret %s changed", event.Field)
        w.RLock()
        // read cfg safely
        w.RUnlock()
    }
}()

The watcher polls at the configured interval (default 1 minute), updates only secret-tagged fields under a write lock, and emits ChangeEvent values on the channel. Use w.RLock()/w.RUnlock() when reading the struct from other goroutines.

Validation

if err := r.Validate(&cfg); err != nil {
    log.Fatal(err) // bad tags, unknown schemes, unsupported types
}

Checks tag syntax and provider registration without making any network calls.

Caching

Wrap a provider with NewCachedProvider to avoid redundant API calls. Cached values are held in memory and reused until the TTL expires. This is especially useful for cloud providers where every Resolve() or Watch poll cycle would otherwise hit the network.

sm, _ := awssm.New(awssm.WithRegion("us-west-2"))
r := secrets.NewResolver(
    secrets.WithDefault(secrets.NewCachedProvider(sm, 5*time.Minute)),
    secrets.WithProvider("env", env.New()), // no cache needed
)

Only successful results are cached — errors always pass through. Call Clear() to evict all entries manually. Close() clears the cache and closes the underlying provider if it implements io.Closer.

Parallel fetching

Secrets are fetched concurrently (default parallelism: 10). Multiple fields referencing the same secret URI with different #fragment values result in a single fetch.

r := secrets.NewResolver(
    secrets.WithDefault(sm),
    secrets.WithParallelism(20),
)