credentials

package
v1.2.1 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2026 License: AGPL-3.0 Imports: 39 Imported by: 0

Documentation

Overview

Package credentials owns encrypted provider credentials and their durable repository.

Index

Constants

View Source 
const (
	// ProviderCredentialStorageSchemaVersion identifies the only credential schema.
	ProviderCredentialStorageSchemaVersion = 1
	// ProviderCredentialStoragePrefix is the credential v1 namespace.
	ProviderCredentialStoragePrefix = "credentials:v1:"
)
View Source 
const (

	// DefaultDirectSecretRefreshInterval is the cache lifetime for a direct
	// secret source that does not publish its own expiry or lease.
	DefaultDirectSecretRefreshInterval = 5 * time.Minute
)
View Source 
const SharedScope = "*"

SharedScope is the scope of the credentials the operator shares with the deployment's accounts. Every other scope names one account.

Variables

View Source 
var (
	// ErrInvalidScope reports an invalid provider-credential owner scope.
	ErrInvalidScope = errors.New("invalid credential scope")
	// ErrInvalidProvider reports an empty provider identity.
	ErrInvalidProvider = errors.New("invalid provider")
	// ErrMissingCredential reports an empty encrypted credential value.
	ErrMissingCredential = errors.New("missing encrypted credential")
	// ErrInvalidAccess reports an unknown shared-credential access value.
	ErrInvalidAccess = errors.New("invalid shared credential access")
)
View Source 
var (
	// ErrRepositoryRequired reports an absent credential storage adapter.
	ErrRepositoryRequired = errors.New("credential storage is required")
	// ErrNotFound reports an absent provider credential.
	ErrNotFound = errors.New("provider credential not found")
	// ErrConflict reports a provider-credential revision conflict.
	ErrConflict = errors.New("provider credential revision conflict")
	// ErrCorruptRecord reports invalid durable credential data.
	ErrCorruptRecord = errors.New("provider credential record is invalid")
	// ErrIdentityImmutable reports an attempted scope or provider change.
	ErrIdentityImmutable = errors.New("provider credential identity is immutable")
)
View Source 
var (
	// ErrResolverRequired reports an absent inference credential resolver.
	ErrResolverRequired = errors.New("inference credential resolver is required")
	// ErrProviderContractRequired reports absent inference credential metadata.
	ErrProviderContractRequired = errors.New("provider inference credential contract is required")
	// ErrProviderNotConfigured reports a selected provider without complete material.
	ErrProviderNotConfigured = errors.New("provider inference credentials are not configured")
	// ErrMaterialRevoked reports material invalidated while source work was in flight.
	ErrMaterialRevoked = errors.New("provider inference credential material was revoked")
)

Functions

func DeriveKeyFromPassword 

func DeriveKeyFromPassword(password string) []byte

DeriveKeyFromPassword derives a master key from a password using Argon2

func GenerateMasterKey 

func GenerateMasterKey() ([]byte, error)

GenerateMasterKey generates a new random master key

func IsSourceError added in v1.0.2 

func IsSourceError(err error, kind SourceErrorKind) bool

IsSourceError reports whether an error has the requested source class.

func NewSourceError added in v1.0.2 

func NewSourceError(kind SourceErrorKind, backend ReferenceBackend) error

NewSourceError creates a secret-free typed source error.

func ScopePrefix 

func ScopePrefix(scope string) string

ScopePrefix returns the canonical scan prefix for one credential scope.

func StorageKey 

func StorageKey(scope, provider string) string

StorageKey returns the canonical key for one scoped provider credential.

Types

type Access added in v1.1.0 

type Access string

Access says who may spend one shared credential. 

const (
	// AccessOpen lets every account spend the credential.
	AccessOpen Access = "open"
	// AccessGranted restricts the credential to the accounts in its grant
	// list. An empty list is a credential granted to nobody yet, which is a
	// valid parked state, not an error.
	AccessGranted Access = "granted"
)

func ParseAccess added in v1.1.0 

func ParseAccess(value string) (Access, error)

ParseAccess validates one access value. An empty value selects the open default, because a credential an operator applies without saying otherwise is for every account.

type CloudChain added in v1.0.2 

