vault

package
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Apr 18, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package vault provides recipients.txt management for multi-user encryption support. Recipients can be added to enable multiple parties to decrypt vault entries.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrRecipientAlreadyExists = errors.New("recipient already exists")
	ErrRecipientNotFound      = errors.New("recipient not found")
	ErrInvalidRecipient       = errors.New("invalid recipient")
	ErrEmptyRecipientFile     = errors.New("recipients file is empty")
)

Common recipients errors

View Source 
var (
	ErrVaultDirEmpty       = errors.New("vault directory is empty")
	ErrNilIdentity         = errors.New("identity is nil")
	ErrNilConfig           = errors.New("config is nil")
	ErrIdentityMismatch    = errors.New("identity mismatch")
	ErrVaultNotInitialized = errors.New("vault not initialized")
	ErrVaultDirEscapes     = errors.New("vault directory path escapes intended directory")
)

Common vault errors

Functions

func DeleteEntry 

func DeleteEntry(vaultDir, path string) error

DeleteEntry removes an entry from the vault

func EnsureDir 

func EnsureDir(v *Vault, path string) error

EnsureDir ensures the directory for an entry exists

func EntryPath 

func EntryPath(v *Vault, path string) string

EntryPath returns the full file path for a vault entry

func Init 

func Init(vaultDir string, identity *age.X25519Identity, cfg *vaultconfig.Config) error

Init initializes a new vault at the given directory with the provided identity and config. It creates the vault directory, config file, and encrypted identity file.

func InitWithPassphrase 

func InitWithPassphrase(vaultDir string, passphrase string, cfg *vaultconfig.Config) (*age.X25519Identity, error)

InitWithPassphrase initializes a new vault with a passphrase-protected identity.

func IsInitialized 

func IsInitialized(vaultDir string) bool

IsInitialized checks if a vault is initialized at the given directory

func IsStructuredEntry 

func IsStructuredEntry(data map[string]any) bool

IsStructuredEntry checks if the given data represents a structured EntryV2 by looking for the presence of version field and created_at timestamp

func List 

func List(vaultDir string, prefix string) ([]string, error)

func WriteEntry 

func WriteEntry(vaultDir, path string, entry *Entry, identity *age.X25519Identity) error

WriteEntry encrypts and writes an entry to the vault

func WriteEntryV2 

func WriteEntryV2(vaultDir, path string, entry *EntryV2, identity *age.X25519Identity) error

WriteEntryV2 writes an EntryV2 to the vault

func WriteEntryWithRecipients 

func WriteEntryWithRecipients(vaultDir, path string, entry *Entry, identity *age.X25519Identity) error

WriteEntryWithRecipients encrypts and writes an entry to the vault, encrypting for all recipients including those in recipients.txt

Types

type CustomField 

type CustomField struct {
	// Name is the field identifier
	Name string `json:"name"`

	// Value is the field content
	Value string `json:"value"`

	// Type indicates how the field should be displayed/handled
	Type CustomFieldType `json:"type,omitempty"`
}

CustomField represents a user-defined field with a type

type CustomFieldType 

type CustomFieldType string

CustomFieldType represents the type of a custom field 

const (
	// FieldTypeString is a plain text field
	FieldTypeString CustomFieldType = "string"

	// FieldTypeHidden is a concealed field (like a second password)
	FieldTypeHidden CustomFieldType = "hidden"

	// FieldTypeURL is a URL field
	FieldTypeURL CustomFieldType = "url"

	// FieldTypeEmail is an email address field
	FieldTypeEmail CustomFieldType = "email"

	// FieldTypeDate is a date field
	FieldTypeDate CustomFieldType = "date"

	// FieldTypeNumber is a numeric field
	FieldTypeNumber CustomFieldType = "number"
)

type Entry 

type Entry struct {
	Data     map[string]any `json:"data"`
	Metadata EntryMetadata  `json:"meta"`
}

Entry represents a vault entry with flexible data storage. This is the legacy format that uses map[string]any for data storage. For a more structured approach, use EntryV2.

func MergeEntry 

func MergeEntry(vaultDir, path string, partialData map[string]any, identity *age.X25519Identity) (*Entry, error)

