defmodule BreakGlass.UserProvider do
  @moduledoc """
  Behaviour that host applications implement to supply a user term on successful
  break-glass authentication.

  ## Callback

  The single callback, `build_user/1`, receives an `attrs` map that is guaranteed
  to contain the following four keys:

  | Key                 | Type           | Description                                       |
  |---------------------|----------------|---------------------------------------------------|
  | `:email`            | `String.t()`   | The configured break-glass email address          |
  | `:sentinel_id`      | `integer()`    | The configured sentinel ID (never a real PK)      |
  | `:authenticated_at` | `DateTime.t()` | UTC timestamp of successful authentication        |
  | `:break_glass`      | `true`         | Always `true`; allows host-app guards to identify |
  |                     |                | a break-glass session                             |

  The return value is `term()` — the library does not inspect it after invoking
  the callback. The host application is free to return any value, including a
  struct, a plain map, or any other term that suits its auth stack.

  ## Example

      defmodule MyApp.BreakGlassUserProvider do
        @behaviour BreakGlass.UserProvider

        @impl true
        def build_user(attrs) do
          %MyApp.User{
            id:              attrs.sentinel_id,
            email:           attrs.email,
            authenticated_at: attrs.authenticated_at,
            break_glass:     attrs.break_glass
          }
        end
      end
  """

  @doc """
  Builds and returns the host application's user term from the given `attrs` map.

  `attrs` is guaranteed to contain `:email`, `:sentinel_id`, `:authenticated_at`,
  and `:break_glass` (always `true`). The return value is an opaque `term()` that
  the library passes through unchanged.
  """
  @callback build_user(attrs :: map()) :: term()
end