vault

Documentation

Overview

Package vault defines the core interfaces for secret storage providers. External providers can implement these interfaces without depending on the main omnivault package, allowing them to be developed as separate Go modules.

To create a custom provider, implement the Vault interface:

type MyProvider struct { /* ... */ }

func (p *MyProvider) Get(ctx context.Context, path string) (*Secret, error) { /* ... */ }
func (p *MyProvider) Set(ctx context.Context, path string, secret *Secret) error { /* ... */ }
func (p *MyProvider) Delete(ctx context.Context, path string) error { /* ... */ }
func (p *MyProvider) Exists(ctx context.Context, path string) (bool, error) { /* ... */ }
func (p *MyProvider) List(ctx context.Context, prefix string) ([]string, error) { /* ... */ }
func (p *MyProvider) Name() string { return "myprovider" }
func (p *MyProvider) Capabilities() Capabilities { /* ... */ }
func (p *MyProvider) Close() error { /* ... */ }

Then inject it into the omnivault client:

client, _ := omnivault.NewClient(omnivault.Config{
    CustomVault: myProvider,
})

Index

• Variables
• type BatchVault
• type Capabilities
• type ExtendedVault
• type Metadata
• type Secret
  • func (s *Secret) Bytes() []byte
  • func (s *Secret) GetField(name string) string
  • func (s *Secret) SetField(name, value string)
  • func (s *Secret) String() string
• type SecretRef
  • func (r SecretRef) Fragment() string
  • func (r SecretRef) Path() string
  • func (r SecretRef) Scheme() string
  • func (r SecretRef) String() string
• type Timestamp
  • func NewTimestamp(t time.Time) *Timestamp
  • func Now() *Timestamp
  • func (t Timestamp) MarshalJSON() ([]byte, error)
  • func (t *Timestamp) UnmarshalJSON(data []byte) error
• type Vault
• type VaultError
  • func NewVaultError(op, path, provider string, err error) *VaultError
  • func (e *VaultError) Error() string
  • func (e *VaultError) Is(target error) bool
  • func (e *VaultError) Unwrap() error
• type Version

Variables

var (
	// ErrSecretNotFound is returned when a secret does not exist.
	ErrSecretNotFound = errors.New("secret not found")

	// ErrAccessDenied is returned when access to a secret is denied.
	ErrAccessDenied = errors.New("access denied")

	// ErrInvalidPath is returned when a secret path is invalid.
	ErrInvalidPath = errors.New("invalid path")

	// ErrReadOnly is returned when attempting to write to a read-only vault.
	ErrReadOnly = errors.New("vault is read-only")

	// ErrNotSupported is returned when an operation is not supported by the provider.
	ErrNotSupported = errors.New("operation not supported")

	// ErrConnectionFailed is returned when the vault connection fails.
	ErrConnectionFailed = errors.New("connection failed")

	// ErrAuthenticationFailed is returned when authentication fails.
	ErrAuthenticationFailed = errors.New("authentication failed")

	// ErrVersionNotFound is returned when a specific version of a secret is not found.
	ErrVersionNotFound = errors.New("version not found")

	// ErrAlreadyExists is returned when attempting to create a secret that already exists.
	ErrAlreadyExists = errors.New("secret already exists")

	// ErrClosed is returned when operating on a closed vault.
	ErrClosed = errors.New("vault is closed")
)

Standard errors that providers should return.

Types

type BatchVault

type BatchVault interface {
	Vault

	// GetBatch retrieves multiple secrets in a single operation.
	GetBatch(ctx context.Context, paths []string) (map[string]*Secret, error)

	// SetBatch stores multiple secrets in a single operation.
	SetBatch(ctx context.Context, secrets map[string]*Secret) error

	// DeleteBatch removes multiple secrets in a single operation.
	DeleteBatch(ctx context.Context, paths []string) error
}

BatchVault provides batch operations for providers that support them.

type Capabilities

type Capabilities struct {
	// Read indicates the provider supports reading secrets.
	Read bool `json:"read"`

	// Write indicates the provider supports writing secrets.
	Write bool `json:"write"`

	// Delete indicates the provider supports deleting secrets.
	Delete bool `json:"delete"`

	// List indicates the provider supports listing secrets.
	List bool `json:"list"`

	// Versioning indicates the provider supports secret versioning.
	Versioning bool `json:"versioning"`

	// Rotation indicates the provider supports secret rotation.
	Rotation bool `json:"rotation"`

	// Binary indicates the provider supports binary secrets.
	Binary bool `json:"binary"`

	// MultiField indicates the provider supports multi-field secrets.
	MultiField bool `json:"multiField"`

	// Batch indicates the provider supports batch operations.
	Batch bool `json:"batch"`

	// Watch indicates the provider supports watching for changes.
	Watch bool `json:"watch"`
}

Capabilities indicates what features a provider supports. This allows clients to adapt their behavior based on provider capabilities.

type ExtendedVault

type ExtendedVault interface {
	Vault

	// GetVersion retrieves a specific version of a secret.
	GetVersion(ctx context.Context, path, version string) (*Secret, error)

	// ListVersions returns all versions of a secret.
	ListVersions(ctx context.Context, path string) ([]Version, error)

	// Rotate generates a new version of the secret and returns it.
	Rotate(ctx context.Context, path string) (*Secret, error)
}

ExtendedVault provides additional features beyond the basic Vault interface. Providers can optionally implement this interface for advanced functionality.

type Metadata

type Metadata struct {
	// CreatedAt is when the secret was created.
	CreatedAt *Timestamp `json:"createdAt,omitempty"`

	// ModifiedAt is when the secret was last modified.
	ModifiedAt *Timestamp `json:"modifiedAt,omitempty"`

	// ExpiresAt is when the secret expires, if applicable.
	ExpiresAt *Timestamp `json:"expiresAt,omitempty"`

	// Version is the version identifier of the secret.
	Version string `json:"version,omitempty"`

	// Tags are key-value pairs for categorization.
	Tags map[string]string `json:"tags,omitempty"`

	// Labels are simple string labels.
	Labels []string `json:"labels,omitempty"`

	// Provider is the name of the provider that stored this secret.
	Provider string `json:"provider,omitempty"`

	// Path is the path where this secret is stored.
	Path string `json:"path,omitempty"`

	// Extra contains provider-specific metadata.
	Extra map[string]any `json:"extra,omitempty"`
}

Metadata contains additional information about a secret.

type Secret

type Secret struct {
	// Value is the primary secret value as a string.
	Value string `json:"value,omitempty"`

	// ValueBytes is the secret value as bytes, for binary secrets.
	// If both Value and ValueBytes are set, ValueBytes takes precedence.
	ValueBytes []byte `json:"valueBytes,omitempty"`

	// Fields contains additional named fields for multi-field secrets.
	// Common for password managers that store username, password, URL, etc.
	Fields map[string]string `json:"fields,omitempty"`

	// Metadata contains additional information about the secret.
	Metadata Metadata `json:"metadata,omitempty"`
}

Secret represents a stored secret with its value and metadata.

func (*Secret) Bytes

func (s *Secret) Bytes() []byte

Bytes returns the secret value as bytes.

func (*Secret) GetField

func (s *Secret) GetField(name string) string

GetField returns a field value, falling back to the main Value if the field doesn't exist and the field name is empty or "value".

func (*Secret) SetField

func (s *Secret) SetField(name, value string)

SetField sets a field value. If the field name is empty or "value", it sets the main Value field.

func (*Secret) String

func (s *Secret) String() string

String returns the primary value of the secret.

type SecretRef

type SecretRef string

SecretRef is a URI-style reference to a secret. Examples:

op://vault/item/field          (1Password)
keychain://service/account     (macOS Keychain)
env://VAR_NAME                 (Environment variable)
file:///path/to/secret         (File)
vault://secret/path#field      (HashiCorp Vault)
aws-sm://secret-name#key       (AWS Secrets Manager)
gcp-sm://project/secret        (GCP Secret Manager)

func (SecretRef) Fragment

func (r SecretRef) Fragment() string

Fragment returns the fragment portion of the secret reference (after #).

func (SecretRef) Path

func (r SecretRef) Path() string

Path returns the path portion of the secret reference (after ://).

func (SecretRef) Scheme

func (r SecretRef) Scheme() string

Scheme returns the scheme portion of the secret reference (e.g., "op", "env").

func (SecretRef) String

func (r SecretRef) String() string

String returns the string representation of the secret reference.

type Timestamp

type Timestamp struct {
	time.Time
}

Timestamp wraps time.Time to provide custom JSON marshaling.

func NewTimestamp

func NewTimestamp(t time.Time) *Timestamp

NewTimestamp creates a new Timestamp from a time.Time.

func Now

func Now() *Timestamp

Now returns a Timestamp for the current time.

func (Timestamp) MarshalJSON

func (t Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Vault

type Vault interface {
	// Get retrieves a secret from the vault at the given path.
	// Returns ErrSecretNotFound if the secret does not exist.
	Get(ctx context.Context, path string) (*Secret, error)

	// Set stores a secret in the vault at the given path.
	// If the secret already exists, it will be overwritten.
	Set(ctx context.Context, path string, secret *Secret) error

	// Delete removes a secret from the vault at the given path.
	// Returns nil if the secret does not exist.
	Delete(ctx context.Context, path string) error

	// Exists checks if a secret exists at the given path.
	Exists(ctx context.Context, path string) (bool, error)

	// List returns all secret paths matching the given prefix.
	// Returns an empty slice if no secrets match.
	List(ctx context.Context, prefix string) ([]string, error)

	// Name returns the provider name (e.g., "onepassword", "aws-sm", "keychain").
	Name() string

	// Capabilities returns the capabilities supported by this provider.
	Capabilities() Capabilities

	// Close releases any resources held by the provider.
	Close() error
}

Vault is the primary interface that all secret storage providers must implement. This interface is designed to be minimal yet complete enough for most use cases.

type VaultError

type VaultError struct {
	// Op is the operation that failed (e.g., "Get", "Set", "Delete").
	Op string

	// Path is the secret path involved in the error.
	Path string

	// Provider is the name of the provider that generated the error.
	Provider string

	// Err is the underlying error.
	Err error
}

VaultError is a structured error with additional context.

func NewVaultError

func NewVaultError(op, path, provider string, err error) *VaultError

NewVaultError creates a new VaultError.

func (*VaultError) Error

func (e *VaultError) Error() string

Error implements the error interface.

func (*VaultError) Is

func (e *VaultError) Is(target error) bool

Is reports whether the error matches the target.

func (*VaultError) Unwrap

func (e *VaultError) Unwrap() error

Unwrap returns the underlying error.

type Version

type Version struct {
	ID        string
	CreatedAt *Timestamp
	Current   bool
}

Version represents a version of a secret.