MergeEntry merges partial data into an existing entry

func MergeEntryWithRecipients 

func MergeEntryWithRecipients(vaultDir, path string, partialData map[string]any, identity *age.X25519Identity) (*Entry, error)

MergeEntryWithRecipients merges partial data into an existing entry, encrypting for all recipients

func ReadEntry 

func ReadEntry(vaultDir, path string, identity *age.X25519Identity) (*Entry, error)

ReadEntry reads and decrypts an entry from the vault

func (*Entry) GetField 

func (e *Entry) GetField(name string) (any, bool)

GetField retrieves a field value from an entry, supporting both legacy map-based data and structured EntryV2 fields

func (*Entry) HasField 

func (e *Entry) HasField(name string) bool

HasField checks if a field exists in the entry

func (Entry) MarshalJSON 

func (e Entry) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling for Entry

func (*Entry) SetField 

func (e *Entry) SetField(name string, value any)

SetField sets a field value in the entry's data map

func (*Entry) UnmarshalJSON 

func (e *Entry) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom JSON unmarshaling for Entry

type EntryMetadata 

type EntryMetadata struct {
	Created time.Time `json:"created"`
	Updated time.Time `json:"updated"`
	Version int       `json:"version"`
}

EntryMetadata contains metadata about an entry

type EntryV2 

type EntryV2 struct {
	CreatedAt    time.Time     `json:"created_at"`
	UpdatedAt    time.Time     `json:"updated_at"`
	TOTP         *TOTPConfig   `json:"totp,omitempty"`
	Name         string        `json:"name,omitempty"`
	Username     string        `json:"username,omitempty"`
	Password     string        `json:"password,omitempty"`
	URL          string        `json:"url,omitempty"`
	Notes        string        `json:"notes,omitempty"`
	Tags         []string      `json:"tags,omitempty"`
	CustomFields []CustomField `json:"custom_fields,omitempty"`
	Version      int           `json:"version"`
}

EntryV2 represents a structured password entry with typed fields. This is the new schema that provides better type safety and structure compared to the legacy Entry type which used map[string]any.

func EntryV2FromLegacy 

func EntryV2FromLegacy(entry *Entry) *EntryV2

EntryV2FromLegacy creates an EntryV2 from a legacy Entry This allows migration from the old format to the new structured format

func MergeEntryV2 

func MergeEntryV2(vaultDir, path string, mergeFn func(*EntryV2) error, identity *age.X25519Identity) (*EntryV2, error)

MergeEntryV2 merges partial data into an existing EntryV2

func NewEntryV2 

func NewEntryV2() *EntryV2

NewEntryV2 creates a new EntryV2 with initialized timestamps

func ReadEntryV2 

func ReadEntryV2(vaultDir, path string, identity *age.X25519Identity) (*EntryV2, error)

ReadEntryV2 reads an entry and converts it to EntryV2 format If the stored entry is in legacy format, it will be converted

func (*EntryV2) AddCustomField 

func (e *EntryV2) AddCustomField(field CustomField)

AddCustomField adds or updates a custom field

func (*EntryV2) AddTag 

func (e *EntryV2) AddTag(tag string)

AddTag adds a tag if it doesn't already exist

func (*EntryV2) GetCustomField 

func (e *EntryV2) GetCustomField(name string) (CustomField, bool)

GetCustomField retrieves a custom field by name

func (EntryV2) MarshalJSON 

func (e EntryV2) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling for EntryV2

func (*EntryV2) RemoveCustomField 

func (e *EntryV2) RemoveCustomField(name string)

RemoveCustomField removes a custom field by name

func (*EntryV2) RemoveTag 

func (e *EntryV2) RemoveTag(tag string)

RemoveTag removes a tag if it exists

func (*EntryV2) ToLegacyEntry 

func (e *EntryV2) ToLegacyEntry() *Entry

ToLegacyEntry converts an EntryV2 to the legacy Entry format This maintains backward compatibility with existing vault data

func (*EntryV2) UnmarshalJSON 

func (e *EntryV2) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom JSON unmarshaling for EntryV2

func (*EntryV2) UpdateTimestamps 

