credentials

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ScopeProcess            = SharingProcess
	ScopeHost               = SharingHost
	ScopeDistributed        = SharingDistributed
	SharingScopeProcess     = SharingProcess
	SharingScopeHost        = SharingHost
	SharingScopeDistributed = SharingDistributed
)

Descriptive aliases retain obvious names at call sites.

View Source 
const (
	MaxDescriptorLength           = 1024
	MaxDescriptorFieldLength      = 256
	MaxDescriptorIdentifierLength = 96
)
View Source 
const (
	FindingOrphan  = FindingOrphanState
	FindingMissing = FindingMissingState
)
View Source 
const (
	MaxReferenceLength          = 128
	MaxReferenceComponentLength = 48
)

Bounds apply before any canonicalization or allocation at an untrusted boundary. A credential reference is deliberately narrower than a general URL: exactly two safe identifier components are allowed.

View Source 
const (
	FailureAuthRejected Failure = "auth_rejected"
	FailureAuthExpired  Failure = "auth_expired"
	FailureAuthRevoked  Failure = "auth_revoked"

	// Short aliases keep call sites readable while retaining the explicit
	// authentication prefix in the canonical values.
	FailureRejected = FailureAuthRejected
	FailureExpired  = FailureAuthExpired
	FailureRevoked  = FailureAuthRevoked
)
View Source 
const MaxGenerationLength = 128
View Source 
const RecordSchemaV1 uint32 = 1

Variables

View Source 
var (
	ErrBuilderDependency   = errors.New("credentials: builder dependency unavailable")
	ErrFactoryUnsupported  = errors.New("credentials: no exact credential factory")
	ErrFactoryMismatch     = errors.New("credentials: credential factory identity mismatch")
	ErrFactoryConstruction = errors.New("credentials: credential factory construction failed")
	ErrRefreshScope        = errors.New("credentials: refresh coordinator scope too weak")
	ErrStateNamespace      = errors.New("credentials: invalid credential state namespace")
	ErrBuilderRecord       = errors.New("credentials: invalid builder record")
)
View Source 
var (
	ErrCatalogCorrupt           = errors.New("credentials: corrupt catalog")
	ErrCatalogConflict          = errors.New("credentials: catalog conflict")
	ErrCatalogNotFound          = errors.New("credentials: catalog record not found")
	ErrCatalogUnavailable       = errors.New("credentials: catalog unavailable")
	ErrCatalogCanceled          = errors.New("credentials: catalog operation canceled")
	ErrCatalogDurabilityUnknown = errors.New("credentials: catalog visible commit durability unknown")
	ErrCatalogUnsupported       = errors.New("credentials: catalog unsupported platform")
	ErrCatalogInvalidRecord     = errors.New("credentials: invalid catalog record")
	ErrCatalogInvalidDependency = errors.New("credentials: invalid catalog dependency")
	// InsecurePath is an alias of corruption for callers that distinguish the
	// filesystem boundary while retaining one fail-closed category.
	ErrCatalogInsecurePath             = ErrCatalogCorrupt
	ErrCatalogUnsupportedPlatform      = ErrCatalogUnsupported
	ErrCatalogVisibleDurabilityUnknown = ErrCatalogDurabilityUnknown
	ErrCatalogUnknownSchema            = ErrCatalogCorrupt
	ErrCatalogDuplicate                = ErrCatalogConflict
)
View Source 
var (
	ErrInvalidReference  = errors.New("credentials: invalid reference")
	ErrInvalidDescriptor = errors.New("credentials: invalid descriptor")
	ErrInvalidGeneration = errors.New("credentials: invalid generation")
	ErrInvalidFailure    = errors.New("credentials: invalid failure")
	ErrInvalidRecord     = errors.New("credentials: invalid record")
	ErrInvalidScheme     = errors.New("credentials: invalid scheme")
	ErrInvalidUsage      = errors.New("credentials: invalid usage class")
	ErrSourceClosed      = errors.New("credentials: source closed")
	ErrClosed            = ErrSourceClosed
	ErrNilContext        = errors.New("credentials: nil context")
	ErrCanceled          = errors.New("credentials: operation canceled")
)

