# `PhoenixKit.Users.Auth.User`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.95/lib/phoenix_kit/users/auth/user.ex#L1)

User schema for PhoenixKit authentication system.

This schema defines the core user entity with email-based authentication and account management features.

## Fields

- `email`: User's email address (unique, required for authentication)
- `password`: Virtual field for password input (redacted in logs)
- `hashed_password`: Bcrypt-hashed password stored in database (redacted)
- `current_password`: Virtual field for password confirmation (redacted)
- `confirmed_at`: Timestamp when email was confirmed (nil for unconfirmed accounts)

## Security Features

- Password hashing with bcrypt
- Email uniqueness enforcement
- Password strength validation
- Sensitive field redaction in logs
- Email confirmation workflow support

# `t`

```elixir
@type t() :: %PhoenixKit.Users.Auth.User{
  __meta__: term(),
  account_type: String.t(),
  confirmed_at: DateTime.t() | nil,
  current_password: String.t() | nil,
  custom_fields: map() | nil,
  email: String.t(),
  first_name: String.t() | nil,
  hashed_password: String.t(),
  inserted_at: DateTime.t(),
  is_active: boolean(),
  last_name: String.t() | nil,
  members: term(),
  organization: term(),
  organization_name: String.t() | nil,
  organization_uuid: UUIDv7.t() | nil,
  password: String.t() | nil,
  registration_city: String.t() | nil,
  registration_country: String.t() | nil,
  registration_ip: String.t() | nil,
  registration_region: String.t() | nil,
  role_assignments: term(),
  roles: term(),
  updated_at: DateTime.t(),
  user_timezone: String.t() | nil,
  username: String.t() | nil,
  uuid: UUIDv7.t() | nil
}
```

# `account_type_changeset`

A user changeset for updating account type and organization fields.

# `admin?`

Checks if a user is an admin or owner.

## Examples

    iex> admin?(user)
    true

# `confirm_changeset`

Confirms the account by setting `confirmed_at`.

# `custom_fields_changeset`

A user changeset for updating custom fields.

Custom fields are stored as JSONB and can contain arbitrary key-value pairs.

## Examples

    iex> custom_fields_changeset(user, %{custom_fields: %{"phone" => "555-1234"}})
    %Ecto.Changeset{valid?: true}

    iex> custom_fields_changeset(user, %{custom_fields: "invalid"})
    %Ecto.Changeset{valid?: false}

# `email_changeset`

A user changeset for changing the email.

It requires the email to change otherwise an error is added.

# `excluded_fields`

Returns list of fields excluded from get_user_field for security.

These fields contain sensitive or internal data and should not be
accessed via the generic field accessor.

## Examples

    iex> excluded_fields()
    [:password, :current_password, :hashed_password, :__meta__, :__struct__]

# `full_name`

Gets the user's full name by combining first and last name.

## Examples

    iex> full_name(%User{first_name: "John", last_name: "Doe"})
    "John Doe"

    iex> full_name(%User{first_name: "John", last_name: nil})
    "John"

    iex> full_name(%User{first_name: nil, last_name: nil})
    nil

# `generate_username_from_email`

Generate a username from an email address.

Takes the part before @ symbol, converts to lowercase, replaces dots with underscores,
and ensures it meets validation requirements.

## Examples

    iex> generate_username_from_email("john.doe@example.com")
    "john_doe"

    iex> generate_username_from_email("user@example.com")
    "user"

# `get_preferred_locale`

Gets the user's preferred locale from custom_fields.

Returns nil if not set (indicating system default should be used).

## Examples

    iex> get_preferred_locale(%User{custom_fields: %{"preferred_locale" => "en-GB"}})
    "en-GB"

    iex> get_preferred_locale(%User{custom_fields: %{}})
    nil

# `get_roles`

Gets all roles for a user.

## Examples

    iex> get_roles(user)
    ["Admin", "User"]

# `guest_user_changeset`

A user changeset for guest checkout.

Creates a temporary user with a random password for guests who
complete checkout without registering. The user will have
`confirmed_at = nil` until they verify their email.

## Features

- Generates a random secure password (required by DB constraint)
- Sets `custom_fields.source` to "guest_checkout" for tracking
- Generates UUID and username automatically
- Does NOT confirm the email (confirmed_at remains nil)

