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 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,
		ttl time.Duration,
		extraClaims map[string]any,
		audience []string,
	) (*TokenResult, error)
	GenerateRefreshToken(
		ctx context.Context,
		userID, clientID, scopes string,
		ttl time.Duration,
		extraClaims map[string]any,
		audience []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,
		ttl time.Duration,
		extraClaims map[string]any,
		audience []string,
	) (*TokenResult, error)
	ValidateToken(ctx context.Context, tokenString string) (*TokenValidationResult, error)
	// ValidateRefreshToken verifies a refresh-token JWT and returns the parsed
	// claims (including `aud`). Callers — notably the refresh flow in
	// TokenService — use the signed claims as the authoritative source of the
	// original grant's audience when the persisted `Resource` column is
	// empty (e.g. legacy rows issued before fix #2 snapshotted the effective
	// audience on issuance). This prevents a later JWT_AUDIENCE rotation
	// from silently retargeting refreshed access tokens to an audience the
	// original token's JWT never carried.
	ValidateRefreshToken(
		ctx context.Context,
		tokenString string,
	) (*TokenValidationResult, error)
	// RefreshAccessToken issues a new access token (and, in rotation mode, a
	// new refresh token) from a valid refresh-token string.
	//
	// accessScope narrows the new access token's `scope` claim (RFC 6749 §6).
	// When non-empty it overrides the scope signed into the original refresh
	// token; when empty the original scope is reused. The caller (TokenService)
	// is responsible for enforcing that accessScope is a subset of the original
	// grant before invoking this method. The rotated refresh token always keeps
	// the original grant's scope so a later refresh can re-request up to it.
	//
	// accessAudience and refreshAudience are kept separate so a refresh token
	// never carries the per-request resource-server `aud`. A refresh token is
	// presented to the AS, not the RS — emitting the same per-request audience
	// as the access token would let a downstream JWT validator that only
	// checks signature/iss/exp/aud silently accept the refresh token as if it
	// were an access token. Pass nil for refreshAudience to fall back to the
	// static JWTAudience config; deployments are expected to set
	// `JWT_AUDIENCE` to an AS-only value (or leave it unset so the claim is
	// omitted) — pointing it at a resource server would re-introduce the
	// confusion this split is designed to prevent.
	RefreshAccessToken(
		ctx context.Context,
		refreshToken string,
		accessTTL, refreshTTL time.Duration,
		extraClaims map[string]any,
		accessScope string,
		accessAudience []string,
		refreshAudience []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
	// 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)
	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)
}