Skip to content
Support this libraryStar on GitHub

Secret Library for Go ​

secret

Read, replace, and delete bound secrets through a small Go API.

License: MITGo: 1.24.4+Status: v0.1.0 candidateLibrary unit coverage: 100%Executed library unit tests

Features · Quick Start · Drivers · Installation · How it works · Examples · API

Bind names such as DATABASE_PASSWORD to encrypted local files, AWS Secrets Manager, Google Secret Manager, Azure Key Vault, or Vault KV v2. Application code reads by name through secret.Reader; provider SDKs and resource locations stay in setup code.

Managed drivers also support replacing and deleting existing secrets. You own provisioning, authentication, and access policies.

Features ​

FeatureWhat you get
Small capabilitiesRead, replace, or delete with ordinary strings.
Explicit bindingsChoose provider locations once during construction.
Exact valuesPreserve bytes within each provider's documented limits.
Safe failuresClassify driver failures without exposing provider errors.
Deliberate mutationsSerialize same-secret writes and report uncertain outcomes.
Isolated testingUse a concurrency-safe store for application fixtures.

Quick Start ​

Encrypt a local secret with AES-256-GCM. The directory must already exist; key is a random 32-byte key loaded from a separate key manager. The caller owns the key and closes the root.

go
root, err := os.OpenRoot(directory)
if err != nil {
	panic(err)
}
defer root.Close()

store, err := filesecret.NewStore(root, key, map[string]string{
	"DATABASE_PASSWORD": "database-password.enc",
})
if err != nil {
	panic(err)
}
ctx := context.Background()
if err := store.Set(ctx, "DATABASE_PASSWORD", "public-example-password"); err != nil {
	panic(err)
}
password, err := store.Get(ctx, "DATABASE_PASSWORD")
if err != nil {
	panic(err)
}
// Pass password to your database client instead of logging it.
_ = password
fmt.Println("credential loaded")
// Output: credential loaded

if err := store.Delete(ctx, "DATABASE_PASSWORD"); err != nil {
	panic(err)
}
fmt.Println("credential deleted")
// Output: credential deleted

Import github.com/goforj/secret/driver/filesecret for this example. The complete runnable program uses a disposable key and directory. For persistent data, use the key-loading and recovery workflow and keep the key outside the secret directory. File confinement requires Go 1.25.12+, Go 1.26.5+, or stable Go 1.27+.

NewStore encrypts and authenticates values on disk. New is a separate, read-only plaintext reader for externally managed Docker and Kubernetes mounts. See file encryption and key management.

For key rotation, NewStoreWithKeys(root, currentKey, bindings, previousKeys...) reads with current or previous keys and always writes with the current key. Call store.Rotate(ctx) to migrate existing files; see the example.

Each Get reads one binding. Reuse the reader and context for additional names; the same pattern works with every managed driver. Reads are independent, so values read together are not an atomic snapshot.

Application services can accept secret.Reader. Workflows that replace or delete values can accept secret.Writer, secret.Deleter, or secret.Store.

Drivers ​

DriverBehaviorVerification
AWS Secrets ManagerText or binary; standard recovery windowMoto 5.1.16 emulator
Azure Key VaultUTF-8; vault-configured soft deletionLowkey Vault 7.4.0 emulator
Local filesAES-256-GCM store; explicit plaintext mounted-file readerReal filesystem, tampering, and projected-volume tests
Google Secret ManagerBinary values, CRC32C, and ETag deletionGoogle Secret Manager emulator (pinned image)
Vault KV v2Owned scalar paths; CAS and all-version deletionReal Vault 1.21.4 server

Cloud verification uses the listed emulators and real provider SDKs. Hosted AWS, Google, and Azure behavior has not been verified against dedicated accounts. See provider contracts for value limits, deletion behavior, construction, and emulator boundaries.

Installation ​

The first v0.1.0 release candidate is being verified; version tags have not been published. Run examples against this checkout's local modules. The examples module requires Go 1.26; use Go 1.26.5+ in that branch or stable Go 1.27+ for file examples:

sh
git clone https://github.com/goforj/secret.git
cd secret
go -C examples run ./encrypted
go -C examples run ./reader

The core has no external dependencies and requires Go 1.24.4. Optional modules isolate provider SDKs and their Go requirements:

ModuleMinimum GoPurpose
github.com/goforj/secret1.24.4Reader, Writer, Deleter, Store, Func, and error classifications
github.com/goforj/secret/secrettest1.24.4Map-backed application test fixtures
github.com/goforj/secret/driver/awssecret1.24.4AWS Secrets Manager
github.com/goforj/secret/driver/azuresecret1.26.0Azure Key Vault
github.com/goforj/secret/driver/filesecret1.25.12Encrypted local storage and plaintext mounted-file reads
github.com/goforj/secret/driver/gcpsecret1.26.0Google Secret Manager
github.com/goforj/secret/driver/vaultsecret1.26.0Vault KV v2

Import only the capabilities and drivers your application needs. Provider SDK dependencies stay in their driver modules. The file driver requires a patched os.Root implementation; Go 1.26.0 through 1.26.4 and prerelease toolchains are unsupported. See development and releases for dependency constraints and publication checks.

