secret

secret

Package secret provides a simple, provider-agnostic interface for retrieving secrets within GitLab services. Secrets are wrapped in a Secret type that is always redacted in logs, error messages, and JSON output.

Quick start

// Default: reads from environment variables.
client := secret.New()

val, err := client.Get(ctx, "DB_PASSWORD")
if errors.Is(err, secret.ErrNotFound) {
    // secret not configured
}

// Use the value explicitly only where needed.
dsn := "postgres://..." + val.Value()

Providers

All providers satisfy the Provider interface:

type Provider interface {
    Get(ctx context.Context, key string) (Secret, error)
}

EnvProvider (default)

Reads from environment variables. New() uses EnvProvider by default.

client := secret.New()
val, err := client.Get(ctx, "DB_PASSWORD")

An unset variable returns ErrNotFound. A variable set to an empty string is returned as-is.

FileProvider

Reads from files in a directory. Each file's name is the key and its contents are the value. This matches the layout produced by Kubernetes secret volume mounts.

p := secret.NewFileProvider("/var/run/secrets/my-service")
client := secret.NewWithConfig(&secret.Config{Provider: p})

// Reads /var/run/secrets/my-service/db-password
val, err := client.Get(ctx, "db-password")

FileProvider rejects keys containing path traversal sequences (e.g. ../../etc/passwd) and returns ErrInvalidKey. File contents are trimmed of leading and trailing whitespace.

RotatingFileProvider

For secrets that change in place (e.g. Kubernetes secret volume mounts updated by the kubelet), RotatingFileProvider polls a file on a configurable interval and notifies consumers when the value changes.

See Live secret rotation below.

Live secret rotation

RotatingFileProvider implements RotatingProvider, which extends Provider with a background poll loop:

p := secret.NewRotatingFileProvider(
    "/var/run/secrets/my-service", // directory
    "db-password",                 // filename (key)
    time.Minute,                   // poll interval
)

if err := p.Start(ctx); err != nil {
    return err
}
defer p.Shutdown(ctx)

// Subscribe to rotation events in a background goroutine.
go func() {
    for event := range p.OnRotate() {
        if event.Err != nil {
            log.Printf("rotation poll error: %v", event.Err)
            continue
        }
        // Reconnect or reload using the new value.
        pool.Reconnect(event.NewValue.Value())
    }
}()

// Point-in-time reads still work; Get reads the file directly.
val, err := p.Get(ctx, "db-password")

Rotation semantics

Lifecycle

RotatingFileProvider integrates cleanly with app.App:

p := secret.NewRotatingFileProvider("/var/run/secrets/my-service", "db-password", time.Minute)

a.Register(p) // app.App calls Start and Shutdown automatically

app.App calls Start(ctx) on registration and Shutdown(ctx) in reverse order during graceful shutdown.

One provider per file

Each RotatingFileProvider watches a single file. For multiple secrets, create multiple instances:

dbPass  := secret.NewRotatingFileProvider(dir, "db-password",  time.Minute)
apiKey  := secret.NewRotatingFileProvider(dir, "api-key",      time.Minute)

The Secret type

Secret is a value type that never leaks its contents through normal formatting paths:

s := secret.NewSecret("supersecret")

fmt.Println(s)         // [REDACTED]
fmt.Printf("%v", s)    // [REDACTED]
fmt.Printf("%#v", s)   // [REDACTED]
json.Marshal(s)        // "[REDACTED]"
slog.Info("got", "secret", s) // secret=[REDACTED]

Use s.Value() only where the raw string is explicitly required (e.g. building a DSN or passing to a client library).

Error handling

val, err := client.Get(ctx, "MY_SECRET")
switch {
case errors.Is(err, secret.ErrNotFound):
    // Secret is not configured; apply a default or return an error.
case errors.Is(err, secret.ErrInvalidKey):
    // Key is malformed (e.g. path traversal). This is a programming error.
case err != nil:
    // Unexpected I/O or backend error.
}

Custom providers

Implement Provider to add a new backend:

type VaultProvider struct { /* ... */ }

func (v *VaultProvider) Get(ctx context.Context, key string) (secret.Secret, error) {
    raw, err := v.client.Read(ctx, key)
    if err != nil {
        return secret.Secret{}, err
    }
    return secret.NewSecret(raw), nil
}

client := secret.NewWithConfig(&secret.Config{
    Provider: &VaultProvider{client: vaultClient},
})

Testing

Use MockProvider from the secrettest package to supply known values in tests without touching the environment or the filesystem:

import "gitlab.com/gitlab-org/labkit/v2/testing/secrettest"

client := secret.NewWithConfig(&secret.Config{
    Provider: secrettest.NewMockProvider(map[string]string{
        "DB_PASSWORD": "hunter2",
        "API_KEY":     "test-key",
    }),
})

val, err := client.Get(ctx, "DB_PASSWORD")
// val.Value() == "hunter2"

Keys absent from the map return ErrNotFound.