core

type AuditLogEntry struct {
	EventType     models.EventType
	Severity      models.EventSeverity
	ActorUserID   string
	ActorUsername 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) 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 IDTokenProvider interface {
	GenerateIDToken(params IDTokenParams) (string, error)
}

type Infrastructure interface {
	Close(ctx context.Context) error
	Health() 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
	AuditStore
	MetricsStore
	DashboardStore
	CleanupStore
	Transactor
	Infrastructure
}

type TokenProvider interface {
	GenerateToken(ctx context.Context, userID, clientID, scopes string) (*TokenResult, error)
	GenerateRefreshToken(ctx context.Context, userID, clientID, scopes string) (*TokenResult, error)
	// GenerateClientCredentialsToken generates a token for the client_credentials grant.
	// May apply a different expiry or claim set than GenerateToken.
	GenerateClientCredentialsToken(
		ctx context.Context,
		userID, clientID, scopes string,
	) (*TokenResult, error)
	ValidateToken(ctx context.Context, tokenString string) (*TokenValidationResult, error)
	RefreshAccessToken(
		ctx context.Context,
		refreshToken string,
	) (*TokenRefreshResult, error)
	Name() string
}

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
	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)
	GetClientAuthorizations(clientID string) ([]models.UserAuthorization, 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)
}