Package errors intentionally expose only closed, package-owned categories. None of the typed errors retain caller strings, provider responses, or wrapped provider causes: those values may contain credential material.

View Source 
var (
	ErrOrphanState            = errors.New("credentials: orphan secret state")
	ErrStateDeleteFailed      = errors.New("credentials: state deletion failed")
	ErrStateUnavailable       = errors.New("credentials: state operation unavailable")
	ErrStateDurabilityUnknown = errors.New("credentials: state visible commit durability unknown")
)

Functions

func CatalogTimeValid 

func CatalogTimeValid(value time.Time) bool

CatalogTimeValid is kept small and explicit for callers constructing records without depending on a particular clock implementation.

func CreateCredentialState 

func CreateCredentialState(ctx context.Context, catalog Catalog, store secrets.Store, namespace secrets.Namespace, record Record, value secrets.Secret) error

CreateCredentialState is a convenient explicit free-function seam.

func DeleteCredentialState 

func DeleteCredentialState(ctx context.Context, catalog Catalog, store secrets.Store, namespace secrets.Namespace, record Record) error

DeleteCredentialState is the free-function deletion seam.

func NewCatalogCanceledError 

func NewCatalogCanceledError(cause ...error) error

func NewCatalogConflictError 

func NewCatalogConflictError(ref Reference) error

NewCatalogConflictError returns a bounded compare-and-swap/duplicate error.

func NewCatalogCorruptError 

func NewCatalogCorruptError() error

func NewCatalogDurabilityUnknownError 

func NewCatalogDurabilityUnknownError(ref Reference) error

NewCatalogDurabilityUnknownError returns a visible-commit durability error.

func NewCatalogNotFoundError 

func NewCatalogNotFoundError(ref Reference) error

NewCatalogNotFoundError returns a bounded not-found error for a validated reference. It is primarily useful to catalog implementations in subpackages.

func NewCatalogUnavailableError 

func NewCatalogUnavailableError() error

func NewCatalogUnsupportedError 

func NewCatalogUnsupportedError() error

func PublishState 

func PublishState(ctx context.Context, publisher StatePublisher, record Record, value secrets.Secret) error

PublishState is a descriptive alias for StatePublisher.Create.

func ValidateRecord 

func ValidateRecord(record Record) error

ValidateRecord is the public safe-record validation seam used by catalog implementations. Record validation never inspects or resolves secret state.

Types

type Builder 

type Builder struct {
	Catalog        Catalog
	Resolver       secrets.Resolver
	Store          secrets.Store
	Preconditions  secrets.PreconditionCapabilities
	StateIndex     secrets.Lister
	StateNamespace secrets.Namespace
	RefreshLocks   RefreshCoordinator
	StateSharing   SharingScope
	HTTPClient     *http.Client
	Clock          Clock
	Callback       CallbackListener
	Providers      ProviderFactories
}

Builder constructs one explicit source from one catalog reference. All dependencies are injected; no environment, home directory, browser, or mutable package registry is consulted.

func (*Builder) Build 

func (b *Builder) Build(ctx context.Context, ref Reference) (Source, error)

Build resolves exactly ref and invokes exactly one complete-binding factory.

func (*Builder) Create 

func (b *Builder) Create(ctx context.Context, record Record, value secrets.Secret) error

Create and Delete on Builder use its explicit catalog/store dependencies and preserve the same ordering as StatePublisher.

func (*Builder) Delete 

func (b *Builder) Delete(ctx context.Context, record Record) error

func (*Builder) Reconcile 

func (b *Builder) Reconcile(ctx context.Context) ([]Finding, error)

Reconcile uses a Builder's explicit catalog, state lister, and namespace.

type CallbackListener 

type CallbackListener interface{}

CallbackListener is an intentionally opaque seam owned by provider OAuth implementations. The base builder does not invoke it or infer a browser.

type CanceledError 

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

CanceledError reports context cancellation without retaining the context or its implementation details.

func NewCanceledError 

func NewCanceledError(cause error) *CanceledError

NewCanceledError returns a closed cancellation classification retaining only whether the operation was canceled or exceeded its deadline.

func (*CanceledError) Error 

func (e *CanceledError) Error() string

func (*CanceledError) Format 

