federation

type AccessCheck struct {
	// Verb is the Kubernetes API verb to check (e.g., "get", "list", "create", "delete", "patch", "watch").
	// This is required.
	Verb string

	// Resource is the Kubernetes resource type to check (e.g., "pods", "deployments", "secrets").
	// This is required.
	Resource string

	// APIGroup is the API group for the resource (e.g., "", "apps", "batch").
	// Use "" for core API resources like pods and services.
	APIGroup string

	// Namespace is the namespace to check permissions in.
	// Leave empty for cluster-scoped resources or cluster-wide checks.
	Namespace string

	// Name is the specific resource name to check.
	// Leave empty to check permissions for all resources of the type.
	Name string

	// Subresource is the subresource to check (e.g., "logs", "exec", "portforward" for pods).
	// Leave empty for the main resource.
	Subresource string
}

type AccessCheckError struct {
	// ClusterName is the cluster where the check was attempted.
	ClusterName string

	// Check contains the access check parameters.
	Check *AccessCheck

	// Reason describes what went wrong during the check.
	Reason string

	// Err is the underlying error.
	Err error
}

type AccessCheckResult struct {
	// Allowed indicates whether the requested action is permitted.
	Allowed bool

	// Denied indicates whether the requested action was explicitly denied.
	// This is different from !Allowed - a request can be neither allowed nor denied
	// (e.g., when no policy matches).
	Denied bool

	// Reason provides a human-readable explanation of the decision.
	// This may include information about which RBAC rule matched or why access was denied.
	Reason string

	// EvaluationError contains any error that occurred during policy evaluation.
	// A non-empty EvaluationError typically means the result is inconclusive.
	EvaluationError string
}

type AccessDeniedError struct {
	// ClusterName is the cluster where the permission check was performed.
	ClusterName string

	// UserEmail is the email of the user (for logging only, anonymized in Error()).
	UserEmail string

	// Verb is the action that was denied (e.g., "delete", "create").
	Verb string

	// Resource is the resource type for which access was denied.
	Resource string

	// APIGroup is the API group of the resource.
	APIGroup string

	// Namespace is the namespace where access was denied (empty for cluster-scoped).
	Namespace string

	// Name is the specific resource name if checked (empty for type-level checks).
	Name string

	// Reason provides details about why access was denied (from Kubernetes).
	Reason string
}

type AmbiguousClusterError struct {
	Pattern string
	// Matches contains the clusters that matched the pattern, used to provide
	// helpful feedback to users about which clusters they might have meant.
	Matches []ClusterSummary
}

type AuthMetricsRecorder interface {
	// RecordWorkloadClusterAuth records a workload cluster authentication attempt.
	// authMode: "impersonation" or "sso-passthrough"
	// clusterName: Target cluster name
	// result: "success", "error", "token_missing"
	RecordWorkloadClusterAuth(ctx context.Context, authMode, clusterName, result string)

	// RecordImpersonation records an impersonation request with cardinality controls.
	// userEmail: User's email (will be reduced to domain by implementation)
	// clusterName: Target cluster name (will be classified by implementation)
	// result: "success", "error", "denied"
	RecordImpersonation(ctx context.Context, userEmail, clusterName, result string)

	// RecordFederationClientCreation records a federation client creation attempt.
	// clusterName: Target cluster name (will be classified by implementation)
	// result: "success", "error"
	RecordFederationClientCreation(ctx context.Context, clusterName, result string)
}

type CacheConfig struct {
	// TTL is the time-to-live for cached clients. After this duration,
	// entries are eligible for eviction.
	//
	// Security note: Set this to be less than or equal to your OAuth token
	// lifetime to ensure cached clients don't outlive user authorization.
	//
	// Default: 10 minutes.
	TTL time.Duration

	// MaxEntries is the maximum number of entries the cache can hold.
	// When exceeded, least recently accessed entries are evicted.
	//
	// Each unique (clusterName, userEmail) pair creates one cache entry.
	// Monitor the mcp_client_cache_entries metric to tune this value.
	//
	// Default: 1000.
	MaxEntries int

	// CleanupInterval is how often the background cleanup runs to remove
	// expired entries.
	//
	// Default: 1 minute.
	CleanupInterval time.Duration
}