type CloudChain interface {
	SuppliedFields(
		catalogs.ProviderCredentialProfile,
		map[catalogs.ProviderCredentialFieldID]catalogs.ProviderCredentialField,
	) ([]catalogs.ProviderCredentialFieldID, error)
	Resolve(
		context.Context,
		catalogs.ProviderCredentialProfile,
		map[catalogs.ProviderCredentialFieldID]catalogs.ProviderCredentialField,
	) (SourceMaterial, error)
}

CloudChain resolves one compiled default-identity primitive.

type CloudChainError added in v1.0.3 

type CloudChainError struct {
	Primitive catalogs.ProviderAuthenticationPrimitive
	Err       error
}

CloudChainError reports a provider-local default-identity failure without exposing credential material.

func (*CloudChainError) Error added in v1.0.3 

func (e *CloudChainError) Error() string

func (*CloudChainError) Unwrap added in v1.0.3 

func (e *CloudChainError) Unwrap() error

Unwrap preserves the primitive client error for internal classification.

type CloudChainFunc added in v1.0.2 

type CloudChainFunc struct {
	Fields func(
		catalogs.ProviderCredentialProfile,
		map[catalogs.ProviderCredentialFieldID]catalogs.ProviderCredentialField,
	) ([]catalogs.ProviderCredentialFieldID, error)
	ResolveFunc func(
		context.Context,
		catalogs.ProviderCredentialProfile,
		map[catalogs.ProviderCredentialFieldID]catalogs.ProviderCredentialField,
	) (SourceMaterial, error)
}

CloudChainFunc adapts functions to one default-identity primitive.

func (CloudChainFunc) Resolve added in v1.0.2 

func (f CloudChainFunc) Resolve(
	ctx context.Context,
	profile catalogs.ProviderCredentialProfile,
	fields map[catalogs.ProviderCredentialFieldID]catalogs.ProviderCredentialField,
) (SourceMaterial, error)

Resolve implements CloudChain.

func (CloudChainFunc) SuppliedFields added in v1.0.3 

func (f CloudChainFunc) SuppliedFields(
	profile catalogs.ProviderCredentialProfile,
	fields map[catalogs.ProviderCredentialFieldID]catalogs.ProviderCredentialField,
) ([]catalogs.ProviderCredentialFieldID, error)

SuppliedFields implements CloudChain.

type CredentialFieldKey added in v1.0.2 

type CredentialFieldKey struct {
	ProviderID catalogs.ProviderID
	FieldID    catalogs.ProviderCredentialFieldID
}

CredentialFieldKey identifies one provider field source policy.

type EncryptionService 

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

EncryptionService provides encryption and decryption for sensitive data

func NewEncryptionService 

func NewEncryptionService(masterKey []byte) (*EncryptionService, error)

NewEncryptionService creates a new encryption service with the provided master key

func (*EncryptionService) DecryptCredential 

func (s *EncryptionService) DecryptCredential(encrypted string) (string, error)

DecryptCredential decrypts a credential encrypted with EncryptCredential

func (*EncryptionService) EncryptCredential 

func (s *EncryptionService) EncryptCredential(plaintext string) (string, error)

EncryptCredential encrypts a credential using AES-256-GCM with Argon2 key derivation

type EnvironmentLookup added in v1.0.2 

type EnvironmentLookup func(string) (string, bool)

EnvironmentLookup reads one environment name without changing process state.

type Lease added in v1.0.2 

type Lease struct {
	Renewable    bool
	RefreshAfter time.Time
}

Lease describes renewable credential material.

type Material added in v1.0.2 

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

Material carries one selected inference profile and its resolved field values. The values are private so serializers and generic formatters cannot expose them.

func NewMaterial added in v1.0.2 

func NewMaterial(
	profile catalogs.ProviderCredentialProfile,
	values map[catalogs.ProviderCredentialFieldID]string,
	metadata MaterialMetadata,
) Material

NewMaterial creates caller-owned inference credential material.

func (Material) Empty added in v1.0.2 

func (m Material) Empty() bool

Empty reports whether the material contains no selected profile.

func (Material) EndpointBindings added in v1.0.2 

func (m Material) EndpointBindings() map[string]string

EndpointBindings returns validated URL-template bindings for the profile.

func (Material) ExpiresAt added in v1.0.2 

func (m Material) ExpiresAt() (time.Time, bool)

ExpiresAt returns the material expiry when a source supplied one.

func (Material) GoString added in v1.0.2 

func (m Material) GoString() string

GoString returns a secret-free Go-syntax material summary.

func (Material) Lease added in v1.0.2 