How it works ​

  • Names and bindings. Names follow [A-Z][A-Z0-9_]*, with a maximum of 255 bytes. Use application identifiers such as DATABASE_PASSWORD. Drivers copy bindings at construction, and unknown names never reach a provider.

  • Exact values. Values are ordinary strings. Reads preserve exact bytes within the provider's capabilities, without trimming, JSON parsing, environment fallback, caching, or rotation. Keep returned values out of logs and diagnostics.

  • Writes and deletion. Managed Set publishes a new current value at an existing resource; encrypted-file Set can also create a bound file. Delete targets the entire resource under the provider's retention policy. Vault deletion is irreversible. File deletion removes ciphertext without promising secure erasure of disk blocks or backups.

  • Concurrency. Each first-party store serializes mutations to the same binding. Different bindings and reads can proceed concurrently. Mutable resources require exclusive lifecycle ownership, including across separate store instances.

  • Retries. Provider SDK retries remain caller-owned except Google version creation, where the driver disables automatic retries.

  • Safe failures. Errors support errors.Is with ErrInvalid, ErrNotFound, ErrPermission, ErrUnavailable, and ErrIndeterminate. First-party drivers do not retain provider errors or response bodies in returned errors. secret.Func returns callback errors unchanged; the callback owns their classification and sanitization.

  • Uncertain writes. Check ErrIndeterminate before cancellation or deadline errors. A canceled mutation may still have committed remotely, so reconcile before retrying. Caller cancellation remains detectable alongside ErrIndeterminate. See the uncertain-write example.

  • Client ownership. Constructing code owns the SDK client or file root. Drivers borrow them and never close them. First-party drivers do not log; review injected client logging separately because it can disclose provider metadata.

Runnable Examples ​

Run from the repository root. No credentials required:

sh
go -C examples run ./encrypted         # Encrypted files
go -C examples run ./rotation          # Encryption key rotation
go -C examples run ./files             # Plaintext mounted files
go -C examples run ./reader            # Reader adapter
go -C examples run ./errors            # Uncertain writes
go -C examples test -run TestStore -v   # Application tests

Configured examples: persistent keys · managed providers.

API Index ​

Examples ​

Provider snippets use resource identifiers from your application configuration. The complete programs accept those identifiers as command-line flags.

Store encrypted files ​

Complete source

go
root, err := os.OpenRoot(directory)
if err != nil {
	panic(err)
}
defer root.Close()

store, err := filesecret.NewStore(root, key, map[string]string{
	"DATABASE_PASSWORD": "database-password.enc",
})
if err != nil {
	panic(err)
}
ctx := context.Background()
if err := store.Set(ctx, "DATABASE_PASSWORD", "public-example-password"); err != nil {
	panic(err)
}
password, err := store.Get(ctx, "DATABASE_PASSWORD")
if err != nil {
	panic(err)
}
// Pass password to your database client instead of logging it.
_ = password
fmt.Println("credential loaded")
// Output: credential loaded

if err := store.Delete(ctx, "DATABASE_PASSWORD"); err != nil {
	panic(err)
}
fmt.Println("credential deleted")
// Output: credential deleted

Load a persistent encryption key ​

Complete source

go
key, err := loadKey(keyFile)
if err != nil {
	return err
}
root, err := os.OpenRoot(directory)
if err != nil {
	return errors.New("encrypted secret directory unavailable")
}
defer root.Close()
store, err := filesecret.NewStore(root, key, map[string]string{
	"DATABASE_PASSWORD": "database-password.enc",
})
if err != nil {
	return err
}
password, err := store.Get(context.Background(), "DATABASE_PASSWORD")
if err != nil {
	return err
}
// Pass password to your database client instead of logging it.
_ = password
fmt.Println("credential loaded from persistent key")
// Output: credential loaded from persistent key

Rotate encryption keys ​

Complete source

go
store, err := filesecret.NewStoreWithKeys(root, currentKey, bindings, previousKey)
if err != nil {
	panic(err)
}
ctx := context.Background()
if _, err := store.Get(ctx, "DATABASE_PASSWORD"); err != nil {
	panic(err)
}
fmt.Println("old-key credential readable")
// Output: old-key credential readable

if err := store.Rotate(ctx); err != nil {
	panic(err)
}
fmt.Println("files rotated")
// Output: files rotated

currentOnly, err := filesecret.NewStore(root, currentKey, bindings)
if err != nil {
	panic(err)
}
if _, err := currentOnly.Get(ctx, "DATABASE_PASSWORD"); err != nil {
	panic(err)
}
fmt.Println("credential readable without previous key")
// Output: credential readable without previous key

Read mounted files ​

Complete source

go
root, err := os.OpenRoot(directory)
if err != nil {
	panic(err)
}
defer root.Close()

reader, err := filesecret.New(root, map[string]string{
	"DATABASE_USERNAME": "database-username",
	"DATABASE_PASSWORD": "database-password",
})
if err != nil {
	panic(err)
}

