teamvault

package
v5.10.0 Latest Latest
Warning

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

 Go to latest Published: Jul 16, 2026 License: BSD-2-Clause Imports: 20 Imported by: 0

Documentation

Overview

Package teamvault provides utilities for accessing and managing TeamVault secrets.

TeamVault is a secret management system, and this package offers Go clients for retrieving passwords, users, URLs, and files from TeamVault instances. It includes various connector implementations for different use cases including remote access, caching, disk fallback, and testing.

The package also provides configuration parsing and generation capabilities to replace TeamVault placeholders in configuration templates with actual secret values.

Index

Constants

View Source 
const KeychainServiceName = "teamvault-cli"

KeychainServiceName is the constant service name used for all teamvault-cli Keychain entries. The account key is the TeamVault URL, which keeps multi-vault setups isolated automatically.

Variables

View Source 
var (
	// ErrUserType is returned when a TeamVault username JSON value is neither a string nor a number.
	ErrUserType = stderrors.New("username must be string or number")
	// ErrPasswordType is returned when a TeamVault password JSON value is neither a string nor a number.
	ErrPasswordType = stderrors.New("password must be string or number")
)
View Source 
var ErrKeychainNotSupported = errors.New(
	context.Background(),
	"keychain storage is supported on macOS only in v1",
)

ErrKeychainNotSupported indicates the current platform has no supported credential store backend. Callers may match this with errors.Is to differentiate "no Keychain on this platform" from real Keychain failures.

Functions

func NormalizePath 

func NormalizePath(path string) (string, error)

NormalizePath converts a path to an absolute path, expanding ~ to the home directory.

Types

type ApiUrl 

type ApiUrl string

ApiUrl represents a TeamVault API URL.

func (ApiUrl) Key 

func (a ApiUrl) Key() (Key, error)

Key extracts the TeamVault Key from the API URL path.

func (ApiUrl) String 

func (a ApiUrl) String() string

String returns the string representation of the ApiUrl.

type Config 

type Config struct {
	Url          Url              `json:"url"`
	User         User             `json:"user"`
	Password     Password         `json:"pass"`
	CacheEnabled bool             `json:"cacheEnabled,omitempty"`
	Timeout      libtime.Duration `json:"timeout,omitempty"`
}

Config holds the configuration for connecting to a TeamVault instance.

func ParseTeamvaultConfig 

func ParseTeamvaultConfig(content []byte) (*Config, error)

ParseTeamvaultConfig parses a TeamVault configuration from JSON content.

type ConfigGenerator 

type ConfigGenerator interface {
	Generate(
		ctx context.Context,
		sourceDirectory SourceDirectory,
		targetDirectory TargetDirectory,
	) error
}

ConfigGenerator generates configuration files by parsing templates and replacing TeamVault placeholders.

func NewConfigGenerator 

func NewConfigGenerator(configParser ConfigParser) ConfigGenerator

NewConfigGenerator creates a new ConfigGenerator with the given ConfigParser.

type ConfigParser 

type ConfigParser interface {
	Parse(ctx context.Context, content []byte) ([]byte, error)
}

ConfigParser parses configuration templates and replaces TeamVault placeholders with actual values.

func NewConfigParser 

func NewConfigParser(
	teamvaultConnector Connector,
) ConfigParser

NewConfigParser creates a new ConfigParser with the given TeamVault Connector.

type Connector 

type Connector interface {
	Password(ctx context.Context, key Key) (Password, error)
	User(ctx context.Context, key Key) (User, error)
	Url(ctx context.Context, key Key) (Url, error)
	File(ctx context.Context, key Key) (File, error)
	// Search returns the secrets whose name matches name as SearchResult values
	// (key + name + username + url), following the server's pagination up to an
	// internal safety cap. NOTE: returns []SearchResult (was []Key in v5.9.x and
	// earlier) — a breaking change for library consumers.
	Search(ctx context.Context, name string) ([]SearchResult, error)
}

Connector provides access to TeamVault secrets including passwords, users, URLs, and files.

func NewCacheConnector 

func NewCacheConnector(connector Connector) Connector

NewCacheConnector creates a new Connector that caches responses from the underlying connector.

func NewDiskFallbackConnector 

func NewDiskFallbackConnector(connector Connector) Connector

NewDiskFallbackConnector creates a new Connector that uses disk cache as fallback when the underlying connector fails.

func NewDummyConnector 

func NewDummyConnector() Connector

NewDummyConnector creates a new Connector that returns deterministic dummy values for testing.

func NewRemoteConnector 

func NewRemoteConnector(
	httpClient *http.Client,
	url Url,
	user User,
	pass Password,
	currentDateTime time.CurrentDateTime,
) Connector

