security

type APIKeyConfig struct {
	// Enabled determines if API key authentication is enabled
	Enabled bool `yaml:"enabled"`

	// KeyLookup defines where to find the API key:
	// - "header:<name>" - look in header (default: "header:X-API-Key")
	// - "query:<name>" - look in query parameter
	// - "cookie:<name>" - look in cookie
	// Can specify multiple separated by comma
	KeyLookup string `yaml:"key_lookup"`

	// KeyPrefix is the prefix before the key (optional)
	// Example: "ApiKey" or "Bearer"
	KeyPrefix string `yaml:"key_prefix"`

	// SkipPaths is a list of paths to skip API key authentication
	SkipPaths []string `yaml:"skip_paths"`

	// AutoApplyMiddleware automatically applies API key middleware globally
	AutoApplyMiddleware bool `yaml:"auto_apply_middleware"`

	// ErrorHandler is called when API key validation fails
	ErrorHandler func(forge.Context, error) error `yaml:"-"`

	// Validator is a custom function to validate API keys
	// If not set, uses the built-in validator
	Validator func(ctx context.Context, key string) (*APIKeyInfo, error) `yaml:"-"`
}

type APIKeyInfo struct {
	Key        string         // The API key
	Name       string         // Friendly name for the key
	UserID     string         // Associated user ID
	Scopes     []string       // Allowed scopes/permissions
	RateLimit  int            // Rate limit for this key
	ExpiresAt  *time.Time     // Expiration time (nil = never expires)
	CreatedAt  time.Time      // Creation time
	LastUsedAt *time.Time     // Last usage time
	Revoked    bool           // Whether the key is revoked
	Metadata   map[string]any // Additional metadata
}

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

type AuditConfig struct {
	// Enabled determines if audit logging is enabled
	Enabled bool `yaml:"enabled"`

	// Level determines what events to log
	// Options: "all", "auth", "data", "admin"
	Level string `yaml:"level"`

	// IncludePaths is a list of path patterns to audit (empty = all paths)
	// Example: ["/api/admin/*", "/api/users/*"]
	IncludePaths []string `yaml:"include_paths"`

	// ExcludePaths is a list of path patterns to exclude from auditing
	// Example: ["/health", "/metrics"]
	ExcludePaths []string `yaml:"exclude_paths"`

	// LogRequestBody logs the request body (be careful with sensitive data)
	LogRequestBody bool `yaml:"log_request_body"`

	// LogResponseBody logs the response body (be careful with sensitive data)
	LogResponseBody bool `yaml:"log_response_body"`

	// SensitiveHeaders are headers that should be redacted in logs
	SensitiveHeaders []string `yaml:"sensitive_headers"`

	// SensitiveFields are JSON fields that should be redacted in logs
	SensitiveFields []string `yaml:"sensitive_fields"`

	// MaxBodySize is the maximum body size to log (in bytes)
	// Default: 1024 (1KB)
	MaxBodySize int `yaml:"max_body_size"`

	// AutoApplyMiddleware automatically applies audit middleware globally
	AutoApplyMiddleware bool `yaml:"auto_apply_middleware"`

	// Handler is called for each audit log entry
	// If not set, uses the default logger
	Handler func(*AuditEntry) `yaml:"-"`
}

type AuditEntry struct {
	// Timestamp of the event
	Timestamp time.Time `json:"timestamp"`

	// Event type (e.g., "auth.login", "auth.logout", "data.create", "data.update")
	EventType string `json:"event_type"`

	// Event category ("auth", "data", "admin", "security")
	Category string `json:"category"`

	// Result of the event ("success", "failure", "error")
	Result string `json:"result"`

	// User information
	UserID   string `json:"user_id,omitempty"`
	Username string `json:"username,omitempty"`
	Email    string `json:"email,omitempty"`

	// Request information
	Method    string            `json:"method"`
	Path      string            `json:"path"`
	Query     string            `json:"query,omitempty"`
	IPAddress string            `json:"ip_address"`
	UserAgent string            `json:"user_agent,omitempty"`
	Headers   map[string]string `json:"headers,omitempty"`
	RequestID string            `json:"request_id,omitempty"`
	SessionID string            `json:"session_id,omitempty"`

	// Request/Response data
	RequestBody  string `json:"request_body,omitempty"`
	ResponseBody string `json:"response_body,omitempty"`
	StatusCode   int    `json:"status_code,omitempty"`

	// Timing information
	Duration time.Duration `json:"duration,omitempty"`

	// Additional context
	Message  string         `json:"message,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`

	// Error information
	Error string `json:"error,omitempty"`
}

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

