bff

type BFFErrorResponse struct {
	// Error is the error code.
	Error string `json:"error" doc:"Error code" example:"session_expired"`

	// Message is the human-readable error message.
	Message string `json:"message" doc:"Human-readable error message" example:"Your session has expired"`
}

type ClientIPConfig struct {
	// TrustCloudflare enables Cloudflare header support.
	// When true, checks CF-Connecting-IP and True-Client-IP headers.
	// Default: false.
	TrustCloudflare bool

	// TrustProxy enables standard proxy headers (X-Forwarded-For, X-Real-IP).
	// Only enable if behind a trusted reverse proxy.
	// Default: false.
	TrustProxy bool

	// TrustedProxies is a list of trusted proxy IP ranges.
	// If set, proxy headers are only trusted when the request comes from these IPs.
	// Supports CIDR notation (e.g., "10.0.0.0/8", "172.16.0.0/12").
	TrustedProxies []string

	// CloudflareIPRanges can be set to validate that CF headers come from Cloudflare.
	// If empty and TrustCloudflare is true, CF headers are trusted unconditionally.
	// Cloudflare publishes their IP ranges at:
	// https://www.cloudflare.com/ips-v4 and https://www.cloudflare.com/ips-v6
	CloudflareIPRanges []string
	// contains filtered or unexported fields
}

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

type CookieConfig struct {
	// Name is the cookie name. Default: "cf_session".
	Name string

	// Domain is the cookie domain. If empty, uses the request host.
	Domain string

	// Path is the cookie path. Default: "/".
	Path string

	// MaxAge is the cookie max age in seconds. Default: 0 (session cookie).
	// Set to -1 to delete the cookie.
	MaxAge int

	// Secure indicates the cookie should only be sent over HTTPS.
	// Default: true.
	Secure bool

	// HTTPOnly prevents JavaScript access to the cookie.
	// Default: true (required for security).
	HTTPOnly bool

	// SameSite controls cross-site cookie behavior.
	// Default: SameSiteStrictMode.
	SameSite http.SameSite
}

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

type CreateSessionParams struct {
	UserID                uuid.UUID
	OrganizationID        *uuid.UUID
	AccessToken           string
	RefreshToken          string
	AccessTokenExpiresIn  time.Duration
	RefreshTokenExpiresIn time.Duration
	DPoPKeyPairJSON       []byte // Serialized DPoP key pair (from dpop.KeyPair.SerializeJSON())
	DPoPThumbprint        string // JWK thumbprint of the DPoP key pair
	Metadata              map[string]string
}

type EndpointLimit struct {
	RequestsPerMinute int
	BurstSize         int
}

type GetSessionInput struct{}

type GetSessionOutput struct {
	Body SessionStatusResponse
}

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

type HandlerConfig struct {
	// Store is the session store. Required.
	Store Store

	// CookieConfig configures session cookies.
	// If zero value, uses DefaultCookieConfig().
	CookieConfig CookieConfig

	// ProxyConfig configures the API proxy.
	// TargetURL is required if using the proxy.
	ProxyConfig ProxyConfig

	// AllowedOrigins is a list of allowed origins for CSRF protection.
	// Required for security. Example: ["https://myapp.com", "https://app.myapp.com"]
	AllowedOrigins []string

	// ClientIPConfig configures client IP extraction.
	// If zero value, uses DefaultClientIPConfig().
	ClientIPConfig ClientIPConfig

	// SessionIDGenerator generates session IDs.
	// If nil, uses GenerateSessionID().
	SessionIDGenerator func() (string, error)

	// OnCreateSession is called when a session is created.
	// Can be used to persist refresh tokens to a database.
	OnCreateSession func(ctx context.Context, session *Session) error

	// OnRefresh is called to refresh tokens.
	// Must return new access token, optional new refresh token, and expiry.
	// If nil, the /refresh endpoint returns 501 Not Implemented.
	OnRefresh func(ctx context.Context, session *Session) (*TokenRefreshResult, error)

	// OnLogout is called when a session is logged out.
	// Can be used to revoke refresh tokens in the database.
	OnLogout func(ctx context.Context, session *Session) error

	// OnSessionLoad is called after a session is loaded from the store.
	// Can be used for logging or enriching session data.
	OnSessionLoad func(ctx context.Context, session *Session) error

	// BasePath is the base path for BFF routes.
	// Default: "" (routes at root of the mounted router).
	BasePath string

	// APIPathPrefix is the path prefix for proxied API requests.
	// Default: "/api".
	APIPathPrefix string

	// EnableProxyForPublicRoutes allows unauthenticated proxy requests.
	// When true, /api/* routes work without a session (for public APIs).
	// Default: false.
	EnableProxyForPublicRoutes bool

	// RateLimitConfig configures rate limiting for BFF endpoints.
	// If nil, rate limiting is disabled.
	RateLimitConfig *RateLimitConfig
}