ctx := context.Background()
username, err := reader.Get(ctx, "DATABASE_USERNAME")
if err != nil {
	panic(err)
}
password, err := reader.Get(ctx, "DATABASE_PASSWORD")
if err != nil {
	panic(err)
}
// Pass both values directly to your database client. Keep them out of logs.
_, _ = username, password
fmt.Println("database credentials loaded")
// Output: database credentials loaded

Read from AWS Secrets Manager ​

Complete source

go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
	return err
}
client := secretsmanager.NewFromConfig(cfg)
store, err := awssecret.New(client, map[string]awssecret.Binding{
	"DATABASE_PASSWORD": {ARN: arn, Encoding: awssecret.Text},
})
if err != nil {
	return err
}
password, err := store.Get(ctx, "DATABASE_PASSWORD")
if err != nil {
	return err
}
// Pass password to your database client instead of logging it.
_ = password
fmt.Println("credential loaded")
// Output: credential loaded

Read from Google Secret Manager ​

Complete source

go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
client, err := secretmanager.NewClient(ctx)
if err != nil {
	return err
}
defer client.Close()
store, err := gcpsecret.New(client, parent, map[string]string{
	"DATABASE_PASSWORD": id,
})
if err != nil {
	return err
}
password, err := store.Get(ctx, "DATABASE_PASSWORD")
if err != nil {
	return err
}
// Pass password to your database client instead of logging it.
_ = password
fmt.Println("credential loaded")
// Output: credential loaded

Read from Azure Key Vault ​

Complete source

go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
	return err
}
client, err := azsecrets.NewClient(vault, credential, nil)
if err != nil {
	return err
}
store, err := azuresecret.New(client, map[string]azuresecret.Binding{
	"DATABASE_PASSWORD": {Name: name},
})
if err != nil {
	return err
}
password, err := store.Get(ctx, "DATABASE_PASSWORD")
if err != nil {
	return err
}
// Pass password to your database client instead of logging it.
_ = password
fmt.Println("credential loaded")
// Output: credential loaded

Read from Vault KV v2 ​

Complete source

go
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
client, err := api.NewClient(nil)
if err != nil {
	return err
}
store, err := vaultsecret.New(client.KVv2(mount), map[string]string{
	"DATABASE_PASSWORD": path,
})
if err != nil {
	return err
}
password, err := store.Get(ctx, "DATABASE_PASSWORD")
if err != nil {
	return err
}
// Pass password to your database client instead of logging it.
_ = password
fmt.Println("credential loaded")
// Output: credential loaded

Adapt an existing reader ​

Complete source

go
reader := secret.Func(func(ctx context.Context, name string) (string, error) {
	if name != "DATABASE_PASSWORD" {
		return "", secret.ErrNotFound
	}
	return "public-example-password", nil
})

ctx := context.Background()
if _, err := reader.Get(ctx, "DATABASE_PASSWORD"); err != nil {
	panic(err)
}
fmt.Println("credential loaded")
// Output: credential loaded

if _, err := reader.Get(ctx, "UNKNOWN"); !errors.Is(err, secret.ErrNotFound) {
	panic("expected an unknown name to return ErrNotFound")
}
fmt.Println("unknown name rejected")
// Output: unknown name rejected

Handle an uncertain write ​

Complete source

go
err := writer.Set(context.Background(), "DATABASE_PASSWORD", "public-replacement")
if errors.Is(err, secret.ErrIndeterminate) {
	// Read back or reconcile through provider tooling before attempting another write.
	fmt.Println("check provider state before retrying")
	// Output: check provider state before retrying
} else if err != nil {
	panic(err)
}
fmt.Println("deadline still detectable:", errors.Is(err, context.DeadlineExceeded))
// Output: deadline still detectable: true

Test replacements and deletion ​

Complete source

go
store := secrettest.New(t, map[string]string{
	"DATABASE_PASSWORD": "public-test-password",
})
ctx := context.Background()

if err := store.Set(ctx, "DATABASE_PASSWORD", "public-replacement"); err != nil {
	t.Fatal(err)
}
if _, err := store.Get(ctx, "DATABASE_PASSWORD"); err != nil {
	t.Fatal(err)
}
fmt.Println("replacement readable")
// Output: replacement readable

if err := store.Delete(ctx, "DATABASE_PASSWORD"); err != nil {
	t.Fatal(err)
}
if _, err := store.Get(ctx, "DATABASE_PASSWORD"); !errors.Is(err, secret.ErrNotFound) {
	t.Fatal("deleted fixture remains readable")
}
fmt.Println("removed")
// Output: removed

Development ​

sh
make test
make test-race
make vet
make test-integration
make test-coverage
make generate
make check-generated
make modules-check

Integration tests require Docker. They use real provider SDKs and isolated public fixtures. Unit coverage is measured independently from integration coverage and enforced at exactly 100% of library statements. Badges are generated from passing test evidence tied to the library source. README snippets come from the example programs.

See development and releases and the accepted design for detailed contracts and verification policy.

License ​

MIT. See LICENSE.