type CacheMetricsRecorder interface {
	// RecordCacheHit records a cache hit event.
	RecordCacheHit(ctx context.Context, clusterName string)

	// RecordCacheMiss records a cache miss event.
	RecordCacheMiss(ctx context.Context, clusterName string)

	// RecordCacheEviction records a cache eviction event.
	RecordCacheEviction(ctx context.Context, reason string)

	// SetCacheSize sets the current cache size gauge.
	SetCacheSize(ctx context.Context, size int)
}

type CacheStats struct {
	// Size is the current number of entries in the cache.
	Size int

	// MaxEntries is the maximum capacity.
	MaxEntries int

	// TTL is the configured time-to-live.
	TTL time.Duration

	// OldestEntry is the age of the oldest entry (if any).
	OldestEntry time.Duration

	// NewestEntry is the age of the newest entry (if any).
	NewestEntry time.Duration
}

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

type ClientCacheOption func(*ClientCache)

type ClientProvider interface {
	// GetClientsForUser returns Kubernetes clients authenticated as the specified user.
	// The returned clients use the user's OAuth token for authentication, ensuring
	// all operations are performed with the user's RBAC permissions.
	//
	// Parameters:
	//   - ctx: Context for the request (may contain OAuth token)
	//   - user: User identity information from OAuth claims
	//
	// Returns:
	//   - kubernetes.Interface: Clientset for typed API access
	//   - dynamic.Interface: Dynamic client for CRD access (e.g., CAPI resources)
	//   - *rest.Config: REST config for creating additional clients
	//   - error: Any error during client creation
	GetClientsForUser(ctx context.Context, user *UserInfo) (kubernetes.Interface, dynamic.Interface, *rest.Config, error)
}

type ClusterClientManager interface {
	// GetClient returns a Kubernetes client for the target cluster,
	// configured to impersonate the provided user.
	// If clusterName is empty, returns the local (Management Cluster) client.
	//
	// The returned client has Impersonate-User and Impersonate-Group headers
	// configured based on the UserInfo, ensuring all operations are executed
	// under the authenticated user's identity.
	GetClient(ctx context.Context, clusterName string, user *UserInfo) (kubernetes.Interface, error)

	// GetDynamicClient returns a dynamic client for the target cluster,
	// useful for working with CRDs like CAPI resources.
	// If clusterName is empty, returns the local (Management Cluster) dynamic client.
	//
	// Like GetClient, the returned client is configured for user impersonation.
	GetDynamicClient(ctx context.Context, clusterName string, user *UserInfo) (dynamic.Interface, error)

	// GetRestConfig returns the REST configuration for the target cluster.
	// This is needed for operations that require direct REST access,
	// such as exec and port-forward which create SPDY connections.
	// If clusterName is empty, returns the local (Management Cluster) config.
	//
	// Like GetClient, the returned config is configured for user impersonation.
	GetRestConfig(ctx context.Context, clusterName string, user *UserInfo) (*rest.Config, error)

	// ListClusters returns a list of available workload clusters.
	// The list is filtered based on the user's RBAC permissions - only clusters
	// the user has access to view will be returned.
	//
	// This method queries CAPI Cluster resources on the Management Cluster.
	ListClusters(ctx context.Context, user *UserInfo) ([]ClusterSummary, error)

	// GetClusterSummary returns detailed information about a specific cluster.
	// Returns ErrClusterNotFound if the cluster doesn't exist or the user
	// doesn't have permission to access it.
	GetClusterSummary(ctx context.Context, clusterName string, user *UserInfo) (*ClusterSummary, error)

	// CheckAccess verifies if the user can perform the specified action on a cluster.
	// This performs a SelfSubjectAccessReview to check permissions without actually
	// attempting the operation.
	//
	// Pre-flight checks improve user experience by failing fast with clear error
	// messages and reduce noise in Kubernetes audit logs from failed requests.
	//
	// Parameters:
	//   - ctx: Context for the request
	//   - clusterName: Target cluster (empty for local/management cluster)
	//   - user: Authenticated user info for impersonation
	//   - check: Describes the action to check (verb, resource, namespace, etc.)
	//
	// Returns:
	//   - *AccessCheckResult: Contains Allowed/Denied status and reason
	//   - error: Non-nil if the check itself failed (not the same as denied)
	//
	// Example:
	//
	//	result, err := manager.CheckAccess(ctx, "prod-cluster", user, &AccessCheck{
	//		Verb:      "delete",
	//		Resource:  "pods",
	//		Namespace: "production",
	//	})
	//	if err != nil {
	//		return err // Check failed
	//	}
	//	if !result.Allowed {
	//		return fmt.Errorf("permission denied: %s", result.Reason)
	//	}
	CheckAccess(ctx context.Context, clusterName string, user *UserInfo, check *AccessCheck) (*AccessCheckResult, error)

	// Close releases all cached clients and resources.
	// After Close is called, all other methods will return ErrManagerClosed.
	Close() error

	// Stats returns current cache and manager statistics for monitoring.
	// This is useful for health endpoints and operational dashboards.
	Stats() ManagerStats
}

