core

type AuditLogEntry struct {
	EventType     models.EventType
	Severity      models.EventSeverity
	ActorUserID   string
	ActorUsername string
	ActorFullName string
	ActorIP       string
	ResourceType  models.ResourceType
	ResourceID    string
	ResourceName  string
	Action        string
	Details       models.AuditDetails
	Success       bool
	ErrorMessage  string
	UserAgent     string
	RequestPath   string
	RequestMethod string
}

type AuditLogger interface {
	Log(ctx context.Context, entry AuditLogEntry)
	LogSync(ctx context.Context, entry AuditLogEntry) error
	GetAuditLogs(
		params types.PaginationParams,
		filters types.AuditLogFilters,
	) ([]models.AuditLog, types.PaginationResult, error)
	CleanupOldLogs(retention time.Duration) (int64, error)
	GetAuditLogStats(startTime, endTime time.Time) (types.AuditLogStats, error)
	Shutdown(ctx context.Context) error
}

type AuditStore interface {
	CreateAuditLog(log *models.AuditLog) error
	CreateAuditLogBatch(logs []*models.AuditLog) error
	GetAuditLogsPaginated(
		params types.PaginationParams,
		filters types.AuditLogFilters,
	) ([]models.AuditLog, types.PaginationResult, error)
	DeleteOldAuditLogs(olderThan time.Time) (int64, error)
	GetAuditLogStats(startTime, endTime time.Time) (types.AuditLogStats, error)
}

type AuthProvider interface {
	Authenticate(ctx context.Context, username, password string) (*AuthResult, error)
	Name() string
}

type AuthResult struct {
	Username   string
	ExternalID string // External user ID (e.g., LDAP DN, API user ID)
	Email      string // Optional
	FullName   string // Optional
}

type AuthorizationCodeStore interface {
	CreateAuthorizationCode(code *models.AuthorizationCode) error
	GetAuthorizationCodeByHash(hash string) (*models.AuthorizationCode, error)
	MarkAuthorizationCodeUsed(id uint) error
}

type Cache[T any] interface {
	// Get retrieves a single value from cache.
	// Returns ErrCacheMiss if the key does not exist or has expired.
	Get(ctx context.Context, key string) (T, error)

	// Set stores a single value in cache with TTL
	Set(ctx context.Context, key string, value T, ttl time.Duration) error

	// Delete removes a key from cache
	Delete(ctx context.Context, key string) error

	// Close closes the cache connection
	Close() error

	// Health checks if the cache is healthy
	Health(ctx context.Context) error

	// GetWithFetch retrieves a value using the cache-aside pattern.
	// On cache miss, fetchFunc is called and the result is stored in cache.
	// Implementations may provide stampede protection (e.g. RueidisAsideCache).
	GetWithFetch(
		ctx context.Context,
		key string,
		ttl time.Duration,
		fetchFunc func(ctx context.Context, key string) (T, error),
	) (T, error)
}

type CleanupStore interface {
	DeleteExpiredTokens() error
	DeleteExpiredDeviceCodes() error
}

type ClientReader interface {
	GetClient(clientID string) (*models.OAuthApplication, error)
	GetClientByIntID(id int64) (*models.OAuthApplication, error)
	GetClientsByIDs(clientIDs []string) (map[string]*models.OAuthApplication, error)
	ListClientsPaginated(
		params types.PaginationParams,
	) ([]models.OAuthApplication, types.PaginationResult, error)
	ListClientsByUserID(
		userID string,
		params types.PaginationParams,
	) ([]models.OAuthApplication, types.PaginationResult, error)
	CountClientsByStatus(status string) (int64, error)
	CountActiveTokensByClientID(clientID string) (int64, error)
}

type ClientType string

type ClientWriter interface {
	CreateClient(client *models.OAuthApplication) error
	UpdateClient(client *models.OAuthApplication) error
	DeleteClient(clientID string) error
}

type DashboardStore interface {
	GetDashboardCounts() (types.DashboardCounts, error)
}

type DeviceCodeStore interface {
	CreateDeviceCode(dc *models.DeviceCode) error
	GetDeviceCodesByID(deviceCodeID string) ([]*models.DeviceCode, error)
	GetDeviceCodeByUserCode(userCode string) (*models.DeviceCode, error)
	UpdateDeviceCode(dc *models.DeviceCode) error
	AuthorizeDeviceCode(id int64, userID string) error
	DeleteDeviceCodeByID(id int64) (int64, error)
}

