credstore

type Backend struct {
	// Name is the keyring.BackendType identifier (e.g. "keychain").
	Name string
	// DisplayName is a human-readable label for Name.
	DisplayName string
}

type Credentials struct {
	RefreshToken      string    `json:"refresh_token"`
	AccessToken       string    `json:"access_token,omitempty"`
	AccessTokenExpiry time.Time `json:"access_token_expiry,omitempty"`
}

type DeviceState struct {
	IDPDomain string `json:"idp_domain,omitempty"`
	// Environment is the `--env` value used at login (prod, staging, or
	// development), determining which compiled-in client ID is used to
	// refresh the access token.
	Environment string `json:"environment,omitempty"`
	// Audience is the `--audience` value used at login. Auth0's
	// refresh_token grant automatically ties the refreshed access token
	// to the audience it was originally issued for, so this isn't sent
	// back on refresh; it's persisted purely for display in
	// `lfx auth status`.
	Audience string `json:"audience,omitempty"`
	// Insecure records whether `--insecure-storage` was passed at login,
	// i.e. whether Credentials live in the plain-file backend rather than
	// the system keychain. state.json itself is not namespaced by
	// backend (both share the same file), so callers must check this
	// against the invocation's own --insecure-storage flag before trusting
	// the rest of the state: without that check, logging into one backend
	// silently overwrites the metadata (env, IdP domain) that the other
	// backend's still-present credentials depend on.
	Insecure bool `json:"insecure,omitempty"`
	// Backend records the keyring.BackendType (e.g. "keychain") pinned via
	// --backend at login, or "" if the backend was left to
	// keyring.Open's own auto-detection. Unlike Insecure, an empty value
	// here is not itself trustworthy: keyring.Open can silently select a
	// *different* system backend across invocations (e.g. Secret Service
	// is reachable in one shell session but not another, falling back to
	// pass), so an unpinned login can't be protected against later landing
	// on a different backend with the same state.json. Once a backend has
	// been pinned, though, callers must require the same --backend
	// value on every later command against this state, the same way
	// Insecure is enforced.
	Backend string `json:"backend,omitempty"`
}

type Options struct {
	// Insecure bypasses the system keychain in favor of a plain, owner-only
	// (0600; see writeOwnerOnlyFile for the Windows caveat) JSON file.
	// Intended for headless/CI use where a passphrase prompt is
	// unacceptable. Corresponds to the CLI's --insecure-storage
	// flag.
	Insecure bool

	// StateDir overrides the computed state directory. Intended for tests;
	// leave empty to use $XDG_STATE_HOME/lfx-cli (or ~/.local/state/lfx-cli
	// if $XDG_STATE_HOME is unset).
	StateDir string

	// Backend pins keyring.Open to a single system backend (e.g.
	// "keychain"; see AvailableBackends for the valid values on this OS),
	// instead of letting it probe systemBackends in priority order and
	// silently use whichever one currently opens. Ignored when Insecure is
	// set. Leave empty to keep the previous auto-detecting behavior.
	Backend string
}

type Store interface {
	// SaveCredentials persists secrets to the system keychain (or, with
	// Options.Insecure, the plain-file backend).
	SaveCredentials(creds Credentials) error
	// LoadCredentials returns the persisted secrets, or ErrNotFound if none
	// have been saved.
	LoadCredentials() (Credentials, error)
	// DeleteCredentials removes any persisted secrets. It is a no-op if
	// none exist.
	DeleteCredentials() error

	// SaveDeviceState persists non-sensitive device state as plain JSON.
	SaveDeviceState(state DeviceState) error
	// LoadDeviceState returns the persisted device state, or ErrNotFound if
	// none has been saved.
	LoadDeviceState() (DeviceState, error)
	// DeleteDeviceState removes any persisted device state. It is a no-op
	// if none exists.
	DeleteDeviceState() error
}