func (m Material) Lease() (Lease, bool)

Lease returns caller-owned renewable-material metadata when present.

func (Material) Profile added in v1.0.2 

func (m Material) Profile() catalogs.ProviderCredentialProfile

Profile returns a caller-owned copy of the selected profile.

func (Material) String added in v1.0.2 

func (m Material) String() string

String returns a secret-free material summary.

func (Material) Value added in v1.0.2 

func (m Material) Value(fieldID catalogs.ProviderCredentialFieldID) (string, bool)

Value returns one exact credential or parameter value.

func (Material) Version added in v1.0.2 

func (m Material) Version() string

Version returns the resolver-owned opaque material version.

type MaterialMetadata added in v1.0.2 

type MaterialMetadata struct {
	Version   string
	ExpiresAt time.Time
	Lease     *Lease
}

MaterialMetadata describes one resolved credential lifecycle. Version is opaque and contains no source path or credential value.

type MaterialSource added in v1.0.2 

type MaterialSource interface {
	ResolveMaterial(context.Context) (Material, error)
}

MaterialSource resolves one configured provider's inference material.

type ProviderHandle added in v1.0.2 

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

ProviderHandle binds one provider contract and its deployment-owned source policies to a shared resolver.

func (*ProviderHandle) CachedMaterial added in v1.0.3 

func (h *ProviderHandle) CachedMaterial(ctx context.Context) (Material, error)

CachedMaterial returns usable cached material without reading any external source. Material remains usable during its refresh window until its actual expiry.

func (*ProviderHandle) CachedSource added in v1.0.3 

func (h *ProviderHandle) CachedSource() MaterialSource

CachedSource returns a request-time source that performs no external I/O. Background reconciliation owns source refresh.

func (*ProviderHandle) Refresh added in v1.0.2 

func (h *ProviderHandle) Refresh(ctx context.Context) (Material, bool, error)

Refresh forces one source resolution and atomically replaces cached material only after success.

func (*ProviderHandle) Resolve added in v1.0.2 

func (h *ProviderHandle) Resolve(ctx context.Context) (Material, bool, error)

Resolve reports whether the provider has a configured inference profile.

func (*ProviderHandle) ResolveLocal added in v1.0.3 

func (h *ProviderHandle) ResolveLocal(ctx context.Context) (Material, bool, error)

ResolveLocal resolves environment references and catalog-declared ambient fields without contacting a remote secret source or cloud default chain.

func (*ProviderHandle) ResolveMaterial added in v1.0.2 

func (h *ProviderHandle) ResolveMaterial(ctx context.Context) (Material, error)

ResolveMaterial returns cached material when its lifecycle is fresh.

func (*ProviderHandle) Revoke added in v1.0.2 

func (h *ProviderHandle) Revoke() error

Revoke invalidates cached material. A resolution that was already in flight cannot repopulate the cache after this call. The next resolution must read the configured source again.

type ProviderKey 

type ProviderKey struct {
	Scope               string             `json:"scope"`
	Provider            string             `json:"provider"`
	EncryptedCredential string             `json:"encrypted_credential,omitempty"`
	Shared              []SharedCredential `json:"shared,omitempty"`
	Config              map[string]any     `json:"config,omitempty"`
	IsFallback          bool               `json:"is_fallback"`
	Priority            int                `json:"priority"`
	RateLimit           *RateLimitConfig   `json:"rate_limit,omitempty"`
	CreatedAt           time.Time          `json:"created_at"`
	LastUsed            *time.Time         `json:"last_used,omitempty"`
	UsageCount          int64              `json:"usage_count"`
	UpdatedAt           time.Time          `json:"updated_at"`
}

ProviderKey is one stored provider-credential record. At an account scope it holds that account's own encrypted credential. At SharedScope it holds the operator's list of shared credentials for the provider instead.

func (ProviderKey) IsShared added in v1.1.0 

func (k ProviderKey) IsShared() bool

IsShared reports whether this record holds the operator's shared credentials. A record at any other scope belongs to one account, which is the only kind this gateway calls BYOK.

func (ProviderKey) Validate 

func (k ProviderKey) Validate() error

Validate checks provider-credential invariants. The shared record and the account record carry different shapes, and each refuses the other's.

type RateLimitConfig 

type RateLimitConfig struct {
	RequestsPerMinute int `json:"requests_per_minute"`
	TokensPerMinute   int `json:"tokens_per_minute"`
}

