internal

type CacheKey struct {
	// Key identifies an auth method being used to get the token and its
	// parameters.
	//
	// Its exact form is not important, since it is used only for string matching
	// when searching for a token inside the cache.
	//
	// The following forms are being used currently:
	//  * user/<client_id> when using UserCredentialsMethod with some ClientID.
	//  * service_account/<email>/<key_id> when using ServiceAccountMethod.
	//  * gce/<account> when using GCEMetadataMethod.
	//  * iam/<account> when using IAM actor mode.
	//  * luci_ts/<account>/<host>/<realm> when using Token Server actor mode.
	//  * luci_ctx/<digest> when using LUCIContextMethod.
	Key string `json:"key"`

	// Scopes is the list of requested OAuth scopes or an ID token audience.
	//
	// The token audience is indicated by a fake scope that looks like
	// "audience:<value>". Cache keys are used only for map indexing, their exact
	// content doesn't matter. Adding a separate field (like `Audience`) to the
	// key causes complication with older binaries that read the token cache and
	// don't know about the new field, so we abuse `Scopes` field instead.
	Scopes []string `json:"scopes,omitempty"`
}

type DiskTokenCache struct {
	Context    context.Context // for logging and timing
	SecretsDir string
}

type IDTokenClaims struct {
	Aud           string `json:"aud"`
	Email         string `json:"email"`
	EmailVerified bool   `json:"email_verified"`
	Exp           int64  `json:"exp"`
	Iss           string `json:"iss"`
	Nonce         string `json:"nonce"`
	Sub           string `json:"sub"`
}

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

type Token struct {
	oauth2.Token

	IDToken string // an ID token derived directly from the access token or NoIDToken
	Email   string // an email or NoEmail or empty string (aka UnknownEmail)
}

type TokenCache interface {
	// GetToken reads the token from cache.
	//
	// Returns (nil, nil) if requested token is not in the cache.
	GetToken(key *CacheKey) (*Token, error)

	// PutToken writes the token to cache.
	PutToken(key *CacheKey, tok *Token) error

	// DeleteToken removes the token from cache.
	DeleteToken(key *CacheKey) error
}

type TokenProvider interface {
	// RequiresInteraction is true if provider may start user interaction
	// in MintToken.
	RequiresInteraction() bool

	// Lightweight is true if MintToken is very cheap to call.
	//
	// In this case the token is not being cached on disk (only in memory), since
	// it's easy to get a new one each time the process starts.
	//
	// By avoiding the disk cache, we reduce the chance of a leak.
	Lightweight() bool

	// Email is email associated with tokens produced by the provider, if known.
	//
	// May return UnknownEmail, which means the provider doesn't know the email
	// in advance and RefreshToken must be used to get the token and the email.
	// This happens, for example, for interactive providers before user has
	// logged in.
	//
	// It can also be NoEmail which means the email is not available, even if
	// caller is using RefreshToken.
	Email() string

	// CacheKey identifies a slot in the token cache to store the token in.
	//
	// Note: CacheKey MAY change during lifetime of a TokenProvider. It happens,
	// for example, for ServiceAccount token provider if the underlying service
	// account key is replaced while the process is still running.
	CacheKey(ctx context.Context) (*CacheKey, error)

	// MintToken launches authentication flow (possibly interactive) and returns
	// a new refreshable token (or error). It must never return (nil, nil).
	//
	// In actor mode 'base' is an IAM-scoped sufficiently fresh oauth token. It's
	// nil otherwise. Used by IAM-based token provider.
	MintToken(ctx context.Context, base *Token) (*Token, error)

	// RefreshToken takes existing token (probably expired, but not necessarily)
	// and returns a new refreshed token. It should never do any user interaction.
	// If a user interaction is required, a error should be returned instead.
	//
	// In actor mode 'base' is an IAM-scoped sufficiently fresh oauth token. It's
	// nil otherwise. Used by IAM-based token provider.
	RefreshToken(ctx context.Context, prev, base *Token) (*Token, error)
}