credential

package
v1.22.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package credential stores secrets in the keyring of the operating system and falls back to files only the user can read where the keyring is unavailable.

Index

Constants

View Source
const (
	// DefaultService is the keyring service of a [Store] without [WithService].
	DefaultService = "nctl"
	// DefaultTimeout bounds a keyring operation of a [Store] without [WithTimeout].
	DefaultTimeout = 10 * time.Second
)

Variables

View Source
var (
	// ErrNotFound is returned when a store holds no secret for a key.
	// It matches [fs.ErrNotExist].
	ErrNotFound = fmt.Errorf("credential not found: %w", fs.ErrNotExist)
	// ErrUnavailable is returned when the keyring cannot be reached,
	// so the store cannot tell whether it holds a secret.
	ErrUnavailable = errors.New("keyring unavailable")
)

Functions

This section is empty.

Types

type FallbackHandler

type FallbackHandler func(path string, created bool, err error)

FallbackHandler is called with the path of the file and the error of the keyring when a secret is written to a file because the keyring failed. created is true if the file did not exist before, so the secret of the key is in plain text for the first time.

type Option

type Option func(*Store)

Option configures a Store.

func WithFallbackHandler

func WithFallbackHandler(handler FallbackHandler) Option

WithFallbackHandler sets the handler called whenever a secret is written to a file because the keyring failed. It is not called for a store using WithInsecure.

func WithInsecure

func WithInsecure(insecure bool) Option

WithInsecure makes the store use files only and never touch the keyring.

func WithNamespace

func WithNamespace(namespace string) Option

WithNamespace prefixes the names of the keyring entries, so stores of different kinds of secrets can share a service.

func WithService

func WithService(service string) Option

WithService sets the keyring service holding the secrets, DefaultService by default.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout bounds each keyring operation, which can hang while the keyring waits for an unlock prompt nobody answers. It is DefaultTimeout by default.

type Store

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

Store keeps secrets by key in the keyring of the operating system or, where the keyring is unavailable, in files below a directory.

A file exists only while it holds the newest secret of its key, as writing a secret to the keyring removes its file. Reads therefore prefer the file, which also picks up secrets written before the keyring was used.

func New

func New(dir string, opts ...Option) *Store

New returns a store keeping the files of its secrets in dir.

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, key string) error

Delete removes the secret of key from both the file and the keyring. It returns ErrNotFound if neither held it. If the keyring cannot be reached, Delete succeeds when it removed the file, which held the newest secret, and otherwise returns an error wrapping ErrUnavailable.

func (*Store) Get

func (s *Store) Get(ctx context.Context, key string) (string, error)

Get returns the secret of key. It returns ErrNotFound if neither the file nor the keyring holds it, and an error wrapping ErrUnavailable if there is no file and the keyring cannot be reached.

func (*Store) Path

func (s *Store) Path(key string) string

Path returns the file holding the secret of key when it is not in the keyring. key must be a valid file name.

func (*Store) Set

func (s *Store) Set(ctx context.Context, key, secret string) error

Set stores secret under key. It writes to the keyring unless the store is insecure, and falls back to a file if the keyring fails.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL