api

type APIKeyInfo struct {
	ID          string       `json:"id"`
	Name        string       `json:"name"`
	KeyPrefix   string       `json:"key_prefix"`
	ExpiresAt   string       `json:"expires_at,omitempty"`
	CreatedAt   string       `json:"created_at"`
	LastUsedAt  string       `json:"last_used_at,omitempty"`
	Permissions []Permission `json:"permissions,omitempty"`
	IsActive    bool         `json:"is_active"`
}

type AccountServiceOverrideRequest struct {
	Enabled        *bool    `json:"enabled,omitempty"`
	Term           *int     `json:"term,omitempty"`
	Payment        *string  `json:"payment,omitempty"`
	Coverage       *float64 `json:"coverage,omitempty"`
	RampSchedule   *string  `json:"ramp_schedule,omitempty"`
	IncludeEngines []string `json:"include_engines,omitempty"`
	ExcludeEngines []string `json:"exclude_engines,omitempty"`
	IncludeRegions []string `json:"include_regions,omitempty"`
	ExcludeRegions []string `json:"exclude_regions,omitempty"`
	IncludeTypes   []string `json:"include_types,omitempty"`
	ExcludeTypes   []string `json:"exclude_types,omitempty"`
}

type AccountSummary struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	ExternalID string `json:"external_id"`
	Provider   string `json:"provider"`
}

type AccountTestResult struct {
	Message string `json:"message"`
	OK      bool   `json:"ok"`
}

type AdminExistsResponse struct {
	AdminExists bool `json:"admin_exists"`
}

type AnalyticsClientInterface interface {
	QueryHistory(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, provider string, start, end time.Time, interval string) ([]HistoryDataPoint, *HistorySummary, error)
	QueryBreakdown(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, start, end time.Time, dimension string) (map[string]BreakdownValue, error)
}

type AnalyticsCollectorInterface interface {
	Collect(ctx context.Context) error
}

type AnalyticsResponse struct {
	Start      string             `json:"start"`
	End        string             `json:"end"`
	Interval   string             `json:"interval"`
	Summary    *HistorySummary    `json:"summary"`
	DataPoints []HistoryDataPoint `json:"data_points"`
}

type AnalyticsSnapshotStoreInterface interface {
	QuerySavings(ctx context.Context, req analytics.QueryRequest) ([]analytics.SavingsSnapshot, error)
	QueryMonthlyTotals(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, months int) ([]analytics.MonthlySummary, error)
	QueryByProvider(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, startDate, endDate time.Time) ([]analytics.ProviderBreakdown, error)
	QueryByService(ctx context.Context, accountUUIDs []string, accountExternalIDsByProvider map[string][]string, provider string, startDate, endDate time.Time) ([]analytics.ServiceBreakdown, error)
}

type AuthLevel int

