# `PhoenixKit.Users.Auth` [πŸ”—](https://github.com/BeamLabEU/phoenix_kit/blob/v2.15.1/lib/phoenix_kit/users/auth.ex#L1) 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 # `admin_confirm_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` 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` 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. **Authorizes as well as audits**: when present, the write is refused unless `can_manage_user_credentials?/2` allows this actor over this target. * `:ip_address` - IP address of the admin (for audit logging) * `:user_agent` - User agent of the admin (for audit logging) Omitting `:admin_user` is the system path β€” seeds, migrations and mix tasks act with no actor and are not rank-checked, matching `update_user_status/3`. A web caller must always pass it; without it there is nothing to check. ## 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(owner, %{password: "new_password"}, %{admin_user: admin}) {:error, :insufficient_permissions} iex> admin_update_user_password(user, %{password: "short"}) {:error, %Ecto.Changeset{}} # `apply_user_email` 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` 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` 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` 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` 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 # `can_delete_user?` Checks if a user can be deleted by the current user. Returns `:ok` if deletion is allowed, or `{:error, reason}` if not. ## Examples iex> can_delete_user?(user_to_delete, current_user) :ok iex> can_delete_user?(current_user, current_user) {:error, :cannot_delete_self} # `can_manage_user_credentials?` True when `current_user` may manage `user`'s credentials β€” set a new password, send a password-reset mail, or change the address those mails are delivered to. Credential management is the one admin action that hands over an account, so it is decided by ROLE and by RANK, not by the `users` permission that admits a visitor to the user pages. Holding `users` answers "may this person administer users at all"; it must never answer "may this person take over that particular account". The rules mirror `can_delete_user?/2` (only an Owner acts on an Admin) and the impersonation authority in `PhoenixKitWeb.Users.MultiSession` (an Owner is never a target for anyone but themselves), so the three account-takeover surfaces agree. 1. Your own account is always yours to manage. 2. The actor must hold Owner or Admin **by role**. 3. An Owner target may be managed only by an Owner. 4. An Admin target may be managed only by an Owner. Everything else β€” an ordinary user changing their own password β€” belongs on their own settings page, not here. ## Examples iex> can_manage_user_credentials?(some_user, admin) true iex> can_manage_user_credentials?(owner, admin) false # `can_manage_user_status?` True when `current_user` may activate or deactivate `user`. Same authority as `can_manage_user_credentials?/2`, for the same reason: deactivation is decided by rank, not by the `users` permission that admits a visitor to the user pages. Without it a role holding only `users` can switch off an Admin β€” or a non-last Owner β€” which is a denial of service against the accounts that are meant to outrank it. Unlike credential management, **your own status is not yours to change**. The admin UI has always said so ("You cannot deactivate your own account for security reasons") but two of the three pages enforced it only in the template, and the third not at all β€” so the rule lived in markup a client composes for itself. It lives here now. The last-Owner protection in `Roles.can_deactivate_user?/1` is a separate, target-only rule and still applies on top of this one. # `change_account_type` Changes a user's account type. Validates no members exist when switching orgβ†’person. # `change_admin_note` Returns a changeset for tracking admin note changes. ## Examples iex> change_admin_note(note) %Ecto.Changeset{} # `change_user_email` Returns an `%Ecto.Changeset{}` for changing the user email. ## Examples iex> change_user_email(user) %Ecto.Changeset{data: %User{}} # `change_user_password` Returns an `%Ecto.Changeset{}` for changing the user password. ## Examples iex> change_user_password(user) %Ecto.Changeset{data: %User{}} # `change_user_profile` Returns an `%Ecto.Changeset{}` for changing the user profile. ## Examples iex> change_user_profile(user) %Ecto.Changeset{data: %User{}} # `change_user_registration` Returns an `%Ecto.Changeset{}` for tracking user changes. ## Examples iex> change_user_registration(user) %Ecto.Changeset{data: %User{}} # `confirm_user` Confirms a user by the given token. If the token matches, the user account is marked as confirmed and the token is deleted. # `confirm_user_from_external_proof` ```elixir @spec confirm_user_from_external_proof(PhoenixKit.Users.Auth.User.t()) :: {:ok, PhoenixKit.Users.Auth.User.t()} | {:error, Ecto.Changeset.t()} ``` Confirms an account whose email ownership was just proven by an external channel (verified OAuth email, magic link) rather than by the confirmation email β€” and closes the account-pre-hijack window while doing so. An unconfirmed row may have been *pre-registered by someone else* with a password they know. Confirming it alone would hand that row to the rightful address holder while leaving the pre-registrant's password and sessions intact. So, atomically with the confirmation, every token (sessions, pending resets, confirmation links) is deleted and the stored password hash is rotated to an unguessable value. The rightful owner sets a password via "forgot password" if they want one; they never knew the old one. Already-confirmed users are returned unchanged. # `create_admin_note` Creates an admin note about a user. ## Parameters - `user` - The user being noted about - `author` - The admin creating the note - `attrs` - Map containing `:content` ## Examples iex> create_admin_note(user, author, %{content: "Important note"}) {:ok, %AdminNote{}} iex> create_admin_note(user, author, %{content: ""}) {:error, %Ecto.Changeset{}} # `create_guest_user` Creates a guest user from checkout billing data. This function is used during guest checkout to create a temporary user account. The user will have `confirmed_at = nil` until they verify their email address. ## Parameters - `attrs` - Map with email (required), first_name, last_name ## Returns - `{:ok, user}` - New user created successfully - `{:error, :email_exists_confirmed}` - Email belongs to confirmed user (should login) - `{:error, :email_exists_unconfirmed, existing_user}` - Reuse existing unconfirmed user - `{:error, changeset}` - Validation errors ## Examples iex> create_guest_user(%{email: "guest@example.com", first_name: "John"}) {:ok, %User{}} iex> create_guest_user(%{email: "existing@confirmed.com"}) {:error, :email_exists_confirmed} iex> create_guest_user(%{email: "existing@unconfirmed.com"}) {:error, :email_exists_unconfirmed, %User{}} # `delete_admin_note` Deletes an admin note. ## Examples iex> delete_admin_note(note) {:ok, %AdminNote{}} # `delete_all_user_session_tokens` 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` Deletes a user account with proper cascade handling and data anonymization. ## Protection Rules 1. Cannot delete self - Prevents accidental self-deletion 2. Cannot delete last Owner - System must always have at least one Owner 3. Admin/Owner only - Only privileged users can delete accounts ## Data Handling Strategy ### Cascade Delete (automatic or manual) - User tokens (ON DELETE CASCADE in DB) - Role assignments (ON DELETE CASCADE in DB) - OAuth providers - Billing profiles - Shop carts - Admin notes ### Anonymize (preserve data, remove PII) - Orders - SET NULL on user_uuid, preserve financial records - Posts - Keep content, set user_uuid to NULL, mark as deleted author - Comments - Keep content, set user_uuid to NULL, mark as deleted author - Tickets - Preserve for support history, anonymize - Email logs - Retain for compliance, anonymize - Files - Anonymize ownership ## Parameters - `user` - The user to delete - `opts` - Options map containing: - `:current_user` - The user performing the deletion (required) - `:ip_address` - IP address for audit logging - `:user_agent` - User agent for audit logging ## Returns - `{:ok, %{deleted_user_uuid: uuid, anonymized_records: count}}` - Success - `{:error, :cannot_delete_self}` - Cannot delete your own account - `{:error, :cannot_delete_last_owner}` - Cannot delete the last Owner - `{:error, :insufficient_permissions}` - Current user lacks permission - `{:error, reason}` - Other errors ## Examples iex> delete_user(user, %{current_user: admin_user}) {:ok, %{deleted_user_uuid: "some-uuid", anonymized_records: 15}} iex> delete_user(user, %{current_user: user}) {:error, :cannot_delete_self} iex> delete_user(last_owner, %{current_user: admin_user}) {:error, :cannot_delete_last_owner} iex> delete_user(admin_user, %{current_user: non_owner_admin}) {:error, :insufficient_permissions} # `delete_user_custom_field` ```elixir @spec delete_user_custom_field(PhoenixKit.Users.Auth.User.t(), String.t(), keyword()) :: {:ok, PhoenixKit.Users.Auth.User.t()} | {:error, :not_found} ``` Deletes a specific custom field for a user. Removes the key at the database level (`custom_fields - key`) β€” the removal counterpart to `merge_user_custom_fields/3`, with the same lost-update rationale: the historical Map.delete + whole-map replace could silently drop a key a concurrent writer had just merged in. Removing an absent key is a no-op that still returns `{:ok, user}`; returns `{:error, :not_found}` if the user row was deleted concurrently. ## Examples iex> delete_user_custom_field(user, "phone") {:ok, %User{}} # `delete_user_session_token` Deletes the signed token with the given context. # `deliver_user_confirmation_instructions` 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` 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}`. ## Options * `:rate_limit` β€” set to `false` when the caller has ALREADY charged `RateLimiter.check_password_reset_rate_limit/1` for this request. The public forgot-password form has to throttle before the user lookup (a limiter that only runs for addresses which resolve to a user is an account-existence oracle), and both checks hit the same per-email bucket β€” so leaving this on there spends two of the three allowed hits per submission and silently drops every second reset email. Defaults to `true` for callers with no limiter of their own (e.g. the admin "send reset link" action). ## 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` Delivers the update email instructions to the given user. ## Examples iex> deliver_user_update_email_instructions(user, current_email, &PhoenixKit.Utils.Routes.url("/profile/settings/confirm-email/#{&1}")) {:ok, %{to: ..., body: ...}} # `demote_to_user` Demotes an admin user to regular user role. ## Examples iex> demote_to_user(user) {:ok, %RoleAssignment{}} # `enforce_registration_account_type` ```elixir @spec enforce_registration_account_type(map(), String.t()) :: map() ``` Stamps the account-type policy onto public-signup params, server-side. ⚠️ This β€” not the hidden `