secrets

package
v0.67.0 Latest Latest
Warning

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

 Go to latest Published: May 30, 2026 License: MIT Imports: 26 Imported by: 3

Documentation

Index

Constants

View Source 
const SecretPrefix = "secret://"

SecretPrefix is the URI scheme used in config values to reference secrets.

Variables

View Source 
var (
	ErrNotFound     = errors.New("secrets: secret not found")
	ErrUnsupported  = errors.New("secrets: operation not supported")
	ErrInvalidKey   = errors.New("secrets: invalid key")
	ErrProviderInit = errors.New("secrets: provider initialization failed")
)

Common errors.

Functions

func DefaultSensitiveKeys added in v0.9.4 

func DefaultSensitiveKeys() []string

DefaultSensitiveKeys returns the default set of output keys considered sensitive.

func GenerateSecret added in v0.9.4 

func GenerateSecret(ctx context.Context, genType string, config map[string]any) (string, error)

GenerateSecret produces a secret value based on genType and config. Supported types: "random_hex", "random_base64", "random_alphanumeric", "provider_credential". For "provider_credential", the returned string is a JSON-encoded map.

func MaskSensitiveOutputs added in v0.9.4 

func MaskSensitiveOutputs(outputs map[string]any, sensitiveKeys []string) map[string]any

MaskSensitiveOutputs returns a copy of outputs with sensitive values replaced by "(sensitive)". sensitiveKeys is the merged set of keys to mask.

func MergeSensitiveKeys added in v0.9.4 

func MergeSensitiveKeys(driverKeys []string) []string

MergeSensitiveKeys combines driver-specific keys with the defaults, deduplicating.

Types

type AWSConfig 

type AWSConfig struct {
	Region          string `json:"region" yaml:"region"`
	AccessKeyID     string `json:"accessKeyId,omitempty" yaml:"accessKeyId,omitempty"`
	SecretAccessKey string `json:"secretAccessKey,omitempty" yaml:"secretAccessKey,omitempty"`
}

AWSConfig holds configuration for AWS Secrets Manager.

type AWSSecretsManagerProvider 

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

AWSSecretsManagerProvider reads secrets from AWS Secrets Manager using the HTTP API with AWS Signature V4 signing. No external AWS SDK is required.

func NewAWSSecretsManagerProvider 

func NewAWSSecretsManagerProvider(cfg AWSConfig) (*AWSSecretsManagerProvider, error)

NewAWSSecretsManagerProvider creates a new AWS Secrets Manager provider. If AccessKeyID/SecretAccessKey are empty, it falls back to the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

func NewAWSSecretsManagerProviderWithClient 

func NewAWSSecretsManagerProviderWithClient(cfg AWSConfig, client HTTPClient) *AWSSecretsManagerProvider

NewAWSSecretsManagerProviderWithClient creates an AWS provider with a custom HTTP client (for testing).

func (*AWSSecretsManagerProvider) CheckAccess added in v0.67.0 

func (p *AWSSecretsManagerProvider) CheckAccess(ctx context.Context) error

CheckAccess implements AccessChecker. It performs a lightweight check by attempting to list secrets. Errors never contain credential material.

func (*AWSSecretsManagerProvider) Config 

func (p *AWSSecretsManagerProvider) Config() AWSConfig

Config returns the provider's AWS configuration.

func (*AWSSecretsManagerProvider) Delete 

func (p *AWSSecretsManagerProvider) Delete(_ context.Context, _ string) error

func (*AWSSecretsManagerProvider) Get 

func (p *AWSSecretsManagerProvider) Get(ctx context.Context, key string) (string, error)

func (*AWSSecretsManagerProvider) List 

func (p *AWSSecretsManagerProvider) List(ctx context.Context) ([]string, error)

List returns the names of all secrets using the ListSecrets API with pagination.

func (*AWSSecretsManagerProvider) Name 

func (p *AWSSecretsManagerProvider) Name() string

func (*AWSSecretsManagerProvider) Set 

func (p *AWSSecretsManagerProvider) Set(_ context.Context, _ string, _ string) error

func (*AWSSecretsManagerProvider) StatAll added in v0.67.0 

func (p *AWSSecretsManagerProvider) StatAll(ctx context.Context) ([]SecretMeta, error)

StatAll implements MetadataProvider on a best-effort basis. It lists secret names from AWS Secrets Manager and returns them with Exists=true and zero UpdatedAt (LastChangedDate is not fetched to avoid N+1 API calls). Returns ErrUnsupported when listing is not available.