type AuthServiceInterface interface {
	Login(ctx context.Context, req LoginRequest) (*LoginResponse, error)
	Logout(ctx context.Context, token string) error
	ValidateSession(ctx context.Context, token string) (*Session, error)
	ValidateCSRFToken(ctx context.Context, sessionToken, csrfToken string) error
	SetupAdmin(ctx context.Context, req SetupAdminRequest) (*LoginResponse, error)
	CheckAdminExists(ctx context.Context) (bool, error)
	RequestPasswordReset(ctx context.Context, email string) error
	ConfirmPasswordReset(ctx context.Context, req PasswordResetConfirm) error
	// ResetTokenStatus returns the runtime state of a reset token
	// without consuming it. Used by the GET /api/auth/reset-password/
	// status endpoint so the frontend can branch on expired / used
	// tokens before rendering the reset-password form (issues #460,
	// #461). state is one of "valid" | "expired" | "used"; flow is
	// "reset" | "invite".
	ResetTokenStatus(ctx context.Context, token string) (state string, flow string, err error)
	GetUser(ctx context.Context, userID string) (*User, error)
	UpdateUserProfile(ctx context.Context, userID string, email string, currentPassword string, newPassword string) error
	// User management - uses auth.API* types
	CreateUserAPI(ctx context.Context, req any) (any, error)
	UpdateUserAPI(ctx context.Context, actorUserID, userID string, req any) (any, error)
	DeleteUser(ctx context.Context, userID string) error
	ListUsersAPI(ctx context.Context) (any, error)
	ChangePasswordAPI(ctx context.Context, userID, currentPassword, newPassword string) error
	// MFA lifecycle (issue #497). All four require the user to be
	// already authenticated; setup + disable additionally require a
	// fresh password re-verify carried in the request body.
	MFASetupAPI(ctx context.Context, userID, password string) (secret, provisioningURI string, err error)
	MFAEnableAPI(ctx context.Context, userID, code string) (recoveryCodes []string, err error)
	MFADisableAPI(ctx context.Context, userID, password, codeOrRecovery string) error
	MFARegenerateRecoveryCodesAPI(ctx context.Context, userID, code string) (recoveryCodes []string, err error)
	// Group management - uses auth.API* types
	// CreateGroupAPI / UpdateGroupAPI take the acting principal so the
	// service can enforce the grant ceiling: a caller may not write a
	// permission onto a group that their own effective permissions do not
	// hold, and the money verbs carved out of admin:* are not grantable at
	// all (issues #1550, #1629).
	CreateGroupAPI(ctx context.Context, actorUserID string, req any) (any, error)
	UpdateGroupAPI(ctx context.Context, actorUserID, groupID string, req any) (any, error)
	DeleteGroup(ctx context.Context, groupID string) error
	GetGroupAPI(ctx context.Context, groupID string) (any, error)
	ListGroupsAPI(ctx context.Context) (any, error)
	// Permission checking
	HasPermissionAPI(ctx context.Context, userID, action, resource string) (bool, error)
	// HasPermissionForConstraintsAPI checks action on resource against
	// request-derived constraint sets so per-permission Constraints
	// (MaxPurchaseAmount, Providers, Services, Regions, AccountIDs) are
	// enforced at execution time. Every constraint set must be granted by
	// at least one of the user's permissions (SEC-01, issue #1141).
	HasPermissionForConstraintsAPI(ctx context.Context, userID, action, resource string, constraintSets []auth.PermissionConstraints) (bool, error)
	// GetUserPermissionsAPI returns the effective permission set for a user
	// (union of all group permissions). Used by GET /api/auth/me/permissions.
	// Returns []auth.APIPermission converted to []PermissionEntry by the handler.
	GetUserPermissionsAPI(ctx context.Context, userID string) (any, error)
	// Account access - returns the union of allowed_accounts from all user groups (empty = all access)
	GetAllowedAccountsAPI(ctx context.Context, userID string) ([]string, error)
	// API Key management
	CreateAPIKeyAPI(ctx context.Context, userID string, req any) (any, error)
	ListUserAPIKeysAPI(ctx context.Context, userID string) (any, error)
	// GetAPIKeysUsageStatsAPI returns the section-level usage summary
	// (active count, fixed-window/lifetime request totals, top-3 most
	// active keys) for the calling user's own API keys.
	GetAPIKeysUsageStatsAPI(ctx context.Context, userID string) (any, error)
	DeleteAPIKeyAPI(ctx context.Context, userID, keyID string) error
	RevokeAPIKeyAPI(ctx context.Context, userID, keyID string) error
	ValidateUserAPIKeyAPI(ctx context.Context, apiKey string) (any, any, error)
	// RecordAPIKeyUsageAsync books exactly one request against the given
	// API key ID (the last_used_at timestamp plus the lifetime and
	// fixed-window request counters). Fire-and-forget: the store write
	// happens off the request path, so it returns nothing and never delays
	// or fails the caller's request.
	//
	// Must be called once per inbound request and only from
	// Handler.validateSecurityContext. Calling it from a credential
	// validation path instead would count validations, which a single
	// request performs several times over.
	RecordAPIKeyUsageAsync(keyID string)
	// HasAPIKeyPermissionAPI validates a user API key and checks the
	// requested action/resource against the key's effective permissions
	// (the intersection of the key's scoped permissions with the owning
	// user's group-derived permissions). Returns the owning user's ID, the
	// key's database ID, and whether the permission is held; a non-nil error
	// means the key did not validate or the lookup failed, and callers must
	// deny (fail closed). Wired into requirePermission so per-key scoping is
	// enforced at request time (issue #1142).
	HasAPIKeyPermissionAPI(ctx context.Context, apiKey, action, resource string) (userID, keyID string, allowed bool, err error)
	// HasAPIKeyPermissionForConstraintsAPI checks request-derived permission
	// constraint sets against a user API key's effective permissions (the
	// intersection of the key's own constraints and the owning user's
	// group-derived permissions). Must be called after HasAPIKeyPermissionAPI
	// confirms action/resource access. Enforces per-key caps (MaxPurchaseAmount,
	// Providers, Services, Regions, AccountIDs) that the key's owner cannot
	// override via their broader group permissions (adversarial-review F2).
	HasAPIKeyPermissionForConstraintsAPI(ctx context.Context, keyID, userID, action, resource string, constraintSets []auth.PermissionConstraints) (bool, error)
}

type AzureCompatibleOfferingsRequestBody struct {
	SubscriptionID string                    `json:"subscription_id"`
	Sources        []AzureExchangeSourceBody `json:"sources"`
	Targets        []AzureExchangeTargetBody `json:"targets"`
}

type AzureCompatibleOfferingsResponse struct {
	Offerings []azurecompute.CompatibleOffering `json:"offerings"`
	Preview   *azurecompute.ExchangePreview     `json:"preview"`
}

type AzureExchangeSourceBody struct {
	ReservationID string `json:"reservation_id"`
	Quantity      int32  `json:"quantity"`
}

type AzureExchangeTargetBody struct {
	SKU      string `json:"sku"`
	Location string `json:"location"`
	Term     string `json:"term"`
	Quantity int32  `json:"quantity"`

	// BillingScopeID is optional and is NOT the scope that gets charged:
	// the handler always derives that from the request's authorized
	// subscription_id (azureBillingScopeID), matching every other Azure
	// reservation purchase path in this repo. When supplied it must match
	// the derived scope, so a caller cannot direct the charge at a
	// different subscription than the one their permission constraints
	// were evaluated against.
	BillingScopeID string `json:"billing_scope_id,omitempty"`
}

type AzureExecuteExchangeRequestBody struct {
	SubscriptionID string                    `json:"subscription_id"`
	Sources        []AzureExchangeSourceBody `json:"sources"`
	Targets        []AzureExchangeTargetBody `json:"targets"`
	MaxPaymentDue  string                    `json:"max_payment_due"`
	Currency       string                    `json:"currency"`
}

