credentialstore

package
v0.0.35 Latest Latest
Warning

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

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

Documentation

Overview

Package credentialstore defines a host-internal, credential-format-agnostic port for opaque binary records and provides namespace-bound backend handles. Reader is the read-only boundary; ConditionalWriter adds CAS mutation, and Store combines both for mutable backends. This port remains under internal because the engine is not its consumer.

Every mutation is conditional: a nil expected version creates only, while a supplied opaque version replaces or deletes only the matching record. Values and keys have no OAuth, MCP, provider, or configuration semantics. The package performs no environment lookup, logging, or key acquisition. Future environment or Kubernetes Secret-backed sources may implement Reader only; durable refresh rotation requires a mutable Store.

The encrypted-file backend is one local Store adapter. It protects copied local disclosure and provides cooperating-process CAS on supported local Unix filesystems. It does not defend against root or the same UID, authenticated rollback, process-memory inspection, crash-left encrypted temporary files, or unreliable advisory locks and rename semantics on non-local filesystems.

Index

Constants

View Source
const (
	// MaxNamespaceBytes bounds the UTF-8 encoding of a namespace.
	MaxNamespaceBytes = 128
	// MaxRecordKeyBytes bounds an opaque record key.
	MaxRecordKeyBytes = 1024
	// MaxValueBytes bounds an opaque record value to one MiB.
	MaxValueBytes = 1 << 20
)
View Source
const (

	// MaxEnvelopeBytes is the largest accepted persisted record.
	MaxEnvelopeBytes = envelopeHeaderBytes + envelopeNonceBytes + envelopeTagBytes + MaxValueBytes
)

Variables

View Source
var (
	// ErrNotFound reports that the selected namespace has no record for the key.
	ErrNotFound = errors.New("credentialstore: record not found")
	// ErrConflict reports that a create target exists or an expected version is stale.
	ErrConflict = errors.New("credentialstore: version conflict")
	// ErrClosed reports an operation attempted through a closed handle.
	ErrClosed = errors.New("credentialstore: closed")
	// ErrTooLarge reports a record key or value above its public size bound.
	ErrTooLarge = errors.New("credentialstore: input too large")
	// ErrInvalidKey reports an empty record key or invalid encryption key.
	ErrInvalidKey = errors.New("credentialstore: invalid key")
	// ErrInvalidNamespace reports a namespace outside the documented grammar.
	ErrInvalidNamespace = errors.New("credentialstore: invalid namespace")
	// ErrInvalidEnvironment reports an invalid environment variable name or lookup.
	ErrInvalidEnvironment = errors.New("credentialstore: invalid environment configuration")
	// ErrCorrupt reports persisted data that cannot be safely authenticated or decoded.
	ErrCorrupt = errors.New("credentialstore: corrupt store")
	// ErrUnavailable reports a backend resource or operation that is unavailable.
	ErrUnavailable = errors.New("credentialstore: unavailable")
)

Functions

func NamespacePhysicalName added in v0.0.22

func NamespacePhysicalName(namespace string) string

NamespacePhysicalName returns the on-disk directory name NewEncryptedFile uses for namespace. Callers that must locate an existing namespace directory without opening the store (e.g. an existing-only precondition check) use this instead of re-deriving the naming scheme themselves.

Types

type Capabilities

type Capabilities struct {
	Persistent      bool
	CrossProcessCAS bool
}

Capabilities describes backend durability and compare-and-swap scope. Mutability is represented by implementing ConditionalWriter, not by a flag that could contradict the implemented interfaces.

type ConditionalWriter

type ConditionalWriter interface {
	// Put is always conditional. A nil expected version means create-only. A
	// non-nil expected version replaces only a record carrying that version.
	// There is no unconditional overwrite mode, and a zero Version is not a
	// wildcard.
	Put(ctx context.Context, key, value []byte, expected *Version) (Record, error)

	// Delete removes only the record carrying expected. A missing record returns
	// ErrNotFound; a stale, zero, or foreign version returns ErrConflict.
	Delete(ctx context.Context, key []byte, expected Version) error
}

ConditionalWriter provides compare-and-swap mutation of opaque credential records. It is intentionally separate from Reader so read-only sources do not have to expose mutations they cannot honor.

type EncryptedFileStore

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

EncryptedFileStore is an encrypted local-file credential store.

func NewEncryptedFile

func NewEncryptedFile(root, namespace string, key []byte) (*EncryptedFileStore, error)

NewEncryptedFile constructs a local encrypted-file store. root must be an explicit absolute owner-only path and key must contain exactly 32 bytes of already-derived random key material. No key or path discovery is performed.

func OpenExistingEncryptedFile added in v0.0.22

func OpenExistingEncryptedFile(root, namespace string, key []byte) (*EncryptedFileStore, error)

OpenExistingEncryptedFile opens an already-created encrypted-file namespace without creating or changing the root or namespace permissions.

func (EncryptedFileStore) Capabilities

func (EncryptedFileStore) Capabilities() Capabilities

Capabilities reports durable, cooperating-process local CAS.

func (EncryptedFileStore) Close

func (s EncryptedFileStore) Close() error

Close waits for operations, closes the rooted handle, and clears the store-owned long-lived key copy. It is safe for concurrent use and idempotent.

func (EncryptedFileStore) Delete

func (s EncryptedFileStore) Delete(ctx context.Context, key []byte, expected Version) error

Delete conditionally removes an authenticated record.

func (EncryptedFileStore) Get

func (s EncryptedFileStore) Get(ctx context.Context, key []byte) (Record, error)

Get returns the authenticated current record.

func (EncryptedFileStore) Put

func (s EncryptedFileStore) Put(ctx context.Context, key, value []byte, expected *Version) (Record, error)

Put creates or conditionally replaces an encrypted record.

func (EncryptedFileStore) ReplaceCorrupt added in v0.0.22

func (s EncryptedFileStore) ReplaceCorrupt(ctx context.Context, key, value []byte) (Record, error)

ReplaceCorrupt atomically replaces a record only while it remains unreadable as an authenticated envelope. Valid, missing, and operationally unreadable records are never overwritten.

type EnvironmentLookup

type EnvironmentLookup func(string) (string, bool)

EnvironmentLookup is the explicit lookup function used by EnvironmentReader. os.LookupEnv may be supplied by a host, but the adapter never selects it itself.

type EnvironmentReader

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

EnvironmentReader exposes one opaque record key from one base64-encoded environment variable. It performs no global environment lookup or mutation.

func NewEnvironment

func NewEnvironment(namespace string, key []byte, name string, lookup EnvironmentLookup) (*EnvironmentReader, error)

NewEnvironment constructs a namespace-bound read-only source. Construction validates configuration but deliberately does not read the environment.

func (*EnvironmentReader) Capabilities

func (*EnvironmentReader) Capabilities() Capabilities

Capabilities reports that process environment is not a writable durable CAS backend.

func (*EnvironmentReader) Close

func (r *EnvironmentReader) Close() error

Close prevents future reads. It is safe for concurrent use and idempotent.

func (*EnvironmentReader) Get

func (r *EnvironmentReader) Get(ctx context.Context, key []byte) (Record, error)

Get returns the configured record only. The environment value must use canonical padded RFC 4648 base64 so arbitrary credential bytes remain safe.

type MemoryBackend

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

MemoryBackend owns records shared by every handle opened from it. It is safe for concurrent use. Namespace maps and the generation counter intentionally survive individual handle closure and reopen.

func NewMemoryBackend

func NewMemoryBackend() *MemoryBackend

NewMemoryBackend constructs an empty in-memory backend.

func (*MemoryBackend) Open

func (b *MemoryBackend) Open(namespace string) (Store, error)

Open validates namespace and returns a new handle bound to it. Closing the handle does not close the backend or any sibling handle.

type PlainFileStore added in v0.0.29

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

PlainFileStore is an owner-only plaintext local-file credential store.

func NewPlainFile added in v0.0.29

func NewPlainFile(root, namespace string) (*PlainFileStore, error)

NewPlainFile constructs an owner-only plaintext store below the dedicated clientauth-plaintext directory. It shares the encrypted store's local CAS and filesystem-safety substrate but performs no encryption.

func OpenExistingPlainFile added in v0.0.29

func OpenExistingPlainFile(root, namespace string) (*PlainFileStore, error)

OpenExistingPlainFile opens an existing plaintext store without creating or changing the root or namespace.

func (PlainFileStore) Capabilities added in v0.0.29

func (PlainFileStore) Capabilities() Capabilities

Capabilities reports durable, cooperating-process local CAS.

func (PlainFileStore) Close added in v0.0.29

func (s PlainFileStore) Close() error

Close waits for operations, closes the rooted handle, and clears the store-owned long-lived key copy. It is safe for concurrent use and idempotent.

func (PlainFileStore) Delete added in v0.0.29

func (s PlainFileStore) Delete(ctx context.Context, key []byte, expected Version) error

Delete conditionally removes an authenticated record.

func (PlainFileStore) Get added in v0.0.29

func (s PlainFileStore) Get(ctx context.Context, key []byte) (Record, error)

Get returns the authenticated current record.

func (PlainFileStore) Put added in v0.0.29

func (s PlainFileStore) Put(ctx context.Context, key, value []byte, expected *Version) (Record, error)

Put creates or conditionally replaces an encrypted record.

func (PlainFileStore) ReplaceCorrupt added in v0.0.29

func (s PlainFileStore) ReplaceCorrupt(ctx context.Context, key, value []byte) (Record, error)

ReplaceCorrupt atomically replaces a record only while it remains unreadable as an authenticated envelope. Valid, missing, and operationally unreadable records are never overwritten.

type Reader

type Reader interface {
	// Get returns an owned value copy and its current opaque version.
	Get(ctx context.Context, key []byte) (Record, error)

	Capabilities() Capabilities

	// Close is safe for concurrent use and idempotent for this handle.
	Close() error
}

Reader is the host-internal read-only port for a namespace-bound opaque credential source. Backends such as environment or Kubernetes Secret sources may implement Reader without supporting mutation.

type Record

type Record struct {
	Value   []byte
	Version Version
}

Record is an owned value copy and the version that identified it when read or written. Mutating Value never mutates the store.

type Store

type Store interface {
	Reader
	ConditionalWriter
}

Store is a mutable namespace-bound opaque record store. Durable credential refresh rotation requires a Store so updates remain conditional.

type Version

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

Version is an opaque record revision. Its zero value is never accepted as a mutation wildcard. Only store implementations in this package can mint valid versions.

func (Version) Equal

func (v Version) Equal(other Version) bool

Equal reports whether two version values are identical. Two zero Versions compare equal, but remain invalid mutation expectations.

Directories

Path Synopsis
Package conformance provides the reusable contract tests for mutable credential stores.
Package conformance provides the reusable contract tests for mutable credential stores.

Jump to

Keyboard shortcuts

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