NewRemoteConnector creates a new Connector that connects to a remote TeamVault instance.

type ContentType added in v5.8.0 

type ContentType string

ContentType is the TeamVault secret content type. Only "password" and "file" are supported; "cc" is deliberately out of scope. 

const (
	// ContentTypePassword is a password secret.
	ContentTypePassword ContentType = "password"
	// ContentTypeFile is a file secret.
	ContentTypeFile ContentType = "file"
)

type CreateSecret added in v5.8.0 

type CreateSecret struct {
	// ContentType selects the secret type: ContentTypePassword or ContentTypeFile.
	ContentType ContentType
	// Name is the secret name (required).
	Name string
	// Username is the optional username field.
	Username string
	// Url is the optional URL field.
	Url string
	// Description is the optional description field.
	Description string
	// Password is the password value, used when ContentType == ContentTypePassword.
	Password Password
	// FileContent is the raw file bytes, base64-encoded into secret_data when
	// ContentType == ContentTypeFile.
	FileContent []byte
}

CreateSecret describes a new secret to create. Exactly one of Password or FileContent carries the value; ContentType selects which. Metadata fields (Username/Url/Description) are optional and omitted from the request body when empty.

type CurrentRevision 

type CurrentRevision string

CurrentRevision represents the current revision identifier of a TeamVault secret.

func (CurrentRevision) String 

func (t CurrentRevision) String() string

String returns the string representation of the CurrentRevision.

type File 

type File string

File represents a base64-encoded file stored in TeamVault.

func (File) Content 

func (t File) Content() ([]byte, error)

Content decodes and returns the file content from base64 encoding.

func (File) String 

func (t File) String() string

String returns the string representation of the File.

type HtpasswdGenerator 

type HtpasswdGenerator interface {
	Generate(ctx context.Context, key Key) ([]byte, error)
}

HtpasswdGenerator generates htpasswd formatted credentials from TeamVault secrets.

func NewHtpasswdGenerator 

func NewHtpasswdGenerator(connector Connector) HtpasswdGenerator

NewHtpasswdGenerator creates a new HtpasswdGenerator with the given Connector.

type Key 

type Key string

Key represents a TeamVault secret identifier.

func (Key) String 

func (k Key) String() string

String returns the string representation of the Key.

func (Key) Validate 

func (k Key) Validate(ctx context.Context) error

Validate checks if the Key is not empty.

type Keychain 

type Keychain interface {
	// ReadPassword returns the password stored for the given TeamVault URL,
	// or ("", nil) if no entry exists. A non-nil error indicates a real
	// failure (Keychain locked, security binary error, etc.) — callers
	// should surface this to the user, not fall through silently.
	ReadPassword(ctx context.Context, url Url) (Password, error)

	// WritePassword stores or overwrites the password for the given URL.
	// On non-darwin platforms it returns ErrKeychainNotSupported.
	WritePassword(ctx context.Context, url Url, password Password) error
}

Keychain reads and writes TeamVault passwords from the OS credential store. On macOS it backs onto the login Keychain via the `security(1)` binary. On other platforms it is a no-op: ReadPassword returns ("", nil); WritePassword returns ErrKeychainNotSupported.

func NewKeychain 

func NewKeychain() Keychain

NewKeychain returns a Keychain backed by the OS credential store. On macOS uses Keychain, on Linux uses Secret Service, on Windows uses Credential Manager. On platforms without a supported backend, ReadPassword returns ("", nil) for missing entries and Read/WritePassword return ErrKeychainNotSupported for no-backend errors.

func NewKeychainWithClient 

func NewKeychainWithClient(client KeyringClient) Keychain

NewKeychainWithClient returns a Keychain using the given KeyringClient. Useful for tests that need to inject a fake credential store.

type KeyringClient 

type KeyringClient interface {
	Get(service, user string) (string, error)
	Set(service, user, password string) error
}

KeyringClient is the package-private seam over zalando/go-keyring used by darwinKeychain. It exists so unit tests can drive WritePassword/ReadPassword without touching the real macOS Keychain. NewKeychain wires up the real implementation; tests construct darwinKeychain with a Counterfeiter fake.

type Password 

type Password string

Password represents a TeamVault password.

func (Password) String 

func (t Password) String() string

String returns the string representation of the Password.

func (*Password) UnmarshalJSON 

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

UnmarshalJSON implements json.Unmarshaler to handle both string and number types.

type RealKeyringClient 

type RealKeyringClient struct{}

func (RealKeyringClient) Get 

func (RealKeyringClient) Get(service, user string) (string, error)

func (RealKeyringClient) Set 