type AzureExecuteExchangeResponse struct {
	SessionID          string   `json:"session_id"`
	Status             string   `json:"status"`
	NetPayable         *float64 `json:"net_payable"`
	NetPayableCurrency string   `json:"net_payable_currency,omitempty"`
	RefundsTotal       *float64 `json:"refunds_total"`
	PurchasesTotal     *float64 `json:"purchases_total"`
}

type BreakdownResponse struct {
	Data      map[string]BreakdownValue `json:"data"`
	Dimension string                    `json:"dimension"`
	Start     string                    `json:"start"`
	End       string                    `json:"end"`
}

type BreakdownValue struct {
	TotalSavings  float64 `json:"total_savings"`
	TotalUpfront  float64 `json:"total_upfront"`
	PurchaseCount int     `json:"purchase_count"`
	Percentage    float64 `json:"percentage"`
}

type ChangePasswordRequest struct {
	CurrentPassword string `json:"current_password"`
	NewPassword     string `json:"new_password"`
}

type CloudAccountRequest struct {
	Enabled                 *bool  `json:"enabled"`
	AWSWebIdentityTokenFile string `json:"aws_web_identity_token_file"`
	AzureClientID           string `json:"azure_client_id"`
	Provider                string `json:"provider"`
	Name                    string `json:"name"`
	Description             string `json:"description"`
	AWSAuthMode             string `json:"aws_auth_mode"`
	AWSRoleARN              string `json:"aws_role_arn"`
	AWSExternalID           string `json:"aws_external_id"`
	ContactEmail            string `json:"contact_email"`
	GCPWIFAudience          string `json:"gcp_wif_audience"`
	ExternalID              string `json:"external_id"`
	AzureSubscriptionID     string `json:"azure_subscription_id"`
	AzureTenantID           string `json:"azure_tenant_id"`
	AWSBastionID            string `json:"aws_bastion_id"`
	AzureAuthMode           string `json:"azure_auth_mode"`
	GCPProjectID            string `json:"gcp_project_id"`
	GCPClientEmail          string `json:"gcp_client_email"`
	GCPAuthMode             string `json:"gcp_auth_mode"`
	AWSIsOrgRoot            bool   `json:"aws_is_org_root"`
}

type CommitmentOptsInterface interface {
	Get(ctx context.Context) (commitmentopts.Options, error)
	Validate(ctx context.Context, provider, service string, term int, payment string) (bool, error)
}

type ConfigResponse struct {
	Global         *config.GlobalConfig   `json:"global"`
	SourceIdentity *sourceIdentity        `json:"source_identity,omitempty"`
	SourceCloud    string                 `json:"source_cloud,omitempty"`
	Services       []config.ServiceConfig `json:"services"`
}

type ConvertibleRIsResponse struct {
	Instances []ec2svc.ConvertibleRI `json:"instances"`
}

type CoverageBreakdownResponse struct {
	Providers []ProviderCoverageSection `json:"providers"`
}

type CoverageServiceRow struct {
	CoveragePct     *float64 `json:"coverage_pct"`
	Service         string   `json:"service"`
	CoveredMonthly  float64  `json:"covered_monthly"`
	OnDemandMonthly float64  `json:"on_demand_monthly"`
}

type CreateAPIKeyRequest struct {
	ExpiresAt   *time.Time   `json:"expires_at,omitempty"`
	Name        string       `json:"name"`
	Permissions []Permission `json:"permissions,omitempty"`
}

type CreateAPIKeyResponse struct {
	Info   *APIKeyInfo `json:"info"`
	APIKey string      `json:"api_key"` //nolint:gosec // G117: intentional one-time serialization -- this response returns the newly created key to its owner; the key is never re-stored or re-serialized
	KeyID  string      `json:"key_id"`
}

type CreateGroupRequest struct {
	Name            string       `json:"name"`
	Description     string       `json:"description,omitempty"`
	Permissions     []Permission `json:"permissions"`
	AllowedAccounts []string     `json:"allowed_accounts,omitempty"`
}

type CreatePlannedPurchasesRequest struct {
	StartDate string `json:"start_date"`
	Count     int    `json:"count"`
}

type CreatePlannedPurchasesResponse struct {
	Created int `json:"created"`
}

type CreateUserRequest struct {
	Email    string   `json:"email"`
	Password string   `json:"password"` //nolint:gosec // G117: intentional credential field in request/response struct -- value is supplied by the authenticated caller or returned once at creation; not re-stored downstream
	Groups   []string `json:"groups,omitempty"`
}

type CredentialsRequest struct {
	Payload        map[string]interface{} `json:"payload"`
	CredentialType string                 `json:"credential_type"`
}

type CurrentUserResponse struct {
	ID         string   `json:"id"`
	Email      string   `json:"email"`
	Groups     []string `json:"groups,omitempty"`
	MFAEnabled bool     `json:"mfa_enabled"`
}

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

type DashboardSummaryResponse struct {
	ByService               map[string]ServiceSavings `json:"by_service"`
	PotentialMonthlySavings float64                   `json:"potential_monthly_savings"`
	TotalRecommendations    int                       `json:"total_recommendations"`
	ActiveCommitments       int                       `json:"active_commitments"`
	CommittedMonthly        float64                   `json:"committed_monthly"`
	CurrentCoverage         float64                   `json:"current_coverage"`
	TargetCoverage          float64                   `json:"target_coverage"`
	YTDSavings              float64                   `json:"ytd_savings"`
}

