README
¶
Secret Package
github.com/OpenNSW/core/secret provides SecretRef, a small, dependency-free
primitive for secret-bearing configuration values.
SecretRef
A SecretRef is the raw string as written in config: either a literal value or a
reference whose scheme prefix names where the value comes from. It unmarshals from
and marshals to a plain JSON string — only the single prefixed-string form is
supported; there is intentionally no object form.
| Form | Meaning |
|---|---|
"plain-value" |
A literal value (the default — backward compatible). |
"env:NAME" |
Read from environment variable NAME. |
"file:/path/to/file" |
Read from a file; trailing whitespace is trimmed. |
"literal:env:foo" |
Explicit literal escape hatch, for a literal that begins with a scheme name. |
A value whose prefix is not a known scheme (including one with no colon at all) is treated as a literal. This lets non-sensitive configuration (URLs, scopes, header names) live alongside references to credentials that are provided out-of-band, so the two are no longer fused into one sensitive blob.
Usage
type Config struct {
Token secret.SecretRef `json:"token"`
}
// Resolution — the I/O — is a separate, explicit step.
token, err := cfg.Token.Resolve()
Resolve is the single I/O seam: the only place that reads env/files and the only
place that can fail. A missing env var or an unreadable/empty file is a loud
error — a reference never silently resolves to the empty string. Resolve once, at
startup, and use the returned plain value; if a referenced value changes, restart
the process to pick it up.
Adding a source
To add a new source (e.g. vault:), register a resolver in the secretSchemes map
in secret.go — no other code changes. File-sourced secrets are capped at 4 KB and
must be regular files.
Documentation
¶
Overview ¶
Package secret provides SecretRef, a secret-bearing configuration value that is either a literal or a scheme-prefixed reference (env:, file:, literal:) resolved to its concrete value on demand. It is a small, dependency-free primitive so any package or module can reference secrets without depending on a larger consumer.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type SecretRef ¶
type SecretRef string
SecretRef is a secret-bearing configuration value: a literal, or a reference whose scheme prefix names where the value comes from. It is the raw string as written in config — it unmarshals from and marshals to a plain JSON string, so only the single prefixed-string form is supported; there is intentionally no object form.
"plain-value" // literal (the default, backward compatible) "env:NAME" // read from environment variable NAME "file:/path/to/file" // read from a file (trailing whitespace trimmed) "literal:env:foo" // explicit literal escape hatch
A value whose prefix is not a known scheme (including one with no colon at all) is treated as a literal. Resolution — the I/O — is a separate step; see Resolve.
func (SecretRef) Resolve ¶
Resolve reads the concrete value for the reference. This is the single I/O seam: the only place that reads env/files and the only place that can fail. A missing env var or an unreadable/empty file is a loud error — a reference never silently resolves to the empty string. A literal is returned as-is; an empty literal (or the zero value) is allowed for backward compatibility.
Source Files