twofactor

type Config struct {
	// Issuer specifies the application name embedded into the TOTP URI shown in authenticator apps (default: "GoModularAuth").
	Issuer string

	// TotpDigits specifies the number of digits in generated TOTP codes (6 or 8, default: 6).
	TotpDigits int

	// TotpPeriod specifies the rotation interval for TOTP codes in seconds (default: 30).
	TotpPeriod int

	// BackupCodeAmount defines the total number of single-use backup codes generated during enrollment (default: 10).
	BackupCodeAmount int

	// BackupCodeLength defines the character length of each generated backup code (default: 10).
	BackupCodeLength int

	// AllowPasswordless allows 2FA management operations without requiring prior password re-validation.
	AllowPasswordless bool

	// SkipVerificationOnEnable marks 2FA as immediately active upon enrollment without demanding a first verified TOTP code.
	SkipVerificationOnEnable bool

	// MaxAllowedAttempts defines the maximum failed attempts permitted before rate limiting lockout triggers (default: 5).
	MaxAllowedAttempts int

	// LockoutDuration defines the temporary lockout penalty after exceeding maximum failed attempts (default: 15 minutes).
	LockoutDuration time.Duration

	// OTPDigits specifies the numeric length for challenge-based OTP codes (default: 6).
	OTPDigits int

	// OTPPeriod defines the expiration duration for temporary OTP challenges (default: 3 minutes).
	OTPPeriod time.Duration

	// SendOTP registers the external delivery callback for SMS or Email OTP dispatches.
	SendOTP SendOTPFunc
}

type DisableParams struct {
	// UserID identifies the user whose 2FA is being deactivated (required).
	UserID string `json:"user_id"`

	// Password is the optional password confirmation.
	Password string `json:"password,omitempty"`

	// Extra holds dynamic metadata passed through event interceptors (optional).
	Extra map[string]any `json:"extra,omitempty"`
}

type DisableTwoFactorEventPayload struct {
	// UserID identifies the user whose 2FA configuration is being disabled.
	UserID string
}

type EnableParams struct {
	// UserID is the unique identifier of the user enrolling in 2FA (required).
	UserID string `json:"user_id"`

	// Password is the user's current password if password re-authentication is enforced (optional).
	Password string `json:"password,omitempty"`

	// Issuer overrides the default application issuer name shown in authenticator apps (optional).
	Issuer string `json:"issuer,omitempty"`

	// Extra holds dynamic metadata passed through event interceptors (optional).
	Extra map[string]any `json:"extra,omitempty"`
}

type EnableResult struct {
	// TOTPURI is the otpauth:// URI encoded with secret, issuer, digits, and period for QR code generation.
	TOTPURI string `json:"totp_uri"`

	// BackupCodes is the list of generated single-use recovery codes.
	BackupCodes []string `json:"backup_codes"`
}

type EnableTwoFactorAfterEventPayload struct {
	// UserID identifies the user whose 2FA enrollment completed.
	UserID string

	// BackupCodesCount is the number of single-use backup codes generated.
	BackupCodesCount int
}

type EnableTwoFactorBeforeEventPayload struct {
	// UserID identifies the user beginning 2FA setup.
	UserID string

	// Params holds the mutable enrollment parameters (including dynamic Extra metadata).
	Params *EnableParams
}

type GenerateBackupCodesParams struct {
	// UserID identifies the user requesting new backup codes (required).
	UserID string `json:"user_id"`

	// Password is an optional password check.
	Password string `json:"password,omitempty"`
}

type GetTOTPURIParams struct {
	// UserID identifies the enrolled user (required).
	UserID string `json:"user_id"`

	// Password is an optional password check.
	Password string `json:"password,omitempty"`
}

type OTPChallenge struct {
	// Key is the unique challenge storage key (e.g. "2fa-otp-<userID>").
	Key string `json:"key"`

	// UserID is the recipient user's unique identifier.
	UserID string `json:"user_id"`

	// CodeHash is the generated numeric OTP challenge code.
	CodeHash string `json:"code_hash"`

	// Attempts tracks the number of failed verification tries against this specific challenge.
	Attempts int `json:"attempts"`

	// ExpiresAt specifies the exact timestamp after which this challenge is invalid.
	ExpiresAt time.Time `json:"expires_at"`
}

type Option func(*Config)

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

