@voxgig/sdkgen 4.29.0 → 4.30.1

package/project/.sdk/tm/go/feature/secrets/sekreto/providers.go

@@ -1,31 +1,6 @@
-// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/sekreto/providers.go)
-// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
+// VENDORED: @voxgig/sekreto sdk-20260925-1316-0 (go/sekreto/providers.go)
+// Source: https://github.com/voxgig/sekreto @ 163f537960de6813cc393b89843949ca3afa8cfc  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
-// What a provider is, what its declarative form looks like, how a provider
-// kind becomes a voxgig/plugin definition - and the four BUILT-IN kinds.
-//
-// A provider answers one question: "do you have this secret?" It returns
-// the value and whether it had it - a false means "ask the next one".
-// Nothing else about a provider is visible to the caller, which is the
-// point: an app reads `api.token` and never learns whether it came from the
-// environment, a .env file, HashiCorp Vault, AWS, GCP, Azure or a boru
-// vault.
-//
-// Two failure shapes, and they are never interchangeable. A store that does
-// not hold the secret is a MISS (false) - the chain carries on. A store
-// that could not answer - bad credentials, unreachable host, missing
-// configuration - is an ERROR: falling through there would quietly reach
-// for a weaker store.
-//
-// THIS PACKAGE IMPORTS NO net/http, NO crypto AND NO os/exec. What makes a
-// kind built in is that it needs nothing of the platform beyond reading a
-// local file; every kind that opens a socket, signs a request or spawns a
-// process is a plugin under plugins/, its own package, linked only by a
-// binary that imports it (docs/design/plugin-providers.md).
-//
-// A port of typescript/src/provider/support.ts and
-// typescript/src/provider/builtin.ts, which are canonical.
-
 package sekreto
 
 import (
@@ -41,131 +16,75 @@ import (
 	plugin "GOMODULE/feature/secrets/plugin"
 )
 
-// Provider is a source of secrets.
 type Provider interface {
-	// Lookup returns the value and whether this provider has it.
 	Lookup(name string) (string, bool, error)
-	// Describe is a short description, shown by Sekreto.Sources.
 	Describe() string
 }
 
-// ProviderSpec is the declarative form of a provider, as used in config and
-// in the shared spec: a Kind naming a built-in or a plugin, plus that
-// kind's own configuration.
-//
-// The JSON tags are the spec's own key names, and they are also how the
-// spec reaches a plugin: New hands each spec to the voxgig/plugin host as
-// the instance's options map, and the plugin's definition reads it back
-// with SpecOf. `omitempty` keeps that map to the keys actually set.
-//
-// A spec may instead CARRY a provider already built - Provider set, Kind
-// empty - which is how a custom provider that is not a plugin joins the
-// chain. Its store name is Name, or the kind its Describe opens with.
 type ProviderSpec struct {
-	Kind string `json:"kind,omitempty"`
-	// Name is the store name GetFrom addresses. Defaults to Kind.
-	Name   string            `json:"name,omitempty"`
-	Prefix string            `json:"prefix,omitempty"`
-	File   string            `json:"file,omitempty"`
-	Values map[string]string `json:"values,omitempty"`
-	// Dir is the file provider's directory of one-secret-per-file entries.
-	Dir string `json:"dir,omitempty"`
-	// hashicorp / boru (wire) / gcp / 1password / doppler / infisical:
-	// the base URL and the access token.
-	Addr  string `json:"addr,omitempty"`
-	Token string `json:"token,omitempty"`
-	// Mount is the hashicorp / boru (wire) KV mount (default `secret`).
-	Mount string `json:"mount,omitempty"`
-	// KV is the hashicorp KV engine version, 1 or 2 (default 2).
-	KV int `json:"kv,omitempty"`
-	// VaultNamespace is the Vault Enterprise namespace (X-Vault-Namespace).
-	VaultNamespace string `json:"vaultnamespace,omitempty"`
+	Kind           string            `json:"kind,omitempty"`
+	Name           string            `json:"name,omitempty"`
+	Prefix         string            `json:"prefix,omitempty"`
+	File           string            `json:"file,omitempty"`
+	Values         map[string]string `json:"values,omitempty"`
+	Dir            string            `json:"dir,omitempty"`
+	Addr           string            `json:"addr,omitempty"`
+	Token          string            `json:"token,omitempty"`
+	Mount          string            `json:"mount,omitempty"`
+	KV             int               `json:"kv,omitempty"`
+	VaultNamespace string            `json:"vaultnamespace,omitempty"`
 	// Auth logs hashicorp in for a token instead of being handed one.
-	Auth *AuthSpec `json:"auth,omitempty"`
-	// Command is the boru / secretspec executable to run (default: the
-	// kind's own name).
-	Command string `json:"command,omitempty"`
-	// boru
-	Namespace string `json:"namespace,omitempty"`
-	Home      string `json:"home,omitempty"`
-	// Profile is the secretspec profile to read (--profile).
-	Profile string `json:"profile,omitempty"`
-	// Backend is which of secretspec's OWN backends to read from
-	// (--provider), e.g. `keyring` or `dotenv://.env`. Named Backend here
-	// because Provider already means a sekreto provider.
-	Backend string `json:"backend,omitempty"`
-	// Reason is the audit reason recorded for a secretspec read
-	// (--reason). SecretSpec refuses to read without one.
-	Reason string `json:"reason,omitempty"`
-	// aws: region and credentials; the standard AWS_* environment
-	// variables fill whichever are not given.
-	Region  string `json:"region,omitempty"`
-	KeyID   string `json:"keyid,omitempty"`
-	Secret  string `json:"secret,omitempty"`
-	Session string `json:"session,omitempty"`
-	// Project is the gcp / doppler / infisical project (GCP project id,
-	// Doppler project slug, Infisical workspace id).
-	Project string `json:"project,omitempty"`
-	// Vault is the azure Key Vault name or full URL, or the 1password
-	// vault name or id.
-	Vault string `json:"vault,omitempty"`
-	// azure: client-credential login. infisical: universal-auth login
-	// (tenant is Azure-only).
-	Tenant       string `json:"tenant,omitempty"`
-	ClientID     string `json:"clientid,omitempty"`
-	ClientSecret string `json:"clientsecret,omitempty"`
+	Auth         *AuthSpec `json:"auth,omitempty"`
+	Command      string    `json:"command,omitempty"`
+	Namespace    string    `json:"namespace,omitempty"`
+	Home         string    `json:"home,omitempty"`
+	Profile      string    `json:"profile,omitempty"`
+	Backend      string    `json:"backend,omitempty"`
+	Reason       string    `json:"reason,omitempty"`
+	Region       string    `json:"region,omitempty"`
+	KeyID        string    `json:"keyid,omitempty"`
+	Secret       string    `json:"secret,omitempty"`
+	Session      string    `json:"session,omitempty"`
+	Project      string    `json:"project,omitempty"`
+	Vault        string    `json:"vault,omitempty"`
+	Tenant       string    `json:"tenant,omitempty"`
+	ClientID     string    `json:"clientid,omitempty"`
+	ClientSecret string    `json:"clientsecret,omitempty"`
 	// azure: where to log in / where IMDS answers. gcp: where the
 	// metadata server answers. Overridable for tests and for clouds with
 	// nonstandard endpoints.
 	LoginAddr    string `json:"loginaddr,omitempty"`
 	ImdsAddr     string `json:"imdsaddr,omitempty"`
 	MetadataAddr string `json:"metadataaddr,omitempty"`
-	// ApiVersion is the azure Key Vault API version (default 7.4).
-	ApiVersion string `json:"apiversion,omitempty"`
-	// Config is the doppler config slug (with Project).
-	Config string `json:"config,omitempty"`
-	// infisical: the environment slug and secret path.
-	Environment string `json:"environment,omitempty"`
-	Path        string `json:"path,omitempty"`
-	// Passphrase is the minivault passphrase that unwraps VaultKey.
-	Passphrase string `json:"passphrase,omitempty"`
+	ApiVersion   string `json:"apiversion,omitempty"`
+	Config       string `json:"config,omitempty"`
+	Environment  string `json:"environment,omitempty"`
+	Path         string `json:"path,omitempty"`
+	Passphrase   string `json:"passphrase,omitempty"`
 	// VaultKey is which key in a minivault file to open with, defaulting
 	// to `master`. Named apart from Key and KeyID because those already
 	// mean a secret name and an AWS access key id.
-	VaultKey string `json:"vaultkey,omitempty"`
-	// Iterations is minivault's PBKDF2 round count, used only when a key
-	// is created.
-	Iterations int `json:"iterations,omitempty"`
-	// Create makes a minivault file if it is not there.
-	Create bool `json:"create,omitempty"`
-
-	// Provider is a provider already built, joining the chain as it is.
-	// Never serialized: a live provider is not data.
+	VaultKey   string `json:"vaultkey,omitempty"`
+	Iterations int    `json:"iterations,omitempty"`
+	Create     bool   `json:"create,omitempty"`
+
 	Provider Provider `json:"-"`
 }
 
 // AuthSpec is how the hashicorp provider logs in for a token instead of
 // being handed one.
 type AuthSpec struct {
-	Method string `json:"method,omitempty"`
-	// Mount is the auth mount, defaulting to the method name.
-	Mount string `json:"mount,omitempty"`
-	// kubernetes: the Vault role to log in as.
-	Role string `json:"role,omitempty"`
-	// Jwt is the service-account JWT itself (tests).
-	Jwt string `json:"jwt,omitempty"`
-	// JwtFile is where the JWT lives; the conventional pod path by
-	// default.
-	JwtFile string `json:"jwtfile,omitempty"`
-	// approle: the role and secret ids.
+	Method   string `json:"method,omitempty"`
+	Mount    string `json:"mount,omitempty"`
+	Role     string `json:"role,omitempty"`
+	Jwt      string `json:"jwt,omitempty"`
+	JwtFile  string `json:"jwtfile,omitempty"`
 	RoleID   string `json:"roleid,omitempty"`
 	SecretID string `json:"secretid,omitempty"`
 }
 
-// EnvProvider reads environment variables: api.token from API_TOKEN.
 type EnvProvider struct {
 	Prefix string
-	// Source overrides the process environment, for tests.
 	Source map[string]string
 }
 
@@ -191,8 +110,6 @@ func (provider *EnvProvider) Describe() string {
 	return "env"
 }
 
-// DotenvProvider reads a `.env` file once, keyed exactly like the
-// environment.
 type DotenvProvider struct {
 	File   string
 	Prefix string
@@ -273,14 +190,6 @@ func (provider *MemoryProvider) Describe() string {
 	return "memory"
 }
 
-// FileProvider reads a directory of one-secret-per-file entries, keyed
-// like the environment: api.token reads <dir>/API_TOKEN.
-//
-// This is the shape of a mounted Kubernetes Secret, a Docker or Swarm
-// secret, and a systemd credentials directory, so those all work with no
-// further configuration. One trailing newline is stripped - tools that
-// write these files disagree about it, and a newline is never part of a
-// secret on purpose.
 type FileProvider struct {
 	Dir    string
 	Prefix string
@@ -317,39 +226,10 @@ func (provider *FileProvider) Describe() string {
 	return "file:" + provider.Dir
 }
 
-// --- providers as voxgig/plugin definitions ----------------------------
-
-// ProviderExport is the export key under which a provider definition
-// publishes the provider it built. New reads `<ref>/provider` off the host.
 const ProviderExport = "provider"
 
-// ErrorCode is the voxgig/plugin error code a SekretoError travels under
-// when a definition's Define returns it.
-//
-// plugin wraps a code-less error returned by a callback as
-// `plugin_define_failed`, and keeps an error that already carries a code.
-// A provider that refuses its own configuration - `kv: 3`, a missing
-// project - returns a SekretoError, and that message is pinned by the
-// spec byte for byte, so it must come back out of the host exactly as it
-// went in. ProviderPlugin gives it this code on the way in; New turns it
-// back into a SekretoError on the way out.
 const ErrorCode = "sekreto_error"
 
-// ProviderPlugin is a provider kind, as a voxgig/plugin definition.
-//
-// This is the whole bridge between the two libraries. The definition's
-// Name is the Kind a ProviderSpec names; its Define reads the spec back
-// off the instance's options, builds the provider with make, and exports
-// it. Nothing runs at activate: a provider opens nothing until its first
-// Lookup, so there is nothing to capture - a provider that does hold a
-// resource acquires it there and lets the instance scope unwind it.
-//
-// Every built-in and every plugin is made this way, so a custom provider
-// kind is one call:
-//
-//	sekreto.ProviderPlugin("mystore", func(spec *sekreto.ProviderSpec) (sekreto.Provider, error) {
-//	    return &MyStore{Addr: spec.Addr}, nil
-//	})
 func ProviderPlugin(kind string, make func(spec *ProviderSpec) (Provider, error)) plugin.Definition {
 	return plugin.Definition{
 		Name: kind,
@@ -395,8 +275,6 @@ func SpecOf(options map[string]any) (*ProviderSpec, error) {
 	return spec, nil
 }
 
-// OptionsOf is a ProviderSpec as a plugin instance's options map: its
-// JSON form, which is the spec's own key names.
 func OptionsOf(spec *ProviderSpec) (map[string]any, error) {
 	text, err := json.Marshal(spec)
 	if nil != err {
@@ -411,9 +289,6 @@ func OptionsOf(spec *ProviderSpec) (map[string]any, error) {
 	return options, nil
 }
 
-// Builtins is the four built-in provider kinds, as definitions, in a fresh
-// slice: env, memory, dotenv and file - the same four in every port. New
-// puts them in every catalog ahead of the plugins it is handed.
 func Builtins() []plugin.Definition {
 	return []plugin.Definition{
 		ProviderPlugin("env", func(spec *ProviderSpec) (Provider, error) {
@@ -439,8 +314,6 @@ func Builtins() []plugin.Definition {
 	}
 }
 
-// Kinds is every kind this library ships, built in or as a plugin, so that
-// an unknown kind can be told from a plugin that was not loaded.
 var Kinds = struct {
 	Builtin []string
 	Plugin  []string

package/project/.sdk/tm/go/feature/secrets/sekreto/sekreto.go

@@ -1,17 +1,6 @@
-// VENDORED: @voxgig/sekreto sdk-20260917-1242-0 (go/sekreto/sekreto.go)
-// Source: https://github.com/voxgig/sekreto @ 108c4a914bee7b6534c30d1c68c25cd1b9377696  [tag: sdk-20260917-1242-0]
+// VENDORED: @voxgig/sekreto sdk-20260925-1316-0 (go/sekreto/sekreto.go)
+// Source: https://github.com/voxgig/sekreto @ 163f537960de6813cc393b89843949ca3afa8cfc  [tag: sdk-20260925-1316-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
-// sekreto: one interface for secrets, wherever they live.
-//
-// A Sekreto is an ordered chain of providers. Get asks each in turn and
-// returns the first hit, so an app can be configured from environment
-// variables in development and a vault in production without changing a
-// line of its own code.
-//
-// A port of typescript/src/Sekreto.ts, which is canonical.
-//
-// Go has no exceptions, so where the canonical implementation throws a
-// SekretoError this port returns one as an error value.
 package sekreto
 
 import (
@@ -25,8 +14,6 @@ import (
 	plugin "GOMODULE/feature/secrets/plugin"
 )
 
-// SekretoError is anything sekreto refuses to do: a bad name, a missing
-// secret, a provider that could not be reached.
 type SekretoError struct {
 	Message string
 }
@@ -35,26 +22,10 @@ func (err *SekretoError) Error() string {
 	return err.Message
 }
 
-// Fail is a SekretoError as an error value, for this package and for the
-// plugins, which return their own refusals through it.
 func Fail(message string) error {
 	return &SekretoError{Message: message}
 }
 
-// WriteJSON is json.Marshal with Go's HTML escaping turned OFF.
-//
-// encoding/json escapes <, > and & as \u003c, \u003e and \u0026 unless
-// told otherwise. That is a defence for JSON pasted into an HTML page,
-// which this library never does, and it made go the only port whose bytes
-// differed: every other port emits those three characters raw. The
-// writer's output is part of what the ports agree on - the CLI line is
-// compared byte for byte across all of them - so go matches the rest
-// rather than the rest matching go.
-//
-// Encode appends a newline, which a JSON document does not carry, so it
-// is trimmed. Use this for every value that LEAVES the process: a request
-// body, a returned secret, the CLI's line. A marshal whose bytes are
-// unmarshalled again without ever being emitted needs no such care.
 func WriteJSON(value any) ([]byte, error) {
 	var buf bytes.Buffer
 
@@ -70,7 +41,6 @@ func WriteJSON(value any) ([]byte, error) {
 
 var namepart = regexp.MustCompile(`^[a-z0-9_]+$`)
 
-// ValidName reports whether this is a well-formed secret name.
 func ValidName(name any) bool {
 	text, is := name.(string)
 	if !is || 0 == len(text) {
@@ -96,7 +66,6 @@ func CheckName(name string) error {
 	return nil
 }
 
-// EnvKey is the environment-variable key for a name: api.token -> API_TOKEN.
 func EnvKey(name string, prefix string) (string, error) {
 	if err := CheckName(name); nil != err {
 		return "", err
@@ -114,7 +83,6 @@ type VaultRef struct {
 	Field string `json:"field"`
 }
 
-// NameVaultRef splits a name into its vault path and field.
 func NameVaultRef(name string) (*VaultRef, error) {
 	if err := CheckName(name); nil != err {
 		return nil, err
@@ -132,15 +100,6 @@ func NameVaultRef(name string) (*VaultRef, error) {
 	}, nil
 }
 
-// FlatName is a name flattened to one segment: api.token -> api_token (GCP
-// Secret Manager, `_`) or api-token (Azure Key Vault, `-`).
-//
-// Those stores have no path hierarchy and reject dots in ids, so the dots
-// become the store's conventional separator. With `-` as the separator,
-// underscores flatten too: Azure Key Vault's alphabet is letters, digits
-// and hyphens only, and a valid sekreto name like with_underscore must
-// still be representable there. (The resulting `.`/`_` collision mirrors
-// the documented EnvKey behaviour, where both already map to `_`.)
 func FlatName(name string, sep string) (string, error) {
 	if err := CheckName(name); nil != err {
 		return "", err
@@ -171,11 +130,6 @@ func AwsParam(name string, prefix string) (string, error) {
 	return base + "/" + strings.Join(strings.Split(name, "."), "/"), nil
 }
 
-// ParseDotenv parses `.env` text into a map of raw keys to values.
-//
-// Deliberately small: KEY=value, optional `export`, `#` comments on their
-// own line, and single- or double-quoted values (double quotes also
-// unescape \n, \r, \t and \\). A line with no `=` is skipped.
 func ParseDotenv(text string) map[string]string {
 	out := map[string]string{}
 
@@ -241,16 +195,9 @@ func unescape(text string) string {
 	return out.String()
 }
 
-// Redact replaces known secret values in text with `[redacted]`.
-//
-// Only values of four characters or more are replaced: shorter ones are too
-// likely to appear in ordinary text, and redacting them would make logs
-// unreadable without making them safer.
 func Redact(text string, values []string) string {
 	out := text
 
-	// A copy: `values` belongs to the caller (it is `seen` when called
-	// through Sekreto.Redact), and sorting in place would reorder it.
 	usable := []string{}
 	for _, value := range values {
 		if 4 <= len(value) {
@@ -268,7 +215,6 @@ func Redact(text string, values []string) string {
 	return out
 }
 
-// Options configure a Sekreto.
 type Options struct {
 	// Providers is the chain, in resolution order. Each entry names a kind
 	// to build - a built-in, or a plugin passed in Plugins - or carries a
@@ -279,7 +225,6 @@ type Options struct {
 	// project imports the plugin packages it needs and passes them here,
 	// and a kind it did not pass is unknown to this Sekreto.
 	Plugins []plugin.Definition
-	// NoCache disables the resolved-value cache.
 	NoCache bool
 }
 
@@ -300,22 +245,10 @@ type cached struct {
 	value string
 }
 
-// StoreName is the store name a provider answers to when nothing says
-// otherwise.
-//
-// Describe opens with the provider's kind - hashicorp:..., dotenv:..., plain
-// env - so the kind is the natural default, and a custom provider gets a
-// sensible name without implementing anything extra.
 func StoreName(provider Provider) string {
 	return strings.SplitN(provider.Describe(), ":", 2)[0]
 }
 
-// unknownkind is the message for a kind the catalog does not hold.
-//
-// A kind sekreto has never heard of is a typo; a kind that exists as a
-// plugin but was not passed in is the split working as designed and
-// telling you what to pass. Collapsing the two was the first thing that
-// made the split confusing to use.
 func unknownkind(kind string, catalog *plugin.Catalog) string {
 	message := "sekreto: unknown provider kind: " + kind +
 		" (available: " + strings.Join(catalog.Names(), ", ") + ")"
@@ -346,11 +279,6 @@ func unwrap(err error) error {
 	return Fail(cause)
 }
 
-// Sekreto is the secrets facade: a chain of providers plus a cache.
-//
-// Two ways to read. Get is transparent - it walks the chain and takes the
-// first hit, and the caller never learns which store answered. GetFrom is
-// directed - it names the store, and only that store is asked.
 type Sekreto struct {
 	// host is the voxgig/plugin host every spec'd provider is an instance
 	// of, and catalog the definitions it can build: the built-ins plus
@@ -360,14 +288,8 @@ type Sekreto struct {
 
 	entries []entry
 	docache bool
-	// Guards cache and seen. Four PROVIDERS were given a mutex for
-	// concurrent resolution; the facade holding the results was not, so two
-	// goroutines appending to seen from the same length silently dropped one
-	// - and a value missing from seen is a value Redact hands straight back
-	// into the log. Held only around the slices, never across a provider
-	// Lookup, so lookups stay concurrent.
-	mu    sync.Mutex
-	cache []cached
+	mu      sync.Mutex
+	cache   []cached
 	// Every value ever resolved, for Redact. Kept independently of the
 	// read cache so that redaction still works when caching is off -
 	// otherwise NoCache would silently disable Redact and leak secrets
@@ -386,10 +308,6 @@ func New(options *Options) (*Sekreto, error) {
 		opts = &Options{}
 	}
 
-	// Built-ins first, then the plugins, into one catalog: a plugin that
-	// names a built-in kind replaces it, which is how a host substitutes
-	// an implementation and never an accident, because the four names
-	// are documented.
 	catalog, err := plugin.MakeCatalog(append(Builtins(), opts.Plugins...)...)
 	if nil != err {
 		return nil, err
@@ -426,13 +344,6 @@ func New(options *Options) (*Sekreto, error) {
 	return sek, nil
 }
 
-// declare is one chain entry, as a plugin instance.
-//
-// The instance is `kind` for a store named after its kind and `kind$store`
-// otherwise - `hashicorp$prod` - so Host().List() reads like the chain. A
-// store name that is already taken gets a numbered tag from the host
-// instead, because two providers MAY share a store name (a directed read
-// walks both) and an instance ref may not.
 func (sek *Sekreto) declare(spec *ProviderSpec) (entry, error) {
 	kind := spec.Kind
 
@@ -500,8 +411,6 @@ func (sek *Sekreto) Host() *plugin.Host {
 	return sek.host
 }
 
-// Catalog is the definitions this Sekreto can build: the built-ins plus
-// what Options.Plugins handed in.
 func (sek *Sekreto) Catalog() *plugin.Catalog {
 	return sek.catalog
 }
@@ -522,7 +431,6 @@ func (sek *Sekreto) Close() error {
 	return err
 }
 
-// Get returns the secret, or an error if no provider has it.
 func (sek *Sekreto) Get(name string) (string, error) {
 	found, has, err := sek.Try(name)
 	if nil != err {
@@ -536,13 +444,10 @@ func (sek *Sekreto) Get(name string) (string, error) {
 	return found, nil
 }
 
-// Try returns the secret and whether any provider had it.
 func (sek *Sekreto) Try(name string) (string, bool, error) {
 	return sek.resolve("", name, sek.entries)
 }
 
-// GetFrom returns the secret from one named store, or an error if that store
-// does not have it.
 func (sek *Sekreto) GetFrom(store string, name string) (string, error) {
 	found, has, err := sek.TryFrom(store, name)
 	if nil != err {
@@ -556,12 +461,6 @@ func (sek *Sekreto) GetFrom(store string, name string) (string, error) {
 	return found, nil
 }
 
-// TryFrom returns the secret from one named store, and whether that store
-// had it.
-//
-// Naming a store that is not in the chain is an error, not a miss: Try
-// already means "this store may not have it", so it cannot also mean "this
-// store may not exist" without hiding a typo.
 func (sek *Sekreto) TryFrom(store string, name string) (string, bool, error) {
 	matching := []entry{}
 
@@ -596,11 +495,6 @@ func (sek *Sekreto) resolve(store string, name string, entries []entry) (string,
 	}
 
 	for _, one := range entries {
-		// Deliberately not under the lock: a provider Lookup is a network
-		// round-trip, and serialising those would turn a chain resolved from
-		// several goroutines into a queue. Two goroutines can therefore both
-		// miss the cache and both fetch, which costs a duplicate read and is
-		// otherwise harmless - the store is being asked the same question.
 		found, has, err := one.provider.Lookup(name)
 		if nil != err {
 			return "", false, err
@@ -620,19 +514,16 @@ func (sek *Sekreto) resolve(store string, name string, entries []entry) (string,
 	return "", false, nil
 }
 
-// Has reports whether any provider has this secret.
 func (sek *Sekreto) Has(name string) (bool, error) {
 	_, has, err := sek.Try(name)
 	return has, err
 }
 
-// HasIn reports whether this named store has this secret.
 func (sek *Sekreto) HasIn(store string, name string) (bool, error) {
 	_, has, err := sek.TryFrom(store, name)
 	return has, err
 }
 
-// All returns every named secret at once. Missing ones are an error.
 func (sek *Sekreto) All(names []string) (map[string]string, error) {
 	out := map[string]string{}
 
@@ -647,7 +538,6 @@ func (sek *Sekreto) All(names []string) (map[string]string, error) {
 	return out, nil
 }
 
-// Sources describes each provider, in resolution order.
 func (sek *Sekreto) Sources() []string {
 	out := []string{}
 
@@ -658,14 +548,6 @@ func (sek *Sekreto) Sources() []string {
 	return out
 }
 
-// Stores names each store that can be named by GetFrom, in resolution order
-// and without repeats.
-// String is what a Sekreto shows of itself when something prints it.
-//
-// fmt reflects into unexported fields, so %v and %+v reach cache and seen,
-// which between them hold every value this chain has ever resolved - one
-// ordinary log line writes every secret out. GoString covers %#v the same
-// way. Neither reaches a value.
 func (sek *Sekreto) String() string {
 	return "Sekreto{stores: [" + strings.Join(sek.Stores(), " ") + "]}"
 }
@@ -706,7 +588,6 @@ func (sek *Sekreto) Redact(text string) string {
 	return Redact(text, seen)
 }
 
-// Refresh drops cached values, so the next Get asks the providers again.
 func (sek *Sekreto) Refresh() {
 	sek.mu.Lock()
 	sek.cache = nil