type DeploymentInfoResponse struct {
	// APIKeySecretURL is the AWS Console deep-link to the Secrets Manager
	// secret holding the CUDly API key.
	APIKeySecretURL string `json:"api_key_secret_url,omitempty"`
	// DeploymentAWSAccountID is the AWS account ID of the Lambda host,
	// resolved via STS GetCallerIdentity. Empty on non-AWS deployments
	// or when STS is unreachable. Used by the frontend to distinguish
	// legitimate ambient-credential executions from orphan rows (#608).
	DeploymentAWSAccountID string `json:"deployment_aws_account_id,omitempty"`
}

type DiscoverOrgRequest struct {
	AccountID string `json:"account_id"`
}

type DiscoverOrgResult struct {
	Discovered int `json:"discovered"`
	Created    int `json:"created"`
	Skipped    int `json:"skipped"`
}

type EmptyServiceConfigResponse struct{}

type ExchangeExecuteRequestBody struct {
	TargetOfferingID string               `json:"target_offering_id,omitempty"`
	MaxPaymentDueUSD string               `json:"max_payment_due_usd"`
	Region           string               `json:"region,omitempty"`
	RIIDs            []string             `json:"ri_ids"`
	Targets          []ExchangeTargetBody `json:"targets,omitempty"`
	TargetCount      int32                `json:"target_count,omitempty"`
}

type ExchangeExecuteResponse struct {
	Quote      *exchange.ExchangeQuoteSummary `json:"quote"`
	ExchangeID string                         `json:"exchange_id"`
}

type ExchangeQuoteRequestBody struct {
	TargetOfferingID string               `json:"target_offering_id,omitempty"`
	Region           string               `json:"region,omitempty"`
	RIIDs            []string             `json:"ri_ids"`
	Targets          []ExchangeTargetBody `json:"targets,omitempty"`
	TargetCount      int32                `json:"target_count,omitempty"`
}

type ExchangeTargetBody struct {
	OfferingID string `json:"offering_id"`
	Count      int32  `json:"count"`
}

type ExchangeableAzureRIsResponse struct {
	Reservations []azurecompute.ExchangeableReservation `json:"reservations"`
}

type ExecutePurchaseRequest struct {
	// Recommendations are matched against the stored recommendation set on
	// (provider, cloud_account_id, service, region, resource_type, engine,
	// term, payment). Only count, recommended_count and selected are taken
	// from the request; id, details and every cost field are replaced from
	// the stored row scaled by count (priceRecommendationsFromStore, #1905).
	Recommendations []config.RecommendationRecord `json:"recommendations"`
	// CapacityPercent is what fraction (1..100) of the originally-
	// recommended counts the user chose in the bulk Purchase flow.
	// Audit-only: the Recommendations slice already carries scaled
	// counts, so backend math ignores this field for purchase work.
	// 0 / absent defaults to 100 ("full capacity").
	CapacityPercent int `json:"capacity_percent,omitempty"`
	// ExecuteMode controls whether this request bypasses the approval
	// email and executes the purchase immediately. The only accepted
	// non-empty value is "direct"; any other value is treated as the
	// default approval-required flow. The handler re-checks the
	// execute-any/execute-own RBAC gate before honoring "direct",
	// even if the session already passed the execute:purchases gate in
	// validateExecutePurchaseRequest, so a client that sets this field
	// without the privilege receives a 403 rather than silent fallback.
	ExecuteMode string `json:"execute_mode,omitempty"`
}

type FederationIaCResponse struct {
	Filename        string `json:"filename"`
	Content         string `json:"content"`
	ContentType     string `json:"content_type"`
	ContentEncoding string `json:"content_encoding,omitempty"` // "base64" for binary (zip)
}

type Group struct {
	ID              string       `json:"id"`
	Name            string       `json:"name"`
	Description     string       `json:"description,omitempty"`
	CreatedAt       string       `json:"created_at,omitempty"`
	UpdatedAt       string       `json:"updated_at,omitempty"`
	Permissions     []Permission `json:"permissions"`
	AllowedAccounts []string     `json:"allowed_accounts,omitempty"`
}

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

type HandlerConfig struct {
	AnalyticsClient     AnalyticsClientInterface
	AnalyticsCollector  AnalyticsCollectorInterface
	PurchaseManager     PurchaseManagerInterface
	RateLimiter         RateLimiterInterface
	AuthService         AuthServiceInterface
	CommitmentOpts      CommitmentOptsInterface
	OIDCSigner          oidc.Signer
	AnalyticsSnapshots  AnalyticsSnapshotStoreInterface
	CredentialStore     credentials.CredentialStore
	EmailNotifier       email.SenderInterface
	Scheduler           SchedulerInterface
	ConfigStore         config.StoreInterface
	DashboardURL        string
	CORSAllowedOrigin   string
	DashboardBucket     string
	OIDCIssuerURL       string
	APIKeySecretARN     string
	EncryptionKeySource string
	EnableDashboard     bool
}

