secret

README

secret

A masked string type for passwords, tokens and other sensitive values. A struct or config that carries a Secret never leaks it when formatted, logged, or serialized; the real value is obtained only through an explicit Reveal call.

Zero dependencies (standard library only), so any library can hold a Secret in its config struct without pulling in a config or env-parsing stack.

Install

go get github.com/uchaloop/secret

Usage

type Config struct {
	User     string
	Password secret.Secret
}

cfg := Config{User: "app", Password: secret.Secret(raw)}

log.Info("db", "config", cfg)        // password logs as "****"
fmt.Sprintf("%+v", cfg)              // "****"
json.Marshal(cfg)                    // "****"

dsn := cfg.Password.Reveal()         // the real value, only at the point of use

Secret masks itself in:

• fmt verbs (%v/%s/%q/%+v/%#v/%x) via String/GoString,
• encoding/json and encoding/text via MarshalText,
• log/slog via LogValue.

An empty Secret renders as empty. UnmarshalText reads a value in (for an env or text decoder) while every outward representation stays masked. The real value leaves the type only through Reveal, which makes every real use greppable.

Testing

go test ./...

License

MIT.

Documentation

Overview

Package secret provides a masked string type for passwords, tokens and other sensitive values. A struct or config that carries a Secret never leaks it when formatted, logged, or serialized; the real value is obtained only through an explicit Reveal call.

The package has no external dependencies, so infrastructure libraries can use Secret in their (source-agnostic) Config structs without pulling in a config or env-parsing dependency.

Index

• type Secret
  • func (s Secret) GoString() string
  • func (s Secret) LogValue() slog.Value
  • func (s Secret) MarshalText() ([]byte, error)
  • func (s Secret) Reveal() string
  • func (s Secret) String() string
  • func (s *Secret) UnmarshalText(text []byte) error

Types

type Secret

type Secret string

Secret is a sensitive string that masks itself everywhere it could be exposed: fmt verbs (%v/%s/%+v/%#v), encoding/json and encoding/text (via MarshalText), and log/slog (via LogValue). An empty Secret renders as empty.

The underlying value is retrieved only with Reveal, which makes every real use greppable.

func (Secret) GoString

func (s Secret) GoString() string

GoString masks the value for fmt %#v.

func (Secret) LogValue

func (s Secret) LogValue() slog.Value

LogValue masks the value for log/slog structured logging.

func (Secret) MarshalText

func (s Secret) MarshalText() ([]byte, error)

MarshalText masks the value for encoding/json, TOML and any other encoding.TextMarshaler-based encoder, so serializing a struct never leaks it.

func (Secret) Reveal

func (s Secret) Reveal() string

Reveal returns the underlying secret value. Call it only where the real value is genuinely required (e.g. building a connection); never log the result.

func (Secret) String

func (s Secret) String() string

String masks the value for fmt %v/%s and any fmt.Stringer consumer.

func (*Secret) UnmarshalText

func (s *Secret) UnmarshalText(text []byte) error

UnmarshalText fills the Secret with the raw bytes, so an env or text decoder (for example a config loader reading a value out of the environment) can set it. It is deliberately asymmetric with MarshalText: the real value is read in here, while every outward representation stays masked.