secrets

package
v1.20.0-beta.16 Latest Latest
Warning

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

 Go to latest Published: Oct 4, 2026 License: MPL-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	SOPSFormatter    = "sops"
	SOPSFormatYAML   = "yaml"
	SOPSFormatJSON   = "json"
	SOPSFormatDotenv = "dotenv"
)
View Source 
const (
	EnvPassphraseFile     = "DEVSY_SECRETS_PASSPHRASE_FILE" // #nosec G101 -- environment variable name.
	MaxPassphraseFileSize = 64 * 1024
)
View Source 
const EncryptedFileName = "secrets.enc"
View Source 
const EnvBackend = "DEVSY_SECRETS_BACKEND"
View Source 
const EnvPassphrase = "DEVSY_SECRETS_PASSPHRASE" // #nosec G101 -- env var name, not a credential.
View Source 
const IndexFileName = "secrets.yaml"
View Source 
const KeyFileName = "secrets.key"
View Source 
const LocalSourceName = "local"

Variables

View Source 
var (
	ErrUnlockRequired     = errors.New("secret store unlock required")
	ErrUnlockFailed       = errors.New("secret store unlock failed")
	ErrBackendUnavailable = errors.New("secret backend unavailable")
	ErrStoreCorrupt       = errors.New("secret store corrupt")
)
View Source 
var ErrSecretNotFound = errors.New("secret not found")
View Source 
var ErrStateIndeterminate = errors.New("managed value state is indeterminate")

Functions

func CleanProjectSourcePath added in v1.18.0 

func CleanProjectSourcePath(value string) (string, error)

CleanProjectSourcePath validates a repository-controlled source path and returns a normalized repository-relative slash path.

func ModifySourceConfigs added in v1.18.0 

func ModifySourceConfigs(
	devsyConfig *config.Config,
	mutate func(sources []SourceConfig) ([]SourceConfig, error),
) error

ModifySourceConfigs serializes external source modifications across processes by holding the secret-sources lock while loading, mutating, and writing configuration.

func ParseSecretsFile 

func ParseSecretsFile(path string) (map[string]string, error)

func ReadRememberedPassphrase added in v1.20.0 

func ReadRememberedPassphrase() (string, error)

func RecoverRekey added in v1.20.0 

func RecoverRekey(dir string) error

RecoverRekey must run under secrets.yaml.lock. An uncommitted transaction rolls back without needing either credential. Committed records the chosen terminal outcome (the new state or a completed rollback), so cleanup can safely remove backups before removing the journal.

func RegisterConfiguredSource added in v1.18.0 

func RegisterConfiguredSource(resolver *Resolver, sourceConfig SourceConfig) error

func ResolveProjectSourcePath added in v1.18.0 

func ResolveProjectSourcePath(root, value string) (string, error)

ResolveProjectSourcePath converts a repository-controlled relative path to a local path while enforcing containment, including after symlink resolution.

func SaveSourceConfigs added in v1.18.0 

func SaveSourceConfigs(devsyConfig *config.Config, sources []SourceConfig) error

SaveSourceConfigs writes external source metadata for the active context.

func ValidateName added in v1.10.0 

func ValidateName(name string) error

func ValidateProjectConfig added in v1.18.0 

func ValidateProjectConfig(cfg *ProjectConfig) error

func ValidateSourceName added in v1.18.0 

func ValidateSourceName(name string) error

Types

type Backend added in v1.10.0 

type Backend string
const (
	BackendAuto    Backend = "auto"
	BackendKeyring Backend = "keyring"
	BackendFile    Backend = "file"
)

type BackendOpenIntent added in v1.20.0 

type BackendOpenIntent string
const (
	BackendOpenExisting  BackendOpenIntent = "open_existing"
	BackendInspect       BackendOpenIntent = "inspect"
	BackendInitializeNew BackendOpenIntent = "initialize_new"
)

type BackendUnavailableError added in v1.20.0 

type BackendUnavailableError struct {
	Backend Backend
	Cause   error
}

func (*BackendUnavailableError) Error added in v1.20.0 

func (e *BackendUnavailableError) Error() string

func (*BackendUnavailableError) Unwrap added in v1.20.0 

