auth

type CachedTokenInfo struct {
	// Handler is the name of the auth handler that owns this token.
	Handler string `json:"handler"`
	// TokenKind is either "refresh" or "access".
	TokenKind string `json:"tokenKind"`
	// Scope is the OAuth scope associated with the token.
	// Empty for refresh tokens that were not scope-specific.
	Scope string `json:"scope,omitempty"`
	// TokenType is the token type, e.g. "Bearer".
	TokenType string `json:"tokenType,omitempty"`
	// Flow is the authentication flow that produced the token.
	Flow Flow `json:"flow,omitempty"`
	// ExpiresAt is when the token expires.
	ExpiresAt time.Time `json:"expiresAt,omitempty"`
	// CachedAt is when the token was written to the on-disk cache.
	CachedAt time.Time `json:"cachedAt,omitempty"`
	// IsExpired indicates whether the token is past its expiry time.
	IsExpired bool `json:"isExpired"`
	// SessionID is the stable identifier of the authentication session that
	// produced this token.  Present on both refresh and access entries, allowing
	// callers to trace which login session minted a given access token.
	SessionID string `json:"sessionId,omitempty"`
}

type Capability string

type Claims struct {
	Issuer    string
	Subject   string
	TenantID  string
	ObjectID  string
	ClientID  string
	Email     string
	Name      string
	Username  string
	IssuedAt  time.Time
	ExpiresAt time.Time
}

type Error struct {
	Handler   string
	Operation string
	Cause     error
}

type Flow string

type GroupsProvider interface {
	// GetGroups returns the ObjectIDs of all groups the authenticated user belongs to.
	// Implementations must handle pagination transparently, so all memberships —
	// including those beyond any per-token cap (e.g. the 200-group JWT limit for
	// Microsoft Entra) — are returned.
	GetGroups(ctx context.Context) ([]string, error)
}

type Handler interface {
	// Name returns the unique identifier for this auth handler.
	Name() string

	// DisplayName returns a human-readable name for display purposes.
	DisplayName() string

	// Login initiates the authentication flow.
	// For interactive flows (like device code), this blocks until completion or timeout.
	// Returns the authenticated identity claims on success.
	Login(ctx context.Context, opts LoginOptions) (*Result, error)

	// Logout clears stored credentials for this handler.
	Logout(ctx context.Context) error

	// Status returns the current authentication status.
	// Returns a status with Authenticated=false if not logged in.
	Status(ctx context.Context) (*Status, error)

	// GetToken returns a valid access token for the specified options.
	// Uses cached tokens when available and valid for the requested duration,
	// otherwise refreshes from the identity provider.
	// Returns ErrNotAuthenticated if user is not logged in.
	// Returns ErrTokenExpired if refresh token has expired (re-login required).
	GetToken(ctx context.Context, opts TokenOptions) (*Token, error)

	// InjectAuth adds authentication to an HTTP request.
	// This is the primary method used by providers (like HTTP) to authenticate requests.
	// Automatically handles token acquisition/refresh as needed.
	InjectAuth(ctx context.Context, req *http.Request, opts TokenOptions) error

	// SupportedFlows returns the authentication flows this handler supports.
	SupportedFlows() []Flow

	// Capabilities returns the set of capabilities this handler supports.
	// Commands use capabilities to dynamically determine which flags and
	// validation rules apply for a given handler.
	Capabilities() []Capability
}

type IdentityType string

type LoginOptions struct {
	TenantID           string
	Scopes             []string
	Flow               Flow
	Timeout            time.Duration
	CallbackPort       int
	DeviceCodeCallback func(userCode, verificationURI, message string)
}

type MockHandler struct {
	NameValue         string
	DisplayNameValue  string
	FlowsValue        []Flow
	CapabilitiesValue []Capability

	LoginResult            *Result
	LoginErr               error
	LogoutErr              error
	StatusResult           *Status
	StatusErr              error
	GetTokenResult         *Token
	GetTokenErr            error
	InjectAuthErr          error
	ListCachedTokensResult []*CachedTokenInfo
	ListCachedTokensErr    error
	PurgeExpiredResult     int
	PurgeExpiredErr        error

	LoginCalls        []LoginOptions
	LogoutCalls       int
	StatusCalls       int
	GetTokenCalls     []TokenOptions
	InjectAuthCalls   []TokenOptions
	PurgeExpiredCalls int
	// contains filtered or unexported fields
}

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

type Result struct {
	Claims    *Claims
	ExpiresAt time.Time
}

type Status struct {
	Authenticated bool
	Claims        *Claims
	ExpiresAt     time.Time
	LastRefresh   time.Time
	TenantID      string
	IdentityType  IdentityType // Type of identity: "user", "service-principal", or "workload-identity"
	ClientID      string       // For service principal/workload identity: the application ID
	TokenFile     string       // For workload identity: path to the federated token file
	Scopes        []string     // Scopes granted during login
}

type Token struct {
	AccessToken string //nolint:gosec // G117: not a hardcoded credential, stores runtime token data
	TokenType   string
	ExpiresAt   time.Time
	Scope       string
	// CachedAt records when this token was written to the on-disk cache.
	// Zero value means the token was not loaded from the cache.
	CachedAt time.Time
	// Flow is the authentication flow that produced this token (e.g. "device_code",
	// "service_principal", "workload_identity").  Empty string means unknown.
	Flow Flow
	// SessionID is a stable identifier linking this access token back to the
	// authentication session (login) that produced it.  Generated once at login
	// time and preserved across refresh-token rotations.
	SessionID string
}

type TokenLister interface {
	ListCachedTokens(ctx context.Context) ([]*CachedTokenInfo, error)
}

type TokenOptions struct {
	Scope        string
	MinValidFor  time.Duration
	ForceRefresh bool
}

type TokenPurger interface {
	PurgeExpiredTokens(ctx context.Context) (int, error)
}