docs: password change UI tutorial (#656)

* docs: password change UI tutorial

Add tutorial for implementing a password-change UI.

* docs(fix): Put field policy bypass in a separate section

Author: aidalgol

README.md

@@ -31,6 +31,7 @@ Welcome! Here you will find everything you need to know to get started with Ash
 - [Get Started](documentation/tutorials/get-started.md)
 - [Using with LiveView](documentation/tutorials/liveview.md)
 - [Overriding UI](documentation/tutorials/ui-overrides.md)
+- [Password-Change UI](documentation/tutorials/password-change.md)
 
 ## Related packages
 

documentation/tutorials/password-change.md

@@ -0,0 +1,281 @@
+# Building a password-change UI
+AshAuthentication's Igniter task adds a `:change_password` action when you specify the password strategy, but AshAuthenticationPhoenix does not provide a component for this action, so you will need to either write your own, or use one provided by a component library that supports [AshPhoenix](https://hexdocs.pm/ash_phoenix/).  The main reason for this is that the password-change UI is usually not as separate from the rest of an application as sign-in, registration, and password-reset actions.
+
+This is the `:change_password` action that we are starting with, generated by Igniter.
+```elixir
+# lib/my_app/accounts/user.ex
+    # ...
+    update :change_password do
+      require_atomic? false
+      accept []
+      argument :current_password, :string, sensitive?: true, allow_nil?: false
+
+      argument :password, :string,
+        sensitive?: true,
+        allow_nil?: false,
+        constraints: [min_length: 8]
+
+      argument :password_confirmation, :string, sensitive?: true, allow_nil?: false
+
+      validate confirm(:password, :password_confirmation)
+
+      validate {AshAuthentication.Strategy.Password.PasswordValidation,
+                strategy_name: :password, password_argument: :current_password}
+
+      change {AshAuthentication.Strategy.Password.HashPasswordChange, strategy_name: :password}
+    end
+    # ...
+```
+
+## LiveComponent
+Most web applications that you have used likely had the UI for changing your password somewhere under your personal settings.  We are going to do the same, and create a [LiveComponent](https://hexdocs.pm/phoenix_live_view/Phoenix.LiveComponent.html) to contain our password-change UI, which we can then mount in a LiveView with the rest of the user settings.
+
+Start by defining the module, and defining the template in the `render/1` function.
+```elixir
+# lib/my_app_web/components/change_password_component.ex
+defmodule MyAppWeb.ChangePasswordComponent do
+  @moduledoc """
+  LiveComponent for changing the current user's password.
+  """
+  use MyAppWeb, :live_component
+  alias MyApp.Accounts.User
+
+  @impl true
+  def render(assigns) do
+    ~H"""
+    <div>
+      <.simple_form
+        for={@form}
+        id="user-password-change-form"
+        phx-target={@myself}
+        phx-submit="save"
+      >
+        <.input field={@form[:current_password]} type="password" label="Current Password" />
+        <.input field={@form[:password]} type="password" label="New Password" />
+        <.input field={@form[:password_confirmation]} type="password" label="Confirm New Password" />
+        <:actions>
+          <.button phx-disable-with="Saving...">Save</.button>
+        </:actions>
+      </.simple_form>
+    </div>
+    """
+  end
+end
+```
+
+This will produce a form with the usual three fields (current password, new password, and confirmation of new password, to guard against typographical errors), and a submit button.  Now let's populate the `@form` assign.
+
+```elixir
+  @impl true
+  def update(assigns, socket) do
+    {:ok,
+     socket
+     |> assign(assigns)
+     |> assign_form()}
+  end
+
+  defp assign_form(%{assigns: %{current_user: user}} = socket) do
+    form = AshPhoenix.Form.for_update(user, :change_password, as: "user", actor: user)
+    assign(socket, form: to_form(form))
+  end
+```
+`update/2` is covered in the `Phoenix.LiveComponent` life-cycle documentation, so we won't go into it here.  The private function `assign_form/1` should look familiar if you have any forms for Ash resources in your application, but with a significant addition: the `prepare_source` option.
+
+The attribute `phx-target={@myself}` on the form in our template ensures the submit event is received by the component, so the `handle_event/3` function in this module is called, rather than the LiveView that mounts this component receiving the event.
+
+```elixir
+  @impl true
+  def handle_event("save", %{"user" => user_params}, %{assigns: assigns} = socket) do
+    case AshPhoenix.Form.submit(assigns.form, params: user_params) do
+      {:ok, user} ->
+        assigns.on_saved.()
+        {:noreply, socket}
+
+      {:error, form} ->
+        {:noreply, assign(socket, form: form)}
+    end
+  end
+```
+
+Again, this should look familiar if you have any forms on your other application resources, but handle the success case a little differently here, calling the function passed by the parent LiveView via the `on_saved` attribute.  This will make more sense when we use this component in a LiveView.
+
+## Policies
+Since the password-change workflow is done entirely in our application code, the [AshAuthentication policy bypass](https://hexdocs.pm/ash_authentication/policies-on-authentication-resources.html) will not pass.  We need to add a policy that allows a user to run the `:change_password` action on themselves.
+```elixir
+# lib/my_app/accounts/user.ex
+  # ...
+  policies do
+    # ...
+    policy action(:change_password) do
+      description "Users can change their own password"
+      authorize_if expr(id == ^actor(:id))
+    end
+  end
+  # ...
+```
+
+## Using the LiveComponent
+Finally, let's use this component in our UI somewhere.  Exactly where this belongs will depend on the wider UX of your application, so for the sake of example, let's assume that you already have a LiveView called `LiveUserSettings` in your application, where you want to add the password-change form.
+
+```elixir
+defmodule MyAppWeb.LiveUserSettings do
+  @moduledoc """
+  LiveView for the current user's account settings.
+  """
+  use MyAppWeb, :live_view
+  alias MyAppWeb.ChangePasswordComponent
+
+  @impl true
+  def render(assigns) do
+    ~H"""
+    <.header>
+      Settings
+    </.header>
+    <% # ... %>
+    <.live_component
+      module={ChangePasswordComponent}
+      id="change-password-component"
+      current_user={@current_user}
+      on_saved={fn -> send(self(), {:saved, :password}) end}
+    />
+    <% # ... %>
+    """
+  end
+
+  @impl true
+  def handle_info({:saved, :password}, socket) do
+    {:noreply,
+     socket
+     |> put_flash(:info, "Password changed successfully")}
+  end
+end
+```
+
+For the `on_saved` callback attribute mentioned earlier, we pass a function that sends a message to the process for this LiveView, and then write a `handle_info/2` clause that matches this message and which puts up an info flash informing the user that the password change succeeded.  This interface decouples `ChangePasswordComponent` from where it is used.  It manages only the password-change form, and leaves user feedback up to the parent.  You could put the form in a modal that closes when the form submits successfully without having to change any code in the component, only `LiveUserSettings`.
+
+## Security Email Notification
+This gets you a working password-change UI, but you should also send an email notification to the user upon a password change.  The reason for this is so that in the case of an account compromise, the attacker cannot change the password and lock out the rightful owner without alerting them.
+
+The simplest way to do this is with a [notifier](https://hexdocs.pm/ash/notifiers.html).
+```elixir
+    # ...
+    update :change_password do
+      notifiers [MyApp.Notifiers.EmailNotifier]
+      # ...
+```
+```elixir
+# lib/my_app/notifiers/email_notifier.ex
+defmodule MyApp.Notifiers.EmailNotifier do
+  use Ash.Notifier
+  alias MyApp.Accounts.User
+
+  @impl true
+  def notify(%Ash.Notifier.Notification{action: %{name: :change_password}, resource: user}) do
+    User.Email.deliver_password_change_notification(user)
+  end
+end
+```
+
+```elixir
+defmodule MyApp.Accounts.User.Email do
+  @moduledoc """
+  Email notifications for `User` records.
+  """
+
+  def deliver_password_change_notification(user) do
+    {"""
+      <html>
+        <p>
+          Hi #{user.display_name},
+        </p>
+        <p>
+          Someone just changed your password.  If this was not you,
+          please <a href="mailto:[email protected]">contact support</a>
+          <em>immediately</em>, because it means someone else has taken over
+          your account.
+        </p>
+      </html>
+     """,
+     """
+     Hi #{user.display_name},
+
+     Someone just changed your password.  If this was not you, please contact
+     support <[email protected]> <em>immediately</em>, because it means
+     someone else has taken over your account.
+     """}
+    |> MyApp.Mailer.send_mail_to_user("Your password has been changed", user)
+  end
+end
+```
+
+`MyApp.Mailer.send_mail_to_user/3` would be your application's internal interface to whichever mailer you are using, such as [Swoosh](https://hexdocs.pm/swoosh) or [Bamboo](https://hexdocs.pm/bamboo), that takes the HTML and text email bodies in a two-element tuple, the subject line, and the recipient user.
+
+# Field Policies
+If you are not using field policies, or you are using field policies with `private_fields :show` (the default), you can skip this section.
+
+When using field policies, the `@current_user` assign set by AshAuthentication may not contain the value of the `hashed_password` attribute, because it is a private field (if you are using `private_fields :hide` or `private_fields :include`).  This is what you normally want in your application, but the `:change_password` action needs this to validate the `:current_password` argument, you will need to explicitly load this attribute when creating the form in `ChangePasswordComponent`.
+
+### Load `hashed_password` in the form
+Change the function `assign_form/1` in `ChangePasswordComponent` as follows.
+
+```elixir
+  defp assign_form(%{assigns: %{current_user: user}} = socket) do
+    form =
+      AshPhoenix.Form.for_update(user, :change_password,
+        as: "user",
+        # Add this argument
+        prepare_source: fn changeset ->
+          %{
+            changeset
+            | data:
+                Ash.load!(changeset.data, :hashed_password,
+                  context: %{private: %{password_change?: true}}
+                )
+          }
+        end,
+        actor: user
+      )
+
+    assign(socket, form: to_form(form))
+  end
+```
+
+There are a couple of things going on here:
+1. We are calling `Ash.load!/3` to load the attribute `hashed_password` on the record in the changeset.
+2. Setting a private context field for this `Ash.load!/3` call to be used in a field policy bypass that we need to write in order for this load to succeed.
+
+### Field Policy Bypass
+The actual work will be done in a separate policy check module, so our bypass will look very simple.  If you are using `private_fields :hide`, you will need to change it to `private_fields :include`, otherwise the `hashed_password` field will always be hidden, regardless of any field policy bypass.
+```elixir
+# lib/my_app/accounts/user.ex
+  # ...
+  field_policies do
+    private_fields :include
+
+    # ...
+
+    field_policy_bypass :* do
+      description "Users can access all fields for password change"
+      authorize_if MyApp.Checks.PasswordChangeInteraction
+    end
+  end
+  # ...
+```
+
+```elixir
+# lib/my_app/checks/password_change_interaction.ex
+defmodule MyApp.Checks.PasswordChangeInteraction do
+  use Ash.Policy.SimpleCheck
+
+  @impl Ash.Policy.Check
+  def describe(_) do
+    "MyApp is performing a password change for this interaction"
+  end
+
+  @impl Ash.Policy.SimpleCheck
+  def match?(_, %{subject: %{context: %{private: %{password_change?: true}}}}, _), do: true
+  def match?(_, _, _), do: false
+end
+```
+
+This is actually how `AshAuthentication.Checks.AshAuthenticationInteraction` is implemented, only matching a slightly different pattern.

mix.exs

@@ -28,7 +28,8 @@ defmodule AshAuthentication.Phoenix.MixProject do
             "README.md",
             {"documentation/tutorials/get-started.md", title: "Get Started"},
             {"documentation/tutorials/liveview.md", title: "LiveView Routes"},
-            {"documentation/tutorials/ui-overrides.md", title: "UI Overrides"}
+            {"documentation/tutorials/ui-overrides.md", title: "UI Overrides"},
+            {"documentation/tutorials/password-change.md", title: "Password-Change UI"}
           ],
           redirects: %{
             "getting-started-with-ash-authentication-phoenix" => "get-started"