func (e *BackendUnavailableError) Unwrap() []error

type DefaultUnlockResolver added in v1.20.0 

type DefaultUnlockResolver struct {
	ExplicitPassphrase string
	LookupEnv          func(string) string
	ReadRemembered     func() (string, error)
	Prompt             func(context.Context, UnlockRequest) (string, error)
}

DefaultUnlockResolver chooses one credential source. Decryption failure never falls through to another source. Prompt callbacks belong to the invoking UI.

func (DefaultUnlockResolver) ResolvePassphrase added in v1.20.0 

func (r DefaultUnlockResolver) ResolvePassphrase(
	ctx context.Context,
	request UnlockRequest,
) (UnlockMaterial, error)

type FileKeySource added in v1.20.0 

type FileKeySource string

FileKeySource describes persisted encryption protection, independent of the runtime source supplying a passphrase. 

const (
	FileKeyPassphrase FileKeySource = "passphrase"
	FileKeyKeyring    FileKeySource = "keyring"
	FileKeyLocalFile  FileKeySource = "file"
)

type Kind added in v1.10.0 

type Kind string

Kind distinguishes secrets (values in the backend) from env vars (inline). 

const (
	KindSecret Kind = "secret"
	KindEnv    Kind = "env"
)

type LocalSource added in v1.18.0 

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

LocalSource adapts the Devsy Store to the generic source interface.

func NewLocalSource added in v1.18.0 

func NewLocalSource(store localSecretReader, contextName string) *LocalSource

func (*LocalSource) Get added in v1.18.0 

func (s *LocalSource) Get(_ context.Context, name string) (ResolvedSecret, error)

type MutationError added in v1.20.0 

type MutationError struct {
	Operation string
	Context   string
	Name      string
	Cause     error
	Rollback  error
}

func (*MutationError) Error added in v1.20.0 

func (e *MutationError) Error() string

func (*MutationError) Unwrap added in v1.20.0 

func (e *MutationError) Unwrap() []error

type PassphraseSource added in v1.20.0 

type PassphraseSource string
const (
	PassphraseExplicit   PassphraseSource = "explicit"
	PassphraseEnv        PassphraseSource = "environment"
	PassphraseFile       PassphraseSource = "file"
	PassphraseRemembered PassphraseSource = "keyring"
	PassphrasePrompt     PassphraseSource = "prompt"
)

type ProjectConfig added in v1.18.0 

type ProjectConfig struct {
	SecretSources []SourceConfig `json:"secretSources,omitempty" yaml:"secretSources,omitempty"`
	Secrets       []string       `json:"secrets,omitempty"       yaml:"secrets,omitempty"`
}

ProjectConfig is the repository-owned subset of Devsy configuration used by secret discovery.

func LoadProjectConfigFromRoot added in v1.18.0 

func LoadProjectConfigFromRoot(root string) (*ProjectConfig, bool, error)

LoadProjectConfigFromRoot loads repository-owned config from a local checkout. A missing configuration is not an error.

func LoadProjectConfigFromRootWithOptions added in v1.18.0 

func LoadProjectConfigFromRootWithOptions(
	root, devContainerPath, devContainerID string,
) (*ProjectConfig, bool, error)

LoadProjectConfigFromRootWithOptions loads repository-owned config from a local checkout, checking the specified devcontainer path, conventional root devcontainer locations, and profile-specific devcontainer directories for customizations.devsy.

func ParseProjectConfig added in v1.18.0 

func ParseProjectConfig(data []byte) (*ProjectConfig, error)

type ProtectionManager added in v1.20.0 

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

func NewProtectionManager added in v1.20.0 

func NewProtectionManager(dir string, resolver UnlockMaterialResolver) *ProtectionManager

func (*ProtectionManager) CatalogStatus added in v1.20.0 

func (p *ProtectionManager) CatalogStatus() (ProtectionStatus, error)

CatalogStatus reads the confirmation list without inspecting value backends.

func (*ProtectionManager) ChangePassphrase added in v1.20.0 

func (p *ProtectionManager) ChangePassphrase(passphrase string) error

func (*ProtectionManager) Forget added in v1.20.0 

func (p *ProtectionManager) Forget() error

func (*ProtectionManager) Remember added in v1.20.0 

