config

type Config struct {

	// DB is the database provider for storing users, sessions, and auth data.
	// Use a pointer so nil can represent "not provided" and to avoid copying
	// a large sql.DB value accidentally.
	DB *sql.DB

	// Router is the HTTP router for mounting authentication endpoints.
	// REQUIRED. Use WithRouter to set this.
	Router router.Router

	// Logger is an optional logger for Aegis lifecycle events.
	// OPTIONAL. Use WithLogger to enable logging.
	// Default: nil (no logging)
	Logger Logger

	// AuditLogger is an optional audit logger for security events.
	// OPTIONAL. Use WithAuditLogger to enable audit logging.
	// Default: nil (no audit logging)
	AuditLogger core.AuditLogger

	// Secret is the master secret for Aegis.
	// REQUIRED for web applications (or use WithAPIOnlyMode for API-only apps).
	// MUST be cryptographically random (32+ bytes recommended).
	// All plugin-specific secrets (CSRF, OAuth, JWT, etc.) are derived from this.
	// Use WithSecret to set this.
	Secret []byte

	// SessionExpiry is the duration before a session token expires.
	// REQUIRED (has default).
	// Default: 24 hours
	// Production recommendation: 15 minutes to 24 hours, depending on sensitivity.
	// Use WithSessionExpiry to override.
	SessionExpiry time.Duration

	// RefreshExpiry is the duration before a refresh token expires.
	// REQUIRED (has default).
	// Default: 7 days
	// MUST be greater than SessionExpiry.
	// Production recommendation: 7-30 days.
	// Use WithRefreshExpiry to override.
	RefreshExpiry time.Duration

	// CookieDomain is the domain for session cookies.
	// OPTIONAL.
	// Default: "" (cookie applies to current domain only)
	// Set to ".example.com" to share cookies across subdomains.
	// Use WithCookieDomain to set this.
	CookieDomain string

	// CookieName is the name of the session cookie.
	// OPTIONAL.
	// Default: "aegis_session"
	// Use WithCookieName to customize.
	CookieName string

	// CookieSecure determines if cookies are sent only over HTTPS.
	// REQUIRED (has default).
	// Default: true
	// MUST be true in production for security.
	// Use WithCookieSecure to override (only for local development).
	CookieSecure bool

	// CookieHTTPOnly prevents JavaScript from accessing cookies.
	// REQUIRED (has default).
	// Default: true
	// MUST be true in production to prevent XSS attacks.
	// DO NOT override in production.
	CookieHTTPOnly bool

	// CookieSameSite controls cross-site cookie behavior.
	// REQUIRED (has default).
	// Default: "Lax"
	// Options: "Strict" (maximum protection), "Lax" (balanced), "None" (cross-site, requires Secure=true)
	// Production recommendation: "Strict" or "Lax"
	// Use WithCookieSameSite to override.
	CookieSameSite string

	// APIMode skips CSRF secret requirement for API-only applications.
	// OPTIONAL.
	// Default: false
	// Set to true if building an API without browser-based sessions.
	// Use WithAPIOnlyMode to enable.
	APIMode bool

	// Argon2Time is the number of iterations for Argon2id hashing.
	// REQUIRED (has default).
	// Default: 1
	// Production recommendation: 1-3 iterations (higher = more secure but slower).
	// See SECURITY.md for detailed guidance.
	Argon2Time uint32

	// Argon2Memory is the memory cost in KB for Argon2id hashing.
	// REQUIRED (has default).
	// Default: 64 MB (65536 KB)
	// Production recommendation: 64-256 MB depending on server resources.
	// See SECURITY.md for detailed guidance.
	Argon2Memory uint32

	// Argon2Threads is the degree of parallelism for Argon2id hashing.
	// REQUIRED (has default).
	// Default: 4
	// Production recommendation: 4 threads is optimal for most servers.
	Argon2Threads uint8

	// Argon2KeyLength is the output key length in bytes for Argon2id.
	// REQUIRED (has default).
	// Default: 32 bytes (256-bit security)
	// DO NOT change unless you have specific requirements.
	Argon2KeyLength uint32

	// IDGenerator is an optional custom function for generating IDs.
	// OPTIONAL.
	// Default: nil (uses built-in ULID generation - sortable, time-based, 26 characters)
	// Override with: UUID, sequential IDs, or custom format (KSUID, nanoid, etc.)
	// Example: WithIDGenerator(func() string { return uuid.New().String() })
	// Use WithIDGenerator to set this.
	IDGenerator func() string

	// IDStrategy defines the algorithm used for generating unique identifiers.
	// OPTIONAL.
	// Default: core.IDStrategyULID
	// Options: core.IDStrategyULID, core.IDStrategyUUID, core.IDStrategyCustom
	// Use WithIDStrategy to set this.
	IDStrategy core.IDStrategy

	// Redis is optional configuration for Redis-based session storage.
	// OPTIONAL.
	// Default: nil (uses database for session storage)
	// Use WithRedis to enable Redis sessions.
	Redis *RedisConfig

	// ========== AUTH CONFIGURATION ==========
	// Auth holds authentication configuration.
	// REQUIRED.
	// Use WithCoreAuthConfig to set this.
	Auth auth.Config

	// CoreAuth holds core authentication configuration.
	// OPTIONAL.
	// Default: DefaultAuthConfig()
	// Use WithCoreAuthConfig to set this.
	CoreAuth *core.AuthConfig

	// RateLimitEnabled enables rate limiting middleware.
	// OPTIONAL.
	// Default: false
	// Use WithRateLimiting to enable.
	RateLimitEnabled bool

	// RateLimitConfig holds rate limiting configuration.
	// OPTIONAL.
	// Default: nil (uses DefaultRateLimitConfig() if enabled)
	// Use WithRateLimiting or WithRateLimitConfig to configure.
	RateLimitConfig *core.RateLimitConfig

	// LoginAttemptConfig holds login attempt tracking configuration.
	// OPTIONAL.
	// Default: nil (uses DefaultLoginAttemptConfig() if rate limiting enabled)
	// Use WithLoginAttemptConfig to configure.
	LoginAttemptConfig *core.LoginAttemptConfig
}

type Logger interface {
	Info(msg string, keysAndValues ...interface{})
	Error(msg string, keysAndValues ...interface{})
	Debug(msg string, keysAndValues ...interface{})
}

type Option func(*Config)

type RedisConfig struct {
	// Host is the Redis server hostname or IP address.
	// REQUIRED if using Redis.
	Host string

	// Port is the Redis server port.
	// REQUIRED if using Redis.
	// Default Redis port: 6379
	Port int

	// Password is the Redis authentication password.
	// REQUIRED in production for security.
	// See SECURITY.md for Redis security recommendations.
	Password string

	// DB is the Redis database number (0-15).
	// OPTIONAL.
	// Default: 0
	DB int
}