type AccessChecker added in v0.67.0 

type AccessChecker interface {
	CheckAccess(ctx context.Context) error
}

AccessChecker is optional: verify the store is reachable + usable for setup. CheckAccess MUST NOT leak credential material in its error.

type DevVaultConfig 

type DevVaultConfig struct {
	// RootToken is the root token for the dev server. Default: "dev-root-token".
	RootToken string
	// ListenAddr is the address to listen on. Default: "127.0.0.1:0" (random port).
	ListenAddr string
	// MountPath is the KV v2 mount path. Default: "secret".
	MountPath string
}

DevVaultConfig holds configuration for a managed Vault dev server.

type DevVaultProvider 

type DevVaultProvider struct {
	*VaultProvider
	// contains filtered or unexported fields
}

DevVaultProvider manages a Vault dev server subprocess and provides a real VaultProvider connected to it. This is useful for local development and integration testing without requiring an external Vault server.

func NewDevVaultProvider 

func NewDevVaultProvider(cfg DevVaultConfig) (*DevVaultProvider, error)

NewDevVaultProvider starts a Vault dev server and returns a provider connected to it. It finds the vault binary on PATH, starts it with -dev mode, waits for readiness, and returns a fully functional VaultProvider.

The caller must call Close() to stop the subprocess.

Returns an error if the vault binary is not found or the server fails to start.

func (*DevVaultProvider) Addr 

func (p *DevVaultProvider) Addr() string

Addr returns the listen address of the dev server.

func (*DevVaultProvider) Close 

func (p *DevVaultProvider) Close() error

Close stops the Vault dev server subprocess and cleans up.

type EnvProvider 

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

EnvProvider reads secrets from environment variables. Keys are converted to uppercase with dots replaced by underscores. For example, "database.password" becomes "DATABASE_PASSWORD".

func NewEnvProvider 

func NewEnvProvider(prefix string) *EnvProvider

NewEnvProvider creates a new environment variable secret provider. If prefix is non-empty, it is prepended to all key lookups (e.g., prefix "APP_" + key "db_pass" -> "APP_DB_PASS").

func (*EnvProvider) CheckAccess added in v0.67.0 

func (p *EnvProvider) CheckAccess(_ context.Context) error

CheckAccess implements AccessChecker. For EnvProvider, access is always available.

func (*EnvProvider) Delete 

func (p *EnvProvider) Delete(_ context.Context, key string) error

func (*EnvProvider) Get 

func (p *EnvProvider) Get(_ context.Context, key string) (string, error)

func (*EnvProvider) List 

func (p *EnvProvider) List(_ context.Context) ([]string, error)

func (*EnvProvider) Name 

func (p *EnvProvider) Name() string

func (*EnvProvider) Set 

func (p *EnvProvider) Set(_ context.Context, key, value string) error

func (*EnvProvider) StatAll added in v0.67.0 

func (p *EnvProvider) StatAll(_ context.Context) ([]SecretMeta, error)

StatAll implements MetadataProvider. It lists env vars that match the prefix (same logic as List) and returns SecretMeta with Exists=true and zero UpdatedAt (env vars have no last-modified timestamp).

type FileProvider 

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

FileProvider reads secrets from files in a directory. Each file name is the secret key, and the file content is the value. This is compatible with Kubernetes secret volume mounts.

func NewFileProvider 

func NewFileProvider(dir string) *FileProvider

NewFileProvider creates a file-based secret provider rooted at dir.

func (*FileProvider) CheckAccess added in v0.67.0 

func (p *FileProvider) CheckAccess(_ context.Context) error

CheckAccess implements AccessChecker. It verifies the directory exists and is writable by attempting to create (then remove) a probe file.

func (*FileProvider) Delete 

func (p *FileProvider) Delete(_ context.Context, key string) error

func (*FileProvider) Get 

func (p *FileProvider) Get(_ context.Context, key string) (string, error)

func (*FileProvider) List 

func (p *FileProvider) List(_ context.Context) ([]string, error)

func (*FileProvider) Name 

func (p *FileProvider) Name() string

func (*FileProvider) Set 

func (p *FileProvider) Set(_ context.Context, key, value string) error

func (*FileProvider) StatAll added in v0.67.0 

func (p *FileProvider) StatAll(_ context.Context) ([]SecretMeta, error)

StatAll implements MetadataProvider. It returns SecretMeta for every file in the directory, using the file's modification time as UpdatedAt.

type GitHubOrgVisibility added in v0.60.7 

type GitHubOrgVisibility string