type IDTokenParams struct {
	Issuer   string
	Subject  string // UserID
	Audience string // ClientID
	AuthTime time.Time
	Nonce    string
	Expiry   time.Duration
	AtHash   string // base64url(SHA-256(access_token)[:16]) – optional

	// Scope-gated profile claims (include when "profile" scope was granted)
	Name              string
	PreferredUsername string
	Picture           string
	UpdatedAt         *time.Time

	// Scope-gated email claims (include when "email" scope was granted)
	Email         string
	EmailVerified bool
}

type Infrastructure interface {
	Close(ctx context.Context) error
	Health() error
}

type LoginSessionStore interface {
	CreateLoginSession(ls *models.LoginSession) error
	GetActiveLoginSessionBySIDHash(hash string) (*models.LoginSession, error)
	GetLoginSessionByID(id string) (*models.LoginSession, error)
	ListActiveLoginSessionsByUserID(userID string) ([]models.LoginSession, error)
	RevokeLoginSessionByID(id string) error
	RevokeLoginSessionBySIDHash(hash string) error
	RevokeLoginSessionsByUserExceptSIDHash(userID, exceptHash string) (int64, error)
	TouchLoginSession(id string, lastSeen, expiresAt time.Time) error
	DeleteExpiredLoginSessions(olderThan time.Time) (int64, error)
}

type MetricsStore interface {
	CountActiveTokensByCategory(category string) (int64, error)
	CountTotalDeviceCodes() (int64, error)
	CountPendingDeviceCodes() (int64, error)
}

type OAuthConnectionStore interface {
	CreateOAuthConnection(conn *models.OAuthConnection) error
	GetOAuthConnection(provider, providerUserID string) (*models.OAuthConnection, error)
	GetOAuthConnectionByUserAndProvider(userID, provider string) (*models.OAuthConnection, error)
	GetOAuthConnectionByUserAndID(userID, connectionID string) (*models.OAuthConnection, error)
	GetOAuthConnectionsByUserID(userID string) ([]models.OAuthConnection, error)
	UpdateOAuthConnection(conn *models.OAuthConnection) error
	DeleteOAuthConnection(id string) error
	DeleteOAuthConnectionsByUserID(userID string) error
}

type Recorder interface {
	// OAuth Device Flow
	RecordOAuthDeviceCodeGenerated(success bool)
	RecordOAuthDeviceCodeAuthorized(authorizationTime time.Duration)
	RecordOAuthDeviceCodeValidation(result string)

	// Token Operations
	RecordTokenIssued(tokenType, grantType string, generationTime time.Duration, provider string)
	RecordTokenRevoked(tokenType, reason string)
	RecordTokenRefresh(success bool)
	RecordTokenValidation(result string, duration time.Duration, provider string)

	// Authentication
	RecordAuthAttempt(method string, success bool, duration time.Duration)
	RecordLogin(authSource string, success bool)
	RecordLogout(sessionDuration time.Duration)
	RecordOAuthCallback(provider string, success bool)

	// Gauge Setters (for periodic updates)
	SetActiveTokensCount(tokenType string, count int)
	SetActiveDeviceCodesCount(total, pending int)

	// Database Operations
	RecordDatabaseQueryError(operation string)
}

type Store interface {
	UserReader
	UserWriter
	ClientReader
	ClientWriter
	DeviceCodeStore
	TokenReader
	TokenWriter
	AuthorizationCodeStore
	UserAuthorizationStore
	OAuthConnectionStore
	LoginSessionStore
	AuditStore
	MetricsStore
	DashboardStore
	CleanupStore
	Transactor
	Infrastructure
}

type TokenReader interface {
	GetAccessTokenByHash(hash string) (*models.AccessToken, error)
	GetAccessTokenByID(tokenID string) (*models.AccessToken, error)
	GetTokensByUserID(userID string) ([]models.AccessToken, error)
	GetTokensByUserIDPaginated(
		userID string,
		params types.PaginationParams,
	) ([]models.AccessToken, types.PaginationResult, error)
	GetTokensPaginated(
		params types.PaginationParams,
	) ([]models.AccessToken, types.PaginationResult, error)
	GetTokensByCategoryAndStatus(userID, category, status string) ([]models.AccessToken, error)
	GetActiveTokenHashesByFamilyID(familyID string) ([]string, error)
	GetActiveTokenHashesByAuthorizationID(authorizationID uint) ([]string, error)
	GetActiveTokenHashesByClientID(clientID string) ([]string, error)
	GetTokenHashesByUserID(userID string) ([]string, error)
}