## Examples

    iex> guest_user_changeset(%User{}, %{email: "guest@example.com", first_name: "John"})
    %Ecto.Changeset{valid?: true}

# `has_role?`

Checks if a user has a specific role.

## Examples

    iex> has_role?(user, "Admin")
    true

    iex> has_role?(user, "Owner")
    false

# `owner?`

Checks if a user is an owner.

## Examples

    iex> owner?(user)
    true

# `password_changeset`

A user changeset for changing the password.

## Options

  * `:hash_password` - Hashes the password so it can be stored securely
    in the database and ensures the password field is cleared to prevent
    leaks in the logs. If password hashing is not needed and clearing the
    password field is not desired (like when using this changeset for
    validations on a LiveView form), this option can be set to `false`.
    Defaults to `true`.

# `preferred_locale_changeset`

A user changeset for updating preferred locale/dialect.

This allows authenticated users to select their preferred dialect variant
(e.g., en-GB instead of en-US) while URLs continue to show base codes.
The locale is stored in the `custom_fields` JSONB column.

## Validation

- Format: Must match ~r/^[a-z]{2,3}(-[A-Za-z]{2,4})?$/
- Existence: Must exist in predefined language list
- NULL/empty allowed: Indicates "use system default"

## Examples

    iex> preferred_locale_changeset(user, %{preferred_locale: "en-GB"})
    #Ecto.Changeset<...>

    iex> preferred_locale_changeset(user, %{preferred_locale: nil})
    #Ecto.Changeset<...>  # Clears preference, uses defaults

    iex> preferred_locale_changeset(user, %{preferred_locale: "invalid"})
    #Ecto.Changeset<errors: [preferred_locale: {"must be a valid locale format", []}]>

# `profile_changeset`

A user changeset for updating profile information.

## Options

  * `:validate_email` - Validates the uniqueness of the email, in case
    you don't want to validate the uniqueness of the email (like when
    using this changeset for validations on a LiveView form before
    submitting the form), this option can be set to `false`.
    Defaults to `true`.

# `registration_changeset`

A user changeset for registration.

It is important to validate the length of both email and password.
Otherwise databases may truncate the email without warnings, which
could lead to unpredictable or insecure behaviour. Long passwords may
also be very expensive to hash for certain algorithms.

## Options

  * `:hash_password` - Hashes the password so it can be stored securely
    in the database and ensures the password field is cleared to prevent
    leaks in the logs. If password hashing is not needed and clearing the
    password field is not desired (like when using this changeset for
    validations on a LiveView form), this option can be set to `false`.
    Defaults to `true`.

  * `:validate_email` - Validates the uniqueness of the email, in case
    you don't want to validate the uniqueness of the email (like when
    using this changeset for validations on a LiveView form before
    submitting the form), this option can be set to `false`.
    Defaults to `true`.

An optional `:custom_fields` map may be included in `attrs` to persist
arbitrary key-value metadata alongside the user record in a single atomic
insert. If omitted, `custom_fields` defaults to `%{}`.

# `status_changeset`

A user changeset for updating active status.

# `timezone_changeset`

A user changeset for updating timezone preference.

## Examples

    iex> timezone_changeset(user, %{"user_timezone" => "+5"})
    %Ecto.Changeset{valid?: true}

    iex> timezone_changeset(user, %{"user_timezone" => "invalid"})
    %Ecto.Changeset{valid?: false}

# `unconfirm_changeset`

Unconfirms the account by setting `confirmed_at` to nil.

# `valid_password?`

Verifies the password.

If there is no user or the user doesn't have a password, we call
`Bcrypt.no_user_verify/0` to avoid timing attacks.

# `validate_current_password`

Validates the current password otherwise adds an error to the changeset.

# `validate_locale_value`

Validates a locale value for format and existence.

Returns `:ok` if valid, `{:error, message}` if invalid.

## Examples

    iex> validate_locale_value("en-US")
    :ok

    iex> validate_locale_value("invalid")
    {:error, "must be a valid locale format (e.g., en-US, es-MX)"}

---

*Consult [api-reference.md](api-reference.md) for complete listing*