func (p *ProtectionManager) Remember(passphrase string) error

func (*ProtectionManager) RemovePassphrase added in v1.20.0 

func (p *ProtectionManager) RemovePassphrase() error

func (*ProtectionManager) ResetFileStore added in v1.20.0 

func (p *ProtectionManager) ResetFileStore() (string, error)

ResetFileStore quarantines the whole ciphertext and removes every file-owned catalog entry. The command layer must obtain destructive confirmation first.

func (*ProtectionManager) ResetFileStoreIfUnchanged added in v1.20.0 

func (p *ProtectionManager) ResetFileStoreIfUnchanged(expected []SecretMeta) (string, error)

ResetFileStoreIfUnchanged prevents deleting entries created after the user reviewed the destructive confirmation list.

func (*ProtectionManager) ResolvePassphrase added in v1.20.0 

func (p *ProtectionManager) ResolvePassphrase(ctx context.Context) (string, error)

ResolvePassphrase resolves current unlock input for remember without putting it in argv. New protection credentials are read separately by the command.

func (*ProtectionManager) SetPassphrase added in v1.20.0 

func (p *ProtectionManager) SetPassphrase(passphrase string) error

func (*ProtectionManager) Status added in v1.20.0 

func (p *ProtectionManager) Status() (ProtectionStatus, error)

type ProtectionStatus added in v1.20.0 

type ProtectionStatus struct {
	Availability        SecretAvailability `json:"availability"`
	ReasonCode          string             `json:"reasonCode,omitempty"`
	KeySource           string             `json:"keySource"`
	Remembered          bool               `json:"remembered"`
	RememberedAvailable bool               `json:"rememberedAvailable"`
	FileEntries         []SecretMeta       `json:"fileEntries"`
}

type Redactor added in v1.10.0 

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

func Combine added in v1.20.0 

func Combine(redactors ...*Redactor) *Redactor

Combine returns a redactor that masks the values known by every input. Nil redactors are ignored.

func NewEnvironmentRedactor added in v1.20.0 

func NewEnvironmentRedactor(env []string) *Redactor

NewEnvironmentRedactor protects values from environment variables that are conventionally credential-bearing, while leaving ordinary environment values available in diagnostics.

func NewRedactor added in v1.10.0 

func NewRedactor(secretsEnv []string) *Redactor

NewRedactor masks the values (not keys) of KEY=VALUE entries; empty values are ignored.

func (*Redactor) Redact added in v1.10.0 

func (r *Redactor) Redact(s string) string

type ResolvedSecret added in v1.18.0 

type ResolvedSecret struct {
	Name      string
	Value     string
	Sensitive bool
	Source    string
}

ResolvedSecret is the runtime value returned by a secret source.

type Resolver added in v1.18.0 

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

Resolver routes a SecretRef to an explicitly registered source instance.

func NewEnvironmentResolverForConfig added in v1.20.0 

func NewEnvironmentResolverForConfig(cfg *config.Config) (*Resolver, error)

NewEnvironmentResolverForConfig avoids external secret-source configuration and secret catalog reads for environment-only workspace requests.

func NewResolver added in v1.18.0 

func NewResolver() *Resolver

func NewResolverForConfig added in v1.18.0 

func NewResolverForConfig(devsyConfig *config.Config, options ...StoreOptions) (*Resolver, error)

NewResolverForConfig constructs the local Devsy source plus all external sources registered in the active local context.

func (*Resolver) Register added in v1.18.0 

func (r *Resolver) Register(name, typeName string, source Source) error

func (*Resolver) RegisterEnvironmentSource added in v1.20.0 

func (r *Resolver) RegisterEnvironmentSource(source Source) error

RegisterEnvironmentSource installs the separate plaintext source used by env injection. Registering a secret source never enables environment resolution.

func (*Resolver) Resolve added in v1.18.0 

func (r *Resolver) Resolve(ctx context.Context, ref SecretRef) (ResolvedSecret, error)

func (*Resolver) ResolveEnvironment added in v1.20.0 

func (r *Resolver) ResolveEnvironment(ctx context.Context, ref SecretRef) (ResolvedSecret, error)

ResolveEnvironment reads the dedicated local environment domain.

