auth

type CacheEntry struct {
	Flow        Flow   `json:"flow" yaml:"flow" doc:"Authentication flow for this cache entry"`
	Fingerprint string `json:"fingerprint" yaml:"fingerprint" doc:"Identity fingerprint for cache partitioning" maxLength:"128"`
	Scope       string `json:"scope" yaml:"scope" doc:"OAuth scope for this cache entry" maxLength:"1024"`
}

type CachedToken struct {
	AccessToken string    `json:"accessToken" yaml:"accessToken" doc:"The cached access token" maxLength:"65536"` //nolint:gosec // G117: not a hardcoded credential, stores runtime token data
	TokenType   string    `json:"tokenType" yaml:"tokenType" doc:"Token type, typically Bearer" example:"Bearer" maxLength:"64"`
	ExpiresAt   time.Time `json:"expiresAt" yaml:"expiresAt" doc:"Time the token expires"`
	Scope       string    `json:"scope" yaml:"scope" doc:"OAuth scope the token was issued for" maxLength:"1024"`
	Flow        Flow      `` /* 131-byte string literal not displayed */
	Fingerprint string    `json:"fingerprint,omitempty" yaml:"fingerprint,omitempty" doc:"Truncated SHA-256 hash of the config identity" maxLength:"128"`
	CachedAt    time.Time `json:"cachedAt" yaml:"cachedAt" doc:"Time the token was written to cache"`
	SessionID   string    `json:"sessionId,omitempty" yaml:"sessionId,omitempty" doc:"Stable identifier of the authentication session" maxLength:"128"`
}

type CachedTokenInfo struct {
	// Handler is the name of the auth handler that owns this token.
	Handler string `json:"handler" yaml:"handler" doc:"Name of the auth handler that owns this token" example:"entra" maxLength:"64"`
	// TokenKind is either "refresh" or "access".
	TokenKind string `json:"tokenKind" yaml:"tokenKind" doc:"Token kind: refresh or access" example:"access" maxLength:"16"`
	// Scope is the OAuth scope associated with the token.
	// Empty for refresh tokens that were not scope-specific.
	Scope string `json:"scope,omitempty" yaml:"scope,omitempty" doc:"OAuth scope associated with the token" maxLength:"1024"`
	// TokenType is the token type, e.g. "Bearer".
	TokenType string `json:"tokenType,omitempty" yaml:"tokenType,omitempty" doc:"Token type, typically Bearer" example:"Bearer" maxLength:"64"`
	// Flow is the authentication flow that produced the token.
	Flow Flow `` /* 130-byte string literal not displayed */
	// Fingerprint is the truncated SHA-256 hash of the config identity
	// (e.g., clientID+tenantID) that produced this token. The value "_"
	// means no config-specific partitioning applies.
	Fingerprint string `json:"fingerprint,omitempty" yaml:"fingerprint,omitempty" doc:"Truncated SHA-256 hash of the config identity" maxLength:"128"`
	// ExpiresAt is when the token expires.
	ExpiresAt time.Time `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty" doc:"Time the token expires"`
	// CachedAt is when the token was written to the on-disk cache.
	CachedAt time.Time `json:"cachedAt,omitempty" yaml:"cachedAt,omitempty" doc:"Time the token was written to the on-disk cache"`
	// IsExpired indicates whether the token is past its expiry time.
	IsExpired bool `json:"isExpired" yaml:"isExpired" doc:"Whether the token is past its expiry time"`
	// 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" yaml:"sessionId,omitempty" doc:"Stable identifier of the authentication session" maxLength:"128"`
}

type Capability string

type Claims struct {
	Issuer    string    `` /* 130-byte string literal not displayed */
	Subject   string    `json:"subject,omitempty" yaml:"subject,omitempty" doc:"Subject identifier" example:"user@example.com" maxLength:"512"`
	TenantID  string    `` /* 139-byte string literal not displayed */
	ObjectID  string    `` /* 147-byte string literal not displayed */
	ClientID  string    `` /* 142-byte string literal not displayed */
	Email     string    `json:"email,omitempty" yaml:"email,omitempty" doc:"Email address of the identity" example:"user@example.com" maxLength:"320"`
	Name      string    `json:"name,omitempty" yaml:"name,omitempty" doc:"Display name of the identity" example:"Jane Doe" maxLength:"256"`
	Username  string    `json:"username,omitempty" yaml:"username,omitempty" doc:"Username or login name" example:"janedoe" maxLength:"256"`
	IssuedAt  time.Time `json:"issuedAt,omitempty" yaml:"issuedAt,omitempty" doc:"Time the token was issued"`
	ExpiresAt time.Time `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty" doc:"Time the token expires"`
}

