<!--
This file was generated by Spark. Do not edit it by hand.
-->
# DSL: AshAuthentication.AddOn.Confirmation

Confirmation support.

Sometimes when creating a new user, or changing a sensitive attribute (such as
their email address) you may want to wait for the user to confirm by way of
sending them a confirmation token to prove that it was really them that took
the action.

In order to add confirmation to your resource, it must been the following
minimum requirements:

1. Have a primary key
2. Have at least one attribute you wish to confirm
3. Tokens must be enabled

## Example

```elixir
defmodule MyApp.Accounts.User do
  use Ash.Resource,
    extensions: [AshAuthentication]

  attributes do
    uuid_primary_key :id
    attribute :email, :ci_string, allow_nil?: false
  end

  authentication do
    api MyApp.Accounts

    add_ons do
      confirmation :confirm do
        monitor_fields [:email]
        sender MyApp.ConfirmationSender
      end
    end

    strategies do
      # ...
    end
  end

  identities do
    identity :email, [:email] do
      eager_check_with MyApp.Accounts
    end
  end
end
```

## Attributes

A `confirmed_at` attribute will be added to your resource if it's not already
present (see `confirmed_at_field` in the DSL documentation).

## Actions

By default confirmation will add an action which updates the `confirmed_at`
attribute as well as retrieving previously stored changes and applying them to
the resource.

If you wish to perform the confirm action directly from your code you can do
so via the `AshAuthentication.Strategy` protocol.

### Example

    iex> strategy = Info.strategy!(Example.User, :confirm)
    ...> {:ok, user} = Strategy.action(strategy, :confirm, %{"confirm" => confirmation_token()})
    ...> user.confirmed_at >= one_second_ago()
    true

## Plugs

Confirmation provides a single endpoint for the `:confirm` phase.  If you wish
to interact with the plugs directly, you can do so via the
`AshAuthentication.Strategy` protocol.

### Example

    iex> strategy = Info.strategy!(Example.User, :confirm)
    ...> conn = conn(:get, "/user/confirm", %{"confirm" => confirmation_token()})
    ...> conn = Strategy.plug(strategy, :confirm, conn)
    ...> {_conn, {:ok, user}} = Plug.Helpers.get_authentication_result(conn)
    ...> user.confirmed_at >= one_second_ago()
    true

## DSL Documentation

User confirmation flow


* `:name` (`t:atom/0`) - Required. Uniquely identifies the add-on.

* `:token_lifetime` - How long should the confirmation token be valid.
  If no unit is provided, then hours is assumed.  
  Defaults to 3 days. The default value is `{3, :days}`.

* `:monitor_fields` (list of `t:atom/0`) - Required. A list of fields to monitor for changes (eg `[:email, :phone_number]`).
  The confirmation will only be sent when one of these fields are changed.

* `:confirmed_at_field` (`t:atom/0`) - The name of a field to store the time that the last confirmation took
  place.
  This attribute will be dynamically added to the resource if not already
  present. The default value is `:confirmed_at`.

* `:confirm_on_create?` (`t:boolean/0`) - Generate and send a confirmation token when a new resource is created?
  Will only trigger when a create action is executed _and_ one of the
  monitored fields is being set. The default value is `true`.

* `:confirm_on_update?` (`t:boolean/0`) - Generate and send a confirmation token when a resource is changed?
  Will only trigger when an update action is executed _and_ one of the
  monitored fields is being set. The default value is `true`.

* `:inhibit_updates?` (`t:boolean/0`) - Wait until confirmation is received before actually changing a monitored
  field?
  If a change to a monitored field is detected, then the change is stored
  in the token resource and  the changeset updated to not make the
  requested change.  When the token is confirmed, the change will be
  applied.
  This could be potentially weird for your users, but useful in the case
  of a user changing their email address or phone number where you want
  to verify that the new contact details are reachable. The default value is `true`.