type ClusterDiscoveryError struct {
	Reason string
	Err    error
}

type ClusterInfo struct {
	// Name is the cluster name.
	Name string

	// Namespace is the namespace where the cluster resource and its kubeconfig secret reside.
	Namespace string

	// Endpoint is the API server endpoint (e.g., "https://api.cluster.example.com:6443").
	// Populated from spec.controlPlaneEndpoint when available. Empty if the cluster
	// resource does not have a control plane endpoint set.
	Endpoint string
}

type ClusterListOptions struct {
	// Namespace filters clusters to a specific namespace (organization).
	// If empty, all namespaces are searched.
	Namespace string

	// LabelSelector filters clusters by label selector expression.
	// Uses standard Kubernetes label selector syntax.
	LabelSelector string

	// Provider filters clusters by infrastructure provider.
	Provider string

	// Status filters clusters by phase.
	Status ClusterPhase

	// ReadyOnly filters to only include ready clusters.
	ReadyOnly bool
}

type ClusterNotFoundError struct {
	ClusterName string
	Namespace   string
	Reason      string
}

type ClusterPhase string

type ClusterSummary struct {
	// Name is the unique identifier of the cluster within its namespace.
	// This corresponds to the Cluster API Cluster resource name.
	Name string `json:"name"`

	// Namespace is the organization namespace on the Management Cluster
	// where the CAPI Cluster resource is located.
	Namespace string `json:"namespace"`

	// Provider indicates the infrastructure provider (e.g., "aws", "azure", "vsphere").
	// This is extracted from the CAPI infrastructure reference.
	Provider string `json:"provider,omitempty"`

	// Release is the Giant Swarm release version running on the cluster.
	// Format follows semver, e.g., "19.3.0".
	Release string `json:"release,omitempty"`

	// KubernetesVersion is the Kubernetes version running on the cluster.
	// Format follows semver, e.g., "1.28.5".
	KubernetesVersion string `json:"kubernetesVersion,omitempty"`

	// Status indicates the current lifecycle phase of the cluster.
	// Common values: "Provisioned", "Provisioning", "Deleting", "Failed".
	Status string `json:"status"`

	// Ready indicates whether the cluster is fully operational and
	// ready to accept workloads.
	Ready bool `json:"ready"`

	// ControlPlaneReady indicates whether the control plane components
	// are healthy and operational.
	ControlPlaneReady bool `json:"controlPlaneReady"`

	// InfrastructureReady indicates whether the underlying infrastructure
	// (VMs, networks, etc.) is provisioned and healthy.
	InfrastructureReady bool `json:"infrastructureReady"`

	// NodeCount is the number of ready control plane replicas (from CAPI v1beta2).
	NodeCount int `json:"nodeCount,omitempty"`

	// CreatedAt is the timestamp when the cluster was initially created.
	CreatedAt time.Time `json:"createdAt"`

	// Labels contains the Kubernetes labels applied to the Cluster resource.
	// These often include organization, team, or environment tags.
	Labels map[string]string `json:"labels,omitempty"`

	// Annotations contains the Kubernetes annotations on the Cluster resource.
	// May include operational metadata or external references.
	Annotations map[string]string `json:"annotations,omitempty"`
}

