Search documentation of phoenix_kit

# PhoenixKit.Users.Auth (phoenix_kit v1.6.19)

View Source

The Auth context for user authentication and management.

This module provides functions for user registration, authentication, password management, and email confirmation. It serves as the main interface for all user-related operations in PhoenixKit.

## Core Functions

### User Registration and Authentication

- `register_user/1` - Register a new user with email and password
- `get_user_by_email_and_password/2` - Authenticate user credentials
- `get_user_by_email/1` - Find user by email address

### Password Management

- `change_user_password/2` - Update user password
- `reset_user_password/2` - Reset password with token
- `deliver_user_reset_password_instructions/1` - Send password reset email

### Email Confirmation

- `deliver_user_confirmation_instructions/1` - Send confirmation email
- `confirm_user/1` - Confirm user account with token
- `update_user_email/2` - Change user email with confirmation

### Session Management

- `generate_user_session_token/1` - Create session token for login
- `get_user_by_session_token/1` - Get user from session token
- `delete_user_session_token/1` - Logout user session

## Usage Examples

    # Register a new user
    {:ok, user} = PhoenixKit.Users.Auth.register_user(%{
      email: "user@example.com",
      password: "secure_password123"
    })

    # Authenticate user
    case PhoenixKit.Users.Auth.get_user_by_email_and_password(email, password) do
      {:ok, user} -> {:ok, user}
      {:error, :invalid_credentials} -> {:error, :invalid_credentials}
      {:error, :rate_limit_exceeded} -> {:error, :rate_limit_exceeded}
    end

    # Send confirmation email
    PhoenixKit.Users.Auth.deliver_user_confirmation_instructions(user)

## Security Features

- Passwords are hashed using bcrypt
- Email confirmation prevents unauthorized account creation
- Session tokens provide secure authentication
- Password reset tokens expire for security
- All sensitive operations are logged

# Summary

## Functions

admin_confirm_user(user)

Manually confirms a user account (admin function).

admin_unconfirm_user(user)

Manually unconfirms a user account (admin function).

admin_update_user_password(user, attrs, context \\ %{})

Updates the user password as an admin (bypasses current password validation).

apply_user_email(user, password, attrs)

Emulates that the email will change without actually changing it in the database.

assign_role(user, role_name, assigned_by \\ nil, opts \\ [])

Assigns a role to a user.

assign_roles_to_existing_users(opts \\ [])

Assigns roles to existing users who don't have any PhoenixKit roles.

bulk_update_user_fields(users, attrs)

Bulk update multiple users with the same field values.

calculate_file_hash(file_path)

Calculate SHA256 hash of a file.