type HealthCheck struct {
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

type HealthResponse struct {
	Timestamp time.Time              `json:"timestamp"`
	Checks    map[string]HealthCheck `json:"checks"`
	Status    string                 `json:"status"`
}

type HistoryDataPoint struct {
	Timestamp         time.Time          `json:"timestamp"`
	ByService         map[string]float64 `json:"by_service,omitempty"`
	ByProvider        map[string]float64 `json:"by_provider,omitempty"`
	TotalSavings      float64            `json:"total_savings"`
	TotalUpfront      float64            `json:"total_upfront"`
	PurchaseCount     int                `json:"purchase_count"`
	CumulativeSavings float64            `json:"cumulative_savings"`
}

type HistoryResponse struct {
	Purchases []config.PurchaseHistoryRecord `json:"purchases"`
	Summary   HistorySummary                 `json:"summary"`
}

type HistorySummary struct {
	TotalPurchases int `json:"total_purchases"`
	TotalCompleted int `json:"total_completed"`
	TotalPending   int `json:"total_pending"`
	// TotalInProgress counts executions that have been approved but whose
	// synchronous purchase has not finalized (status approved/running/paused).
	// Tracked separately from pending and excluded from the dollar totals so an
	// interrupted approval (issue #621) stays visible without inflating
	// committed spend/savings.
	TotalInProgress int `json:"total_in_progress"`
	TotalFailed     int `json:"total_failed"`
	TotalExpired    int `json:"total_expired"`
	// TotalRevoked counts commitments that have been revoked/refunded via
	// MarkPurchaseRevoked. They are excluded from TotalCompleted and all dollar
	// totals because the provider has canceled the commitment.
	TotalRevoked        int     `json:"total_revoked"`
	TotalUpfront        float64 `json:"total_upfront"`
	TotalMonthlySavings float64 `json:"total_monthly_savings"`
	TotalAnnualSavings  float64 `json:"total_annual_savings"`
}

type HistorySummaryAnalytics struct {
	TotalPeriodSavings      float64 `json:"total_period_savings"`
	TotalUpfrontSpent       float64 `json:"total_upfront_spent"`
	PurchaseCount           int     `json:"purchase_count"`
	AverageSavingsPerPeriod float64 `json:"average_savings_per_period"`
	PeakSavings             float64 `json:"peak_savings"`
}

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

type InventoryCommitment struct {
	StartDate time.Time `json:"start_date"`
	EndDate   time.Time `json:"end_date"`
	// MonthlyCost is nil when the source purchase_history row has a NULL
	// monthly_cost (provider did not return a monthly breakdown). The
	// frontend renders "--" for nil and "$X.XX" when non-nil.
	MonthlyCost      *float64 `json:"monthly_cost"`
	Provider         string   `json:"provider"`
	AccountID        string   `json:"account_id"`
	AccountName      string   `json:"account_name,omitempty"`
	Service          string   `json:"service"`
	ResourceType     string   `json:"resource_type,omitempty"`
	Region           string   `json:"region"`
	Status           string   `json:"status"`
	ID               string   `json:"id"`
	PaymentOption    string   `json:"payment_option,omitempty"`
	TermYears        int      `json:"term_years"`
	UpfrontCost      float64  `json:"upfront_cost"`
	EstimatedSavings float64  `json:"estimated_savings"`
	Count            int      `json:"count"`
}

type InventoryCommitmentsResponse struct {
	Commitments []InventoryCommitment `json:"commitments"`
}

type LambdaInvokerInterface interface {
	Invoke(ctx context.Context, params *lambda.InvokeInput, optFns ...func(*lambda.Options)) (*lambda.InvokeOutput, error)
}

type LoginRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"` //nolint:gosec // G117: intentional credential field in request/response struct -- value is supplied by the authenticated caller or returned once at creation; not re-stored downstream
	MFACode  string `json:"mfa_code,omitempty"`
}

type LoginResponse struct {
	Token     string    `json:"token"`
	ExpiresAt string    `json:"expires_at"`
	User      *UserInfo `json:"user"`
	CSRFToken string    `json:"csrf_token,omitempty"`
}

type MFADisableRequest struct {
	Password string `json:"password"` //nolint:gosec // G117: intentional credential field in request/response struct -- value is supplied by the authenticated caller or returned once at creation; not re-stored downstream
	Code     string `json:"code"`
}

type MFAEnableRequest struct {
	Code string `json:"code"`
}

type MFAEnableResponse struct {
	RecoveryCodes []string `json:"recovery_codes"`
}

type MFARegenerateRequest struct {
	Code string `json:"code"`
}

type MFARegenerateResponse struct {
	RecoveryCodes []string `json:"recovery_codes"`
}

type MFASetupRequest struct {
	Password string `json:"password"` //nolint:gosec // G117: intentional credential field in request/response struct -- value is supplied by the authenticated caller or returned once at creation; not re-stored downstream
}

type MFASetupResponse struct {
	Secret          string `json:"secret"` //nolint:gosec // G117: intentional credential field in request/response struct -- value is supplied by the authenticated caller or returned once at creation; not re-stored downstream
	ProvisioningURI string `json:"provisioning_uri"`
}

type MarketplaceListRequest struct {
	PriceSchedule []MarketplacePriceTier `json:"price_schedule,omitempty"`
}

type MarketplaceListResponse struct {
	ListingID     string                 `json:"listing_id"`
	ListingState  string                 `json:"listing_state"`
	PriceSchedule []MarketplacePriceTier `json:"price_schedule"`
	AWSFeePercent float64                `json:"aws_fee_percent"`
	Note          string                 `json:"note,omitempty"`
}