type CORSConfig struct {
	// Enabled determines if CORS is enabled
	Enabled bool `yaml:"enabled"`

	// AllowOrigins is a list of allowed origins
	// Use ["*"] to allow all origins (not recommended for production)
	// Example: ["https://example.com", "https://app.example.com"]
	AllowOrigins []string `yaml:"allow_origins"`

	// AllowMethods is a list of allowed HTTP methods
	// Default: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
	AllowMethods []string `yaml:"allow_methods"`

	// AllowHeaders is a list of allowed request headers
	// Use ["*"] to allow all headers (not recommended for production, and cannot be used with AllowCredentials)
	// Default: ["Origin", "Content-Type", "Accept", "Authorization"]
	AllowHeaders []string `yaml:"allow_headers"`

	// ExposeHeaders is a list of headers exposed to the browser
	// Default: []
	ExposeHeaders []string `yaml:"expose_headers"`

	// AllowCredentials indicates if credentials are allowed
	// Default: false
	// Note: Cannot be true when AllowOrigins is ["*"]
	AllowCredentials bool `yaml:"allow_credentials"`

	// MaxAge indicates how long (in seconds) the results of a preflight request can be cached
	// Default: 3600 (1 hour)
	MaxAge int `yaml:"max_age"`

	// AllowPrivateNetwork allows requests from private networks
	// Default: false
	AllowPrivateNetwork bool `yaml:"allow_private_network"`

	// SkipPaths is a list of paths to skip CORS handling
	SkipPaths []string `yaml:"skip_paths"`

	// AutoApplyMiddleware automatically applies CORS middleware globally
	AutoApplyMiddleware bool `yaml:"auto_apply_middleware"`
}

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

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

type CSRFConfig struct {
	// Enabled determines if CSRF protection is enabled
	Enabled bool `yaml:"enabled"`

	// TokenLength is the length of the CSRF token in bytes (default: 32)
	TokenLength int `yaml:"token_length"`

	// TokenLookup defines where to find the token:
	// - "header:<name>" - look in header
	// - "form:<name>" - look in form field
	// - "query:<name>" - look in query parameter
	// Default: "header:X-CSRF-Token"
	TokenLookup string `yaml:"token_lookup"`

	// CookieName is the name of the CSRF cookie (default: "csrf_token")
	CookieName string `yaml:"cookie_name"`

	// CookiePath is the path for the CSRF cookie (default: "/")
	CookiePath string `yaml:"cookie_path"`

	// CookieDomain is the domain for the CSRF cookie
	CookieDomain string `yaml:"cookie_domain"`

	// CookieSecure indicates if the cookie should only be sent over HTTPS
	CookieSecure bool `yaml:"cookie_secure"`

	// CookieHTTPOnly indicates if the cookie should be inaccessible to JavaScript
	// Note: For CSRF tokens, this should be false so JavaScript can read it
	CookieHTTPOnly bool `yaml:"cookie_http_only"`

	// CookieSameSite specifies the SameSite attribute
	CookieSameSite string `yaml:"cookie_same_site"`

	// TTL is the token time-to-live (default: 12 hours)
	TTL time.Duration `yaml:"ttl"`

	// SafeMethods are HTTP methods that don't require CSRF protection
	// Default: GET, HEAD, OPTIONS, TRACE
	SafeMethods []string `yaml:"safe_methods"`

	// SkipPaths is a list of paths to skip CSRF protection
	SkipPaths []string `yaml:"skip_paths"`

	// AutoApplyMiddleware automatically applies CSRF middleware globally
	AutoApplyMiddleware bool `yaml:"auto_apply_middleware"`

	// ErrorHandler is called when CSRF validation fails
	ErrorHandler func(forge.Context, error) error `yaml:"-"`
}

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

type Config struct {
	// Enabled determines if the security extension is enabled
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Session configuration
	Session SessionConfig `json:"session" yaml:"session"`

	// Cookie configuration
	Cookie CookieConfig `json:"cookie" yaml:"cookie"`

	// CSRF protection configuration
	CSRF CSRFConfig `json:"csrf" yaml:"csrf"`

	// Rate limiting configuration
	RateLimit RateLimitConfig `json:"rate_limit" yaml:"rate_limit"`

	// Security headers configuration
	SecurityHeaders SecurityHeadersConfig `json:"security_headers" yaml:"security_headers"`

	// Password hashing configuration
	PasswordHasher PasswordHasherConfig `json:"password_hasher" yaml:"password_hasher"`

	// JWT configuration
	JWT JWTConfig `json:"jwt" yaml:"jwt"`

	// CORS configuration
	CORS CORSConfig `json:"cors" yaml:"cors"`

	// API Key configuration
	APIKey APIKeyConfig `json:"api_key" yaml:"api_key"`

	// Audit logging configuration
	Audit AuditConfig `json:"audit" yaml:"audit"`

	// RequireConfig requires config from ConfigManager
	RequireConfig bool `json:"-" yaml:"-"`
}

type ConfigOption func(*Config)

type CookieConfig struct {
	// Enabled determines if cookie management is enabled
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Secure indicates if cookies should only be sent over HTTPS
	Secure bool `json:"secure" yaml:"secure"`

	// HttpOnly indicates if cookies should be inaccessible to JavaScript
	HttpOnly bool `json:"http_only" yaml:"http_only"`

	// SameSite specifies the SameSite attribute
	SameSite string `json:"same_site" yaml:"same_site"`

	// Path specifies the cookie path
	Path string `json:"path" yaml:"path"`

	// Domain specifies the cookie domain
	Domain string `json:"domain" yaml:"domain"`

	// MaxAge specifies the cookie lifetime in seconds
	MaxAge int `json:"max_age" yaml:"max_age"`
}

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

type CookieOptions struct {
	// Path specifies the cookie path
	Path string

	// Domain specifies the cookie domain
	Domain string

	// MaxAge specifies the cookie lifetime in seconds
	MaxAge int

	// Expires specifies the cookie expiration time
	Expires time.Time

	// Secure indicates if the cookie should only be sent over HTTPS
	Secure bool

	// HttpOnly indicates if the cookie should be inaccessible to JavaScript
	HttpOnly bool

	// SameSite specifies the SameSite attribute
	SameSite SameSiteMode
}

type Extension struct {
	*forge.BaseExtension
	// contains filtered or unexported fields
}

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