RateLimitConfig defines optional provider-credential limits.

type Record 

type Record struct {
	Revision uint64
	Key      ProviderKey
}

Record is one versioned provider-credential repository value.

type Reference added in v1.0.2 

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

Reference identifies one operator-selected source without containing source authentication values.

func ParseReference added in v1.0.2 

func ParseReference(value string) (Reference, error)

ParseReference parses backend:resource?version=VERSION#field syntax.

func (Reference) Backend added in v1.0.2 

func (r Reference) Backend() ReferenceBackend

Backend returns the selected source primitive.

func (Reference) Field added in v1.0.2 

func (r Reference) Field() string

Field returns the selected structured-source field.

func (Reference) Resource added in v1.0.2 

func (r Reference) Resource() string

Resource returns the operator-selected source resource.

func (Reference) Version added in v1.0.2 

func (r Reference) Version() string

Version returns the selected source version.

type ReferenceBackend added in v1.0.2 

type ReferenceBackend string

ReferenceBackend identifies one credential source primitive. 

const (
	// ReferenceBackendEnvironment reads one exact environment variable.
	ReferenceBackendEnvironment ReferenceBackend = "env"
	// ReferenceBackendFile reads one exact local file.
	ReferenceBackendFile ReferenceBackend = "file"
	// ReferenceBackendGCPStore reads Google Cloud Secret Manager.
	ReferenceBackendGCPStore ReferenceBackend = "gcp-secret-manager"
	// ReferenceBackendAzureVault reads Azure Key Vault.
	ReferenceBackendAzureVault ReferenceBackend = "azure-key-vault"
	// ReferenceBackendAWSStore reads AWS Secrets Manager.
	ReferenceBackendAWSStore ReferenceBackend = "aws-secrets-manager"
	// ReferenceBackendVault reads HashiCorp Vault KV v2.
	ReferenceBackendVault ReferenceBackend = "vault"
	// ReferenceBackendOpenBao reads OpenBao KV v2.
	ReferenceBackendOpenBao ReferenceBackend = "openbao"
)

type ReferenceError added in v1.0.2 

type ReferenceError struct {
	Field   string
	Message string
}

ReferenceError reports an invalid source reference without its value.

func (*ReferenceError) Error added in v1.0.2 

func (e *ReferenceError) Error() string

type ReferencePolicy added in v1.0.2 

type ReferencePolicy struct {
	Reference       Reference
	FallbackAmbient bool
}

ReferencePolicy selects an explicit source and an optional not-configured fallback to ambient discovery.

type ReferenceSource added in v1.0.2 

type ReferenceSource interface {
	Backend() ReferenceBackend
	Resolve(context.Context, Reference) (SourceMaterial, error)
}

ReferenceSource resolves one explicit credential reference.

type Repository 

type Repository interface {
	Create(context.Context, ProviderKey) (Record, error)
	Get(context.Context, string, string) (Record, error)
	ListScope(context.Context, string, int) ([]Record, error)
	ListAll(context.Context, int) ([]Record, error)
	Update(context.Context, ProviderKey, uint64) (Record, error)
	Delete(context.Context, string, string, uint64) error
}

Repository is the durable provider-credential contract.

func Open 

func Open(store storage.KVStore) (Repository, error)

Open returns a storage-backed provider-credential repository.

type Resolver added in v1.0.2 

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

Resolver owns inference credential source selection, caching, refresh, and single-flight work. It contains no provider roster.

func NewResolver added in v1.0.2 

func NewResolver(options ...ResolverOption) *Resolver

NewResolver creates the built-in inference credential resolver.

func (*Resolver) Provider added in v1.0.2 

func (r *Resolver) Provider(
	provider catalogs.Provider,
	policies map[catalogs.ProviderCredentialFieldID]ReferencePolicy,
	forced bool,
) (*ProviderHandle, error)

Provider creates one validated inference credential handle.

type ResolverOption added in v1.0.2 

type ResolverOption func(*Resolver)

ResolverOption configures inference credential resolution.

func WithCloudChain added in v1.0.2 

func WithCloudChain(
	primitive catalogs.ProviderAuthenticationPrimitive,
	chain CloudChain,
) ResolverOption

WithCloudChain registers one typed default-identity primitive.

func WithDirectSecretRefreshInterval added in v1.0.2 

func WithDirectSecretRefreshInterval(interval time.Duration) ResolverOption