func (e *EntryV2) UpdateTimestamps()

UpdateTimestamps updates the UpdatedAt timestamp and increments version

type Match 

type Match struct {
	Path   string
	Fields []string
}

func Find 

func Find(vaultDir string, query string) ([]Match, error)

type RecipientInfo 

type RecipientInfo struct {
	RawString  string
	Normalized string
	Error      string
	LineNumber int
	Valid      bool
}

RecipientInfo contains information about a recipient entry

type RecipientsManager 

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

RecipientsManager handles the recipients.txt file operations

func NewRecipientsManager 

func NewRecipientsManager(vaultDir string) *RecipientsManager

NewRecipientsManager creates a new recipients manager for the given vault directory

func (*RecipientsManager) AddRecipient 

func (rm *RecipientsManager) AddRecipient(recipientStr string) error

AddRecipient adds a new recipient to the recipients.txt file. Validates the recipient format before adding. Returns ErrRecipientAlreadyExists if the recipient is already in the file.

func (*RecipientsManager) ListRecipients 

func (rm *RecipientsManager) ListRecipients() ([]RecipientInfo, error)

ListRecipients returns a list of all recipients with their line numbers. Useful for displaying to users.

func (*RecipientsManager) LoadRecipientStrings 

func (rm *RecipientsManager) LoadRecipientStrings() ([]string, error)

LoadRecipientStrings loads all recipient strings from the file without validation. Used for listing and management operations.

func (*RecipientsManager) LoadRecipients 

func (rm *RecipientsManager) LoadRecipients() ([]*age.X25519Recipient, error)

LoadRecipients loads all valid recipients from the recipients.txt file. Lines starting with # are treated as comments and ignored. Empty lines are skipped. Returns the list of recipients and any validation errors encountered.

func (*RecipientsManager) RecipientsFileExists 

func (rm *RecipientsManager) RecipientsFileExists() bool

RecipientsFileExists checks if the recipients.txt file exists

func (*RecipientsManager) RecipientsFilePath 

func (rm *RecipientsManager) RecipientsFilePath() string

RecipientsFilePath returns the full path to the recipients.txt file

func (*RecipientsManager) RemoveRecipient 

func (rm *RecipientsManager) RemoveRecipient(recipientStr string) error

RemoveRecipient removes a recipient from the recipients.txt file. Returns ErrRecipientNotFound if the recipient is not in the file.

type TOTPConfig 

type TOTPConfig struct {
	Secret      string `json:"secret"`
	Algorithm   string `json:"algorithm,omitempty"`
	Issuer      string `json:"issuer,omitempty"`
	AccountName string `json:"account_name,omitempty"`
	Digits      int    `json:"digits,omitempty"`
	Period      int    `json:"period,omitempty"`
}

TOTPConfig represents configuration for time-based one-time passwords

type Vault 

type Vault struct {
	Identity *age.X25519Identity
	Config   *vaultconfig.Config
	Dir      string
}

Vault represents an encrypted password vault

func Open 

func Open(vaultDir string, identity *age.X25519Identity) (*Vault, error)

Open opens an existing vault at the given directory with the provided identity. It verifies the identity matches the stored encrypted identity.

func OpenWithPassphrase 

func OpenWithPassphrase(vaultDir string, passphrase string) (*Vault, error)

OpenWithPassphrase opens a vault using a passphrase-protected identity file.

func (*Vault) AutoCommit 

func (v *Vault) AutoCommit(message string) error

AutoCommit performs a git auto-commit with vault configuration

func (*Vault) GetAllRecipientsForEncryption 

func (v *Vault) GetAllRecipientsForEncryption() ([]*age.X25519Recipient, error)

GetAllRecipientsForEncryption returns all recipients that should be used for encryption. This includes the vault's own recipient plus all recipients from the recipients.txt file.

func (*Vault) GetRecipient 

func (v *Vault) GetRecipient() (*age.X25519Recipient, error)

GetRecipient returns the vault's recipient (public key)

func (*Vault) ValidateIdentity 

func (v *Vault) ValidateIdentity(identity *age.X25519Identity) error

ValidateIdentity validates that the provided identity matches the vault

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.