type MarketplacePriceTier struct {
	// TermMonths is the remaining-months count this tier covers.
	TermMonths int64 `json:"term_months"`
	// Price is the USD list price per unit for this tier.
	Price float64 `json:"price"`
}

type PasswordResetConfirm struct {
	Token       string `json:"token"`
	NewPassword string `json:"new_password"`
}

type PasswordResetRequest struct {
	Email string `json:"email"`
}

type PatchPlanRequest struct {
	Name                   *string `json:"name,omitempty"`
	Enabled                *bool   `json:"enabled,omitempty"`
	AutoPurchase           *bool   `json:"auto_purchase,omitempty"`
	NotificationDaysBefore *int    `json:"notification_days_before,omitempty"`
}

type PaymentAdjustment struct {
	// RecIndex is the rec's position in the request's recommendations slice.
	RecIndex int    `json:"rec_index"`
	Provider string `json:"provider"`
	Service  string `json:"service"`
	// RequestedPaymentOption is the caller's token after trim/lowercase only
	// (case-only differences are not surfaced as adjustments, matching the
	// operator WARN-log semantics).
	RequestedPaymentOption string `json:"requested_payment_option"`
	// AppliedPaymentOption is the provider-canonical token the purchase will
	// actually carry.
	AppliedPaymentOption string `json:"applied_payment_option"`
	Reason               string `json:"reason"`
}

type Permission struct {
	Constraints *PermissionConstraint `json:"constraints,omitempty"`
	Action      string                `json:"action"`
	Resource    string                `json:"resource"`
}

type PermissionConstraint struct {
	Accounts  []string `json:"accounts,omitempty"`
	Providers []string `json:"providers,omitempty"`
	Services  []string `json:"services,omitempty"`
	Regions   []string `json:"regions,omitempty"`
	MaxAmount float64  `json:"max_amount,omitempty"`
}

type PermissionEntry struct {
	Action   string `json:"action"`
	Resource string `json:"resource"`
}

type PlanHealthFactor struct {
	Code    PlanHealthFactorCode `json:"code"`
	Penalty int                  `json:"penalty"`
	Note    string               `json:"note"`
}

type PlanHealthFactorCode string

type PlanRequest struct {
	Payment                string   `json:"payment,omitempty"`
	Description            string   `json:"description,omitempty"`
	RampSchedule           string   `json:"ramp_schedule,omitempty"`
	Name                   string   `json:"name"`
	Provider               string   `json:"provider,omitempty"`
	Service                string   `json:"service,omitempty"`
	TargetAccounts         []string `json:"target_accounts,omitempty"`
	TargetCoverage         int      `json:"target_coverage,omitempty"`
	Term                   int      `json:"term,omitempty"`
	NotificationDaysBefore int      `json:"notification_days_before"`
	CustomStepPercent      int      `json:"custom_step_percent,omitempty"`
	CustomIntervalDays     int      `json:"custom_interval_days,omitempty"`
	AutoPurchase           bool     `json:"auto_purchase"`
	Enabled                bool     `json:"enabled"`
}

type PlanWithHealth struct {
	config.PurchasePlan
	HealthScore   *int               `json:"health_score"`
	HealthFactors []PlanHealthFactor `json:"health_factors,omitempty"`
}

type PlannedPurchase struct {
	// CreatedByUserID is the UUID of the user who created the scheduled
	// purchase, mirroring PurchaseHistoryRecord.CreatedByUserID. The
	// frontend gates the row action buttons on creator-scope ownership
	// (issue #950); omitted for legacy rows with a NULL creator.
	CreatedByUserID  *string `json:"created_by_user_id,omitempty"`
	Status           string  `json:"status"`
	PlanID           string  `json:"plan_id"`
	PlanName         string  `json:"plan_name"`
	ScheduledDate    string  `json:"scheduled_date"`
	Provider         string  `json:"provider"`
	Service          string  `json:"service"`
	ResourceType     string  `json:"resource_type"`
	Region           string  `json:"region"`
	ID               string  `json:"id"`
	Payment          string  `json:"payment"`
	Count            int     `json:"count"`
	UpfrontCost      float64 `json:"upfront_cost"`
	EstimatedSavings float64 `json:"estimated_savings"`
	StepNumber       int     `json:"step_number"`
	TotalSteps       int     `json:"total_steps"`
	Term             int     `json:"term"`
}

type PlannedPurchasesResponse struct {
	Purchases []PlannedPurchase `json:"purchases"`
}

type PlansResponse struct {
	Plans []PlanWithHealth `json:"plans"`
}

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

type Principal struct {
	// Field order groups the pointer-bearing Session ahead of the trailing
	// string so the struct satisfies govet fieldalignment.
	Kind    PrincipalKind
	Session *Session // non-nil when a valid bearer session was presented
	UserID  string   // empty for PrincipalAdminAPIKey
	Email   string   // empty for PrincipalAdminAPIKey; populated for session/user-api-key
	// APIKeyID is the database ID of the user API key the request
	// authenticated with. Non-empty exactly when Kind is
	// PrincipalUserAPIKey; empty for every other kind. It lets
	// validateSecurityContext book the key's usage once per request without
	// re-validating the credential.
	APIKeyID string
}

type PrincipalKind string