func (e *CanceledError) Format(state fmt.State, _ rune)

func (*CanceledError) GoString 

func (e *CanceledError) GoString() string

func (*CanceledError) Is 

func (e *CanceledError) Is(target error) bool

func (*CanceledError) LogValue 

func (e *CanceledError) LogValue() slog.Value

func (*CanceledError) Unwrap 

func (e *CanceledError) Unwrap() error

type Catalog 

type Catalog interface {
	Get(context.Context, Reference) (Record, error)
	List(context.Context) ([]Record, error)
	Create(context.Context, Record) error
	Delete(context.Context, Reference) error
}

Catalog is the safe, secret-free index of configured credential identities. Implementations must validate the complete on-disk/in-memory collection before returning a result: a duplicate reference or unknown schema is a fail-closed error, never a best-effort partial result.

type CatalogCAS 

type CatalogCAS interface {
	Catalog
	Update(context.Context, Record, Record) error
}

CatalogCAS is an optional capability for explicit reauthentication of an existing reference. Implementations must compare the complete expected record before replacing it; callers must never use it as an unconditional update primitive.

type CatalogDurabilityUnknownError 

type CatalogDurabilityUnknownError = CatalogError

CatalogDurabilityUnknownError reports a visible catalog mutation whose directory durability could not be confirmed. Callers must reread and adopt the visible result; they must not assume the previous catalog survived.

type CatalogError 

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

CatalogError contains only package-owned classification and, where applicable, the already-validated safe credential reference.

func (*CatalogError) Error 

func (e *CatalogError) Error() string

func (*CatalogError) Format 

func (e *CatalogError) Format(state fmt.State, _ rune)

func (*CatalogError) GoString 

func (e *CatalogError) GoString() string

func (*CatalogError) Is 

func (e *CatalogError) Is(target error) bool

func (*CatalogError) LogValue 

func (e *CatalogError) LogValue() slog.Value

func (*CatalogError) Reference 

func (e *CatalogError) Reference() Reference

func (*CatalogError) Unwrap 

func (e *CatalogError) Unwrap() error

func (*CatalogError) Visible 

func (e *CatalogError) Visible() bool

type Clock 

type Clock interface{ Now() time.Time }

Clock is an injected time source for provider factories. Builder itself does not use ambient time; the interface exists to keep construction explicit.

type ClockFunc 

type ClockFunc func() time.Time

func (ClockFunc) Now 

func (f ClockFunc) Now() time.Time

type Descriptor 

type Descriptor struct {
	Provider  string
	Transport string
	Scheme    Scheme
	Usage     UsageClass
	Issuer    string
	Audience  string
	Label     string
}

Descriptor is a bounded, secret-free binding between a source and the exact provider transport it may authorize. Authenticated bindings require non-empty issuer and audience values; the explicit none/local binding is the only unauthenticated exception and requires both values to be empty.

func NewDescriptor 

func NewDescriptor(provider, transport string, scheme Scheme, usage UsageClass, issuer, audience, label string) (Descriptor, error)

NewDescriptor validates and canonicalizes a descriptor. Provider and transport identifiers are lower-case; safe textual identity fields are trimmed but retain case because URI and audience paths can be case-sensitive.

func (Descriptor) Binding 

func (d Descriptor) Binding() DescriptorBinding

Binding returns the factory-selection tuple for d.

func (Descriptor) BindingCanonical 

func (d Descriptor) BindingCanonical() string

BindingCanonical is stable and excludes presentation label.

func (Descriptor) Canonical 

func (d Descriptor) Canonical() string

Canonical returns a stable, bounded key for exact descriptor matching. The separator is package-owned and cannot appear in any safe field.

func (Descriptor) Format 

func (d Descriptor) Format(state fmt.State, _ rune)

func (Descriptor) GoString 

func (d Descriptor) GoString() string

func (Descriptor) LogValue 

func (d Descriptor) LogValue() slog.Value

func (Descriptor) String 

func (d Descriptor) String() string

func (Descriptor) Valid 

func (d Descriptor) Valid() bool

func (Descriptor) Validate 

func (d Descriptor) Validate() error

Validate verifies that an exported descriptor value is one that a constructor could have produced. It never mutates the receiver.