GitHubOrgVisibility controls who can pull an org-scoped secret. Mirrors GitHub's API field; one of "all", "selected", "private". 

const (
	OrgVisibilityAll      GitHubOrgVisibility = "all"
	OrgVisibilitySelected GitHubOrgVisibility = "selected"
	OrgVisibilityPrivate  GitHubOrgVisibility = "private"
)

type GitHubSecretScope added in v0.60.7 

type GitHubSecretScope string

GitHubSecretScope selects which GitHub secret namespace a provider writes to. Default zero value = repo (backwards-compat). 

GitHubScopeRepo → /repos/{owner}/{repo}/actions/secrets/...
GitHubScopeEnv  → /repos/{owner}/{repo}/environments/{env}/secrets/...
GitHubScopeOrg  → /orgs/{org}/actions/secrets/...

const (
	GitHubScopeRepo GitHubSecretScope = "repo"
	GitHubScopeEnv  GitHubSecretScope = "env"
	GitHubScopeOrg  GitHubSecretScope = "org"
)

type GitHubSecretsProvider added in v0.9.4 

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

GitHubSecretsProvider manages GitHub Actions secrets at repo, env, or org scope. Secrets are write-only on GitHub, so Get() returns ErrUnsupported.

func NewGitHubOrgSecretsProvider added in v0.60.7 

func NewGitHubOrgSecretsProvider(org string, tokenEnvVar string, visibility GitHubOrgVisibility, selectedRepoIDs []int64) (*GitHubSecretsProvider, error)

NewGitHubOrgSecretsProvider creates an org-scoped provider. visibility is one of OrgVisibilityAll / Selected / Private. selectedRepoIDs is required iff visibility=Selected.

Requires the token to have admin:org scope.

func NewGitHubSecretsProvider added in v0.9.4 

func NewGitHubSecretsProvider(repo string, tokenEnvVar string) (*GitHubSecretsProvider, error)

NewGitHubSecretsProvider creates a repo-scoped provider for the given "owner/repo". tokenEnvVar is the name of the environment variable holding the GitHub token. Backwards-compatible — sets scope=repo.

func (*GitHubSecretsProvider) CheckAccess added in v0.67.0 

func (p *GitHubSecretsProvider) CheckAccess(ctx context.Context) error

CheckAccess implements AccessChecker. It verifies the configured credentials have at least read access by fetching the public key. Errors never contain credential material.

func (*GitHubSecretsProvider) Delete added in v0.9.4 

func (p *GitHubSecretsProvider) Delete(ctx context.Context, key string) error

Delete removes a GitHub Actions secret.

func (*GitHubSecretsProvider) Environment added in v0.57.5 

func (p *GitHubSecretsProvider) Environment() string

Environment returns the configured GitHub Actions environment scope.

func (*GitHubSecretsProvider) Get added in v0.9.4 

func (p *GitHubSecretsProvider) Get(_ context.Context, _ string) (string, error)

Get always returns ErrUnsupported because GitHub secrets are write-only.

func (*GitHubSecretsProvider) List added in v0.9.4 

func (p *GitHubSecretsProvider) List(ctx context.Context) ([]string, error)

List returns the names of all GitHub Actions secrets for the repo.

func (*GitHubSecretsProvider) Name added in v0.9.4 

func (p *GitHubSecretsProvider) Name() string

func (*GitHubSecretsProvider) Scope added in v0.60.7 

func (p *GitHubSecretsProvider) Scope() GitHubSecretScope

Scope reports the current scope.

func (*GitHubSecretsProvider) Set added in v0.9.4 

func (p *GitHubSecretsProvider) Set(ctx context.Context, key, value string) error

Set encrypts value with the repo's public key and stores it as a secret.

func (*GitHubSecretsProvider) SetEnvironment added in v0.57.5 

func (p *GitHubSecretsProvider) SetEnvironment(environment string)

SetEnvironment scopes subsequent operations to a GitHub Actions environment. Empty scope means repository-level secrets. Calling SetEnvironment with a non-empty value flips scope to env.

func (*GitHubSecretsProvider) StatAll added in v0.67.0 

func (p *GitHubSecretsProvider) StatAll(ctx context.Context) ([]SecretMeta, error)

StatAll implements MetadataProvider. It returns presence + timestamp for every secret visible to the configured token. UpdatedAt is the updated_at field from GitHub, falling back to created_at when updated_at is zero.

type HTTPClient 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is an interface for HTTP requests (allows testing). Used by the AWS Secrets Manager provider.

type KeychainProvider added in v0.11.0 

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

