From e5ba987ee18992e6f595bbf81fe44213f5adc0e3 Mon Sep 17 00:00:00 2001
From: James Harton <james@harton.nz>
Date: Fri, 4 Nov 2022 11:46:03 +1300
Subject: [PATCH] improvement(docs): Improve endpoint docs for
 PasswordAuthentication and PasswordReset.

---
 .../password_authentication.ex                | 30 +++++++++++++++++++
 lib/ash_authentication/password_reset.ex      | 17 ++++++++---
 .../password_reset/transformer.ex             | 15 ++++++----
 lib/ash_authentication/plug/dispatcher.ex     |  2 --
 4 files changed, 53 insertions(+), 11 deletions(-)

diff --git a/lib/ash_authentication/password_authentication.ex b/lib/ash_authentication/password_authentication.ex
index 2d9ba02..b343733 100644
--- a/lib/ash_authentication/password_authentication.ex
+++ b/lib/ash_authentication/password_authentication.ex
@@ -100,6 +100,36 @@ defmodule AshAuthentication.PasswordAuthentication do
   end
   ```
 
+  ## Endpoints
+
+  This provider routes requests to both the `request` and `callback` endpoints
+  to the same handler, so either can be used.  Requests are differentiated by
+  the presence of an `action` parameter in the request body.
+
+  ### Examples
+
+  When attempting to register a new user
+
+  ```
+  %{"user" => %{
+    "action" => "register",
+    "email" => "marty@mcfly.me",
+    "password" => "back to 1985",
+    "password_confirmation" => "back to 1985"
+    # any additional user fields you wish to accept on creation.
+  }}
+  ```
+
+  When attempting to sign-in a user
+
+  ```
+  %{"user" => %{
+    "action" => "sign_in",
+    "email" => "marty@mcfly.me",
+    "password" => "back to 1985"
+  }}
+  ```
+
   ## DSL Documentation
 
   ### Index
diff --git a/lib/ash_authentication/password_reset.ex b/lib/ash_authentication/password_reset.ex
index 54b0b35..1069339 100644
--- a/lib/ash_authentication/password_reset.ex
+++ b/lib/ash_authentication/password_reset.ex
@@ -86,10 +86,19 @@ defmodule AshAuthentication.PasswordReset do
   end
   ```
 
-  Because you often want to submit the password reset token via the web, you can
-  also use the password authentication callback endpoint with an action of
-  "reset_password" and the reset password action will be called with the
-  included params.
+  ## Endpoints
+
+  * `request` - send the identity field nested below the subject name (eg
+    `%{"user" => %{"email" => "marty@mcfly.me"}}`).  If the resource supports
+    password resets then the success callback will be called with a `nil` user
+    and token regardless of whether the user could be found.  If the user is
+    found then the `sender` will be called.
+  * `callback` - attempt to perform a password reset.  Should be called with the
+    reset token, password and password confirmation if confirmation is enabled,
+    nested below the subject name (eg `%{"user" => %{"reset_token" => "abc123",
+    "password" => "back to 1985", "password_confirmation" => "back to 1975"}}`).
+    If the password was successfully changed then the relevant user will be
+    returned to the `success` callback.
 
   ## DSL Documentation
 
diff --git a/lib/ash_authentication/password_reset/transformer.ex b/lib/ash_authentication/password_reset/transformer.ex
index 2bf711b..9ab20bd 100644
--- a/lib/ash_authentication/password_reset/transformer.ex
+++ b/lib/ash_authentication/password_reset/transformer.ex
@@ -219,6 +219,9 @@ defmodule AshAuthentication.PasswordReset.Transformer do
         |> Enum.concat([
           Transformer.build_entity!(Resource.Dsl, [:actions, :update], :change,
             change: PA.HashPasswordChange
+          ),
+          Transformer.build_entity!(Resource.Dsl, [:actions, :update], :change,
+            change: PA.GenerateTokenChange
           )
         ])
 
@@ -254,12 +257,14 @@ defmodule AshAuthentication.PasswordReset.Transformer do
              action,
              password_confirmation_field,
              confirmation_required?
+           ),
+         :ok <-
+           PA.UserValidations.validate_action_has_validation(
+             action,
+             PA.PasswordConfirmationValidation,
+             confirmation_required?
            ) do
-      PA.UserValidations.validate_action_has_validation(
-        action,
-        PA.PasswordConfirmationValidation,
-        confirmation_required?
-      )
+      validate_action_has_change(action, PA.GenerateTokenChange)
     end
   end
 end
diff --git a/lib/ash_authentication/plug/dispatcher.ex b/lib/ash_authentication/plug/dispatcher.ex
index 02988c8..cdfe9ba 100644
--- a/lib/ash_authentication/plug/dispatcher.ex
+++ b/lib/ash_authentication/plug/dispatcher.ex
@@ -25,8 +25,6 @@ defmodule AshAuthentication.Plug.Dispatcher do
     |> return(return_to)
   end
 
-  def call(conn, {_phase, _routes, return_to}), do: return_to.handle_failure(conn)
-
   defp dispatch(
          %{params: %{"subject_name" => subject_name, "provider" => provider}} = conn,
          phase,