type Repository interface {
	// FindByUserID retrieves the 2FA configuration record for a given user ID.
	//
	// Function:
	//   Used during TOTP validation, backup code verification, and viewing active backup codes.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: The unique user identifier to look up.
	//
	// Returns:
	//   - *TwoFactor: The populated TwoFactor configuration entity.
	//   - error: ErrTwoFactorNotEnabled if no record exists, or database error on failure.
	//
	// Example SQL:
	//   SELECT id, user_id, secret, backup_codes, verified, failures, locked_until, created_at, updated_at
	//   FROM two_factors WHERE user_id = $1 LIMIT 1;
	FindByUserID(ctx context.Context, userID string) (*TwoFactor, error)

	// Create persists a new TwoFactor entity in storage.
	//
	// Function:
	//   Called during Enable when initializing 2FA enrollment for a user.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - tf: The newly initialized TwoFactor struct.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   INSERT INTO two_factors (id, user_id, secret, backup_codes, verified, failures, locked_until, created_at, updated_at)
	//   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9);
	Create(ctx context.Context, tf *TwoFactor) error

	// Update modifies an existing TwoFactor record in storage.
	//
	// Function:
	//   Called after consuming a backup code, regenerating backup codes, updating failure counts,
	//   setting lockout expiration, or marking enrollment as verified.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - tf: The modified TwoFactor struct.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   UPDATE two_factors SET secret = $1, backup_codes = $2, verified = $3, failures = $4, locked_until = $5, updated_at = $6
	//   WHERE user_id = $7;
	Update(ctx context.Context, tf *TwoFactor) error

	// DeleteByUserID removes 2FA configuration for a user ID when disabling 2FA.
	//
	// Function:
	//   Called during Disable to completely purge 2FA credentials for the user.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: The target user's ID.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   DELETE FROM two_factors WHERE user_id = $1;
	DeleteByUserID(ctx context.Context, userID string) error

	// SaveOTPChallenge stores or updates a short-lived challenge code.
	//
	// Function:
	//   Called during SendOTP when creating a new numeric challenge, or during VerifyOTP when incrementing failed attempts.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - challenge: The OTPChallenge entity to persist or update.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL / Redis:
	//   INSERT INTO otp_challenges (key, user_id, code_hash, attempts, expires_at)
	//   VALUES ($1, $2, $3, $4, $5) ON CONFLICT (key) DO UPDATE SET attempts = $4;
	SaveOTPChallenge(ctx context.Context, challenge *OTPChallenge) error

	// GetOTPChallenge retrieves an active challenge by its composite key.
	//
	// Function:
	//   Called during VerifyOTP to compare the user's submitted challenge code and verify expiration.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - key: The composite challenge key (e.g. "2fa-otp-<userID>").
	//
	// Returns:
	//   - *OTPChallenge: The matching challenge entity.
	//   - error: ErrOTPExpired if no active challenge matches, or database error on failure.
	//
	// Example SQL:
	//   SELECT key, user_id, code_hash, attempts, expires_at FROM otp_challenges WHERE key = $1 LIMIT 1;
	GetOTPChallenge(ctx context.Context, key string) (*OTPChallenge, error)

	// DeleteOTPChallenge deletes a consumed or expired OTP challenge.
	//
	// Function:
	//   Called upon successful verification (single-use consumption) or when maximum attempts are exceeded.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - key: The composite challenge key to delete.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   DELETE FROM otp_challenges WHERE key = $1;
	DeleteOTPChallenge(ctx context.Context, key string) error
}

type SendOTPAfterEventPayload struct {
	// UserID identifies the target user for the OTP challenge.
	UserID string

	// ExpiresAt specifies the exact expiration time for the OTP challenge.
	ExpiresAt time.Time
}

type SendOTPBeforeEventPayload struct {
	// UserID identifies the target user for the OTP challenge.
	UserID string
}

type SendOTPFunc func(ctx context.Context, userID string, otp string) error

type SendOTPParams struct {
	// UserID identifies the user receiving the OTP challenge (required).
	UserID string `json:"user_id"`
}

type TOTPGeneratedEventPayload struct {
	// UserID identifies the user for whom the secret was created.
	UserID string

	// Secret is the Base32-encoded TOTP secret.
	Secret string
}

type TwoFactor struct {
	// ID is the unique database record identifier.
	ID string `json:"id"`

	// UserID uniquely identifies the owner user of this 2FA configuration.
	UserID string `json:"user_id"`

	// Secret is the Base32-encoded cryptographic secret used for TOTP calculation.
	Secret string `json:"secret"`

	// BackupCodes is a serialized JSON array containing unconsumed single-use backup codes (e.g. `["CODE1", "CODE2"]`).
	BackupCodes string `json:"backup_codes"`

	// Verified indicates whether initial TOTP verification has succeeded and 2FA is actively enforced.
	Verified bool `json:"verified"`

	// Failures tracks the number of consecutive failed verification attempts.
	Failures int `json:"failures"`

	// LockedUntil specifies the timestamp until which 2FA operations are locked due to rate limiting (nil if unlocked).
	LockedUntil *time.Time `json:"locked_until"`

	// CreatedAt records the timestamp when 2FA enrollment was initialized.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt records the timestamp when 2FA settings were last modified.
	UpdatedAt time.Time `json:"updated_at"`
}

type VerifyBackupCodeAfterEventPayload struct {
	// UserID identifies the user consuming a backup code.
	UserID string

	// Success indicates whether the backup code was found, valid, and consumed.
	Success bool

	// RemainingCodes is the count of remaining unconsumed backup codes.
	RemainingCodes int
}

type VerifyBackupCodeParams struct {
	// UserID identifies the user attempting backup code recovery (required).
	UserID string `json:"user_id"`

	// Code is the alphanumeric single-use recovery code (required).
	Code string `json:"code"`
}

type VerifyOTPAfterEventPayload struct {
	// UserID identifies the user attempting OTP challenge verification.
	UserID string

	// Success indicates whether the challenge code was valid.
	Success bool
}

type VerifyOTPParams struct {
	// UserID identifies the user submitting the challenge verification code (required).
	UserID string `json:"user_id"`

	// Code is the numeric challenge code delivered to the user (required).
	Code string `json:"code"`
}

type VerifyTOTPAfterEventPayload struct {
	// UserID identifies the user who attempted TOTP validation.
	UserID string

	// Success indicates whether the submitted code was valid and accepted.
	Success bool
}

type VerifyTOTPBeforeEventPayload struct {
	// UserID identifies the user submitting the TOTP code.
	UserID string
}

type VerifyTOTPParams struct {
	// UserID identifies the user submitting the verification code (required).
	UserID string `json:"user_id"`

	// Code is the numeric TOTP code generated by an authenticator application (required).
	Code string `json:"code"`
}

type ViewBackupCodesParams struct {
	// UserID identifies the user querying their backup codes (required).
	UserID string `json:"user_id"`
}