type JWTClaims struct {
	UserID   string         `json:"user_id"`
	Username string         `json:"username,omitempty"`
	Email    string         `json:"email,omitempty"`
	Roles    []string       `json:"roles,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
	//nolint:embeddedstructfieldcheck // moving it reorders an exported struct and breaks callers' unkeyed literals
	jwt.RegisteredClaims
}

type JWTConfig struct {
	// Enabled determines if JWT authentication is enabled
	Enabled bool `yaml:"enabled"`

	// SigningKey is the secret key for signing tokens (for HS256/HS384/HS512)
	SigningKey string `yaml:"signing_key"`

	// SigningMethod is the JWT signing algorithm
	// Options: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512
	// Default: HS256
	SigningMethod string `yaml:"signing_method"`

	// TokenLookup defines where to find the token:
	// - "header:<name>" - look in header (default: "header:Authorization")
	// - "query:<name>" - look in query parameter
	// - "cookie:<name>" - look in cookie
	// - "form:<name>" - look in form field
	// Can specify multiple separated by comma: "header:Authorization,cookie:jwt"
	TokenLookup string `yaml:"token_lookup"`

	// TokenPrefix is the prefix before the token in Authorization header
	// Default: "Bearer"
	TokenPrefix string `yaml:"token_prefix"`

	// Issuer is the JWT issuer (iss claim)
	Issuer string `yaml:"issuer"`

	// Audience is the JWT audience (aud claim)
	Audience string `yaml:"audience"`

	// TTL is the token time-to-live
	// Default: 1 hour
	TTL time.Duration `yaml:"ttl"`

	// RefreshTTL is the refresh token time-to-live
	// Default: 7 days
	RefreshTTL time.Duration `yaml:"refresh_ttl"`

	// SkipPaths is a list of paths to skip JWT authentication
	SkipPaths []string `yaml:"skip_paths"`

	// AutoApplyMiddleware automatically applies JWT middleware globally
	AutoApplyMiddleware bool `yaml:"auto_apply_middleware"`

	// ErrorHandler is called when JWT validation fails
	ErrorHandler func(forge.Context, error) error `yaml:"-"`
}

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

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

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

type PasswordHasherConfig struct {
	// Algorithm specifies the hashing algorithm ("argon2id", "bcrypt")
	// Default: "argon2id" (recommended)
	Algorithm string `yaml:"algorithm"`

	// Argon2 parameters
	Argon2Memory      uint32 `yaml:"argon2_memory"`      // Memory in KiB (default: 64MB = 65536)
	Argon2Iterations  uint32 `yaml:"argon2_iterations"`  // Number of iterations (default: 3)
	Argon2Parallelism uint8  `yaml:"argon2_parallelism"` // Degree of parallelism (default: 4)
	Argon2SaltLength  uint32 `yaml:"argon2_salt_length"` // Salt length in bytes (default: 16)
	Argon2KeyLength   uint32 `yaml:"argon2_key_length"`  // Derived key length (default: 32)

	// Bcrypt parameters
	BcryptCost int `yaml:"bcrypt_cost"` // Cost factor 4-31 (default: 12)
}

type PasswordStrength int

type RateLimitConfig struct {
	// Enabled determines if rate limiting is enabled
	Enabled bool `yaml:"enabled"`

	// RequestsPerWindow is the maximum number of requests allowed per window
	RequestsPerWindow int `yaml:"requests_per_window"`

	// Window is the time window for rate limiting
	Window time.Duration `yaml:"window"`

	// SkipPaths is a list of paths to skip rate limiting
	SkipPaths []string `yaml:"skip_paths"`

	// AutoApplyMiddleware automatically applies rate limiting middleware globally
	AutoApplyMiddleware bool `yaml:"auto_apply_middleware"`

	// Store specifies the rate limit store backend ("memory", "redis")
	// For now, only memory is implemented
	Store string `yaml:"store"`
}

type RateLimitInfo struct {
	Limit      int           // Maximum requests allowed
	Remaining  int           // Remaining requests in current window
	Reset      time.Time     // When the rate limit resets
	RetryAfter time.Duration // How long to wait before retrying
}

type RedisConfig struct {
	// Address is the Redis server address
	Address string `json:"address" yaml:"address"`

	// Password is the Redis password
	Password string `json:"password" yaml:"password"`

	// DB is the Redis database number
	DB int `json:"db" yaml:"db"`

	// PoolSize is the connection pool size
	PoolSize int `json:"pool_size" yaml:"pool_size"`
}

type SameSiteMode string

type SecurityHeadersConfig struct {
	// Enabled determines if security headers are enabled
	Enabled bool `yaml:"enabled"`

	// XFrameOptions prevents clickjacking attacks
	// Values: "DENY", "SAMEORIGIN", "ALLOW-FROM https://example.com"
	// Default: "SAMEORIGIN"
	XFrameOptions string `yaml:"x_frame_options"`

	// XContentTypeOptions prevents MIME-sniffing attacks
	// Value: "nosniff"
	// Default: "nosniff"
	XContentTypeOptions string `yaml:"x_content_type_options"`

	// XSSProtection enables XSS filter in older browsers
	// Values: "0" (disable), "1" (enable), "1; mode=block" (enable and block)
	// Default: "1; mode=block"
	// Note: Modern browsers use CSP instead
	XSSProtection string `yaml:"xss_protection"`

	// ContentSecurityPolicy defines CSP rules
	// Example: "default-src 'self'; script-src 'self' 'unsafe-inline'"
	// Default: "" (not set)
	ContentSecurityPolicy string `yaml:"content_security_policy"`

	// ContentSecurityPolicyReportOnly enables CSP in report-only mode
	// Useful for testing CSP without breaking the site
	ContentSecurityPolicyReportOnly string `yaml:"content_security_policy_report_only"`

	// StrictTransportSecurity enforces HTTPS
	// Example: "max-age=31536000; includeSubDomains; preload"
	// Default: "max-age=31536000; includeSubDomains"
	StrictTransportSecurity string `yaml:"strict_transport_security"`

	// ReferrerPolicy controls referrer information
	// Values: "no-referrer", "no-referrer-when-downgrade", "origin",
	//         "origin-when-cross-origin", "same-origin", "strict-origin",
	//         "strict-origin-when-cross-origin", "unsafe-url"
	// Default: "strict-origin-when-cross-origin"
	ReferrerPolicy string `yaml:"referrer_policy"`

	// PermissionsPolicy controls browser features
	// Example: "geolocation=(self), microphone=()"
	// Default: ""
	PermissionsPolicy string `yaml:"permissions_policy"`

	// CrossOriginEmbedderPolicy controls document embedding
	// Values: "unsafe-none", "require-corp", "credentialless"
	// Default: "" (not set)
	CrossOriginEmbedderPolicy string `yaml:"cross_origin_embedder_policy"`

	// CrossOriginOpenerPolicy controls cross-origin window interaction
	// Values: "unsafe-none", "same-origin-allow-popups", "same-origin"
	// Default: "" (not set)
	CrossOriginOpenerPolicy string `yaml:"cross_origin_opener_policy"`

	// CrossOriginResourcePolicy controls resource loading
	// Values: "same-site", "same-origin", "cross-origin"
	// Default: "" (not set)
	CrossOriginResourcePolicy string `yaml:"cross_origin_resource_policy"`

	// RemoveServerHeader removes the Server header
	// Default: true
	RemoveServerHeader bool `yaml:"remove_server_header"`

	// RemovePoweredBy removes the X-Powered-By header
	// Default: true
	RemovePoweredBy bool `yaml:"remove_powered_by"`

	// CustomHeaders allows setting custom security headers
	CustomHeaders map[string]string `yaml:"custom_headers"`

	// SkipPaths is a list of paths to skip security headers
	SkipPaths []string `yaml:"skip_paths"`

	// AutoApplyMiddleware automatically applies security headers middleware globally
	AutoApplyMiddleware bool `yaml:"auto_apply_middleware"`
}

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

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

	// UserID is the user identifier (optional)
	UserID string `json:"user_id,omitempty"`

	// Data holds arbitrary session data
	Data map[string]any `json:"data"`

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

	// ExpiresAt is when the session expires
	ExpiresAt time.Time `json:"expires_at"`

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

	// IPAddress of the client that created the session
	IPAddress string `json:"ip_address,omitempty"`

	// UserAgent of the client that created the session
	UserAgent string `json:"user_agent,omitempty"`
}

type SessionConfig struct {
	// Enabled determines if session management is enabled
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Store specifies the session store backend ("inmemory", "redis")
	Store string `json:"store" yaml:"store"`

	// CookieName is the name of the session cookie
	CookieName string `json:"cookie_name" yaml:"cookie_name"`

	// TTL is the session time-to-live
	TTL time.Duration `json:"ttl" yaml:"ttl"`

	// IdleTimeout is the session idle timeout
	IdleTimeout time.Duration `json:"idle_timeout" yaml:"idle_timeout"`

	// AutoRenew automatically extends session TTL on access
	AutoRenew bool `json:"auto_renew" yaml:"auto_renew"`

	// AutoApplyMiddleware automatically applies session middleware globally
	AutoApplyMiddleware bool `json:"auto_apply_middleware" yaml:"auto_apply_middleware"`

	// SkipPaths is a list of paths to skip session handling (when auto-applied)
	SkipPaths []string `json:"skip_paths" yaml:"skip_paths"`

	// TrackIPAddress stores the client IP address in session
	TrackIPAddress bool `json:"track_ip_address" yaml:"track_ip_address"`

	// TrackUserAgent stores the client user agent in session
	TrackUserAgent bool `json:"track_user_agent" yaml:"track_user_agent"`

	// Redis configuration (used when Store is "redis")
	Redis RedisConfig `json:"redis" yaml:"redis"`
}

type SessionContextKey struct{}

type SessionMiddlewareOptions struct {
	// Store is the session store to use
	Store SessionStore

	// CookieManager is the cookie manager to use
	CookieManager *CookieManager

	// Config is the session configuration
	Config SessionConfig

	// Logger for logging
	Logger forge.Logger

	// Metrics for metrics
	Metrics forge.Metrics

	// OnSessionCreated is called when a new session is created
	OnSessionCreated func(session *Session)

	// OnSessionExpired is called when a session expires
	OnSessionExpired func(sessionID string)

	// SkipPaths is a list of paths to skip session handling
	SkipPaths []string
}

type SessionStore interface {
	// Create creates a new session with the given TTL
	Create(ctx context.Context, session *Session, ttl time.Duration) error

	// Get retrieves a session by ID
	Get(ctx context.Context, sessionID string) (*Session, error)

	// Update updates an existing session
	Update(ctx context.Context, session *Session, ttl time.Duration) error

	// Delete removes a session by ID
	Delete(ctx context.Context, sessionID string) error

	// DeleteByUserID removes all sessions for a user
	DeleteByUserID(ctx context.Context, userID string) error

	// Touch updates the last accessed time and extends TTL
	Touch(ctx context.Context, sessionID string, ttl time.Duration) error

	// Cleanup removes expired sessions (for stores that don't auto-expire)
	Cleanup(ctx context.Context) (int, error)

	// Count returns the total number of active sessions
	Count(ctx context.Context) (int64, error)

	// Connect establishes connection to the backend
	Connect(ctx context.Context) error

	// Disconnect closes connection to the backend
	Disconnect(ctx context.Context) error

	// Ping checks if the backend is reachable
	Ping(ctx context.Context) error
}