type DescriptorBinding 

type DescriptorBinding struct {
	Provider  string
	Transport string
	Scheme    Scheme
	Usage     UsageClass
	Issuer    string
	Audience  string
}

DescriptorBinding is the complete authority binding used for factory selection. Label is deliberately omitted because it is presentation only.

func DescriptorBindingOf 

func DescriptorBindingOf(descriptor Descriptor) DescriptorBinding

func StableBindings 

func StableBindings(factories ProviderFactories) []DescriptorBinding

StableBindings returns the factory bindings in deterministic order for diagnostics and tests. It does not expose factories or mutable state.

func (DescriptorBinding) Canonical 

func (b DescriptorBinding) Canonical() string

func (DescriptorBinding) Valid 

func (b DescriptorBinding) Valid() bool

type FactoryInput 

type FactoryInput struct {
	Record             Record
	Reference          Reference
	Descriptor         Descriptor
	State              secrets.Reference
	Resolver           secrets.Resolver
	Store              secrets.Store
	Preconditions      secrets.PreconditionCapabilities
	StateIndex         secrets.Lister
	StateNamespace     secrets.Namespace
	RefreshCoordinator RefreshCoordinator
	StateSharing       SharingScope
	HTTPClient         *http.Client
	Clock              Clock
	Callback           CallbackListener
}

FactoryInput is the complete explicit construction context. It contains a safe catalog record and opaque state capabilities, never secret bytes.

type Failure 

type Failure string

Failure is a closed authentication-failure classification. Provider bodies, account details, and status text are intentionally not representable.

func NewFailure 

func NewFailure(value Failure) (Failure, error)

func (Failure) Format 

func (f Failure) Format(state fmt.State, _ rune)

func (Failure) GoString 

func (f Failure) GoString() string

func (Failure) IsZero 

func (f Failure) IsZero() bool

func (Failure) LogValue 

func (f Failure) LogValue() slog.Value

func (Failure) MarshalText 

func (f Failure) MarshalText() ([]byte, error)

func (Failure) String 

func (f Failure) String() string

func (*Failure) UnmarshalText 

func (f *Failure) UnmarshalText(text []byte) error

func (Failure) Valid 

func (f Failure) Valid() bool

func (Failure) Validate 

func (f Failure) Validate() error

type FailureClass 

type FailureClass = Failure

FailureClass is an alias for integrations that use “class” terminology.

type Finding 

type Finding = ReconcileFinding

Finding is the concise public name for ReconcileFinding.

func Reconcile 

func Reconcile(ctx context.Context, catalog Catalog, states secrets.Lister, namespace secrets.Namespace) ([]Finding, error)

Reconcile compares the complete safe catalog list to metadata-only state listing constrained to namespace. It never adopts, deletes, or mutates either backend. Findings are grouped by kind and sorted by canonical state reference for stable diagnostics.

type FindingKind 

type FindingKind uint8

FindingKind identifies a report-only state/catalog discrepancy. 

const (
	FindingOrphanState FindingKind = iota + 1
	FindingMissingState
)

func (FindingKind) String 

func (k FindingKind) String() string

type Generation 

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

Generation is an opaque, comparable source-issued value. Its safe text representation is bounded and cannot contain arbitrary provider material. The representation is private so callers must use NewGeneration instead of converting arbitrary strings into source generations.

func NewGeneration 

func NewGeneration(value string) (Generation, error)

func (Generation) Format 

func (g Generation) Format(state fmt.State, _ rune)

func (Generation) GoString 

func (g Generation) GoString() string

func (Generation) IsZero 

func (g Generation) IsZero() bool

func (Generation) LogValue 

func (g Generation) LogValue() slog.Value

func (Generation) MarshalText 

func (g Generation) MarshalText() ([]byte, error)

func (Generation) String 

func (g Generation) String() string

func (*Generation) UnmarshalText 

func (g *Generation) UnmarshalText(text []byte) error

func (Generation) Valid 

func (g Generation) Valid() bool

func (Generation) Validate 

func (g Generation) Validate() error

type InvalidDescriptorError 

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

InvalidDescriptorError reports an invalid binding descriptor.