type ConnectionError struct {
	ClusterName string
	Host        string
	Reason      string
	Err         error
}

type ConnectivityConfig struct {
	// ConnectionTimeout is the maximum time to wait for the initial TCP connection
	// to the cluster API server. This applies to the TCP dial phase only.
	//
	// Default: 5 seconds.
	ConnectionTimeout time.Duration

	// RequestTimeout is the maximum time to wait for individual API requests
	// to complete. This includes TLS handshake, sending the request, and receiving
	// the response.
	//
	// Default: 30 seconds.
	RequestTimeout time.Duration

	// RetryAttempts is the number of times to retry a failed connection before
	// giving up. This helps with transient network issues.
	//
	// Default: 3.
	RetryAttempts int

	// RetryBackoff is the initial backoff duration between retry attempts.
	// Subsequent retries use exponential backoff (backoff * 2^attempt).
	//
	// Default: 1 second.
	RetryBackoff time.Duration

	// HealthCheckPath is the API path used for health checks.
	// This path is validated to prevent path injection attacks.
	// Default: "/healthz" (standard Kubernetes health endpoint).
	HealthCheckPath string

	// QPS is the queries per second limit for the Kubernetes client.
	// This controls client-side rate limiting to prevent overwhelming the
	// target cluster's API server.
	//
	// # Operational Considerations
	//
	// The default value of 50 QPS is tuned for AI agent workloads, which
	// typically make burst requests when exploring cluster resources.
	// Consider adjusting this value based on:
	//   - Number of concurrent users/agents
	//   - Target cluster API server capacity
	//   - Workload patterns (batch operations vs. interactive queries)
	//
	// For shared clusters with many users, consider lowering this value
	// to ensure fair resource allocation.
	//
	// Default: 50 (suitable for single-user AI agent workloads).
	QPS float32

	// Burst is the maximum burst size for throttled requests.
	// This allows short bursts of requests above the QPS limit, which is
	// useful for AI agents that often need to fetch multiple resources
	// in quick succession (e.g., listing pods then fetching their logs).
	//
	// # Operational Considerations
	//
	// The default value of 100 allows agents to handle burst scenarios
	// like initial cluster exploration or responding to user queries
	// that require multiple API calls.
	//
	// The burst value should typically be 2x the QPS value. Lower values
	// may cause request throttling during legitimate burst scenarios.
	// Higher values may impact cluster API server performance.
	//
	// Default: 100 (allows burst operations while protecting API servers).
	Burst int
}

type ConnectivityTimeoutError struct {
	// ClusterName is the target cluster that timed out.
	ClusterName string

	// Host is the API server endpoint that couldn't be reached.
	Host string

	// Timeout is the duration waited before giving up (if known).
	Timeout time.Duration

	// Err is the underlying error that caused the timeout.
	Err error
}

type CredentialMode int

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

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