type SOPSSource added in v1.18.0 

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

SOPSSource resolves values from one SOPS-encrypted document. A source is command-scoped: decrypted values are cached in memory for the lifetime of the source instance.

func NewSOPSDataSource added in v1.18.0 

func NewSOPSDataSource(name, logicalPath, format string, encrypted []byte) *SOPSSource

NewSOPSDataSource is used for repository inspection where the encrypted file is read directly from a Git revision without being materialized on disk.

func NewSOPSSource added in v1.18.0 

func NewSOPSSource(name, filePath, format string) *SOPSSource

func (*SOPSSource) Get added in v1.18.0 

func (s *SOPSSource) Get(ctx context.Context, name string) (ResolvedSecret, error)

func (*SOPSSource) Validate added in v1.18.0 

func (s *SOPSSource) Validate(ctx context.Context) error

Validate forces decryption and document validation without exposing values.

type SecretAvailability added in v1.20.0 

type SecretAvailability string
const (
	SecretAvailable          SecretAvailability = "available"
	SecretLocked             SecretAvailability = "locked"
	SecretMissing            SecretAvailability = "missing"
	SecretBackendUnavailable SecretAvailability = "backend_unavailable"
	SecretStateUnknown       SecretAvailability = "unknown"
)

type SecretCatalog added in v1.20.0 

type SecretCatalog interface {
	Meta(contextName, name string) (SecretMeta, error)
	ListMeta(contextName string) ([]SecretMeta, error)
	Inspect(contextName string) ([]SecretInspection, error)
}

type SecretInspection added in v1.20.0 

type SecretInspection struct {
	Meta         SecretMeta         `json:"meta"`
	Availability SecretAvailability `json:"availability"`
	ReasonCode   string             `json:"reasonCode,omitempty"`
}

type SecretMeta added in v1.10.0 

type SecretMeta struct {
	Name     string    `json:"name"`
	Context  string    `json:"context"`
	Kind     Kind      `json:"kind"`
	Value    string    `json:"value,omitempty"`
	Created  time.Time `json:"created"`
	LastUsed time.Time `json:"lastUsed,omitzero"`
	Backend  Backend   `json:"backend,omitempty"`

	Orphaned bool `json:"-"`
}

func (SecretMeta) Sensitive added in v1.10.0 

func (m SecretMeta) Sensitive() bool

An unspecified kind is secret metadata; only explicit legacy env entries are plaintext.

type SecretRef added in v1.18.0 

type SecretRef struct {
	Type   string
	Source string
	Name   string
}

SecretRef identifies a named secret and the source instance that owns it. Unqualified references resolve from the local Devsy store. Qualified references use TYPE:SOURCE/NAME, for example sops:project/API_TOKEN.

func ParseRef added in v1.18.0 

func ParseRef(value string) (SecretRef, error)

func (SecretRef) String added in v1.18.0 

func (r SecretRef) String() string

type SecretRestorer added in v1.20.0 

type SecretRestorer interface {
	Restore(meta SecretMeta, value string) error
}

SecretRestorer compensates a synchronous managed-value deletion using its captured metadata and plaintext. It preserves the recorded owning backend.

type SecretStore added in v1.20.0 

type SecretStore interface {
	SecretCatalog
	Set(contextName, name, value string) error
	Get(contextName, name string) (string, error)
	Delete(contextName, name string) error
}

func NewSecretStoreForConfig added in v1.20.0 

func NewSecretStoreForConfig(
	devsyConfig *config.Config,
	options ...StoreOptions,
) (SecretStore, error)

type Source added in v1.18.0 

type Source interface {
	Get(ctx context.Context, name string) (ResolvedSecret, error)
}

Source resolves externally or locally owned secret values.

type SourceConfig added in v1.18.0 

type SourceConfig struct {
	Name   string `json:"name"             yaml:"name"`
	Type   string `json:"type"             yaml:"type"`
	Path   string `json:"path,omitempty"   yaml:"path,omitempty"`
	Format string `json:"format,omitempty" yaml:"format,omitempty"`
}

SourceConfig describes an external secret source. It contains references only; secret values and decryption credentials are never persisted here.

func AddSourceConfig added in v1.18.0 