KeychainProvider implements Provider using the OS credential store (macOS Keychain, Linux Secret Service, Windows Credential Manager).

All keys are namespaced under a single "service" string so multiple workflow services on the same machine don't collide.

On Linux, requires a running Secret Service implementation (libsecret, gnome-keyring, or KWallet). Headless servers without one should use FileProvider or VaultProvider instead.

KeychainProvider is safe for concurrent use. mu guards all access to trackedKeys.

func NewKeychainProvider added in v0.11.0 

func NewKeychainProvider(service string) (*KeychainProvider, error)

NewKeychainProvider returns a provider namespaced to the given service name. Service must not be empty — an empty service stores secrets in a shared namespace where they can collide across applications.

func (*KeychainProvider) Delete added in v0.11.0 

func (p *KeychainProvider) Delete(ctx context.Context, key string) error

Delete removes the secret stored under key from the OS keychain.

func (*KeychainProvider) Get added in v0.11.0 

func (p *KeychainProvider) Get(ctx context.Context, key string) (string, error)

Get retrieves the secret stored under the given key from the OS keychain.

func (*KeychainProvider) List added in v0.11.0 

func (p *KeychainProvider) List(ctx context.Context) ([]string, error)

List returns all keys that have been set during the lifetime of this provider instance.

func (*KeychainProvider) Name added in v0.11.0 

func (p *KeychainProvider) Name() string

Name returns the provider identifier "keychain".

func (*KeychainProvider) Set added in v0.11.0 

func (p *KeychainProvider) Set(ctx context.Context, key, value string) error

Set stores the given value under key in the OS keychain.

type MetadataProvider added in v0.67.0 

type MetadataProvider interface {
	Provider
	StatAll(ctx context.Context) ([]SecretMeta, error)
}

MetadataProvider is optional: stores that can report which keys exist and when they changed.

type MultiResolver 

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

MultiResolver resolves secret references in configuration values using multiple providers identified by URI scheme. It is backward-compatible: bare ${VAR_NAME} references (without a scheme) default to env resolution.

func NewMultiResolver 

func NewMultiResolver() *MultiResolver

NewMultiResolver creates a new MultiResolver. An EnvProvider is registered by default under the "env" scheme.

func (*MultiResolver) Expand 

func (m *MultiResolver) Expand(ctx context.Context, input string) (string, error)

Expand replaces all ${...} patterns in input with resolved values.