type HybridOAuthClientProviderConfig struct {
	// UserProvider is the OAuth client provider for user-scoped operations
	UserProvider *OAuthClientProvider

	// Logger for audit trail and operational logging
	Logger *slog.Logger

	// ConfigProvider creates in-cluster config (optional, defaults to rest.InClusterConfig)
	ConfigProvider InClusterConfigProvider

	// StrictPrivilegedAccess when true, causes GetPrivilegedClientForSecrets to fail
	// instead of falling back to user credentials when ServiceAccount access is unavailable.
	//
	// # Security Consideration
	//
	// Enable this in production environments where the split-credential model is required.
	// When disabled (default), the system falls back to user credentials, which may require
	// users to have secret read permissions (weaker security model).
	//
	// Default: false (fallback enabled for backward compatibility)
	StrictPrivilegedAccess bool

	// PrivilegedCAPIDiscovery controls whether CAPI cluster discovery uses
	// ServiceAccount credentials instead of user credentials. This acts as
	// the cluster visibility switch:
	//
	//   - true (default): All users can discover all CAPI clusters.
	//     Access control is enforced at the workload cluster level.
	//   - false: Users can only discover clusters they have explicit RBAC
	//     to list, providing per-user cluster visibility filtering.
	//
	// Default: true
	PrivilegedCAPIDiscovery *bool

	// Metrics recorder for privileged access events (optional)
	// When configured, records success/failure/rate_limited/fallback events
	Metrics PrivilegedAccessMetricsRecorder

	// RateLimitPerSecond is the rate limit for privileged access per user (requests/second)
	// Default: 10.0
	RateLimitPerSecond float64

	// RateLimitBurst is the burst size for privileged access per user
	// Default: 20
	RateLimitBurst int

	// RateLimiterCleanupInterval is how often to clean up expired rate limiters
	// Default: 5 minutes
	RateLimiterCleanupInterval time.Duration

	// RateLimiterExpiry is how long to keep a user's rate limiter after last use
	// Default: 10 minutes
	RateLimiterExpiry time.Duration
}

type ImpersonationError struct {
	// ClusterName is the target cluster where impersonation failed.
	ClusterName string

	// UserEmail is the email of the user being impersonated (for logging only).
	UserEmail string

	// GroupCount is the number of groups in the impersonation request.
	GroupCount int

	// Reason describes what went wrong.
	Reason string

	// Err is the underlying error that caused the failure.
	Err error
}

type InClusterConfigProvider func() (*rest.Config, error)

type KubeconfigError struct {
	ClusterName string
	// ResourceName is the name of the Secret or ConfigMap that failed.
	// For kubeconfig secrets: ${CLUSTER_NAME}-kubeconfig
	// For CA ConfigMaps: ${CLUSTER_NAME}-ca-public
	ResourceName string
	Namespace    string
	Reason       string
	Err          error
	// NotFound indicates the resource was not found (vs other errors like invalid data).
	// When true, Is() matches ErrKubeconfigSecretNotFound; otherwise it matches ErrKubeconfigInvalid.
	NotFound bool
}

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

type ManagerOption func(*Manager)

type ManagerStats struct {
	// CacheSize is the current number of cached client entries.
	CacheSize int

	// CacheMaxEntries is the maximum cache capacity.
	CacheMaxEntries int

	// CacheTTL is the configured time-to-live for cache entries.
	CacheTTL time.Duration

	// Closed indicates whether the manager has been closed.
	Closed bool
}

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

type OAuthClientProviderConfig struct {
	// ClusterHost is the Kubernetes API server URL (e.g., "https://kubernetes.default.svc").
	ClusterHost string

	// CACertFile is the path to the CA certificate for TLS verification.
	CACertFile string

	// QPS is the queries per second rate limit for the Kubernetes client.
	QPS float32

	// Burst is the burst limit for the Kubernetes client.
	Burst int

	// Timeout is the request timeout for API calls.
	Timeout time.Duration
}

type OAuthMetricsRecorder interface {
	// RecordOAuthDownstreamAuth records an OAuth downstream authentication attempt.
	// result should be one of: "success", "fallback", "failure", "no_token"
	RecordOAuthDownstreamAuth(ctx context.Context, result string)
}

type PrivilegedAccessMetricsRecorder interface {
	// RecordPrivilegedAccess records a privileged access attempt.
	// Parameters:
	//   - ctx: Request context
	//   - userDomain: User's email domain (e.g., "giantswarm.io") for cardinality control
	//   - operation: The type of privileged operation ("secret_access" or "capi_discovery")
	//   - result: One of "success", "error", "rate_limited", "fallback"
	RecordPrivilegedAccess(ctx context.Context, userDomain, operation, result string)
}