type TokenRefreshResult struct {
	AccessToken  *TokenResult // required
	RefreshToken *TokenResult // non-nil only in rotation mode
}

type TokenResult struct {
	TokenString string
	TokenType   string
	ExpiresAt   time.Time
	Claims      map[string]any
}

type TokenValidationResult struct {
	Valid     bool
	UserID    string
	ClientID  string
	Scopes    string
	ExpiresAt time.Time
	Claims    map[string]any
}

type TokenWriter interface {
	CreateAccessToken(token *models.AccessToken) error
	RevokeToken(tokenID string) error
	RevokeTokensByUserID(userID string) error
	RevokeTokensByClientID(clientID string) error
	RevokeTokenFamily(familyID string) (int64, error)
	UpdateTokenStatus(tokenID, status string) error
	// RevokeRefreshTokenIfActive atomically revokes a refresh token only when it
	// is still active, returning RowsAffected (1 = won the race, 0 = a concurrent
	// refresh already consumed it). Used by rotation-mode refresh to guarantee
	// single use; distinct from UpdateTokenStatus, which stays unconditional for
	// the enable/disable/revoke admin paths.
	RevokeRefreshTokenIfActive(tokenID string) (int64, error)
	UpdateTokenLastUsedAt(tokenID string, t time.Time) error
	RevokeTokensByAuthorizationID(authorizationID uint) error
	RevokeAllActiveTokensByClientID(clientID string) (int64, error)
}

type Transactor interface {
	RunInTransaction(fn func(tx Store) error) error
}

type UserAuthorizationStore interface {
	GetUserAuthorization(userID string, applicationID int64) (*models.UserAuthorization, error)
	GetUserAuthorizationByUUID(authUUID, userID string) (*models.UserAuthorization, error)
	UpsertUserAuthorization(auth *models.UserAuthorization) error
	RevokeUserAuthorization(authUUID, userID string) (*models.UserAuthorization, error)
	ListUserAuthorizations(userID string) ([]models.UserAuthorization, error)
	ListUserAuthorizationsPaginated(
		userID string,
		params types.PaginationParams,
	) ([]models.UserAuthorization, types.PaginationResult, error)
	GetClientAuthorizations(clientID string) ([]models.UserAuthorization, error)
	GetClientAuthorizationsPaginated(
		clientID string,
		params types.PaginationParams,
	) ([]models.UserAuthorization, types.PaginationResult, error)
	RevokeAllUserAuthorizationsByClientID(clientID string) error
	RevokeAllUserAuthorizationsByUserID(userID string) error
}

type UserReader interface {
	GetUserByUsername(username string) (*models.User, error)
	GetUserByID(id string) (*models.User, error)
	GetUserByEmail(email string) (*models.User, error)
	// FindUserByNormalizedEmail locates a user whose stored email matches the
	// input after trimming whitespace on both sides, and returns an error when
	// more than one legacy row ties to the same normalized value. Used by the
	// OAuth auto-link path where picking a non-deterministic match would risk
	// binding a verified provider to the wrong local user. Slower than
	// GetUserByEmail because the fallback is not index-friendly — callers that
	// don't need whitespace tolerance should keep using GetUserByEmail.
	FindUserByNormalizedEmail(email string) (*models.User, error)
	GetUserByExternalID(externalID, authSource string) (*models.User, error)
	GetUsersByIDs(userIDs []string) (map[string]*models.User, error)
	ListUsersPaginated(params types.PaginationParams) ([]models.User, types.PaginationResult, error)
	CountUsersByRole(role string) (int64, error)
	GetUserStatsByUserID(userID string) (types.UserStatsCounts, error)
}

type UserWriter interface {
	CreateUser(user *models.User) error
	UpdateUser(user *models.User) error
	DeleteUser(id string) error
	UpsertExternalUser(
		username, externalID, authSource, email, fullName string,
	) (*models.User, error)
}