Documentation
¶
Overview ¶
Package keyring wraps the zalando/go-keyring package with timeouts and provides a service-credential registry for fetching, parsing, and validating secrets stored in the OS keychain.
Raw operations (Set, Get, Delete) live in this file. Service definitions and the generic pipeline live in service.go. Per-service types and accessors live in their own files (e.g. claude_code.go).
TODO: Give attribution to gh authors
Index ¶
- Variables
- func Delete(service, user string) error
- func Get(service, user string) (string, error)
- func GetClaudeCodeCredentialsRaw() (string, error)
- func MockInit()
- func MockInitWithError(err error)
- func Set(service, user, secret string) error
- type ClaudeAiOauth
- type ClaudeCodeCredentials
- type ServiceDef
- type TimeoutError
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidSchema indicates the raw keyring value could not be parsed into the // expected credential struct (e.g. malformed JSON). ErrInvalidSchema = errors.New("credential data does not match expected schema") // ErrEmptyCredential indicates the keyring entry exists but contains an empty value. ErrEmptyCredential = errors.New("credential is empty") )
Sentinel errors returned by the service-credential pipeline.
var ErrNotFound = errors.New("secret not found in keyring")
ErrNotFound is returned when no secret exists for the given service+user.
Functions ¶
func GetClaudeCodeCredentialsRaw ¶ added in v0.12.0
GetClaudeCodeCredentialsRaw fetches the current user's Claude Code credential blob from the OS keychain verbatim, without parsing or re-encoding.
Claude Code stores this as a plain JSON object (not a JWT) and refreshes it in place at runtime using the embedded refreshToken. The blob must be injected byte-for-byte: round-tripping it through ClaudeCodeCredentials would fabricate a zero-value organizationUuid for a host that omits the key (claiming an org the user is not a member of, which the refresh endpoint rejects) and would drop any field the struct does not model.
func MockInitWithError ¶
func MockInitWithError(err error)
MockInitWithError sets up an in-memory keyring backend that returns err for every operation.
Types ¶
type ClaudeAiOauth ¶
type ClaudeAiOauth struct {
AccessToken string `json:"accessToken"`
RefreshToken string `json:"refreshToken"`
ExpiresAt int64 `json:"expiresAt"`
Scopes []string `json:"scopes"`
SubscriptionType string `json:"subscriptionType"`
RateLimitTier string `json:"rateLimitTier"`
}
ClaudeAiOauth contains the OAuth token fields within ClaudeCodeCredentials.
type ClaudeCodeCredentials ¶
type ClaudeCodeCredentials struct {
ClaudeAiOauth ClaudeAiOauth `json:"claudeAiOauth"`
OrganizationUUID uuid.UUID `json:"organizationUuid"`
}
ClaudeCodeCredentials is the top-level JSON schema stored in the OS keychain by Claude Code under the service name "Claude Code-credentials".
func GetClaudeCodeCredentials ¶
func GetClaudeCodeCredentials() (*ClaudeCodeCredentials, error)
GetClaudeCodeCredentials fetches and parses the current user's Claude Code credentials from the OS keychain.
The parsed struct is lossy: keys the host omits surface as zero values and keys absent from the struct are dropped. Readers that only need typed fields can use it; injection paths must use GetClaudeCodeCredentialsRaw to preserve the blob verbatim.
type ServiceDef ¶
type ServiceDef[T any] struct { // ServiceName is the keyring service identifier (e.g. "Claude Code-credentials"). ServiceName string // User returns the keyring username for this service. // Most services use currentOSUser; some may hard-code or derive a value. User func() (string, error) // Parse converts the raw keyring string into a typed credential. // Return an error if the data does not match the expected schema. Parse func(raw string) (*T, error) // Validate performs service-specific checks on the parsed credential // (e.g. expiry). Nil means no validation. Validate func(*T) error }
ServiceDef describes how to fetch, parse, and validate a credential of type T.
Each service (Claude Code, GitHub CLI, etc.) defines one of these as a package-level var and exposes a thin public function that calls getCredential.
type TimeoutError ¶
type TimeoutError struct {
// contains filtered or unexported fields
}
TimeoutError is returned when a keyring operation exceeds the deadline.
func (*TimeoutError) Error ¶
func (e *TimeoutError) Error() string