type CredentialDetector struct {
	// HasCredentials returns true if this credential type is available.
	HasCredentials func() bool
	// Flow is the auth flow to use when these credentials are detected.
	Flow Flow
	// Description is a human-readable message shown when this credential is detected.
	Description string
}

type Error struct {
	Handler   string `json:"handler" yaml:"handler" doc:"Name of the auth handler" example:"entra" maxLength:"64"`
	Operation string `json:"operation" yaml:"operation" doc:"Operation that failed" example:"login" maxLength:"64"`
	Cause     error  `json:"-" yaml:"-"`
}

type Flow string

type FlowDetectionResult struct {
	// Flow is the selected authentication flow.
	Flow Flow
	// Description is a human-readable message about what was detected,
	// or empty if the default flow was used.
	Description 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                                          `json:"tenantId,omitempty" yaml:"tenantId,omitempty" doc:"Azure AD tenant ID override" maxLength:"128"`
	Scopes             []string                                        `json:"scopes,omitempty" yaml:"scopes,omitempty" doc:"OAuth scopes to request" maxItems:"20"`
	Flow               Flow                                            `json:"flow,omitempty" yaml:"flow,omitempty" doc:"Authentication flow to use" example:"device_code" maxLength:"64"`
	Timeout            time.Duration                                   `json:"timeout,omitempty" yaml:"timeout,omitempty" doc:"Maximum time to wait for authentication"`
	CallbackPort       int                                             `` /* 130-byte string literal not displayed */
	DeviceCodeCallback func(userCode, verificationURI, message string) `json:"-" yaml:"-"`
}

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 PreLoginAction int

type PreLoginResult struct {
	// Action indicates what the caller should do.
	Action PreLoginAction
	// Identity is the display name of the authenticated identity (if any).
	Identity string
}

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

type Result struct {
	Claims    *Claims   `json:"claims,omitempty" yaml:"claims,omitempty" doc:"Identity claims from authentication"`
	ExpiresAt time.Time `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty" doc:"Time the authentication expires"`
}

type Status struct {
	Authenticated bool         `json:"authenticated" yaml:"authenticated" doc:"Whether the user is currently authenticated"`
	Claims        *Claims      `json:"claims,omitempty" yaml:"claims,omitempty" doc:"Identity claims from the current session"`
	ExpiresAt     time.Time    `json:"expiresAt,omitempty" yaml:"expiresAt,omitempty" doc:"Time the authentication expires"`
	LastRefresh   time.Time    `json:"lastRefresh,omitempty" yaml:"lastRefresh,omitempty" doc:"Time the token was last refreshed"`
	TenantID      string       `json:"tenantId,omitempty" yaml:"tenantId,omitempty" doc:"Azure AD tenant ID" maxLength:"128"`
	IdentityType  IdentityType `` /* 126-byte string literal not displayed */
	ClientID      string       `` /* 131-byte string literal not displayed */
	TokenFile     string       `` /* 131-byte string literal not displayed */
	Scopes        []string     `json:"scopes,omitempty" yaml:"scopes,omitempty" doc:"Scopes granted during login" maxItems:"20"`
}

type Token struct {
	AccessToken string    `json:"accessToken" yaml:"accessToken" doc:"The access token value"` //nolint:gosec // G117: not a hardcoded credential, stores runtime token data
	TokenType   string    `json:"tokenType" yaml:"tokenType" doc:"Token type, typically Bearer" example:"Bearer" maxLength:"64"`
	ExpiresAt   time.Time `json:"expiresAt" yaml:"expiresAt" doc:"Time the token expires"`
	Scope       string    `json:"scope,omitempty" yaml:"scope,omitempty" doc:"OAuth scope the token was issued for" maxLength:"1024"`
	// 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 `json:"cachedAt,omitempty" yaml:"cachedAt,omitempty" doc:"Time the token was written to the on-disk cache"`
	// Flow is the authentication flow that produced this token (e.g. "device_code",
	// "service_principal", "workload_identity").  Empty string means unknown.
	Flow Flow `` /* 131-byte string literal not displayed */
	// 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 `json:"sessionId,omitempty" yaml:"sessionId,omitempty" doc:"Stable identifier of the authentication session" maxLength:"128"`
}

type TokenAcquireFunc[T any] func(ctx context.Context, creds T, scope string) (*Token, error)

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

type TokenCacheAccessor interface {
	GetTokenCache() *TokenCache
}

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

type TokenOptions struct {
	Scope        string        `` /* 149-byte string literal not displayed */
	MinValidFor  time.Duration `json:"minValidFor,omitempty" yaml:"minValidFor,omitempty" doc:"Minimum remaining validity for cached tokens"`
	ForceRefresh bool          `json:"forceRefresh,omitempty" yaml:"forceRefresh,omitempty" doc:"Force token refresh even if cached token is valid"`
}

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