type PrivilegedAccessProvider interface {
	ClientProvider

	// GetPrivilegedClientForSecrets returns a Kubernetes client using ServiceAccount credentials.
	// This client is used ONLY for reading kubeconfig secrets in CAPI mode.
	//
	// # Security
	//
	// - The returned client uses the pod's ServiceAccount credentials
	// - This enables secret access without granting users secret read permissions
	// - The user parameter is used for audit logging only, not for authentication
	// - The returned client should ONLY be used for secret retrieval, not other operations
	//
	// Parameters:
	//   - ctx: Context for the request
	//   - user: User identity for audit logging (who triggered this access)
	//
	// Returns:
	//   - kubernetes.Interface: Client for secret access
	//   - error: Any error during client creation
	GetPrivilegedClientForSecrets(ctx context.Context, user *UserInfo) (kubernetes.Interface, error)

	// GetPrivilegedDynamicClient returns a dynamic client using ServiceAccount credentials.
	// This client is used for CAPI cluster discovery operations.
	//
	// # Security
	//
	// - The returned client uses the pod's ServiceAccount credentials
	// - This enables CAPI cluster discovery without granting users cluster-scoped CAPI permissions
	// - The user parameter is used for audit logging only, not for authentication
	// - The returned client should ONLY be used for CAPI cluster listing/discovery
	//
	// Parameters:
	//   - ctx: Context for the request
	//   - user: User identity for audit logging (who triggered this access)
	//
	// Returns:
	//   - dynamic.Interface: Dynamic client for CAPI operations
	//   - error: Any error during client creation
	GetPrivilegedDynamicClient(ctx context.Context, user *UserInfo) (dynamic.Interface, error)

	// PrivilegedCAPIDiscovery returns whether CAPI cluster discovery uses
	// ServiceAccount credentials instead of user credentials.
	//
	// This setting acts as a cluster visibility switch:
	//   - true (default): All users can discover all CAPI clusters. Access
	//     control is enforced at the workload cluster level via impersonation
	//     or SSO passthrough. Maps to CredentialModeFullPrivileged.
	//   - false: Users can only discover clusters they have RBAC to list.
	//     This provides per-user cluster filtering at the MC level.
	//     Maps to CredentialModePrivilegedSecrets.
	PrivilegedCAPIDiscovery() bool

	// IsStrictMode returns true if strict privileged access mode is enabled.
	// When strict mode is enabled, the Manager will NOT fall back to user
	// credentials if ServiceAccount access fails at runtime. Instead, it
	// returns an error.
	IsStrictMode() bool
}

type SSOPassthroughConfig struct {
	// CAConfigMapSuffix is the suffix for CA ConfigMaps (default: "-ca-public").
	// The full ConfigMap name is: ${CLUSTER_NAME}${CAConfigMapSuffix}
	// These ConfigMaps should be created by an operator that extracts the CA certificate
	// from the CAPI-generated secret.
	CAConfigMapSuffix string

	// TokenExtractor extracts the user's SSO token from context.
	// This is typically oauth.GetIDTokenFromContext.
	TokenExtractor TokenExtractor
}

type StaticClientProvider struct {
	Clientset     kubernetes.Interface
	DynamicClient dynamic.Interface
	RestConfig    *rest.Config
}

type TLSError struct {
	// ClusterName is the target cluster where TLS failed.
	ClusterName string

	// Host is the API server endpoint.
	Host string

	// Reason describes what went wrong in the TLS handshake.
	Reason string

	// Err is the underlying TLS error.
	Err error
}

type TokenExtractor func(ctx context.Context) (string, bool)

type UserInfo struct {
	// Email is the user's email address from the OAuth token's email claim.
	// This is used as the Impersonate-User header value.
	Email string

	// Groups contains the user's group memberships from OAuth claims.
	// These are passed via Impersonate-Group headers for RBAC evaluation.
	Groups []string

	// Extra contains additional claims from the OAuth token that should be
	// propagated to the Kubernetes API server via Impersonate-Extra headers.
	// Common examples include organization IDs, tenant identifiers, or custom claims.
	Extra map[string][]string
}

type ValidationError struct {
	Field  string
	Value  string // Sanitized value (may be truncated or anonymized)
	Reason string
	Err    error
}

type WorkloadClusterAuthMode string