type ProfileUpdateRequest struct {
	Email           string `json:"email"`
	CurrentPassword string `json:"current_password"`
	NewPassword     string `json:"new_password,omitempty"`
}

type ProviderCoverageSection struct {
	OverallCoveragePct *float64             `json:"overall_coverage_pct"`
	Provider           string               `json:"provider"`
	Services           []CoverageServiceRow `json:"services"`
}

type PublicInfoResponse struct {
	Version     string `json:"version"`
	AdminExists bool   `json:"admin_exists"`
}

type PurchaseManagerInterface interface {
	ApproveExecution(ctx context.Context, execID, token, actor string) error
	ApproveAndExecute(ctx context.Context, execID, actor string, transitionedBy *string) error
	CancelExecution(ctx context.Context, execID, token, actor string) error
}

type RIExchangeConfigResponse struct {
	Mode                     string  `json:"mode"`
	UtilizationThreshold     float64 `json:"utilization_threshold"`
	MaxPaymentPerExchangeUSD float64 `json:"max_payment_per_exchange_usd"`
	MaxPaymentDailyUSD       float64 `json:"max_payment_daily_usd"`
	LookbackDays             int     `json:"lookback_days"`
	AutoExchangeEnabled      bool    `json:"auto_exchange_enabled"`
}

type RIExchangeConfigUpdateRequest struct {
	Mode                     string  `json:"mode"`
	UtilizationThreshold     float64 `json:"utilization_threshold"`
	MaxPaymentPerExchangeUSD float64 `json:"max_payment_per_exchange_usd"`
	MaxPaymentDailyUSD       float64 `json:"max_payment_daily_usd"`
	LookbackDays             int     `json:"lookback_days"`
	AutoExchangeEnabled      bool    `json:"auto_exchange_enabled"`
}

type RIExchangeHistoryResponse struct {
	Records []config.RIExchangeRecord `json:"records"`
}

type RIUtilizationResponse struct {
	Utilization []recommendations.RIUtilization `json:"utilization"`
}

type RateLimitConfig struct {
	MaxAttempts int           // Maximum number of attempts allowed
	WindowSecs  int           // Time window in seconds
	Window      time.Duration // Computed time window (for convenience)
}

type RateLimiterInterface interface {
	// Allow checks if a request should be allowed based on rate limits
	// Returns (allowed bool, error)
	Allow(ctx context.Context, key string, endpoint string) (bool, error)

	// AllowWithIP is a convenience method for IP-based rate limiting
	AllowWithIP(ctx context.Context, ip string, endpoint string) (bool, error)

	// AllowWithEmail is a convenience method for email-based rate limiting
	AllowWithEmail(ctx context.Context, email string, endpoint string) (bool, error)

	// AllowWithUser is a convenience method for user-based rate limiting
	AllowWithUser(ctx context.Context, userID string, endpoint string) (bool, error)
}

type RecommendationDetailResponse struct {
	ID               string       `json:"id"`
	UsageHistory     []UsagePoint `json:"usage_history"`
	ConfidenceBucket string       `json:"confidence_bucket"`
	ProvenanceNote   string       `json:"provenance_note"`
	// HiddenBy is non-nil when the rec is filtered out by an account-service
	// override (issue #214). Each element names one failing dimension:
	// "enabled=false", "engine", "region", or "resource_type". The frontend
	// renders a "hidden by your override" banner when this field is present.
	// Absent (null) means the rec is fully visible.
	HiddenBy []string `json:"hidden_by,omitempty"`
}

type RecommendationsResponse struct {
	Recommendations []config.RecommendationRecord `json:"recommendations"`
	Regions         []string                      `json:"regions"`
	Summary         RecommendationsSummary        `json:"summary"`
}

type RecommendationsSummary struct {
	TotalCount          int     `json:"total_count"`
	TotalMonthlySavings float64 `json:"total_monthly_savings"`
	TotalUpfrontCost    float64 `json:"total_upfront_cost"`
	AvgPaybackMonths    float64 `json:"avg_payback_months"`
}

type RefreshResponse struct {
	StartedAt       time.Time  `json:"started_at"`
	LastCollectedAt *time.Time `json:"last_collected_at"`
}

type RegistrationRequest struct {
	Provider            string `json:"provider"`
	ExternalID          string `json:"external_id"`
	AccountName         string `json:"account_name"`
	ContactEmail        string `json:"contact_email"`
	Description         string `json:"description"`
	SourceProvider      string `json:"source_provider"`
	AWSRoleARN          string `json:"aws_role_arn"`
	AWSAuthMode         string `json:"aws_auth_mode"`
	AWSExternalID       string `json:"aws_external_id"`
	AzureSubscriptionID string `json:"azure_subscription_id"`
	AzureTenantID       string `json:"azure_tenant_id"`
	AzureClientID       string `json:"azure_client_id"`
	AzureAuthMode       string `json:"azure_auth_mode"`
	GCPProjectID        string `json:"gcp_project_id"`
	GCPClientEmail      string `json:"gcp_client_email"`
	GCPAuthMode         string `json:"gcp_auth_mode"`
	GCPWIFAudience      string `json:"gcp_wif_audience"`
	CredentialType      string `json:"credential_type"`
	CredentialPayload   string `json:"credential_payload"`
}

type RegistrationStatusResponse struct {
	Status          string `json:"status"`
	CreatedAt       string `json:"created_at"`
	RejectionReason string `json:"rejection_reason,omitempty"`
}

