twofactor

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

type AssuranceLevel string

type Challenge struct {
	ID        string    `json:"id"`
	UserID    string    `json:"user_id"`
	ExpiresAt time.Time `json:"expires_at"`
	CreatedAt time.Time `json:"created_at"`
}

type ChallengeRecord struct {
	ID        string     `json:"id"`
	UserID    string     `json:"user_id"`
	ExpiresAt time.Time  `json:"expires_at"`
	UsedAt    *time.Time `json:"used_at,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
}

type Config struct {
	// Protector encrypts and decrypts factor secrets at rest.
	// If nil, defaults to an AES-256-GCM protector initialized with a secure random key.
	Protector SecretProtector

	// Issuer is the default organization or application name included in otpauth:// URIs.
	Issuer string

	// StepDuration is the time interval for TOTP tokens (RFC 6238 recommends 30 seconds).
	StepDuration time.Duration

	// SkewSteps is the number of time-steps allowed before and after current time to tolerate clock drift.
	// Default is 1 (covering +/- 30 seconds).
	SkewSteps int

	// ChallengeTTL is the lifetime for ephemeral MFA challenges.
	ChallengeTTL time.Duration

	// DefaultRecoveryCodesCount is the number of recovery codes generated by default.
	DefaultRecoveryCodesCount int

	// EnforceMFAOnSignIn controls whether the plugin verifies that users with active 2FA
	// are not granted final sessions without completing MFA verification.
	EnforceMFAOnSignIn bool
}

type EnrollConfig struct {
	Label       string
	Issuer      string
	AccountName string
}

type EnrollOption func(*EnrollConfig)

type Factor struct {
	ID          string     `json:"id"`
	UserID      string     `json:"user_id"`
	Type        FactorType `json:"type"`
	Label       string     `json:"label,omitempty"`
	Confirmed   bool       `json:"confirmed"`
	ConfirmedAt *time.Time `json:"confirmed_at,omitempty"`
	LastUsedAt  *time.Time `json:"last_used_at,omitempty"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
}

type FactorRecord struct {
	ID               string     `json:"id"`
	UserID           string     `json:"user_id"`
	Type             string     `json:"type"`
	Label            string     `json:"label,omitempty"`
	EncryptedSecret  string     `json:"encrypted_secret"`
	Confirmed        bool       `json:"confirmed"`
	ConfirmedAt      *time.Time `json:"confirmed_at,omitempty"`
	LastUsedAt       *time.Time `json:"last_used_at,omitempty"`
	LastUsedTimeStep int64      `json:"last_used_time_step"`
	CreatedAt        time.Time  `json:"created_at"`
	UpdatedAt        time.Time  `json:"updated_at"`
}

type FactorType string

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

type Option func(*Config)

type RecoveryCodeRecord struct {
	ID        string     `json:"id"`
	UserID    string     `json:"user_id"`
	CodeHash  string     `json:"code_hash"`
	UsedAt    *time.Time `json:"used_at,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
}

type SecretProtector interface {
	Encrypt(plaintext []byte) (string, error)
	Decrypt(ciphertext string) ([]byte, error)
}

type Status struct {
	Enabled            bool       `json:"enabled"`
	Factors            []Factor   `json:"factors"`
	RecoveryCodesCount int        `json:"recovery_codes_count"`
	PrimaryFactorType  FactorType `json:"primary_factor_type,omitempty"`
}

type TOTPEnrollment struct {
	FactorID        string `json:"factor_id"`
	Secret          string `json:"secret"`           // Plaintext base32 secret; returned only during enrollment
	ProvisioningURI string `json:"provisioning_uri"` // Standard otpauth:// URI for QR code generation
	Issuer          string `json:"issuer"`
	AccountName     string `json:"account_name"`
}

type TwoFactor interface {
	// GetStatus returns the complete 2FA status and configured factors for a user.
	GetStatus(ctx context.Context, userID string) (*Status, error)

	// IsEnabled reports whether the user has at least one confirmed MFA factor.
	IsEnabled(ctx context.Context, userID string) (bool, error)

	// ListFactors returns all registered factors (confirmed or pending) for a user.
	ListFactors(ctx context.Context, userID string) ([]Factor, error)

	// EnrollTOTP initiates TOTP enrollment. It creates a pending factor and returns the secret & provisioning URI.
	// The factor remains inactive until confirmed via ConfirmTOTP.
	EnrollTOTP(ctx context.Context, userID string, opts ...EnrollOption) (*TOTPEnrollment, error)

	// ConfirmTOTP confirms a pending TOTP factor with a valid code from the authenticator app.
	// Upon success, the factor is activated and EventTwoFactorEnabled is emitted.
	ConfirmTOTP(ctx context.Context, userID, factorID, code string) error

	// VerifyTOTP verifies a TOTP code for a user against their confirmed TOTP factors.
	// It applies clock-skew tolerance and prevents replay attacks. Emits EventTwoFactorVerified.
	VerifyTOTP(ctx context.Context, userID, code string) (*VerifyResult, error)

	// VerifyRecoveryCode verifies and consumes a single-use backup recovery code.
	// Emits EventTwoFactorVerified upon successful consumption.
	VerifyRecoveryCode(ctx context.Context, userID, code string) (*VerifyResult, error)

	// CreateChallenge creates a short-lived MFA challenge for two-step authentication flows.
	CreateChallenge(ctx context.Context, userID string) (*Challenge, error)

	// VerifyChallenge verifies a challenge token with either a TOTP code or a recovery code.
	VerifyChallenge(ctx context.Context, challengeID, code string) (*VerifyResult, error)

	// GenerateRecoveryCodes generates a fresh set of recovery codes, hashing them before storing.
	// Returns the plaintext codes ONCE.
	GenerateRecoveryCodes(ctx context.Context, userID string, count int) ([]string, error)

	// RotateRecoveryCodes revokes all existing recovery codes for a user and generates a fresh set.
	RotateRecoveryCodes(ctx context.Context, userID string) ([]string, error)

	// GetRemainingRecoveryCodesCount returns the number of unused active recovery codes.
	GetRemainingRecoveryCodesCount(ctx context.Context, userID string) (int, error)

	// Disable disables MFA for a user by removing all factors and recovery codes.
	// Emits EventTwoFactorDisabled.
	Disable(ctx context.Context, userID string) error

	// DisableFactor removes a specific factor. If no confirmed factors remain, MFA is effectively disabled.
	DisableFactor(ctx context.Context, userID, factorID string) error
}

type TwoFactorDisabledPayload struct {
	UserID     string    `json:"user_id"`
	DisabledAt time.Time `json:"disabled_at"`
	Reason     string    `json:"reason,omitempty"`
}

type TwoFactorEnabledPayload struct {
	UserID     string     `json:"user_id"`
	FactorID   string     `json:"factor_id"`
	FactorType FactorType `json:"factor_type"`
	EnabledAt  time.Time  `json:"enabled_at"`
}

type TwoFactorVerifiedPayload struct {
	UserID         string         `json:"user_id"`
	FactorID       string         `json:"factor_id,omitempty"`
	FactorType     FactorType     `json:"factor_type"`
	AssuranceLevel AssuranceLevel `json:"assurance_level"`
	VerifiedAt     time.Time      `json:"verified_at"`
}

type VerifyResult struct {
	UserID         string         `json:"user_id"`
	FactorID       string         `json:"factor_id,omitempty"`
	FactorType     FactorType     `json:"factor_type"`
	AssuranceLevel AssuranceLevel `json:"assurance_level"`
	VerifiedAt     time.Time      `json:"verified_at"`
}