secretx

package
v0.38.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 31, 2026 License: MIT Imports: 7 Imported by: 1

Documentation

Overview

Package secretx separates a secret's storage from its use: application data holds a reference, a Resolver turns that reference into the value, and the value travels in a type that refuses to print itself.

The discipline it enforces is that a credential belongs in a secret store, while the row, document or config that needs it holds only a pointer to it. A database dump, a log line or an API response then leaks a reference, which is worth nothing without the permission to resolve it.

Index

Constants

View Source
const EnvPrefix = "env:"

EnvPrefix is the reference prefix Env answers to.

View Source
const Redacted = "[REDACTED]"

Redacted is what a Value prints as. It is deliberately conspicuous: seeing it in a log is the signal that the redaction worked, not that data was lost.

View Source
const StaticPrefix = "static:"

StaticPrefix is the reference prefix Static issues and answers to.

Variables

This section is empty.

Functions

func EnvRef

func EnvRef(name string) string

EnvRef returns the reference that resolves to environment variable name.

func Guard

func Guard(r Resolver, isProduction bool) error

Guard reports whether r may be used, given whether this is production.

Call it once at startup, so an insecure resolver left in place by a bad deployment stops the process rather than quietly protecting nothing:

if err := secretx.Guard(resolver, app.Config.App.IsProduction()); err != nil {
    return err
}

A resolver that does not implement Insecure is assumed to be safe, so a real secret store needs no cooperation to pass.

func StaticRef

func StaticRef(name string) string

StaticRef returns the reference that resolves to the static secret name.

Types

type Env

type Env struct{}

Env resolves a reference of the form "env:NAME" from the process environment. It is a legitimate production mechanism — it is how a container orchestrator or a secrets operator usually delivers a credential — so it is not marked insecure.

It is read-only: there is no way to write an environment variable that outlives the process, so Env implements Resolver and not Storer. Pair it with a real store when the application also has to create secrets.

func NewEnv

func NewEnv() *Env

NewEnv returns a Resolver backed by the process environment.

func (*Env) Resolve

func (e *Env) Resolve(_ context.Context, ref string) (Value, error)

Resolve reads the environment variable named by ref, which must carry the "env:" prefix so that a reference issued by a different store is rejected rather than silently looked up in the environment.

type Insecure

type Insecure interface {
	// Insecure reports that this resolver must not hold production secrets.
	Insecure() bool
}

Insecure is implemented by a Resolver that does not actually protect what it holds — one that keeps secrets in memory, in plain config, or alongside the data that references them. Such a resolver is useful for tests and local development and has no business in production.

type InsecureError

type InsecureError struct {
	Resolver Resolver
}

InsecureError reports an insecure Resolver reaching production. It is a distinct type so a caller can tell this apart from an ordinary startup failure — it is a deployment mistake, not a broken dependency.

func (*InsecureError) Error

func (e *InsecureError) Error() string

type ReadWriter

type ReadWriter interface {
	Resolver
	Storer
}

ReadWriter is the pair of them, for a store that does both.

type Resolver

type Resolver interface {
	Resolve(ctx context.Context, ref string) (Value, error)
}

Resolver turns a reference into the secret it points at.

A reference is opaque to its holder: only the Resolver that issued it knows whether it is an ARN, an environment variable name or a path. Implementations should return a not-found error for an unknown reference, distinguishable from a failure to reach the store — the caller usually treats the first as a misconfiguration and the second as worth retrying.

type Static

type Static struct {
	// contains filtered or unexported fields
}

Static keeps secrets in memory. It exists for tests and for running locally without a secret store, and it reports itself as Insecure so that Guard stops a deployment that reaches production still using it.

Stored secrets do not outlive the process, which is the other reason not to mistake it for a store: a reference recorded in a database today resolves to nothing after a restart.

func NewStatic

func NewStatic(seed map[string]string) *Static

NewStatic returns an in-memory store seeded with the given name/value pairs, each reachable at StaticRef(name).

func (*Static) Delete

func (s *Static) Delete(_ context.Context, ref string) error

Delete removes the secret ref points at, and is a no-op for one that is already gone.

func (*Static) Insecure

func (s *Static) Insecure() bool

Insecure implements the Insecure interface, and always reports true.

func (*Static) Resolve

func (s *Static) Resolve(_ context.Context, ref string) (Value, error)

Resolve returns the secret stored under ref.

func (*Static) Store

func (s *Static) Store(_ context.Context, name string, value Value) (string, error)

Store writes value under name, replacing whatever was there.

type Storer

type Storer interface {
	// Store writes value under a name of the caller's choosing and returns the
	// reference to record. Storing the same name again replaces the value and
	// returns a reference to it.
	Store(ctx context.Context, name string, value Value) (ref string, err error)
	// Delete removes the secret a reference points at. Deleting an unknown
	// reference is not an error, so cleaning up twice is safe.
	Delete(ctx context.Context, ref string) error
}

Storer writes secrets and hands back the references to them. Splitting it from Resolver keeps the read path — the one every request takes — free of permissions it does not need.

type Value

type Value struct {
	// contains filtered or unexported fields
}

Value holds a secret and will not reveal it by accident.

It prints as [REDACTED] through fmt, slog and encoding/json, so a secret cannot reach a log line, an error message or a response body by being interpolated into one. Reveal is the only way out, which makes every place that genuinely needs the plaintext greppable.

password, err := resolver.Resolve(ctx, cfg.PasswordRef)
if err != nil {
    return err
}
logger.Info("dialling", "user", cfg.Username, "password", password) // [REDACTED]
client.Auth(cfg.Username, password.Reveal())

The zero Value is an empty secret. Values are comparable, so a Value can be a map key or be compared with ==, and copying one copies the secret.

func New

func New(s string) Value

New wraps a plaintext secret in a Value.

func (Value) GoString

func (v Value) GoString() string

GoString implements fmt.GoStringer, covering %#v — the verb a debugging print reaches for, and the one that would otherwise dump the struct field.

func (Value) IsEmpty

func (v Value) IsEmpty() bool

IsEmpty reports whether the Value holds nothing, which is how a missing secret differs from one that resolved to the empty string.

func (Value) LogValue

func (v Value) LogValue() slog.Value

LogValue implements slog.LogValuer, so a Value passed to a structured logger as an attribute is redacted rather than formatted.

func (Value) MarshalJSON

func (v Value) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler, so a Value on a response struct serialises as [REDACTED] instead of the secret.

func (Value) Reveal

func (v Value) Reveal() string

Reveal returns the plaintext. Call it at the point of use — passing it to the client that needs it — and do not hold the result in a struct that something might later log or serialise.

func (Value) String

func (v Value) String() string

String implements fmt.Stringer, covering %v, %s and %q.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL