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
- Variables
- func NamespacePhysicalName(namespace string) string
- type Capabilities
- type ConditionalWriter
- type EncryptedFileStore
- func (EncryptedFileStore) Capabilities() Capabilities
- func (s EncryptedFileStore) Close() error
- func (s EncryptedFileStore) Delete(ctx context.Context, key []byte, expected Version) error
- func (s EncryptedFileStore) Get(ctx context.Context, key []byte) (Record, error)
- func (s EncryptedFileStore) Put(ctx context.Context, key, value []byte, expected *Version) (Record, error)
- func (s EncryptedFileStore) ReplaceCorrupt(ctx context.Context, key, value []byte) (Record, error)
- type EnvironmentLookup
- type EnvironmentReader
- type MemoryBackend
- type PlainFileStore
- func (PlainFileStore) Capabilities() Capabilities
- func (s PlainFileStore) Close() error
- func (s PlainFileStore) Delete(ctx context.Context, key []byte, expected Version) error
- func (s PlainFileStore) Get(ctx context.Context, key []byte) (Record, error)
- func (s PlainFileStore) Put(ctx context.Context, key, value []byte, expected *Version) (Record, error)
- func (s PlainFileStore) ReplaceCorrupt(ctx context.Context, key, value []byte) (Record, error)
- type Reader
- type Record
- type Store
- type Version
Constants ¶
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 )
const ( // MaxEnvelopeBytes is the largest accepted persisted record. MaxEnvelopeBytes = envelopeHeaderBytes + envelopeNonceBytes + envelopeTagBytes + MaxValueBytes )
Variables ¶
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 = errors.New("credentialstore: unavailable") )
Functions ¶
func NamespacePhysicalName ¶ added in v0.0.22
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 ¶
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) 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
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 ¶
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.
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.
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
Delete conditionally removes an authenticated 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
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 ¶
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.
Source Files
¶
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. |