* `:sender` - Required. How to send the confirmation instructions to the user.
  Allows you to glue sending of confirmation instructions to
  [swoosh](https://hex.pm/packages/swoosh),
  [ex_twilio](https://hex.pm/packages/ex_twilio) or whatever notification
  system is appropriate for your application.
  Accepts a module, module and opts, or a function that takes a record,
  reset token and options.
  The options will be a keyword list containing the original
  changeset, before any changes were inhibited.  This allows you
  to send an email to the user's new email address if it is being
  changed for example.
  See `AshAuthentication.Sender` for more information.

* `:confirm_action_name` (`t:atom/0`) - The name of the action to use when performing confirmation.
  If this action is not already present on the resource, it will be
  created for you. The default value is `:confirm`.


## authentication.add_ons.confirmation
```elixir
confirmation name \ :confirm
```


User confirmation flow


### Arguments

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Default</th>
      <th colspan=2>Docs</th>
    </tr>
  </thead>
  <tbody>
    <tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-name" href="#authentication-add_ons-confirmation-name">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        name
      </span>
    </a>
      <sup style="color: red">*</sup>

  </td>
  <td style="text-align: left">
    <code class="inline">atom</code>
  </td>
  <td style="text-align: left">
    
  </td>
  <td style="text-align: left" colspan=2>
    Uniquely identifies the add-on.

  </td>
</tr>

  </tbody>
</table>
### Options

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Default</th>
      <th colspan=2>Docs</th>
    </tr>
  </thead>
  <tbody>
    <tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-monitor_fields" href="#authentication-add_ons-confirmation-monitor_fields">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        monitor_fields
      </span>
    </a>
      <sup style="color: red">*</sup>

  </td>
  <td style="text-align: left">
    <code class="inline">list(atom)</code>
  </td>
  <td style="text-align: left">
    
  </td>
  <td style="text-align: left" colspan=2>
    A list of fields to monitor for changes (eg `[:email, :phone_number]`).
The confirmation will only be sent when one of these fields are changed.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-sender" href="#authentication-add_ons-confirmation-sender">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        sender
      </span>
    </a>
      <sup style="color: red">*</sup>

  </td>
  <td style="text-align: left">
    <code class="inline">(any, any, any -> any) | module</code>
  </td>
  <td style="text-align: left">
    
  </td>
  <td style="text-align: left" colspan=2>
    How to send the confirmation instructions to the user.
Allows you to glue sending of confirmation instructions to
[swoosh](https://hex.pm/packages/swoosh),
[ex_twilio](https://hex.pm/packages/ex_twilio) or whatever notification
system is appropriate for your application.
Accepts a module, module and opts, or a function that takes a record,
reset token and options.
The options will be a keyword list containing the original
changeset, before any changes were inhibited.  This allows you
to send an email to the user's new email address if it is being
changed for example.
See `AshAuthentication.Sender` for more information.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-token_lifetime" href="#authentication-add_ons-confirmation-token_lifetime">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        token_lifetime
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">pos_integer | {pos_integer, :days | :hours | :minutes | :seconds}</code>
  </td>
  <td style="text-align: left">
    <code class="inline">{3, :days}</code>
  </td>
  <td style="text-align: left" colspan=2>
    How long should the confirmation token be valid.
If no unit is provided, then hours is assumed.

Defaults to 3 days.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-confirmed_at_field" href="#authentication-add_ons-confirmation-confirmed_at_field">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        confirmed_at_field
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">atom</code>
  </td>
  <td style="text-align: left">
    <code class="inline">:confirmed_at</code>
  </td>
  <td style="text-align: left" colspan=2>
    The name of a field to store the time that the last confirmation took
place.
This attribute will be dynamically added to the resource if not already
present.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-confirm_on_create?" href="#authentication-add_ons-confirmation-confirm_on_create?">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        confirm_on_create?
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">boolean</code>
  </td>
  <td style="text-align: left">
    <code class="inline">true</code>
  </td>
  <td style="text-align: left" colspan=2>
    Generate and send a confirmation token when a new resource is created?
Will only trigger when a create action is executed _and_ one of the
monitored fields is being set.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-confirm_on_update?" href="#authentication-add_ons-confirmation-confirm_on_update?">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        confirm_on_update?
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">boolean</code>
  </td>
  <td style="text-align: left">
    <code class="inline">true</code>
  </td>
  <td style="text-align: left" colspan=2>
    Generate and send a confirmation token when a resource is changed?
Will only trigger when an update action is executed _and_ one of the
monitored fields is being set.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-inhibit_updates?" href="#authentication-add_ons-confirmation-inhibit_updates?">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        inhibit_updates?
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">boolean</code>
  </td>
  <td style="text-align: left">
    <code class="inline">true</code>
  </td>
  <td style="text-align: left" colspan=2>
    Wait until confirmation is received before actually changing a monitored
field?
If a change to a monitored field is detected, then the change is stored
in the token resource and  the changeset updated to not make the
requested change.  When the token is confirmed, the change will be
applied.
This could be potentially weird for your users, but useful in the case
of a user changing their email address or phone number where you want
to verify that the new contact details are reachable.

  </td>
</tr>

<tr>
  <td style="text-align: left">
    <a id="authentication-add_ons-confirmation-confirm_action_name" href="#authentication-add_ons-confirmation-confirm_action_name">
      <span style="font-family: Inconsolata, Menlo, Courier, monospace;">
        confirm_action_name
      </span>
    </a>
      
  </td>
  <td style="text-align: left">
    <code class="inline">atom</code>
  </td>
  <td style="text-align: left">
    <code class="inline">:confirm</code>
  </td>
  <td style="text-align: left" colspan=2>
    The name of the action to use when performing confirmation.
If this action is not already present on the resource, it will be
created for you.

  </td>
</tr>

  </tbody>
</table>


### Introspection

Target: `AshAuthentication.AddOn.Confirmation`