func (RealKeyringClient) Set(service, user, password string) error

type SearchResult added in v5.10.0 

type SearchResult struct {
	Key      Key
	Name     string
	Username string
	Url      Url
}

SearchResult is one match from a TeamVault secret search. Name/Username/Url come directly from the search response's result object (no per-key fetch).

type SourceDirectory 

type SourceDirectory string

SourceDirectory represents the source directory path for configuration generation.

func (SourceDirectory) String 

func (s SourceDirectory) String() string

String returns the string representation of the SourceDirectory.

type Staging 

type Staging bool

Staging indicates whether the TeamVault instance is a staging environment.

func (Staging) Bool 

func (s Staging) Bool() bool

Bool returns the boolean value of Staging.

type TargetDirectory 

type TargetDirectory string

TargetDirectory represents the target directory path for configuration generation.

func (TargetDirectory) String 

func (t TargetDirectory) String() string

String returns the string representation of the TargetDirectory.

type TeamvaultConfigPath 

type TeamvaultConfigPath string

TeamvaultConfigPath represents a path to a TeamVault configuration file.

func (TeamvaultConfigPath) Exists 

func (t TeamvaultConfigPath) Exists() bool

Exists checks if the TeamvaultConfigPath points to an existing non-empty file.

func (TeamvaultConfigPath) NormalizePath 

func (t TeamvaultConfigPath) NormalizePath() (TeamvaultConfigPath, error)

NormalizePath converts the TeamvaultConfigPath to an absolute path.

func (TeamvaultConfigPath) Parse 

func (t TeamvaultConfigPath) Parse() (*Config, error)

Parse reads and parses the TeamVault configuration from the file.

func (TeamvaultConfigPath) String 

func (t TeamvaultConfigPath) String() string

String returns the string representation of the TeamvaultConfigPath.

type UpdateSecret added in v5.8.0 

type UpdateSecret struct {
	// Name is the new secret name.
	Name *string
	// Username is the new username.
	Username *string
	// Url is the new URL.
	Url *string
	// Description is the new description.
	Description *string
	// Password is the new password value; non-nil creates a new revision.
	Password *Password
	// FileContent is the new file content; non-nil creates a new revision.
	FileContent []byte
}

UpdateSecret describes a partial update. Only non-nil pointer fields are sent, so a metadata-only update omits secret_data entirely, and each absent field is left untouched server-side. A non-nil Password or FileContent creates a new revision.

type Url 

type Url string

Url represents a TeamVault URL or secret URL value.

func (Url) Normalize added in v5.6.0 

func (u Url) Normalize() Url

Normalize returns the Url with surrounding whitespace and trailing slashes removed. TeamVault API paths are built as "<url>/api/secrets/...", so a base URL that ends in a slash (e.g. the value copied from a browser, "https://teamvault.example.com/") would produce a double-slash path that 404s. It is also the key the Keychain stores the password under, so login (write) and fetch (read) must normalize identically or the lookup misses.

func (Url) String 

func (u Url) String() string

String returns the string representation of the Url.

type User 

type User string

User represents a TeamVault username.

func (User) String 

func (u User) String() string

String returns the string representation of the User.

func (*User) UnmarshalJSON 

func (u *User) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler to handle both string and number types.

type Writer added in v5.8.0 

type Writer interface {
	// Create posts a new secret and returns its key and api_url.
	Create(ctx context.Context, secret CreateSecret) (Key, ApiUrl, error)
	// Update patches an existing secret named by key. Only the fields set
	// in UpdateSecret are sent.
	Update(ctx context.Context, key Key, secret UpdateSecret) (Key, ApiUrl, error)
	// GeneratePassword asks the server to generate a strong password.
	GeneratePassword(ctx context.Context) (Password, error)
}

Writer creates and updates TeamVault secrets. It is intentionally separate from Connector so the read interface stays unchanged (a new method on the exported Connector would be a breaking, major-bump change).

func NewRemoteWriter added in v5.8.0 

func NewRemoteWriter(
	httpClient *http.Client,
	url Url,
	user User,
	pass Password,
	currentDateTime time.CurrentDateTime,
) Writer

NewRemoteWriter creates a Writer that issues POST/PATCH calls to a remote TeamVault instance, reusing HTTP Basic auth identical to the read path.

Source Files

View all Source files

Directories

Path Synopsis
Package cli provides the command-line interface for the teamvault utility.
 Package cli provides the command-line interface for the teamvault utility.
Package factory provides factory functions for creating TeamVault connectors and HTTP clients.
 Package factory provides factory functions for creating TeamVault connectors and HTTP clients.
Code generated by counterfeiter.
 Code generated by counterfeiter.

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.