Supported formats:

  • ${vault:secret/path#field} — uses "vault" provider with key "secret/path#field"
  • ${aws-sm:secret-name} — uses "aws-sm" provider with key "secret-name"
  • ${env:VAR_NAME} — uses "env" provider with key "VAR_NAME"
  • ${VAR_NAME} — backward-compatible, uses "env" provider (os.LookupEnv via EnvProvider)

func (*MultiResolver) Provider 

func (m *MultiResolver) Provider(scheme string) Provider

Provider returns the provider for a given scheme, or nil if not found.

func (*MultiResolver) Register 

func (m *MultiResolver) Register(scheme string, provider Provider)

Register adds or replaces a provider for a given scheme.

func (*MultiResolver) Schemes 

func (m *MultiResolver) Schemes() []string

Schemes returns the list of registered provider schemes.

func (*MultiResolver) Unregister 

func (m *MultiResolver) Unregister(scheme string)

Unregister removes a provider for the given scheme.

type Provider 

type Provider interface {
	// Name returns the provider identifier.
	Name() string
	// Get retrieves a secret value by key.
	Get(ctx context.Context, key string) (string, error)
	// Set stores a secret. Returns ErrUnsupported if read-only.
	Set(ctx context.Context, key, value string) error
	// Delete removes a secret. Returns ErrUnsupported if read-only.
	Delete(ctx context.Context, key string) error
	// List returns all available secret keys. Returns ErrUnsupported if not supported.
	List(ctx context.Context) ([]string, error)
}

Provider defines the interface for secret storage backends.

type Resolver 

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

Resolver resolves secret:// references in configuration values.

func NewResolver 

func NewResolver(provider Provider) *Resolver

NewResolver creates a resolver backed by the given provider.

func (*Resolver) Provider 

func (r *Resolver) Provider() Provider

Provider returns the underlying provider.

func (*Resolver) Resolve 

func (r *Resolver) Resolve(ctx context.Context, value string) (string, error)

Resolve replaces a value containing a secret:// reference with the actual secret. If the value does not start with SecretPrefix, it is returned as-is.

func (*Resolver) ResolveMap 

func (r *Resolver) ResolveMap(ctx context.Context, m map[string]any) (map[string]any, error)

ResolveMap resolves all secret:// references in a string map.

type RotationProvider added in v0.3.3 

type RotationProvider interface {
	Provider
	// Rotate generates a new secret value and stores it, returning the new value.
	Rotate(ctx context.Context, key string) (string, error)
	// GetPrevious retrieves the previous version of a rotated secret (for grace periods).
	GetPrevious(ctx context.Context, key string) (string, error)
}

RotationProvider extends Provider with key rotation capabilities.

type SecretMeta added in v0.67.0 

type SecretMeta struct {
	Name      string
	Exists    bool
	UpdatedAt time.Time // zero when the store doesn't expose it
}

SecretMeta is presence + freshness for one key. Never carries a value.

type VaultConfig 

type VaultConfig struct {
	Address   string `json:"address" yaml:"address"`
	Token     string `json:"token" yaml:"token"`
	MountPath string `json:"mount_path" yaml:"mount_path"`
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
}

VaultConfig holds configuration for HashiCorp Vault.

type VaultProvider 

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

VaultProvider implements a HashiCorp Vault secret provider using the official vault/api client library. It supports KV v2 operations: Get, Set, Delete, and List.

func NewVaultProvider 

func NewVaultProvider(cfg VaultConfig) (*VaultProvider, error)

NewVaultProvider creates a new Vault provider using the official vault/api client. It validates the config, creates an api.Client, sets the token and namespace.

func NewVaultProviderFromClient 

func NewVaultProviderFromClient(client *vault.Client, cfg VaultConfig) *VaultProvider

NewVaultProviderFromClient creates a VaultProvider from an existing vault/api client. This is useful for testing or when you need custom client configuration.

func NewVaultProviderHTTP deprecated 

func NewVaultProviderHTTP(cfg VaultConfig) (*VaultProvider, error)

NewVaultProviderHTTP is a deprecated alias for NewVaultProvider. It exists for backward compatibility.

Deprecated: Use NewVaultProvider instead.

func (*VaultProvider) CheckAccess added in v0.67.0 

func (p *VaultProvider) CheckAccess(ctx context.Context) error

CheckAccess implements AccessChecker. It performs a lightweight check by attempting to list the mount's metadata root. The returned error never wraps the raw vault error, which may carry the address or secret path.

func (*VaultProvider) Client 

func (p *VaultProvider) Client() *vault.Client

Client returns the underlying vault/api client for advanced use.

func (*VaultProvider) Config 

func (p *VaultProvider) Config() VaultConfig

Config returns the provider's Vault configuration.

func (*VaultProvider) Delete 

func (p *VaultProvider) Delete(ctx context.Context, key string) error

Delete removes a secret from Vault KV v2.

func (*VaultProvider) Get 

func (p *VaultProvider) Get(ctx context.Context, key string) (string, error)

Get retrieves a secret value from Vault KV v2. The key can be in the format "path" or "path#field". If #field is specified, returns that specific field from the secret data. Otherwise, returns the entire data as JSON.

func (*VaultProvider) GetPrevious added in v0.3.3 

func (p *VaultProvider) GetPrevious(ctx context.Context, key string) (string, error)

GetPrevious retrieves version N-1 of the secret at the given key from Vault KV v2. It reads the current version metadata to determine N, then fetches version N-1. Returns ErrNotFound if the secret has only one version or does not exist.

func (*VaultProvider) List 

func (p *VaultProvider) List(ctx context.Context) ([]string, error)

List returns all secret keys under the mount path. It uses the Vault logical LIST operation on the metadata path.

func (*VaultProvider) Name 

func (p *VaultProvider) Name() string

func (*VaultProvider) Rotate added in v0.3.3 

func (p *VaultProvider) Rotate(ctx context.Context, key string) (string, error)

Rotate generates a new random 32-byte hex-encoded secret and stores it at the given key, creating a new version in Vault KV v2. It returns the newly generated value.

func (*VaultProvider) Set 

func (p *VaultProvider) Set(ctx context.Context, key, value string) error

Set stores a secret value in Vault KV v2. The value is stored as {"value": val} in the secret data map.

func (*VaultProvider) StatAll added in v0.67.0 

func (p *VaultProvider) StatAll(ctx context.Context) ([]SecretMeta, error)

StatAll implements MetadataProvider on a best-effort basis. If the Vault client is wired and the mount is reachable, it returns entries from the KV v2 metadata list. Otherwise it returns ErrUnsupported so callers can fall back.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.