func NewInvalidDescriptorError 

func NewInvalidDescriptorError(value string) *InvalidDescriptorError

func (*InvalidDescriptorError) Error 

func (e *InvalidDescriptorError) Error() string

func (*InvalidDescriptorError) Format 

func (e *InvalidDescriptorError) Format(state fmt.State, _ rune)

func (*InvalidDescriptorError) GoString 

func (e *InvalidDescriptorError) GoString() string

func (*InvalidDescriptorError) LogValue 

func (e *InvalidDescriptorError) LogValue() slog.Value

func (*InvalidDescriptorError) Reason 

func (e *InvalidDescriptorError) Reason() string

func (*InvalidDescriptorError) Unwrap 

func (e *InvalidDescriptorError) Unwrap() []error

type InvalidFailureError 

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

InvalidFailureError reports an unknown or empty failure classification.

func NewInvalidFailureError 

func NewInvalidFailureError(value string) *InvalidFailureError

func (*InvalidFailureError) Error 

func (e *InvalidFailureError) Error() string

func (*InvalidFailureError) Format 

func (e *InvalidFailureError) Format(state fmt.State, _ rune)

func (*InvalidFailureError) GoString 

func (e *InvalidFailureError) GoString() string

func (*InvalidFailureError) LogValue 

func (e *InvalidFailureError) LogValue() slog.Value

func (*InvalidFailureError) Reason 

func (e *InvalidFailureError) Reason() string

func (*InvalidFailureError) Unwrap 

func (e *InvalidFailureError) Unwrap() error

type InvalidGenerationError 

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

InvalidGenerationError reports an invalid source generation.

func NewInvalidGenerationError 

func NewInvalidGenerationError(value string) *InvalidGenerationError

func (*InvalidGenerationError) Error 

func (e *InvalidGenerationError) Error() string

func (*InvalidGenerationError) Format 

func (e *InvalidGenerationError) Format(state fmt.State, _ rune)

func (*InvalidGenerationError) GoString 

func (e *InvalidGenerationError) GoString() string

func (*InvalidGenerationError) LogValue 

func (e *InvalidGenerationError) LogValue() slog.Value

func (*InvalidGenerationError) Reason 

func (e *InvalidGenerationError) Reason() string

func (*InvalidGenerationError) Unwrap 

func (e *InvalidGenerationError) Unwrap() error

type InvalidRecordError 

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

InvalidRecordError reports an invalid safe catalog record.

func NewInvalidRecordError 

func NewInvalidRecordError(value string) *InvalidRecordError

func (*InvalidRecordError) Error 

func (e *InvalidRecordError) Error() string

func (*InvalidRecordError) Format 

func (e *InvalidRecordError) Format(state fmt.State, _ rune)

func (*InvalidRecordError) GoString 

func (e *InvalidRecordError) GoString() string

func (*InvalidRecordError) LogValue 

func (e *InvalidRecordError) LogValue() slog.Value

func (*InvalidRecordError) Reason 

func (e *InvalidRecordError) Reason() string

func (*InvalidRecordError) Unwrap 

func (e *InvalidRecordError) Unwrap() error

type InvalidReferenceError 

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

InvalidReferenceError reports malformed reference text without retaining that text.

func NewInvalidReferenceError 

func NewInvalidReferenceError(value string) *InvalidReferenceError

func (*InvalidReferenceError) Error 

func (e *InvalidReferenceError) Error() string

func (*InvalidReferenceError) Format 

func (e *InvalidReferenceError) Format(state fmt.State, _ rune)

func (*InvalidReferenceError) GoString 

func (e *InvalidReferenceError) GoString() string

func (*InvalidReferenceError) LogValue 

func (e *InvalidReferenceError) LogValue() slog.Value

func (*InvalidReferenceError) Reason 

func (e *InvalidReferenceError) Reason() string

func (*InvalidReferenceError) Unwrap 

func (e *InvalidReferenceError) Unwrap() error

type Lease 

type Lease interface {
	Generation() Generation
	Descriptor() Descriptor
	ExpiresAt() time.Time
	Authorizer() httpauth.Authorizer
}

Lease is an immutable, concurrency-safe snapshot of usable authority.

type NilContextError 