type HumaConfig struct {
	// Handler is the BFF handler to use for operations.
	Handler *Handler

	// PathPrefix is the prefix for all BFF routes.
	// Default: "/bff".
	PathPrefix string

	// Tags are OpenAPI tags for BFF endpoints.
	// Default: ["BFF"].
	Tags []string

	// IncludeRateLimitDocs adds x-ratelimit-* extensions to OpenAPI.
	// Default: true.
	IncludeRateLimitDocs bool
}

type LogoutInput struct {
	Origin string `header:"Origin" required:"true" doc:"Origin header for CSRF protection"`
}

type LogoutOutput struct {
	Body LogoutResponse
}

type LogoutResponse struct {
	// Message indicates the logout result.
	Message string `json:"message" doc:"Logout result message" example:"Logged out successfully"`
}

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

type MiddlewareConfig struct {
	// Store is the session store.
	Store Store

	// CookieManager handles session cookies.
	CookieManager *CookieManager

	// RefreshThreshold is how long before access token expiry to trigger refresh.
	// Default: 5 minutes.
	RefreshThreshold time.Duration

	// OnSessionLoad is called after a session is loaded.
	// Can be used for logging or session modification.
	OnSessionLoad func(ctx context.Context, session *Session) error

	// OnSessionExpired is called when a session is expired.
	OnSessionExpired func(w http.ResponseWriter, r *http.Request)

	// OnSessionInvalid is called when a session is invalid.
	OnSessionInvalid func(w http.ResponseWriter, r *http.Request)

	// OnNoSession is called when no session is found and RequireSession is true.
	OnNoSession func(w http.ResponseWriter, r *http.Request)

	// RequireSession when true rejects requests without valid sessions.
	RequireSession bool

	// TouchOnAccess when true updates LastAccessedAt on each request.
	TouchOnAccess bool
}

type OriginConfig struct {
	// AllowedOrigins is a list of allowed origins.
	// Origins should be in the format "https://example.com" (no trailing slash).
	AllowedOrigins []string

	// AllowedHosts is a list of allowed hosts (without scheme).
	// This is an alternative to AllowedOrigins for simpler configuration.
	AllowedHosts []string

	// OnError is called when origin validation fails.
	// If nil, returns 403 Forbidden.
	OnError func(w http.ResponseWriter, r *http.Request)

	// AllowMissingOrigin allows requests without Origin header.
	// Default: false (more secure).
	AllowMissingOrigin bool

	// CheckReferer uses Referer header as fallback when Origin is missing.
	// Default: true.
	CheckReferer bool

	// SkipMethods is a list of HTTP methods to skip origin validation.
	// Typically safe methods (GET, HEAD, OPTIONS) can be skipped.
	// Default: none (validate all methods).
	SkipMethods []string
}

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

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

type ProxyConfig struct {
	// TargetURL is the base URL of the API backend.
	TargetURL string

	// UseDPoP enables DPoP proof injection.
	// Default: true
	UseDPoP bool

	// Client is the HTTP client to use for proxied requests.
	// If nil, uses http.DefaultClient.
	Client *http.Client

	// Timeout is the request timeout.
	// Default: 30 seconds.
	Timeout time.Duration

	// OnError is called when a proxy error occurs.
	// If nil, returns 502 Bad Gateway.
	OnError func(w http.ResponseWriter, r *http.Request, err error)

	// OnRequestRewrite allows modifying the proxied request before sending.
	OnRequestRewrite func(r *http.Request, session *Session)

	// PathRewrite allows modifying the request path.
	// The function receives the original path and returns the rewritten path.
	PathRewrite func(path string) string

	// StripPrefix removes a prefix from the request path before proxying.
	StripPrefix string

	// HeadersToForward specifies which request headers to forward.
	// If empty, forwards all headers except hop-by-hop headers.
	HeadersToForward []string

	// HeadersToRemove specifies headers to remove from the proxied request.
	HeadersToRemove []string

	// ResponseHeadersToRemove specifies headers to remove from the response.
	ResponseHeadersToRemove []string
}

type RateLimitConfig struct {
	// RequestsPerMinute is the sustained request rate.
	// Default: 60.
	RequestsPerMinute int

	// BurstSize is the maximum burst of requests allowed.
	// Default: 10.
	BurstSize int

	// EndpointLimits allows per-endpoint rate limit overrides.
	// Key is the endpoint path (e.g., "/refresh", "/logout").
	EndpointLimits map[string]EndpointLimit

	// KeyFunc extracts the rate limit key from a request.
	// Default: client IP address.
	KeyFunc func(r *http.Request) string

	// OnLimitExceeded is called when rate limit is exceeded.
	// If nil, returns 429 Too Many Requests with standard headers.
	OnLimitExceeded func(w http.ResponseWriter, r *http.Request, info RateLimitInfo)

	// ExcludePaths are paths that bypass rate limiting.
	// Example: []string{"/health", "/metrics"}
	ExcludePaths []string

	// TrustCloudflare uses CF-Connecting-IP for client identification.
	// Default: false.
	TrustCloudflare bool

	// CleanupInterval is how often to clean up expired entries.
	// Default: 1 minute.
	CleanupInterval time.Duration
}

type RateLimitInfo struct {
	Limit      int       // Maximum requests per window
	Remaining  int       // Requests remaining in current window
	ResetAt    time.Time // When the window resets
	RetryAfter int       // Seconds until next request allowed (if limited)
}

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

type RefreshConfig struct {
	// Store is the session store.
	Store Store

	// CookieManager handles session cookies.
	CookieManager *CookieManager

	// TokenEndpoint is the OAuth token endpoint URL.
	TokenEndpoint string

	// ClientID is the OAuth client ID.
	ClientID string

	// ClientSecret is the OAuth client secret (optional for public clients).
	ClientSecret string //nolint:gosec // G117: config field, not a hardcoded secret

	// UseDPoP enables DPoP for token refresh requests.
	// When true, generates a new DPoP key pair and binds the new tokens to it.
	// Default: true.
	UseDPoP bool

	// Client is the HTTP client to use for refresh requests.
	// If nil, uses http.DefaultClient.
	Client *http.Client

	// Timeout is the refresh request timeout.
	// Default: 30 seconds.
	Timeout time.Duration

	// RefreshThreshold is how early before expiry to refresh tokens.
	// Default: 5 minutes.
	RefreshThreshold time.Duration

	// OnRefreshSuccess is called when tokens are successfully refreshed.
	OnRefreshSuccess func(ctx context.Context, session *Session)

	// OnRefreshError is called when token refresh fails.
	OnRefreshError func(w http.ResponseWriter, r *http.Request, err error)

	// ParseTokenResponse allows custom parsing of the token response.
	// If nil, uses the default OAuth2 token response format.
	ParseTokenResponse func(body []byte) (*TokenResponse, error)
}

type RefreshInput struct {
	Origin string `header:"Origin" required:"true" doc:"Origin header for CSRF protection"`
}

type RefreshOutput struct {
	Body RefreshResponse

	// Standard rate limit headers
	RateLimitLimit     int   `header:"X-RateLimit-Limit" doc:"Maximum requests per window"`
	RateLimitRemaining int   `header:"X-RateLimit-Remaining" doc:"Requests remaining in current window"`
	RateLimitReset     int64 `header:"X-RateLimit-Reset" doc:"Unix timestamp when window resets"`
}

type RefreshResponse struct {
	// Message indicates the refresh result.
	Message string `json:"message" doc:"Refresh result message" example:"Session refreshed"`

	// ExpiresAt is the Unix timestamp when the new access token expires.
	ExpiresAt int64 `json:"expires_at" doc:"Unix timestamp when access token expires"`
}

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

