Help us shape the future of Go! Take the 2026 Go Developer Survey

credentials

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: AGPL-3.0 Imports: 47 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")
)
View Source 
var ErrDestinationUnapproved = errors.New("inference credential destination is not approved")

ErrDestinationUnapproved reports a request outside its credential grant.

View Source 
var ErrMaterialExpired = errors.New("credential material expired")

ErrMaterialExpired reports material outside its allowed validity period.

View Source 
var ErrRecoveryCredential = errors.New("stored credential cannot be verified for recovery")

ErrRecoveryCredential reports invalid stored identity, ciphertext, or secret fields. It deliberately omits credential values and decoder details.

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 InspectSelectionPolicyDirectory added in v1.3.0 

func InspectSelectionPolicyDirectory(ctx context.Context, path string, owner SelectionPolicyOwner) (resultErr error)

InspectSelectionPolicyDirectory validates retained inference policy without creating or changing files. It refuses pending publications. The caller must fence writers and verify the complete inventory. A valid directory does not authorize credentials, restore a replica, or approve admission.

func InspectSelectionPolicyPublications added in v1.3.0 

func InspectSelectionPolicyPublications(ctx context.Context, files map[string]productfiles.RetainedFile, read productfiles.RetainedRecordReader) ([]string, error)

InspectSelectionPolicyPublications selects verified staging evidence for inactive retention. The caller preserves selected bytes and validates the remaining policy through its owner. This check never accepts candidate policy or grants credential use.

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 MayRetainMaterial added in v1.3.0 

func MayRetainMaterial(err error) bool

MayRetainMaterial permits prior usable material only after a transient refresh failure. The caller must still enforce the material's expiry and revocation state.

func NewSourceError added in v1.0.2 

func NewSourceError(kind SourceErrorKind, backend ReferenceBackend) error

NewSourceError creates a secret-free typed source error.

func PrepareRecoveryReplay added in v1.3.0 

func PrepareRecoveryReplay(ctx context.Context, source RecoveryReader, encryption *EncryptionService, changes []RecoveryChange) ([]storage.CompareAndSwapMutation, error)

PrepareRecoveryReplay prepares typed credential changes while admission remains closed. The source must remain the immutable pre-step snapshot for every exact retry. Ciphertext stays encrypted. Grant lists and retained credential configuration remain complete.

func RecoveryMaterialSourceSHA256 added in v1.3.0 

func RecoveryMaterialSourceSHA256(source MaterialSource) (string, error)

RecoveryMaterialSourceSHA256 binds built-in source selections without resolving credentials. Custom sources require a separate owner recovery contract.

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.

func VerifyRecoveryRecord added in v1.3.0 

func VerifyRecoveryRecord(ctx context.Context, key string, data []byte, encryption *EncryptionService) (int, error)

VerifyRecoveryRecord validates one retained record and decrypts every credential. It does not consult the current catalog, reach providers, or grant permission.

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 Destination added in v1.3.0 

type Destination struct {
	Operation catalogs.ProviderOperation
	Method    string
	URL       string
	// PathTemplate permits named path variables in URL, such as {model}.
	// {name} matches one segment. {name...} also permits namespace segments.
	// Both forms reject traversal and URL delimiters.
	PathTemplate bool
}

Destination names one approved operation and HTTP request target. URL contains no credential value. Streaming targets require their own entries.

type DestinationApprovals added in v1.3.0 

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

DestinationApprovals holds one applied set of explicit credential grants. Its caller selects the authority. Catalog refresh must not construct approvals.

func NewDestinationApprovals added in v1.3.0 

func NewDestinationApprovals(grants []*DestinationGrant, policies ...*DestinationPolicy) (*DestinationApprovals, error)

NewDestinationApprovals rejects ambiguous grants for the same credential profile. An empty set denies all credential destinations.

func (*DestinationApprovals) Bind added in v1.3.0 

func (a *DestinationApprovals) Bind(provider catalogs.ProviderID, role string, material Material, operation catalogs.ProviderOperation) (Material, error)