type NilContextError struct{}

NilContextError reports a nil context passed to a public operation.

func (*NilContextError) Error 

func (e *NilContextError) Error() string

func (*NilContextError) Format 

func (e *NilContextError) Format(state fmt.State, _ rune)

func (*NilContextError) GoString 

func (e *NilContextError) GoString() string

func (*NilContextError) LogValue 

func (e *NilContextError) LogValue() slog.Value

func (*NilContextError) Unwrap 

func (e *NilContextError) Unwrap() error

type NoneSource 

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

NoneSource is the explicit local unauthenticated source. It has no credential reference, never expires, never refreshes, and returns only the no-op authorizer. Close is linearized under mu and is idempotent.

func NewNoneSource 

func NewNoneSource(descriptor Descriptor) (*NoneSource, error)

NewNoneSource constructs the only source permitted to have a zero credential Reference. The descriptor must still identify an exact local transport and use SchemeNone/UsageLocal.

func (*NoneSource) Acquire 

func (s *NoneSource) Acquire(ctx context.Context) (Lease, error)

func (*NoneSource) Close 

func (s *NoneSource) Close() error

func (*NoneSource) Descriptor 

func (s *NoneSource) Descriptor() Descriptor

func (*NoneSource) Format 

func (s *NoneSource) Format(state fmt.State, _ rune)

func (*NoneSource) GoString 

func (s *NoneSource) GoString() string

func (*NoneSource) Invalidate 

func (s *NoneSource) Invalidate(ctx context.Context, generation Generation, failure Failure) error

func (*NoneSource) LogValue 

func (s *NoneSource) LogValue() slog.Value

func (*NoneSource) Reference 

func (s *NoneSource) Reference() Reference

func (*NoneSource) String 

func (s *NoneSource) String() string

type OrphanState 

type OrphanState struct {
	Credential Reference
	State      secrets.Reference
	Version    secrets.Version
}

OrphanState identifies one exact opaque state version that could not be cleaned up after catalog publication failed. It intentionally contains no secret value or provider response.

func (OrphanState) Error 

func (o OrphanState) Error() string

func (OrphanState) Format 

func (o OrphanState) Format(state fmt.State, _ rune)

func (OrphanState) GoString 

func (o OrphanState) GoString() string

func (OrphanState) LogValue 

func (o OrphanState) LogValue() slog.Value

func (OrphanState) Unwrap 

func (o OrphanState) Unwrap() error

func (OrphanState) Valid 

func (o OrphanState) Valid() bool

type ProviderFactories 

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

ProviderFactories is an immutable copied factory registry. It is keyed by the complete descriptor binding, not by provider or a presentation label. The backing map is private; callers can only obtain copied snapshots.

func NewProviderFactories 

func NewProviderFactories(input map[DescriptorBinding]SourceFactory) ProviderFactories

NewProviderFactories copies an input map so later caller mutation cannot affect an active Builder.

func (ProviderFactories) List 

func (p ProviderFactories) List() []DescriptorBinding

List returns all registered bindings in deterministic canonical order.

func (ProviderFactories) Lookup 

func (p ProviderFactories) Lookup(binding DescriptorBinding) (SourceFactory, bool)

Lookup returns the factory for one exact descriptor binding.

func (ProviderFactories) Snapshot 

func (p ProviderFactories) Snapshot() map[DescriptorBinding]SourceFactory

Snapshot returns a mutable copy that cannot alter this registry.

type ReconcileFinding 

type ReconcileFinding struct {
	Kind       FindingKind
	State      secrets.Reference
	Reference  secrets.Reference // alias for callers that emphasize state ref
	Credential Reference
}

ReconcileFinding is metadata only. State is the opaque secret-store reference; Credential identifies a safe catalog record for missing-state findings. No secret values or provider responses can be represented.

type Record 

