credentials

type BaseTokenOptions struct {
	// EnvVars (optional) environment variables to use for this token. Defaults to key (upper-cased with s/-/_/, eg. "vault-token" -> "VAULT_TOKEN").
	// Ideally only one environment variable should be used, but multiple are supported for backwards compatibility.
	// Environment variables will be checked both with the "THELMA_" prefix and without.
	EnvVars []string
	// PromptEnabled (optional) if true, user will be prompted to manually enter a token value if one does not exist in credential store.
	PromptEnabled bool
	// PromptMessage (optional) Override default prompt message ("Please enter VAULT_TOKEN: ")
	PromptMessage string
	// CredentialStore (optional) Use a custom credential store instead of the default store (~/.thelma/credentials/$key)
	CredentialStore stores.Store
}

type Credentials interface {
	// GetTokenProvider returns a TokenProvider for the given key, applying the given options if a new TokenProvider is
	// created to fulfill the request. If a TokenProvider already exists for the given key, it will be returned.
	// It's important for callers to be consistent with the options they pass in, at least for a given Thelma execution,
	// since the options are only used on the first call for a given key.
	//
	// The caching means that there will only ever be one TokenProvider for a given key, so the TokenProvider's
	// concurrency-safety guarantees will reliably apply (and the caller doesn't need to worry about caching the
	// response of this function).
	GetTokenProvider(key string, opts ...TokenOption) TokenProvider
}

type MockTokenProvider struct {
	ReturnString string
	ReturnBytes  []byte
	ReturnNil    bool
	ReturnErr    bool
	FailIfCalled *testing.T
}

type TokenOption func(*TokenOptions)

type TokenOptions struct {
	BaseTokenOptions
	// ValidateFn (optional) Optional function for validating a token. If supplied, stored credentials will be validated before being returned to caller.
	// This function can be called quite frequently in Goroutine scenarios, so offline validation is ideal.
	ValidateFn func([]byte) error
	// RefreshFn (optional) Optional function for refreshing a token. Called if a stored credential turns out to be invalid. If an error is returned, IssueFn will be called to issue a new credential.
	RefreshFn func([]byte) ([]byte, error)
	// IssueFn (optional) Optional function for issuing a new token. If supplied, prompt options are ignored.
	IssueFn func() ([]byte, error)
	// contains filtered or unexported fields
}

type TokenProvider interface {
	// Get provides a token value based on the configuration of the TokenProvider. The overall flow is as follows:
	//
	// 1. If a match for any TokenOptions.EnvVars is found, immediately return that value
	// 2. If a match for the key is found in the TokenOptions.CredentialStore:
	//    - If it is valid per TokenOptions.ValidateFn, return it
	//    - If it is invalid but TokenOptions.RefreshFn is provided, attempt to refresh the token and validate, store, and return it
	//      (errors from TokenOptions.RefreshFn will cause the flow to continue to step 3)
	// 3. If TokenOptions.IssueFn is provided, issue a new token and validate, store, and return it
	// 4. If TokenOptions.IssueFn isn't provided but TokenOptions.PromptEnabled is true and the session is interactive,
	//    prompt the user for a new token value and validate, store, and return it
	Get() ([]byte, error)
	// Reissue clears the state of the TokenProvider and then calls Get (which will usually then issue a new token).
	Reissue() ([]byte, error)
}

type TypedTokenOption[T any] func(*TypedTokenOptions[T])

type TypedTokenOptions[T any] struct {
	BaseTokenOptions

	// UnmarshalFromStoreFn (required) parses T from the BaseTokenOptions.CredentialStore.
	//
	// If you're trying to change the stored representation of a token, it's safe to just error here.
	// UnmarshalFromStoreFn and MarshalToStoreFn get baked into TokenOptions.ValidateFn and similar,
	// so if they return an error it'll be seen as a validation error (and so will fall through to
	// refreshing/issuing). In other words, you don't need to gracefully handle it.
	UnmarshalFromStoreFn func([]byte) (T, error)
	// MarshalToStoreFn (required) will be used to store T in the BaseTokenOptions.CredentialStore.
	MarshalToStoreFn func(T) ([]byte, error)

	// MarshalToReturnFn (optional) will be used to return T to the caller of TokenProvider.Get.
	// If omitted, MarshalToStoreFn will be used.
	MarshalToReturnFn func(T) ([]byte, error)

	// ValidateFn (optional) is like TokenOptions.ValidateFn, but for T.
	ValidateFn func(T) error
	// RefreshFn (optional) is like TokenOptions.RefreshFn, but for T.
	RefreshFn func(T) (T, error)
	// IssueFn (optional) is like TokenOptions.IssueFn, but for T.
	IssueFn func() (T, error)
}