Bind selects approval from the material's actual credential handle. It reads only the applied policy in memory.

func (*DestinationApprovals) RecoverySelectionSHA256 added in v1.3.0 

func (a *DestinationApprovals) RecoverySelectionSHA256() (string, error)

RecoverySelectionSHA256 binds applied grants, policies, and current revocation states. Nil retains the distinct installation-default selection.

type DestinationAuthorization added in v1.3.0 

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

DestinationAuthorization checks a request target before credential placement. Revocation invalidates all authorizations from the grant.

func (DestinationAuthorization) AfterPlacement added in v1.3.0 

func (a DestinationAuthorization) AfterPlacement(request *http.Request) (DestinationAuthorization, error)

AfterPlacement binds the final query after approved credential placement. Other target fields must remain unchanged.

func (*DestinationAuthorization) Check added in v1.3.0 

func (a *DestinationAuthorization) Check(request *http.Request) error

Check refuses revocation or a changed HTTP request target.

type DestinationGrant added in v1.3.0 

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

DestinationGrant retains an approved profile and request target rules. Catalog refresh cannot extend this immutable grant.

func NewDestinationGrant added in v1.3.0 

func NewDestinationGrant(identity DestinationIdentity, profile catalogs.ProviderCredentialProfile, destinations []Destination) (*DestinationGrant, error)

NewDestinationGrant validates an explicit approval without network access. The caller must receive approval before it constructs or replaces a grant.

func (*DestinationGrant) Authorize added in v1.3.0 

func (g *DestinationGrant) Authorize(identity DestinationIdentity, material Material, operation catalogs.ProviderOperation, request *http.Request) (DestinationAuthorization, error)

Authorize binds material to an approved operation and request target. It compares the complete profile before credential placement can occur.

func (*DestinationGrant) Revoke added in v1.3.0 

func (g *DestinationGrant) Revoke()

Revoke prevents new authorizations and invalidates existing request handles.

type DestinationIdentity added in v1.3.0 

type DestinationIdentity struct {
	Provider catalogs.ProviderID
	Role     string
	Handle   string
}

DestinationIdentity binds a grant to one provider, credential role, and handle. Keyring supplies the role. Handle must identify the credential without its value.

type DestinationPolicy added in v1.3.0 

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

DestinationPolicy approves a destination contract for one provider and credential role. Bind creates a handle-specific grant from the actual selected material. Account access and credential selection remain separate requirements.

func NewDestinationPolicy added in v1.3.0 

func NewDestinationPolicy(provider catalogs.ProviderID, role string, profile catalogs.ProviderCredentialProfile, destinations []Destination) (*DestinationPolicy, error)

NewDestinationPolicy validates an approved deployment contract without network access. The caller must approve its use for every credential handle in the selected role.

func (*DestinationPolicy) Revoke added in v1.3.0 

func (p *DestinationPolicy) Revoke()

Revoke invalidates this policy and every request grant derived from it.

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 EnvironmentPolicy added in v1.3.0 

type EnvironmentPolicy string

EnvironmentPolicy identifies a versioned inference credential selection order. 

const (
	// InferencePolicyLegacy preserves conventional-first selection for upgrade comparison.
	InferencePolicyLegacy EnvironmentPolicy = "starport-inference-v1"
	// InferencePolicyCurrent selects gateway names before conventional names.
	InferencePolicyCurrent EnvironmentPolicy = "starport-inference-v2"
)

type FileSelectionPolicyStore added in v1.3.0 

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

FileSelectionPolicyStore retains immutable default and accepted provider policies.

func OpenSelectionPolicyStore added in v1.3.0 

func OpenSelectionPolicyStore(ctx context.Context, path string, owner SelectionPolicyOwner, legacy bool) (*FileSelectionPolicyStore, error)

OpenSelectionPolicyStore opens private history without reading credential sources. A retained default overrides the installation hint.

func (*FileSelectionPolicyStore) Accept added in v1.3.0 

func (s *FileSelectionPolicyStore) Accept(ctx context.Context, provider catalogs.ProviderID) error

Accept records a provider decision without storing source names or material.