type Session struct {
	// ID is the unique session identifier.
	ID string `json:"id"`

	// UserID is the authenticated user's ID.
	UserID uuid.UUID `json:"user_id"`

	// OrganizationID is the current organization context (optional).
	OrganizationID *uuid.UUID `json:"organization_id,omitempty"`

	// AccessToken is the OAuth access token.
	AccessToken string `json:"access_token"`

	// RefreshToken is the OAuth refresh token.
	RefreshToken string `json:"refresh_token"`

	// AccessTokenExpiresAt is when the access token expires.
	AccessTokenExpiresAt time.Time `json:"access_token_expires_at"`

	// RefreshTokenExpiresAt is when the refresh token expires.
	RefreshTokenExpiresAt time.Time `json:"refresh_token_expires_at"`

	// DPoPKeyPairJSON is the serialized DPoP key pair for this session.
	// The BFF uses this to sign DPoP proofs when proxying requests to the API.
	DPoPKeyPairJSON []byte `json:"dpop_key_pair,omitempty"`

	// DPoPThumbprint is the JWK thumbprint of the DPoP key pair.
	DPoPThumbprint string `json:"dpop_thumbprint,omitempty"`

	// Metadata contains optional session metadata.
	Metadata map[string]string `json:"metadata,omitempty"`

	// CreatedAt is when the session was created.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when the session was last updated.
	UpdatedAt time.Time `json:"updated_at"`

	// LastAccessedAt is when the session was last accessed.
	LastAccessedAt time.Time `json:"last_accessed_at"`

	// ExpiresAt is when the session expires (based on refresh token or absolute timeout).
	ExpiresAt time.Time `json:"expires_at"`

	// IPAddress is the IP address that created the session.
	IPAddress string `json:"ip_address,omitempty"`

	// UserAgent is the user agent that created the session.
	UserAgent string `json:"user_agent,omitempty"`
}

type SessionInfoResponse struct {
	Authenticated bool       `json:"authenticated"`
	UserID        *uuid.UUID `json:"user_id,omitempty"`
	ExpiresAt     *time.Time `json:"expires_at,omitempty"`
}

type SessionStatusResponse struct {
	// Authenticated indicates if the user has a valid session.
	Authenticated bool `json:"authenticated" doc:"Whether the user has a valid session"`

	// UserID is the authenticated user's ID (only present if authenticated).
	UserID *uuid.UUID `json:"user_id,omitempty" doc:"The authenticated user's ID"`

	// OrganizationID is the current organization context (only present if set).
	OrganizationID *uuid.UUID `json:"organization_id,omitempty" doc:"Current organization context"`

	// ExpiresAt is when the session expires (only present if authenticated).
	ExpiresAt *time.Time `json:"expires_at,omitempty" doc:"When the session expires" format:"date-time"`

	// AccessTokenExpiresAt is when the access token expires (only present if authenticated).
	AccessTokenExpiresAt *time.Time `json:"access_token_expires_at,omitempty" doc:"When the access token expires" format:"date-time"`
}

type Store interface {
	// Create stores a new session and returns the session ID.
	Create(ctx context.Context, session *Session) error

	// Get retrieves a session by ID.
	// Returns ErrSessionNotFound if the session doesn't exist.
	// Returns ErrSessionExpired if the session has expired.
	Get(ctx context.Context, id string) (*Session, error)

	// Update updates an existing session.
	// Returns ErrSessionNotFound if the session doesn't exist.
	Update(ctx context.Context, session *Session) error

	// Delete removes a session by ID.
	// Returns ErrSessionNotFound if the session doesn't exist.
	Delete(ctx context.Context, id string) error

	// DeleteByUserID removes all sessions for a user.
	// Returns the number of sessions deleted.
	DeleteByUserID(ctx context.Context, userID string) (int, error)

	// Touch updates the LastAccessedAt timestamp.
	// This is used to track session activity without modifying other fields.
	Touch(ctx context.Context, id string) error

	// Cleanup removes expired sessions.
	// Returns the number of sessions removed.
	Cleanup(ctx context.Context) (int, error)

	// Close closes the store and releases any resources.
	Close() error
}

type StoreConfig struct {
	// CleanupInterval is how often to run automatic cleanup.
	// Set to 0 to disable automatic cleanup.
	CleanupInterval int

	// MaxSessions is the maximum number of sessions to store (0 = unlimited).
	MaxSessions int

	// EncryptionKey is used to encrypt sensitive session data.
	// If nil, session data is stored unencrypted.
	EncryptionKey []byte
}

type TokenErrorResponse struct {
	Error            string `json:"error"`
	ErrorDescription string `json:"error_description,omitempty"`
}

type TokenRefreshResult struct {
	AccessToken           string
	RefreshToken          string // Optional: new refresh token
	AccessTokenExpiresIn  time.Duration
	RefreshTokenExpiresIn time.Duration // Optional: if new refresh token issued
}

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int    `json:"expires_in"`
	RefreshToken string `json:"refresh_token,omitempty"`
	Scope        string `json:"scope,omitempty"`
}