Documentation
¶
Overview ¶
Package vaultsecrets resolves Fullsend runner secrets from HashiCorp Vault KV v2 through the job's workload identity (ADR 0155). It knows nothing about Fullsend configuration files: callers translate the trusted connections and secrets mappings into Connection and Source values and supply the trusted target-repository context.
Index ¶
- Constants
- Variables
- func ExpandPath(tmpl string, rc RepoContext) (string, error)
- func ValidateAddress(addr string) error
- func ValidateAuthPath(p string) error
- func ValidatePath(path string) error
- func ValidateTemplate(tmpl string) error
- type Client
- type Connection
- type RepoContext
- type Resolver
- type Source
- type TokenSource
Constants ¶
const ( // DefaultAuthPath is the default JWT auth mount path. DefaultAuthPath = "jwt" // DefaultRole is the default Vault JWT role. DefaultRole = "fullsend-runner" // DefaultAudience is the default OIDC audience requested for Vault. DefaultAudience = "https://fullsend.sh/vault" )
Variables ¶
var ErrVault = errors.New("vault request failed")
ErrVault marks an authentication, transport, or server failure that must abort resolution rather than advance to the next candidate.
Functions ¶
func ExpandPath ¶
func ExpandPath(tmpl string, rc RepoContext) (string, error)
ExpandPath expands the variables in tmpl from rc and validates the result as a relative KV v2 API path. Each variable value is validated and encoded with path-segment semantics; {{repo.full_name}} is split on "/" and each component is handled separately, preserving nested groups. Raw values are never inserted into the path.
func ValidateAddress ¶
ValidateAddress checks a Vault API base URL: HTTPS, a host, and no user information, query, or fragment.
func ValidateAuthPath ¶
ValidateAuthPath checks a JWT auth mount path (without the auth/ prefix): one or more non-empty components with no "." or "..".
func ValidatePath ¶
ValidatePath checks a complete relative KV v2 API path: no leading "/", scheme, authority, query, fragment, backslash, control character, empty component, or "." / ".." component, including in percent-encoded form.
func ValidateTemplate ¶
ValidateTemplate checks a Vault path template without a repository context: the variable syntax, the variable names, and the literal text. Configuration validation uses it; ExpandPath repeats every check on the expanded path.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client talks to one Vault server. It never logs or returns token or secret values in errors.
func NewClient ¶
func NewClient(conn Connection, httpClient *http.Client) (*Client, error)
NewClient returns a Client for conn. httpClient overrides the HTTP client (tests only); the default client refuses redirects so a bearer token is never forwarded to another address.
func (*Client) Login ¶
Login exchanges a job OIDC token for a short-lived Vault token at the configured JWT auth mount and role.
func (*Client) ReadField ¶
func (c *Client) ReadField(ctx context.Context, token, path, field string) (value string, found bool, err error)
ReadField reads the latest version of the KV v2 secret at path and returns the named field from data.data. found is false, with a nil error, when the path is missing, denied by policy, or holds no non-empty string field of that name: the caller advances to the next candidate. Any other status is an error.
type Connection ¶
type Connection struct {
Address string
Namespace string
AuthPath string
Role string
Audience string
}
Connection is a resolved Vault connection: the address and the JWT auth settings. Empty optional fields take the ADR 0155 defaults.
func (Connection) WithDefaults ¶
func (c Connection) WithDefaults() Connection
WithDefaults returns c with empty optional fields set to their defaults.
type RepoContext ¶
type RepoContext struct {
// Forge is the forge platform name (github, gitlab).
Forge string
// Host is the forge host name, such as github.com.
Host string
// Owner is the canonical owner or top-level namespace.
Owner string
// Name is the repository or project name.
Name string
// FullName is the canonical namespace/project path, including nested
// GitLab groups.
FullName string
// Org is the organization or group; empty when the target does not
// belong to one, which makes {{org}} unavailable.
Org string
}
RepoContext holds the trusted target-repository values Vault path templates may reference. Values come from the CI platform's own job context, never from PR-head files or event-supplied repository names.
type Resolver ¶
type Resolver struct {
// Repo is the trusted target-repository context for path templates.
Repo RepoContext
// Token fetches the job OIDC token.
Token TokenSource
// HTTPClient overrides the Vault HTTP client (tests only).
HTTPClient *http.Client
}
Resolver resolves Vault-selected runner secrets.
func (Resolver) Resolve ¶
Resolve returns name → value for every source. Every path is expanded and validated before any OIDC token is requested. Candidates are tried in order: a missing or denied path, or one without a non-empty string field named for the secret, advances to the next; any other Vault failure aborts. A source with no candidate value is an error; there is no fallback to another credential source.