func (*FileSelectionPolicyStore) Policy added in v1.3.0 

func (s *FileSelectionPolicyStore) Policy(ctx context.Context, provider catalogs.ProviderID) (EnvironmentPolicy, error)

Policy reads the installation default and any accepted provider migration.

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) AuthorizeDestination added in v1.3.0 

func (m Material) AuthorizeDestination(request *http.Request) (DestinationAuthorization, error)

AuthorizeDestination refuses absent or mismatched destination approval.

func (Material) CheckValidity added in v1.3.0 

func (m Material) CheckValidity(now time.Time) error

CheckValidity checks both the source expiry and the managed deadline.

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) Handle added in v1.3.0 

func (m Material) Handle() string

Handle returns the source-owned credential identity without its value.

func (Material) HasDestinationGrant added in v1.3.0 

func (m Material) HasDestinationGrant() bool

HasDestinationGrant reports whether selection supplied a grant binding.

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) RecoverySelectionSHA256 added in v1.3.0 

func (m Material) RecoverySelectionSHA256() (string, error)

RecoverySelectionSHA256 binds private material without exporting credential values. The digest does not establish credential validity or authorize a destination.

func (Material) SecretBytes added in v1.3.0 

func (m Material) SecretBytes() int

SecretBytes reports the retained field-value bytes without exposing values.

func (Material) String added in v1.0.2 

func (m Material) String() string

String returns a secret-free material summary.

func (Material) Validity added in v1.3.0 

func (m Material) Validity() *MaterialValidity

Validity returns the material's revocation and deadline handle.

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.

func (Material) WithDestinationGrant added in v1.3.0 

func (m Material) WithDestinationGrant(grant *DestinationGrant, identity DestinationIdentity, operation catalogs.ProviderOperation) Material

WithDestinationGrant binds material to its selected approval and operation. A nil grant remains a bound refusal rather than unrestricted material.

func (Material) WithValidity added in v1.3.0 

func (m Material) WithValidity(validity *MaterialValidity) Material

WithValidity binds material to a request-validity handle.

type MaterialLimits added in v1.3.0 

type MaterialLimits struct {
	Entries               int
	SecretBytes           int
	ConcurrentLoads       int
	TenantConcurrentLoads int
	Validity              time.Duration
	LoadTimeout           time.Duration
	Idle                  time.Duration
	RefreshInterval       time.Duration
}

MaterialLimits bounds resident secrets and credential refresh work.

func DefaultMaterialLimits added in v1.3.0 

func DefaultMaterialLimits() MaterialLimits

DefaultMaterialLimits returns the initial managed credential profile.

func (MaterialLimits) Validate added in v1.3.0 

func (l MaterialLimits) Validate() error

Validate checks resource bounds and the maximum permission-validity window.

type MaterialMetadata added in v1.0.2 

