emailpassword

type Config struct {
	// MinPasswordLength specifies the minimum acceptable length for user passwords (default: 8).
	MinPasswordLength int

	// RequireEmailVerification enforces that user.EmailVerified must be true before sign-in succeeds (default: false).
	RequireEmailVerification bool

	// ResetTokenExpiry specifies the duration for which password reset tokens remain valid (default: 15 minutes).
	ResetTokenExpiry time.Duration
}

type Option func(*Config)

type PasswordChangeEventPayload struct {
	// UserID identifies the user whose password is being modified.
	UserID string
}

type PasswordResetCompletedEventPayload struct {
	// UserID identifies the user whose password was reset.
	UserID string
}

type PasswordResetRequestedEventPayload struct {
	// User is the target user entity requesting the reset.
	User *entity.User

	// Token is the secure random token generated for the password reset request.
	Token string

	// ExpiresAt specifies the exact expiration time for the reset token.
	ExpiresAt time.Time
}

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

type Repository interface {
	// GetUserByEmail retrieves a user entity matching the provided unique email address.
	//
	// Function:
	//   Used during Sign-In and Forgot-Password to check user existence and retrieve profile details.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - email: The normalized email address to query.
	//
	// Returns:
	//   - *entity.User: The matching user entity if found.
	//   - error: ErrUserNotFound if no user matches, or database failure error.
	//
	// Example SQL:
	//   SELECT id, email, name, email_verified, created_at, updated_at FROM users WHERE email = $1 LIMIT 1;
	GetUserByEmail(ctx context.Context, email string) (*entity.User, error)

	// GetUserByID retrieves a user entity matching the given unique identifier.
	//
	// Function:
	//   Used during Change-Password and Reset-Password verification flows.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: The unique primary key identifier of the user (e.g. UUID).
	//
	// Returns:
	//   - *entity.User: The matching user entity.
	//   - error: ErrUserNotFound if no record matches, or database failure error.
	//
	// Example SQL:
	//   SELECT id, email, name, email_verified, created_at, updated_at FROM users WHERE id = $1 LIMIT 1;
	GetUserByID(ctx context.Context, id string) (*entity.User, error)

	// CreateUser persists a new user record generated from the provided registration parameters.
	//
	// Function:
	//   Called during SignUp to create the primary user entity. Plugins may inspect or modify
	//   params.Extra before this method is called via EventSignUpBefore.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - params: Pointer to CreateUserParams containing Email, Name, PasswordHash, and Extra metadata.
	//
	// Returns:
	//   - *entity.User: The newly created user entity with populated ID and timestamps.
	//   - error: ErrUserAlreadyExists on unique violation, or database failure error.
	//
	// Example SQL:
	//   INSERT INTO users (id, email, name, password_hash, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	CreateUser(ctx context.Context, params *dto.CreateUserParams) (*entity.User, error)

	// UpdateUser updates an existing user profile record in storage.
	//
	// Function:
	//   Used when updating user metadata, email verification state, or profile attributes.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - user: The updated user entity.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   UPDATE users SET email = $1, name = $2, email_verified = $3, updated_at = $4 WHERE id = $5;
	UpdateUser(ctx context.Context, user *entity.User) error

	// GetAccountByUserIDAndProvider retrieves the credential account associated with a user and authentication provider.
	//
	// Function:
	//   Used during SignIn and ChangePassword to retrieve stored hashed passwords (provider: "credential").
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: The target user's ID.
	//   - provider: The authentication provider identifier (typically "credential").
	//
	// Returns:
	//   - *entity.Account: The matching credentials account containing the password hash.
	//   - error: ErrAccountNotFound if no record matches, or database failure error.
	//
	// Example SQL:
	//   SELECT id, user_id, provider, password, created_at FROM accounts WHERE user_id = $1 AND provider = $2 LIMIT 1;
	GetAccountByUserIDAndProvider(ctx context.Context, userID, provider string) (*entity.Account, error)

	// CreateAccount persists a new provider credentials record associated with a user.
	//
	// Function:
	//   Called immediately after CreateUser during SignUp to link credential passwords to the user.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - account: The credentials account entity to insert.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   INSERT INTO accounts (id, user_id, provider, password, created_at) VALUES ($1, $2, $3, $4, $5);
	CreateAccount(ctx context.Context, account *entity.Account) error

	// UpdateAccountPassword updates the hashed password for a specific account record.
	//
	// Function:
	//   Called during ChangePassword and ResetPassword to overwrite the stored password hash.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - accountID: Primary key ID of the account record to update.
	//   - hashedPassword: The newly computed bcrypt/argon2 password hash.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   UPDATE accounts SET password = $1 WHERE id = $2;
	UpdateAccountPassword(ctx context.Context, accountID, hashedPassword string) error

	// CreateVerificationToken persists a short-lived token record for password resets or email confirmations.
	//
	// Function:
	//   Called during ForgotPassword to save the generated reset token and expiration timestamp.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: The VerificationToken entity (Identifier/Email, Token, ExpiresAt).
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   INSERT INTO verification_tokens (identifier, token, expires_at) VALUES ($1, $2, $3);
	CreateVerificationToken(ctx context.Context, token *entity.VerificationToken) error

	// GetVerificationToken retrieves an active token record by its token string.
	//
	// Function:
	//   Called during ResetPassword to validate token existence and verify whether it has expired.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: The raw token string submitted by the user.
	//
	// Returns:
	//   - *entity.VerificationToken: The matching token entity with its expiration timestamp.
	//   - error: ErrInvalidToken if no record is found, or database failure error.
	//
	// Example SQL:
	//   SELECT identifier, token, expires_at FROM verification_tokens WHERE token = $1 LIMIT 1;
	GetVerificationToken(ctx context.Context, token string) (*entity.VerificationToken, error)

	// DeleteVerificationToken removes a consumed or invalidated token from storage.
	//
	// Function:
	//   Called immediately upon successful password reset to guarantee single-use token consumption.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: The token string to delete.
	//
	// Returns:
	//   - error: Nil on success, or database error on failure.
	//
	// Example SQL:
	//   DELETE FROM verification_tokens WHERE token = $1;
	DeleteVerificationToken(ctx context.Context, token string) error
}

type SignInEventPayload struct {
	// User is the authenticated user entity.
	User *entity.User
}

type SignUpEventPayload struct {
	// Params holds mutable user creation parameters (including dynamic Extra metadata).
	Params *dto.CreateUserParams

	// User contains the persisted user entity (populated in EventSignUpAfter).
	User *entity.User
}