Secret Library for Go

Read, replace, and delete bound secrets through a small Go API.
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
| Feature | What you get |
|---|---|
| Read, replace, or delete with ordinary strings. | |
| Choose provider locations once during construction. | |
| Preserve bytes within each provider's documented limits. | |
| Classify driver failures without exposing provider errors. | |
| Serialize same-secret writes and report uncertain outcomes. | |
| Use 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.
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 deletedImport 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
| Driver | Behavior | Verification |
|---|---|---|
| Text or binary; standard recovery window | Moto 5.1.16 emulator | |
| UTF-8; vault-configured soft deletion | Lowkey Vault 7.4.0 emulator | |
| AES-256-GCM store; explicit plaintext mounted-file reader | Real filesystem, tampering, and projected-volume tests | |
| Binary values, CRC32C, and ETag deletion | Google Secret Manager emulator (pinned image) | |
| Owned scalar paths; CAS and all-version deletion | Real 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:
git clone https://github.com/goforj/secret.git
cd secret
go -C examples run ./encrypted
go -C examples run ./readerThe core has no external dependencies and requires Go 1.24.4. Optional modules isolate provider SDKs and their Go requirements:
| Module | Minimum Go | Purpose |
|---|---|---|
| github.com/goforj/secret | 1.24.4 | Reader, Writer, Deleter, Store, Func, and error classifications |
| github.com/goforj/secret/secrettest | 1.24.4 | Map-backed application test fixtures |
| github.com/goforj/secret/driver/awssecret | 1.24.4 | AWS Secrets Manager |
| github.com/goforj/secret/driver/azuresecret | 1.26.0 | Azure Key Vault |
| github.com/goforj/secret/driver/filesecret | 1.25.12 | Encrypted local storage and plaintext mounted-file reads |
| github.com/goforj/secret/driver/gcpsecret | 1.26.0 | Google Secret Manager |
| github.com/goforj/secret/driver/vaultsecret | 1.26.0 | Vault 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 asDATABASE_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
Setpublishes a new current value at an existing resource; encrypted-fileSetcan also create a bound file.Deletetargets 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.IswithErrInvalid,ErrNotFound,ErrPermission,ErrUnavailable, andErrIndeterminate. First-party drivers do not retain provider errors or response bodies in returned errors.secret.Funcreturns callback errors unchanged; the callback owns their classification and sanitization.Uncertain writes. Check
ErrIndeterminatebefore cancellation or deadline errors. A canceled mutation may still have committed remotely, so reconcile before retrying. Caller cancellation remains detectable alongsideErrIndeterminate. 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:
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 testsConfigured examples: persistent keys · managed providers.
API Index
| Group | Functions |
|---|---|
| Core | Func.Get · Reader.Get · Store.Delete · Store.Set · Writer.Set · filesecret.Store.Rotate |
| Driver Constructors | awssecret.New · azuresecret.New · filesecret.NewStoreWithKeys · filesecret.NewStore · filesecret.New · gcpsecret.New · vaultsecret.New |
| Errors | ErrIndeterminate · ErrNotFound |
| Testing | secrettest.New |
Examples
Provider snippets use resource identifiers from your application configuration. The complete programs accept those identifiers as command-line flags.
Store encrypted files
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 deletedLoad a persistent encryption key
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 keyRotate encryption keys
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 keyRead mounted files
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 loadedRead from AWS Secrets Manager
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 loadedRead from Google Secret Manager
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 loadedRead from Azure Key Vault
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 loadedRead from Vault KV v2
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 loadedAdapt an existing reader
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 rejectedHandle an uncertain write
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: trueTest replacements and deletion
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: removedDevelopment
make test
make test-race
make vet
make test-integration
make test-coverage
make generate
make check-generated
make modules-checkIntegration 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.