func AddSourceConfig(sources []SourceConfig, source SourceConfig) ([]SourceConfig, error)

func FindSourceConfig added in v1.18.0 

func FindSourceConfig(sources []SourceConfig, name string) (SourceConfig, bool)

func LoadSourceConfigs added in v1.18.0 

func LoadSourceConfigs(devsyConfig *config.Config) ([]SourceConfig, error)

LoadSourceConfigs loads external sources registered for the active context.

func RemoveSourceConfig added in v1.18.0 

func RemoveSourceConfig(sources []SourceConfig, name string) ([]SourceConfig, bool)

type Store deprecated added in v1.10.0 

type Store interface {
	Set(context, name, value string, kind Kind) error
	Get(context, name string) (string, error)
	Meta(context, name string) (SecretMeta, error)
	List(context string) ([]SecretMeta, error)
	// Delete returns nil after removal. An ordinary error guarantees the
	// original store state was restored; ErrStateIndeterminate means it was not.
	Delete(context, name string) error
}

Store is the legacy mixed managed-value API retained for compatibility.

Deprecated: use SecretStore for secrets and envstore.EnvStore for environment values.

func NewStoreForConfig deprecated added in v1.10.0 

func NewStoreForConfig(devsyConfig *config.Config, options ...StoreOptions) (Store, error)

NewStoreForConfig creates the legacy mixed store.

Deprecated: use NewSecretStoreForConfig or envstore.NewStoreForConfig.

type StoreCorruptError added in v1.20.0 

type StoreCorruptError struct{ Cause error }

func (*StoreCorruptError) Error added in v1.20.0 

func (e *StoreCorruptError) Error() string

func (*StoreCorruptError) Unwrap added in v1.20.0 

func (e *StoreCorruptError) Unwrap() []error

type StoreOptions added in v1.20.0 

type StoreOptions struct {
	UnlockResolver UnlockMaterialResolver
	AllowPrompt    bool
}

type StreamingRedactor added in v1.20.0 

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

StreamingRedactor masks secrets split across text writes, buffering a short suffix until the next write or Flush.

func NewStreamingRedactor added in v1.20.0 

func NewStreamingRedactor(r *Redactor) *StreamingRedactor

NewStreamingRedactor creates a chunk-safe redactor around r.

func (*StreamingRedactor) Flush added in v1.20.0 

func (r *StreamingRedactor) Flush() string

Flush returns the final pending suffix, redacted as a complete fragment.

func (*StreamingRedactor) RedactChunk added in v1.20.0 

func (r *StreamingRedactor) RedactChunk(chunk string) string

RedactChunk returns the portion safe to emit immediately.

type UnlockFailedError added in v1.20.0 

type UnlockFailedError struct {
	Backend Backend
	Cause   error
}

func (*UnlockFailedError) Error added in v1.20.0 

func (e *UnlockFailedError) Error() string

func (*UnlockFailedError) Unwrap added in v1.20.0 

func (e *UnlockFailedError) Unwrap() []error

type UnlockMaterial added in v1.20.0 

type UnlockMaterial struct {
	Passphrase string
	Source     PassphraseSource
}

type UnlockMaterialResolver added in v1.20.0 

type UnlockMaterialResolver interface {
	ResolvePassphrase(context.Context, UnlockRequest) (UnlockMaterial, error)
}

type UnlockMaterialResolverFunc added in v1.20.0 

type UnlockMaterialResolverFunc func(context.Context, UnlockRequest) (UnlockMaterial, error)

func (UnlockMaterialResolverFunc) ResolvePassphrase added in v1.20.0 

func (f UnlockMaterialResolverFunc) ResolvePassphrase(
	ctx context.Context,
	r UnlockRequest,
) (UnlockMaterial, error)

type UnlockRequest added in v1.20.0 

type UnlockRequest struct {
	AllowPrompt bool
	Purpose     string
}

type UnlockRequiredError added in v1.20.0 

type UnlockRequiredError struct{ Backend Backend }

func (*UnlockRequiredError) Error added in v1.20.0 

func (e *UnlockRequiredError) Error() string

func (*UnlockRequiredError) Unwrap added in v1.20.0 

func (e *UnlockRequiredError) Unwrap() error

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.