core

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 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 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 MetricsStore interface {
	CountActiveTokensByCategory(category string) (int64, error)
	CountTotalDeviceCodes() (int64, error)
	CountPendingDeviceCodes() (int64, 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 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.
	// HTTP API provider delegates to GenerateToken; local provider may apply
	// a different expiry or claim set.
	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 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
}