type Record struct {
	Schema     uint32
	Reference  Reference
	Descriptor Descriptor
	State      secrets.Reference
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

Record is the safe catalog metadata for one credential. Sensitive state is held only by the referenced secrets record.

func NewRecord 

func NewRecord(reference Reference, descriptor Descriptor, state secrets.Reference, createdAt, updatedAt time.Time) (Record, error)

func (Record) Format 

func (r Record) Format(state fmt.State, _ rune)

func (Record) GoString 

func (r Record) GoString() string

func (Record) LogValue 

func (r Record) LogValue() slog.Value

func (Record) String 

func (r Record) String() string

func (Record) Validate 

func (r Record) Validate() error

type Reference 

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

Reference is an opaque, comparable credential identity. Its fields are private so a valid value can only be obtained through a constructor or text parser. It contains no authority, URL, filesystem path, or secret value.

func NewReference 

func NewReference(provider, name string) (Reference, error)

NewReference constructs an opaque credential identity from safe provider and name components.

func ParseReference 

func ParseReference(raw string) (Reference, error)

ParseReference parses exactly credential://provider/name. The scheme and identifier components are canonicalized to lower case; no query, fragment, URL authority, path traversal, or additional path segment is accepted.

func (Reference) Canonical 

func (r Reference) Canonical() string

func (Reference) Format 

func (r Reference) Format(state fmt.State, _ rune)

func (Reference) GoString 

func (r Reference) GoString() string

func (Reference) IsZero 

func (r Reference) IsZero() bool

func (Reference) LogValue 

func (r Reference) LogValue() slog.Value

func (Reference) MarshalText 

func (r Reference) MarshalText() ([]byte, error)

func (Reference) Name 

func (r Reference) Name() string

Name returns the safe human-selected credential name component.

func (Reference) Provider 

func (r Reference) Provider() string

Provider returns the safe provider component.

func (Reference) Scheme 

func (r Reference) Scheme() string

Scheme returns the fixed credential scheme.

func (Reference) String 

func (r Reference) String() string

String returns the canonical safe representation, or an empty string for the invalid zero value.

func (*Reference) UnmarshalText 

func (r *Reference) UnmarshalText(text []byte) error

func (Reference) Valid 

func (r Reference) Valid() bool

func (Reference) Validate 

func (r Reference) Validate() error

type RefreshCoordinator 

type RefreshCoordinator interface {
	Scope() SharingScope
	WithLock(context.Context, Reference, func(context.Context) error) error
}

RefreshCoordinator provides context-aware exclusion around one refresh or state rotation. Implementations own any lock lifetime and must invoke fn while exclusion is held.

type Scheme 

type Scheme string

Scheme describes the mechanism that establishes outbound authority. 

const (
	SchemeNone             Scheme = "none"
	SchemeAPIKey           Scheme = "api_key"
	SchemeOAuth            Scheme = "oauth"
	SchemeSigV4            Scheme = "sigv4"
	SchemeWorkloadIdentity Scheme = "workload_identity"
)

func (Scheme) Format 

func (s Scheme) Format(state fmt.State, _ rune)

func (Scheme) GoString 

func (s Scheme) GoString() string

func (Scheme) IsZero 

func (s Scheme) IsZero() bool

func (Scheme) LogValue 

func (s Scheme) LogValue() slog.Value

func (Scheme) String 

func (s Scheme) String() string

func (Scheme) Valid 

func (s Scheme) Valid() bool

type SharingScope 

type SharingScope uint8

SharingScope describes the widest visibility for state coordination. The values are ordered so a coordinator can be checked against the configured state store without relying on provider-specific knowledge. 

const (
	SharingProcess SharingScope = iota + 1
	SharingHost
	SharingDistributed
)

func (SharingScope) AtLeast 

func (s SharingScope) AtLeast(required SharingScope) bool

func (SharingScope) String 

func (s SharingScope) String() string

func (SharingScope) Valid 

func (s SharingScope) Valid() bool

type Source 

type Source interface {
	Reference() Reference
	Descriptor() Descriptor
	Acquire(context.Context) (Lease, error)
	Invalidate(context.Context, Generation, Failure) error
	Close() error
}

Source owns acquisition and invalidation for one explicit identity.

type SourceClosedError 

type SourceClosedError struct{}

SourceClosedError reports an operation that began after Close linearized.

func (*SourceClosedError) Error 

func (e *SourceClosedError) Error() string

func (*SourceClosedError) Format 

func (e *SourceClosedError) Format(state fmt.State, _ rune)

func (*SourceClosedError) GoString 

func (e *SourceClosedError) GoString() string

func (*SourceClosedError) LogValue 

func (e *SourceClosedError) LogValue() slog.Value

func (*SourceClosedError) Unwrap 

func (e *SourceClosedError) Unwrap() error

type SourceFactory 

type SourceFactory func(context.Context, FactoryInput) (Source, error)

SourceFactory constructs exactly one source for one already-validated catalog record.

type StateDeletionError 

type StateDeletionError struct {
	Credential Reference
	State      secrets.Reference
	// contains filtered or unexported fields
}

StateDeletionError reports that the catalog was made unavailable but exact state deletion did not complete. The state reference is safe metadata only.

func (*StateDeletionError) Error 

func (e *StateDeletionError) Error() string

func (*StateDeletionError) Format 

func (e *StateDeletionError) Format(state fmt.State, _ rune)

func (*StateDeletionError) GoString 

func (e *StateDeletionError) GoString() string

func (*StateDeletionError) LogValue 

func (e *StateDeletionError) LogValue() slog.Value

func (*StateDeletionError) Unwrap 

func (e *StateDeletionError) Unwrap() []error

type StatePublicationError 

type StatePublicationError struct {
	Orphan *OrphanState
	// contains filtered or unexported fields
}

StatePublicationError reports catalog publication failure and whether exact state cleanup left a detectable orphan. Causes are normalized privately and exposed only through errors.Is.

func (*StatePublicationError) Error 

func (e *StatePublicationError) Error() string

func (*StatePublicationError) Format 

func (e *StatePublicationError) Format(state fmt.State, _ rune)

func (*StatePublicationError) GoString 

func (e *StatePublicationError) GoString() string

func (*StatePublicationError) LogValue 

func (e *StatePublicationError) LogValue() slog.Value

func (*StatePublicationError) Orphaned 

func (e *StatePublicationError) Orphaned() bool

func (*StatePublicationError) Unwrap 

func (e *StatePublicationError) Unwrap() []error

type StatePublisher 

type StatePublisher struct {
	Catalog       Catalog
	Store         secrets.Store
	Preconditions secrets.PreconditionCapabilities
	Namespace     secrets.Namespace
}

StatePublisher composes the two independent stores with explicit ordering. It is intentionally small: OAuth/reauthentication algorithms belong to refreshable sources, not this persistence seam.

func (StatePublisher) Create 

func (p StatePublisher) Create(ctx context.Context, record Record, value secrets.Secret) error

Create writes opaque state with create-only semantics before publishing the safe catalog record. A visible state warning is adopted using the returned committed record; a visible catalog warning is never rolled back.

func (StatePublisher) Delete 

func (p StatePublisher) Delete(ctx context.Context, supplied Record) error

Delete removes a credential in the required order: it uses only the caller's reference, rereads the current catalog record, resolves that exact state version, makes the catalog unavailable, then CAS-deletes that version.

type UsageClass 

type UsageClass string

UsageClass describes how use of a credential is accounted for independently of the authority mechanism. 

const (
	UsageLocal        UsageClass = "local"
	UsageMeteredAPI   UsageClass = "metered_api"
	UsageSubscription UsageClass = "subscription"
)

func (UsageClass) Format 

func (u UsageClass) Format(state fmt.State, _ rune)

func (UsageClass) GoString 

func (u UsageClass) GoString() string

func (UsageClass) IsZero 

func (u UsageClass) IsZero() bool

func (UsageClass) LogValue 

func (u UsageClass) LogValue() slog.Value

func (UsageClass) String 

func (u UsageClass) String() string

func (UsageClass) Valid 

func (u UsageClass) Valid() bool

Source Files

View all Source files

Directories

Path Synopsis
Package catalog contains explicit credential catalog backends.
 Package catalog contains explicit credential catalog backends.
Package httpauth contains call-scoped HTTP request authorizers.
 Package httpauth contains call-scoped HTTP request authorizers.
Package oauth contains provider-neutral OAuth acquisition mechanics.
 Package oauth contains provider-neutral OAuth acquisition mechanics.
Package refresh contains provider-neutral renewable credential sources.
 Package refresh contains provider-neutral renewable credential sources.

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.