type RejectRequest struct {
	Reason string `json:"reason"`
}

type ReshapeRecommendationsResponse struct {
	RecsCollectedAt *time.Time                       `json:"recs_collected_at,omitempty"`
	RecsStaleness   string                           `json:"recs_staleness,omitempty"`
	Recommendations []exchange.ReshapeRecommendation `json:"recommendations"`
}

type Route struct {
	Handler    RouteHandler
	ExactPath  string
	PathPrefix string
	PathSuffix string
	Method     string
	Auth       AuthLevel
}

type RouteHandler func(ctx context.Context, req *events.LambdaFunctionURLRequest, params map[string]string) (any, error)

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

type SchedulerInterface interface {
	CollectRecommendations(ctx context.Context, ownerToken string) (*scheduler.CollectResult, error)
	ListRecommendations(ctx context.Context, filter config.RecommendationFilter) ([]config.RecommendationRecord, error)
	// GetRecommendationByID fetches a single rec by its application-level id,
	// bypassing account-override filtering so deep-linked URLs to override-
	// hidden recs resolve. hiddenBy is non-nil when the rec would be dropped by
	// the override filter; callers render a "hidden" banner. Returns nil, nil,
	// nil when the rec is absent or fully suppressed.
	GetRecommendationByID(ctx context.Context, id string) (rec *config.RecommendationRecord, hiddenBy []string, err error)
}

type ServiceSavings struct {
	PotentialSavings float64 `json:"potential_savings"`
	CurrentSavings   float64 `json:"current_savings"`
}

type Session struct {
	UserID string `json:"user_id"`
	Email  string `json:"email"`
	// UserAPIKeyID is the database key ID when the request was authenticated via
	// a user API key (not the admin infra key). Empty for bearer-token and
	// admin-API-key sessions. Used by requirePermissionConstraints to evaluate
	// constraints against the key's effective permissions rather than the owning
	// user's full group permissions (adversarial-review F2).
	UserAPIKeyID string `json:"-"`
}

type SetupAdminRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"` //nolint:gosec // G117: intentional credential field in request/response struct -- value is supplied by the authenticated caller or returned once at creation; not re-stored downstream
}

type StatusResponse struct {
	Status string `json:"status"`
}

type TargetOfferingsResponse struct {
	Offerings []ec2svc.TargetOffering `json:"offerings"`
}

type TrendsResponse struct {
	Start    string                        `json:"start"`
	End      string                        `json:"end"`
	Monthly  []analytics.MonthlySummary    `json:"monthly"`
	Provider []analytics.ProviderBreakdown `json:"by_provider"`
	Service  []analytics.ServiceBreakdown  `json:"by_service"`
	Months   int                           `json:"months"`
}

type UpcomingPurchase struct {
	// CreatedByUserID propagates the underlying execution's
	// created_by_user_id so the dashboard widget can apply the same
	// creator-scope ownership gate the Plans page uses (issue #950).
	// Without it the widget renders a "Cancel" button on every row
	// while the backend now 403s for non-owners -- a UX hole that
	// surfaces as a confusing toast on click. Mirrors the field on
	// PlannedPurchase / PurchaseHistoryEntry. omitempty so legacy
	// NULL-creator rows keep the JSON shape they had pre-fix.
	CreatedByUserID  *string `json:"created_by_user_id,omitempty"`
	ExecutionID      string  `json:"execution_id"`
	PlanID           string  `json:"plan_id"`
	PlanName         string  `json:"plan_name"`
	ScheduledDate    string  `json:"scheduled_date"`
	Provider         string  `json:"provider"`
	Service          string  `json:"service"`
	StepNumber       int     `json:"step_number"`
	TotalSteps       int     `json:"total_steps"`
	EstimatedSavings float64 `json:"estimated_savings"`
}

type UpcomingPurchaseResponse struct {
	Purchases []UpcomingPurchase `json:"purchases"`
}

type UpdateGroupRequest struct {
	Name            string       `json:"name,omitempty"`
	Description     string       `json:"description,omitempty"`
	Permissions     []Permission `json:"permissions,omitempty"`
	AllowedAccounts []string     `json:"allowed_accounts,omitempty"`
}

type UpdateUserRequest struct {
	Email  string   `json:"email,omitempty"`
	Groups []string `json:"groups,omitempty"`
}

type UsagePoint struct {
	Timestamp string  `json:"timestamp"`
	CPUPct    float64 `json:"cpu_pct"`
	MemPct    float64 `json:"mem_pct"`
}

type User struct {
	ID         string   `json:"id"`
	Email      string   `json:"email"`
	CreatedAt  string   `json:"created_at,omitempty"`
	UpdatedAt  string   `json:"updated_at,omitempty"`
	Groups     []string `json:"groups,omitempty"`
	MFAEnabled bool     `json:"mfa_enabled"`
}

type UserInfo struct {
	ID         string   `json:"id"`
	Email      string   `json:"email"`
	Groups     []string `json:"groups,omitempty"`
	MFAEnabled bool     `json:"mfa_enabled"`
}

type UserPermissionsResponse struct {
	Permissions []PermissionEntry `json:"permissions"`
	IsAdmin     bool              `json:"is_admin"`
}

type VersionResponse struct {
	Version   string `json:"version"`
	GitSHA    string `json:"git_sha"`
	BuildTime string `json:"build_time"`
}