type MaterialMetadata struct {
	Version   string
	Handle    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 MaterialValidity added in v1.3.0 

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

MaterialValidity binds an optional deadline to a shared revocation fence. Renewal does not extend the deadline of an existing request handle.

func NewMaterialValidity added in v1.3.0 

func NewMaterialValidity(deadline time.Time) *MaterialValidity

NewMaterialValidity starts a revocable credential generation. A zero deadline permits use until revocation.

func (*MaterialValidity) Check added in v1.3.0 

func (v *MaterialValidity) Check(now time.Time) error

Check rejects revoked or expired material without reading external state.

func (*MaterialValidity) Renew added in v1.3.0 

func (v *MaterialValidity) Renew(deadline time.Time) *MaterialValidity

Renew creates a new deadline under the same revocation fence.

func (*MaterialValidity) Revoke added in v1.3.0 

func (v *MaterialValidity) Revoke()

Revoke invalidates all handles in the credential generation.

type PolicyConflictError added in v1.3.0 

type PolicyConflictError struct {
	Provider catalogs.ProviderID
	Names    []string
}

PolicyConflictError refuses a changed deployment credential during migration. Names identify environment selections and never contain credential values.

func (*PolicyConflictError) Error added in v1.3.0 

func (e *PolicyConflictError) Error() string

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 material from memory without external reads. The background worker refreshes sources.

func (*ProviderHandle) Refresh added in v1.0.2 

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

Refresh resolves sources again. Success replaces cached material atomically. Terminal failures invalidate it. Transient failures retain usable prior material.

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 RecoveryChange added in v1.3.0 

type RecoveryChange struct {
	Scope          string          `json:"scope"`
	Provider       string          `json:"provider"`
	ExpectedSHA256 string          `json:"expected_sha256"`
	Next           *RecoveryRecord `json:"next"`
}

RecoveryChange names an exact expected record and a later record or deletion. An empty ExpectedSHA256 requires absence. A nil Next means explicit deletion.

type RecoveryReader added in v1.3.0 

type RecoveryReader interface {
	ReadCaptured(context.Context, string, int) (storage.TransferRecord, error)
}

RecoveryReader reads bounded immutable credential records with their original expiration. Replay preparation never changes the source or infers missing credential history.

type RecoveryRecord added in v1.3.0 

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

RecoveryRecord holds complete private permission evidence for operator recovery. JSON contains durable fields. Diagnostic formatting never exposes those fields.

func CaptureRecoveryRecord added in v1.3.0 

func CaptureRecoveryRecord(ctx context.Context, source RecoveryReader, scope, provider string, encryption *EncryptionService) (RecoveryRecord, error)

CaptureRecoveryRecord retains encrypted credential evidence without reaching a provider.

func (RecoveryRecord) Format added in v1.3.0 

func (RecoveryRecord) Format(state fmt.State, _ rune)

Format excludes private evidence from diagnostic formatting.

func (RecoveryRecord) GoString added in v1.3.0 

func (RecoveryRecord) GoString() string

GoString excludes private permission evidence from formatted diagnostics.

func (RecoveryRecord) MarshalJSON added in v1.3.0 

func (r RecoveryRecord) MarshalJSON() ([]byte, error)

MarshalJSON returns the complete retained durable record.

func (RecoveryRecord) SHA256 added in v1.3.0 

func (r RecoveryRecord) SHA256() string

SHA256 binds the complete record to an expected replay preimage.

func (RecoveryRecord) String added in v1.3.0 

func (RecoveryRecord) String() string

func (*RecoveryRecord) UnmarshalJSON added in v1.3.0 

func (r *RecoveryRecord) UnmarshalJSON(data []byte) error

UnmarshalJSON refuses unknown fields, unsupported schemas, and oversized records.

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) ForSelectionPolicy added in v1.3.0 

func (r *Resolver) ForSelectionPolicy(store SelectionPolicyStore, allowStarmap bool) *Resolver

ForSelectionPolicy creates a fresh resolver cache with the same source clients. Startup uses it before it exposes any provider material to request routing.

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 WithEnvironmentPolicy added in v1.3.0 

func WithEnvironmentPolicy(policy EnvironmentPolicy) ResolverOption

WithEnvironmentPolicy selects the order used by this resolver.

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.

func WithSelectionPolicyStore added in v1.3.0 

func WithSelectionPolicyStore(store SelectionPolicyStore) ResolverOption

WithSelectionPolicyStore requires migration checks before caching newly selected material.

func WithStarmapFallback added in v1.3.0 

func WithStarmapFallback(enabled bool) ResolverOption

WithStarmapFallback explicitly permits Starmap names after ordinary inference names.

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 SelectionPolicyOwner added in v1.3.0 

type SelectionPolicyOwner struct {
	Product    string `json:"product"`
	Deployment string `json:"deployment"`
	Instance   string `json:"instance"`
}

SelectionPolicyOwner binds inference policy history to one deployment instance.

type SelectionPolicyStore added in v1.3.0 

type SelectionPolicyStore interface {
	Policy(context.Context, catalogs.ProviderID) (EnvironmentPolicy, error)
	Accept(context.Context, catalogs.ProviderID) error
}

SelectionPolicyStore retains accepted policy versions without credential material.

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 the source refused access or authentication.
	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.