WithDirectSecretRefreshInterval sets the cache lifetime for direct secret sources that do not publish an expiry or renewable lease.

func WithEnvironmentLookup added in v1.0.2 

func WithEnvironmentLookup(lookup EnvironmentLookup) ResolverOption

WithEnvironmentLookup replaces process environment access.

func WithReferenceSource added in v1.0.2 

func WithReferenceSource(source ReferenceSource) ResolverOption

WithReferenceSource registers one typed explicit source primitive.

func WithResolverClock added in v1.0.2 

func WithResolverClock(now func() time.Time) ResolverOption

WithResolverClock replaces wall-clock access for lifecycle tests.

type SelectedValueError added in v1.0.2 

type SelectedValueError struct {
	Environment string
	ProviderID  catalogs.ProviderID
	FieldID     catalogs.ProviderCredentialFieldID
}

SelectedValueError reports a selected invalid ambient value without the value.

func (*SelectedValueError) Error added in v1.0.2 

func (e *SelectedValueError) Error() string

type SharedCredential added in v1.1.0 

type SharedCredential struct {
	ID                  string           `json:"id"`
	Label               string           `json:"label,omitempty"`
	EncryptedCredential string           `json:"encrypted_credential"`
	Config              map[string]any   `json:"config,omitempty"`
	RateLimit           *RateLimitConfig `json:"rate_limit,omitempty"`
	Access              Access           `json:"access"`
	Grants              []string         `json:"grants,omitempty"`
	CreatedAt           time.Time        `json:"created_at"`
	UpdatedAt           time.Time        `json:"updated_at"`
	LastUsed            *time.Time       `json:"last_used,omitempty"`
	UsageCount          int64            `json:"usage_count"`
}

SharedCredential is one of the operator's provider credentials at the shared scope. A provider holds a list of them, so an operator can run several keys for one provider and decide per key who may spend it.

func CloneSharedCredential added in v1.1.0 

func CloneSharedCredential(credential SharedCredential) SharedCredential

CloneSharedCredential returns a caller-owned copy of one shared credential, so a mutation on a returned value never reaches the stored record.

func (SharedCredential) Usable added in v1.1.0 

func (c SharedCredential) Usable(accountID string) bool

Usable reports whether the named account may spend this credential. An empty account is an anonymous caller, which only an open credential serves.

func (SharedCredential) Validate added in v1.1.0 

func (c SharedCredential) Validate() error

Validate checks shared-credential invariants.

type SourceError added in v1.0.2 

type SourceError struct {
	Kind    SourceErrorKind
	Backend ReferenceBackend
}

SourceError reports a typed source failure without resource or material.

func (*SourceError) Error added in v1.0.2 

func (e *SourceError) Error() string

type SourceErrorKind added in v1.0.2 

type SourceErrorKind string

SourceErrorKind classifies a secret-free credential source failure. 

const (
	// SourceErrorNotConfigured means that the selected source has no material.
	SourceErrorNotConfigured SourceErrorKind = "not_configured"
	// SourceErrorDenied means that source access or authentication was denied.
	SourceErrorDenied SourceErrorKind = "denied"
	// SourceErrorInvalid means that the source reference or material is invalid.
	SourceErrorInvalid SourceErrorKind = "invalid"
	// SourceErrorUnavailable means that a configured source could not complete.
	SourceErrorUnavailable SourceErrorKind = "unavailable"
)

type SourceMaterial added in v1.0.2 

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

SourceMaterial is one source result before profile assembly. Values and source versions stay private outside the credential package.

func NewSourceMaterial added in v1.0.2 

func NewSourceMaterial(
	values map[string]string,
	version string,
	expiresAt time.Time,
	lease *Lease,
) SourceMaterial

NewSourceMaterial creates a caller-owned source result.

func (SourceMaterial) GoString added in v1.0.2 

func (m SourceMaterial) GoString() string

GoString returns a secret-free Go-syntax source-material summary.

func (SourceMaterial) String added in v1.0.2 

func (m SourceMaterial) String() string

String returns a secret-free source-material summary.

func (SourceMaterial) Value added in v1.0.2 

func (m SourceMaterial) Value(field string) (string, bool)

Value returns one exact source field.

Source Files

View all Source files

Directories

Path Synopsis
Package cloudchain resolves renewable cloud credential material for inference.
 Package cloudchain resolves renewable cloud credential material for inference.

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.