change_user_email(user, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for changing the user email.

change_user_password(user, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for changing the user password.

change_user_profile(user, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for changing the user profile.

change_user_registration(user, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for tracking user changes.

confirm_user(token)

Confirms a user by the given token.

delete_all_user_session_tokens(user)

Deletes all session tokens for the given user.

delete_user_custom_field(user, key)

Deletes a specific custom field for a user.

delete_user_session_token(token)

Deletes the signed token with the given context.

deliver_user_confirmation_instructions(user, confirmation_url_fun)

Delivers the confirmation email instructions to the given user.

deliver_user_reset_password_instructions(user, reset_password_url_fun)

Delivers the reset password email to the given user.

deliver_user_update_email_instructions(user, current_email, update_email_url_fun)

Delivers the update email instructions to the given user.

demote_to_user(user)

Demotes an admin user to regular user role.

ensure_active_user(user)

Ensures the user is active by checking the is_active field.

generate_user_session_token(user, opts \\ [])

Generates a session token.

get_all_user_session_tokens(user)

Gets all active session tokens for the given user.

get_first_admin()

Gets the first admin user (Owner or Admin role).

get_first_admin_id()

Gets the ID of the first admin user.

get_first_user()

Gets the first user in the system (by ID).

get_first_user_id()

Gets the ID of the first user in the system.

get_role_stats()

Gets role statistics for dashboard display.

get_session_token_record(token)

Gets the user token record for the given session token.

get_user(id)

Gets a single user.

get_user!(id)

Gets a single user.

get_user_by_email(email)

Gets a user by email.

get_user_by_email_and_password(email, password, ip_address \\ nil)

Gets a user by email and password.

get_user_by_reset_password_token(token)

Gets the user by reset password token.

get_user_by_session_token(token)

Gets the user with the given signed token.

get_user_custom_field(user, key)

Gets a specific custom field value for a user.

get_user_field(user, field)

Gets a user field value from either schema fields or custom fields.

get_user_for_selection(user_id)

Gets a user by ID with minimal fields for selection interfaces.

get_user_roles(user)

Gets all active roles for a user.

get_user_with_roles(id)

Gets a user by ID with preloaded roles.

list_roles()

Lists all roles.

list_users_paginated(opts \\ [])

Lists users with pagination and optional role filtering.

promote_to_admin(user, assigned_by \\ nil)

Promotes a user to admin role.

register_user(attrs, ip_address \\ nil)

Registers a user with automatic role assignment.

register_user_with_geolocation(attrs, ip_address)

Registers a user with IP geolocation data.

remove_role(user, role_name, opts \\ [])

Removes a role from a user.

reset_user_password(user, attrs)

Resets the user password.

search_users(search_term)

Searches users by email or name for selection interfaces.

set_user_custom_field(user, key, value)

Sets a specific custom field value for a user.

toggle_user_confirmation(user)

Toggles user confirmation status (admin function).

update_user_avatar(user, file_path, filename, user_id \\ nil)

Update a user's avatar by storing the file and saving the file ID.

update_user_custom_fields(user, custom_fields)

Updates user custom fields.

update_user_email(user, token)

Updates the user email using the given token.

update_user_fields(user, attrs)

Updates both schema and custom fields in a single call.

update_user_locale_preference(user, preferred_locale)

Updates user's preferred locale (dialect preference).

update_user_password(user, password, attrs)

Updates the user password.

update_user_profile(user, attrs)

Updates a user's profile information.

update_user_status(user, attrs)

Updates user status with Owner protection.

user_has_role?(user, role_name)

Checks if a user has a specific role.

users_with_role(role_name)

Gets all users who have a specific role.

verify_session_fingerprint(conn, token)

Verifies a session fingerprint against the stored token data.

# Functions

# admin_confirm_user(user)

Manually confirms a user account (admin function).

## Examples

    iex> admin_confirm_user(user)
    {:ok, %User{}}

    iex> admin_confirm_user(invalid_user)
    {:error, %Ecto.Changeset{}}

# admin_unconfirm_user(user)

Manually unconfirms a user account (admin function).

## Examples

    iex> admin_unconfirm_user(user)
    {:ok, %User{}}

    iex> admin_unconfirm_user(invalid_user)
    {:error, %Ecto.Changeset{}}

# admin_update_user_password(user, attrs, context \\ %{})

Updates the user password as an admin (bypasses current password validation).

## Parameters

- `user` - The user whose password is being updated
- `attrs` - Password attributes (password, password_confirmation)
- `context` - Optional context map containing:
  - `:admin_user` - The admin performing the action (for audit logging)
  - `:ip_address` - IP address of the admin (for audit logging)
  - `:user_agent` - User agent of the admin (for audit logging)

## Examples

    iex> admin_update_user_password(user, %{password: "new_password", password_confirmation: "new_password"})
    {:ok, %User{}}

    iex> admin_update_user_password(user, %{password: "new_password", password_confirmation: "new_password"}, %{admin_user: admin, ip_address: "192.168.1.1"})
    {:ok, %User{}}

    iex> admin_update_user_password(user, %{password: "short"})
    {:error, %Ecto.Changeset{}}

# apply_user_email(user, password, attrs)

Emulates that the email will change without actually changing it in the database.

## Examples

    iex> apply_user_email(user, "valid password", %{email: ...})
    {:ok, %User{}}

    iex> apply_user_email(user, "invalid password", %{email: ...})
    {:error, %Ecto.Changeset{}}

# assign_role(user, role_name, assigned_by \\ nil, opts \\ [])

Assigns a role to a user.

## Examples

    iex> assign_role(user, "Admin")
    {:ok, %RoleAssignment{}}

    iex> assign_role(user, "Admin", assigned_by_user)
    {:ok, %RoleAssignment{}}

    iex> assign_role(user, "NonexistentRole")
    {:error, :role_not_found}

# assign_roles_to_existing_users(opts \\ [])

Assigns roles to existing users who don't have any PhoenixKit roles.

This is useful for migration scenarios where PhoenixKit is installed into an existing application with users.

## Examples

    iex> assign_roles_to_existing_users()
    {:ok, %{assigned_owner: 1, assigned_users: 5, total_processed: 6}}

# bulk_update_user_fields(users, attrs)

Bulk update multiple users with the same field values.

This function updates multiple users at once with the same set of fields. Each user is updated independently, and the function returns a list of results showing which updates succeeded and which failed.

Both schema fields and custom fields can be updated in the same call.

## Parameters

- `users` - List of User structs to update
- `attrs` - Map of field names to values (can include both schema and custom fields)

## Returns

Returns `{:ok, results}` where results is a list of tuples:

- `{:ok, user}` - Successfully updated user
- `{:error, changeset}` - Failed update with error details

## Examples

    # Update multiple users with the same fields
    iex> users = [user1, user2, user3]
    iex> bulk_update_user_fields(users, %{status: "active", department: "Engineering"})
    {:ok, [
      {:ok, %User{status: "active", custom_fields: %{"department" => "Engineering"}}},
      {:ok, %User{status: "active", custom_fields: %{"department" => "Engineering"}}},
      {:error, %Ecto.Changeset{}}
    ]}

    # Update both schema and custom fields
    iex> bulk_update_user_fields(users, %{
    ...>   first_name: "John",           # Schema field
    ...>   last_name: "Doe",             # Schema field
    ...>   custom_field_1: "value1",     # Custom field
    ...>   custom_field_2: "value2"      # Custom field
    ...> })
    {:ok, [results...]}

# calculate_file_hash(file_path)

Calculate SHA256 hash of a file.

Used internally for file integrity verification.

## Parameters

- `file_path` - Path to the file

## Returns

- String containing the lowercase hexadecimal SHA256 hash

# change_user_email(user, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for changing the user email.

## Examples

    iex> change_user_email(user)
    %Ecto.Changeset{data: %User{}}

# change_user_password(user, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for changing the user password.

## Examples

    iex> change_user_password(user)
    %Ecto.Changeset{data: %User{}}

# change_user_profile(user, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for changing the user profile.

## Examples

    iex> change_user_profile(user)
    %Ecto.Changeset{data: %User{}}

# change_user_registration(user, attrs \\ %{})

Returns an `%Ecto.Changeset{}` for tracking user changes.

## Examples

    iex> change_user_registration(user)
    %Ecto.Changeset{data: %User{}}

# confirm_user(token)

Confirms a user by the given token.

If the token matches, the user account is marked as confirmed and the token is deleted.

# delete_all_user_session_tokens(user)

Deletes all session tokens for the given user.

This function is useful when you need to force logout a user from all sessions, for example when their roles change and they need fresh authentication.

# delete_user_custom_field(user, key)

Deletes a specific custom field for a user.

Removes the key from the custom_fields map.

## Examples

    iex> delete_user_custom_field(user, "phone")
    {:ok, %User{}}

# delete_user_session_token(token)

Deletes the signed token with the given context.

# deliver_user_confirmation_instructions(user, confirmation_url_fun)

Delivers the confirmation email instructions to the given user.

## Examples

    iex> deliver_user_confirmation_instructions(user, &PhoenixKit.Utils.Routes.url("/users/confirm/#{&1}"))
    {:ok, %{to: ..., body: ...}}

    iex> deliver_user_confirmation_instructions(confirmed_user, &PhoenixKit.Utils.Routes.url("/users/confirm/#{&1}"))
    {:error, :already_confirmed}

# deliver_user_reset_password_instructions(user, reset_password_url_fun)

Delivers the reset password email to the given user.

This function includes rate limiting protection to prevent mass password reset attacks. After exceeding the rate limit (default: 3 requests per 5 minutes), subsequent requests will be rejected with `{:error, :rate_limit_exceeded}`.

## Examples

    iex> deliver_user_reset_password_instructions(user, &PhoenixKit.Utils.Routes.url("/users/reset-password/#{&1}"))
    {:ok, %{to: ..., body: ...}}

    iex> deliver_user_reset_password_instructions(user, &PhoenixKit.Utils.Routes.url("/users/reset-password/#{&1}"))
    {:error, :rate_limit_exceeded}

# deliver_user_update_email_instructions(user, current_email, update_email_url_fun)

Delivers the update email instructions to the given user.

## Examples

    iex> deliver_user_update_email_instructions(user, current_email, &PhoenixKit.Utils.Routes.url("/users/settings/confirm_email/#{&1}"))
    {:ok, %{to: ..., body: ...}}

# demote_to_user(user)

Demotes an admin user to regular user role.

## Examples

    iex> demote_to_user(user)
    {:ok, %RoleAssignment{}}

# ensure_active_user(user)

Ensures the user is active by checking the is_active field.

Returns nil for inactive users and logs a warning. Returns the user for active users or nil input.

## Examples

    iex> ensure_active_user(%User{is_active: true})
    %User{is_active: true}

    iex> ensure_active_user(%User{is_active: false, id: 123})
    nil

    iex> ensure_active_user(nil)
    nil

# generate_user_session_token(user, opts \\ [])

Generates a session token.

## Options

- `:fingerprint` - Optional session fingerprint map with `:ip_address` and `:user_agent_hash`

## Examples

    # Without fingerprinting (backward compatible)
    token = generate_user_session_token(user)

    # With fingerprinting
    fingerprint = PhoenixKit.Utils.SessionFingerprint.create_fingerprint(conn)
    token = generate_user_session_token(user, fingerprint: fingerprint)

# get_all_user_session_tokens(user)

Gets all active session tokens for the given user.

This is useful for finding all active sessions to broadcast logout messages.

# get_first_admin()

Gets the first admin user (Owner or Admin role).

Useful for programmatic operations that require a user ID, such as creating entities via scripts or seeds.

Returns the first Owner if one exists, otherwise the first Admin, otherwise nil.

## Examples

    iex> get_first_admin()
    %User{id: 1, email: "admin@example.com"}

    iex> get_first_admin()
    nil  # No admin users exist

# get_first_admin_id()

Gets the ID of the first admin user.

Convenience function that returns just the user ID, useful for setting `created_by` fields programmatically.

## Examples

    iex> get_first_admin_id()
    1

    iex> get_first_admin_id()
    nil  # No admin users exist

    # Common usage for creating entities
    PhoenixKit.Entities.create_entity(%{
      name: "contact",
      display_name: "Contact",
      created_by: PhoenixKit.Users.Auth.get_first_admin_id()
    })

# get_first_user()

Gets the first user in the system (by ID).

Returns the user with the lowest ID, typically the first registered user. Useful as a fallback when no specific admin is needed.

## Examples

    iex> get_first_user()
    %User{id: 1}

# get_first_user_id()

Gets the ID of the first user in the system.

Convenience function for getting a user ID for `created_by` fields.

## Examples

    iex> get_first_user_id()
    1

# get_role_stats()

Gets role statistics for dashboard display.

## Examples

    iex> get_role_stats()
    %{
      total_users: 10,
      owner_count: 1,
      admin_count: 2,
      user_count: 7
    }

# get_session_token_record(token)

Gets the user token record for the given session token.

This is useful for accessing fingerprint data stored with the token.

## Examples

    iex> get_session_token_record("valid_token")
    %UserToken{ip_address: "192.168.1.1", user_agent_hash: "abc123"}

    iex> get_session_token_record("invalid_token")
    nil

# get_user(id)

Gets a single user.

Returns `nil` if the user does not exist.

## Examples

    iex> get_user(123)
    %User{}

    iex> get_user(456)
    nil

# get_user!(id)

Gets a single user.

Raises `Ecto.NoResultsError` if the User does not exist.

## Examples

    iex> get_user!(123)
    %User{}

    iex> get_user!(456)
    ** (Ecto.NoResultsError)

# get_user_by_email(email)

Gets a user by email.

## Examples

    iex> get_user_by_email("foo@example.com")
    %User{}

    iex> get_user_by_email("unknown@example.com")
    nil

# get_user_by_email_and_password(email, password, ip_address \\ nil)

Gets a user by email and password.

This function includes rate limiting protection to prevent brute-force attacks. After exceeding the rate limit (default: 5 attempts per minute), subsequent attempts will be rejected with `{:error, :rate_limit_exceeded}`.

## Examples

    iex> get_user_by_email_and_password("foo@example.com", "correct_password")
    {:ok, %User{}}

    iex> get_user_by_email_and_password("foo@example.com", "invalid_password")
    {:error, :invalid_credentials}

    iex> get_user_by_email_and_password("foo@example.com", "password", "192.168.1.1")
    {:ok, %User{}}

# get_user_by_reset_password_token(token)

Gets the user by reset password token.

## Examples

    iex> get_user_by_reset_password_token("validtoken")
    %User{}

    iex> get_user_by_reset_password_token("invalidtoken")
    nil

# get_user_by_session_token(token)

Gets the user with the given signed token.

# get_user_custom_field(user, key)

Gets a specific custom field value for a user.

Returns the value if the key exists, or nil otherwise.

## Examples

    iex> get_user_custom_field(user, "phone")
    "555-1234"

    iex> get_user_custom_field(user, "nonexistent")
    nil

# get_user_field(user, field)

Gets a user field value from either schema fields or custom fields.

This unified accessor provides O(1) performance by checking struct fields first using Map.has_key?/2, then falling back to custom_fields JSONB.

Certain sensitive fields are excluded for security:

- password, current_password (virtual fields)
- hashed_password (use authentication functions instead)

## Examples

    # Standard schema fields (O(1) struct access)
    iex> get_user_field(user, "email")
    "user@example.com"

    iex> get_user_field(user, :first_name)
    "John"

    # Custom fields (O(1) JSONB lookup)
    iex> get_user_field(user, "phone")
    "555-1234"

    # Nonexistent returns nil
    iex> get_user_field(user, "nonexistent")
    nil

    # Excluded sensitive fields return nil
    iex> get_user_field(user, "hashed_password")
    nil

## Performance

- Standard fields: ~0.5μs (direct struct access)
- Custom fields: ~1-2μs (JSONB lookup)
- No performance penalty from checking both locations

# get_user_for_selection(user_id)

Gets a user by ID with minimal fields for selection interfaces.

Returns a user map with id, email, first_name, and last_name fields. Returns nil if user is not found.

## Examples

    iex> PhoenixKit.Users.Auth.get_user_for_selection(123)
    %{id: 123, email: "user@example.com", first_name: "John", last_name: "Doe"}

    iex> PhoenixKit.Users.Auth.get_user_for_selection(999)
    nil

# get_user_roles(user)

Gets all active roles for a user.

## Examples

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

    iex> get_user_roles(user_with_no_roles)
    []

# get_user_with_roles(id)

Gets a user by ID with preloaded roles.

## Examples

    iex> get_user_with_roles(123)
    %User{roles: [%Role{}, %Role{}]}

    iex> get_user_with_roles(999)
    nil

# list_roles()

Lists all roles.

## Examples

    iex> list_roles()
    [%Role{}, %Role{}, %Role{}]

# list_users_paginated(opts \\ [])

Lists users with pagination and optional role filtering.

## Examples

    iex> list_users_paginated(page: 1, page_size: 10)
    %{users: [%User{}], total_count: 50, total_pages: 5}

    iex> list_users_paginated(page: 1, page_size: 10, role: "Admin")
    %{users: [%User{}], total_count: 3, total_pages: 1}

# promote_to_admin(user, assigned_by \\ nil)

Promotes a user to admin role.

## Examples

    iex> promote_to_admin(user)
    {:ok, %RoleAssignment{}}

    iex> promote_to_admin(user, assigned_by_user)
    {:ok, %RoleAssignment{}}

# register_user(attrs, ip_address \\ nil)

Registers a user with automatic role assignment.

Role assignment is handled by Elixir application logic:

- First user receives Owner role
- Subsequent users receive User role
- Uses database transactions to prevent race conditions

This function includes rate limiting protection to prevent spam account creation. Rate limits apply per email address and optionally per IP address.

## Examples

    iex> register_user(%{field: value})
    {:ok, %User{}}

    iex> register_user(%{field: bad_value})
    {:error, %Ecto.Changeset{}}

    iex> register_user(%{email: "user@example.com"}, "192.168.1.1")
    {:ok, %User{}}

# register_user_with_geolocation(attrs, ip_address)

Registers a user with IP geolocation data.

This function attempts to look up geographical location information based on the provided IP address and includes it in the user registration. If geolocation lookup fails, the user is still registered with just the IP address.

This function automatically applies rate limiting based on the IP address.

## Examples

    iex> register_user_with_geolocation(%{email: "user@example.com", password: "password"}, "192.168.1.1")
    {:ok, %User{registration_ip: "192.168.1.1", registration_country: "United States"}}

    iex> register_user_with_geolocation(%{email: "invalid"}, "192.168.1.1")
    {:error, %Ecto.Changeset{}}

# remove_role(user, role_name, opts \\ [])

Removes a role from a user.

## Examples

    iex> remove_role(user, "Admin")
    {:ok, %RoleAssignment{}}

    iex> remove_role(user, "NonexistentRole")
    {:error, :assignment_not_found}

# reset_user_password(user, attrs)

Resets the user password.

## Examples

    iex> reset_user_password(user, %{password: "new long password", password_confirmation: "new long password"})
    {:ok, %User{}}

    iex> reset_user_password(user, %{password: "valid", password_confirmation: "not the same"})
    {:error, %Ecto.Changeset{}}

# search_users(search_term)

Searches users by email or name for selection interfaces.

Returns a list of users matching the search term, limited to 10 results for performance. Useful for autocomplete/typeahead interfaces.

## Examples

    iex> PhoenixKit.Users.Auth.search_users("john")
    [%User{email: "john@example.com", first_name: "John"}, ...]

    iex> PhoenixKit.Users.Auth.search_users("")
    []

# set_user_custom_field(user, key, value)

Sets a specific custom field value for a user.

Updates a single key in the custom_fields map while preserving other fields.

## Examples

    iex> set_user_custom_field(user, "phone", "555-1234")
    {:ok, %User{}}

    iex> set_user_custom_field(user, "department", "Product")
    {:ok, %User{}}

# toggle_user_confirmation(user)

Toggles user confirmation status (admin function).

## Examples

    iex> toggle_user_confirmation(confirmed_user)
    {:ok, %User{confirmed_at: nil}}

    iex> toggle_user_confirmation(unconfirmed_user)
    {:ok, %User{confirmed_at: ~N[2023-01-01 12:00:00]}}

# update_user_avatar(user, file_path, filename, user_id \\ nil)

Update a user's avatar by storing the file and saving the file ID.

This function handles the complete avatar upload workflow:

1. Stores the file in configured storage buckets
2. Automatically queues background job for variant generation
3. Saves the file ID to the user's custom_fields

This is a convenience function that combines file storage with user update. Can be called from any context (LiveView, controllers, scripts, etc.) outside of the PhoenixKit project.

## Parameters

- `user` - The User struct to update
- `file_path` - Path to the uploaded file (temporary location)
- `filename` - Original filename for the upload
- `user_id` - The user ID owning this file (defaults to user.id)

## Returns

- `{:ok, user}` - Avatar saved successfully
- `{:error, reason}` - File storage or update failed

## Examples

    # Store avatar in default location with automatic variant generation
    {:ok, updated_user} = Auth.update_user_avatar(user, "/tmp/upload_xyz", "avatar.jpg")

    # Store with explicit user_id (for custom workflows)
    {:ok, updated_user} = Auth.update_user_avatar(user, "/tmp/upload_xyz", "avatar.jpg", custom_user_id)

## Automatically Generated Variants

The storage layer automatically generates these image variants:

- original - Full-size image
- large - 800x800px
- medium - 400x400px
- small - 200x200px
- thumbnail - 100x100px

# update_user_custom_fields(user, custom_fields)

Updates user custom fields.

Custom fields are stored as JSONB and can contain arbitrary key-value pairs for extending user data without schema changes.

## Examples

    iex> update_user_custom_fields(user, %{"phone" => "555-1234", "department" => "Engineering"})
    {:ok, %User{}}

    iex> update_user_custom_fields(user, "invalid")
    {:error, %Ecto.Changeset{}}

# update_user_email(user, token)

Updates the user email using the given token.

If the token matches, the user email is updated and the token is deleted. The confirmed_at date is also updated to the current time.

# update_user_fields(user, attrs)

Updates both schema and custom fields in a single call.

This is a unified update function that automatically splits the provided attributes into schema fields and custom fields, updating both appropriately.

## Schema Fields

- first_name, last_name, email, username, user_timezone

## Custom Fields

- Any other keys are treated as custom fields

## Examples

    iex> update_user_fields(user, %{
    ...>   "first_name" => "John",
    ...>   "email" => "john@example.com",
    ...>   "phone" => "555-1234",
    ...>   "department" => "Engineering"
    ...> })
    {:ok, %User{}}

    iex> update_user_fields(user, %{email: "invalid"})
    {:error, %Ecto.Changeset{}}

# update_user_locale_preference(user, preferred_locale)

Updates user's preferred locale (dialect preference).

This allows users to select specific language dialects (e.g., en-GB, en-US) while URLs continue to use base codes (e.g., /en/).

## Examples

    iex> update_user_locale_preference(user, "en-GB")
    {:ok, %User{preferred_locale: "en-GB"}}

    iex> update_user_locale_preference(user, "invalid")
    {:error, %Ecto.Changeset{}}

# update_user_password(user, password, attrs)

Updates the user password.

## Examples

    iex> update_user_password(user, "valid password", %{password: ...})
    {:ok, %User{}}

    iex> update_user_password(user, "invalid password", %{password: ...})
    {:error, %Ecto.Changeset{}}

# update_user_profile(user, attrs)

Updates a user's profile information.

## Examples

    iex> update_user_profile(user, %{first_name: "John", last_name: "Doe"})
    {:ok, %User{}}

    iex> update_user_profile(user, %{first_name: ""})
    {:error, %Ecto.Changeset{}}

# update_user_status(user, attrs)

Updates user status with Owner protection.

Prevents deactivation of the last Owner to maintain system security.

## Parameters

- `user`: User to update
- `attrs`: Status attributes (typically %{"is_active" => true/false})

## Examples

    iex> update_user_status(user, %{"is_active" => false})
    {:ok, %User{}}

    iex> update_user_status(last_owner, %{"is_active" => false})
    {:error, :cannot_deactivate_last_owner}

# user_has_role?(user, role_name)

Checks if a user has a specific role.

## Examples

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

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

# users_with_role(role_name)

Gets all users who have a specific role.

## Examples

    iex> users_with_role("Admin")
    [%User{}, %User{}]

    iex> users_with_role("NonexistentRole")
    []

# verify_session_fingerprint(conn, token)

Verifies a session fingerprint against the stored token data.

Returns:

- `:ok` if fingerprint matches or fingerprinting is disabled
- `{:warning, reason}` if there's a partial mismatch (IP or UA changed)
- `{:error, :fingerprint_mismatch}` if both IP and UA changed

## Examples

    iex> verify_session_fingerprint(conn, token)
    :ok

    iex> verify_session_fingerprint(conn, token)
    {:warning, :ip_mismatch}