# Auth Adapters

Accrue does not own authentication. The host app wires an adapter with:

```elixir
config :accrue, :auth_adapter, MyApp.Auth.PhxGenAuth
```

An adapter implements `Accrue.Auth` so Accrue Admin, audit logging, and destructive-action step-up checks can read host auth state without knowing how the host signs users in.

## Required callbacks

- `current_user/1` reads the signed-in user from a `%Plug.Conn{}` or compatible map and returns the user struct/map or `nil`.
- `require_admin_plug/0` returns a plug that allows authorized admins and rejects everyone else before Accrue Admin routes run.
- `user_schema/0` returns the host user schema module when the adapter can name it, such as `MyApp.Accounts.User`.
- `log_audit/2` records or forwards an admin action. It should not log raw Stripe payloads, API keys, webhook secrets, or request bodies.
- `actor_id/1` returns the canonical actor id string used when Accrue records event-ledger rows.
- `step_up_challenge/2` starts a destructive-action challenge, such as password confirmation, TOTP, WebAuthn, or a Sigra-backed challenge.
- `verify_step_up/3` verifies the challenge result for the user and action.

`step_up_challenge/2` and `verify_step_up/3` are optional callbacks, but production admin installs should implement them for destructive billing actions.

## MyApp.Auth.PhxGenAuth

Phoenix `phx.gen.auth` apps usually already have `fetch_current_user` and route-level plugs in `MyAppWeb.UserAuth`. Keep that module as the source of truth and wrap it with a small adapter.

```elixir
defmodule MyApp.Auth.PhxGenAuth do
  @behaviour Accrue.Auth

  import Plug.Conn

  alias MyApp.Accounts.User
  alias MyAppWeb.UserAuth

  @impl Accrue.Auth
  def current_user(conn), do: conn.assigns[:current_user]

  @impl Accrue.Auth
  def require_admin_plug do
    fn conn, _opts ->
      conn = UserAuth.fetch_current_user(conn, [])

      if admin?(conn.assigns[:current_user]) do
        conn
      else
        conn
        |> send_resp(:forbidden, "forbidden")
        |> halt()
      end
    end
  end

  @impl Accrue.Auth
  def user_schema, do: User

  @impl Accrue.Auth
  def log_audit(user, event), do: MyApp.Audit.log(user, event)

  @impl Accrue.Auth
  def actor_id(%User{id: id}), do: to_string(id)
  def actor_id(%{id: id}), do: to_string(id)
  def actor_id(_user), do: nil

  @impl Accrue.Auth
  def step_up_challenge(user, action), do: MyApp.Accounts.start_step_up(user, action)

  @impl Accrue.Auth
  def verify_step_up(user, params, action), do: MyApp.Accounts.verify_step_up(user, params, action)

  defp admin?(%User{role: :admin}), do: true
  defp admin?(%User{role: "admin"}), do: true
  defp admin?(_user), do: false
end
```

The important boundary is `require_admin_plug/0`: do not rely on hiding links in the UI. Protect the Accrue Admin mount in the router.

## MyApp.Auth.Pow

Pow apps can read the current user through `Pow.Plug.current_user/1` and use the host role policy for admin checks.

```elixir
defmodule MyApp.Auth.Pow do
  @behaviour Accrue.Auth

  import Plug.Conn

  alias MyApp.Users.User

  @impl Accrue.Auth
  def current_user(conn), do: Pow.Plug.current_user(conn)

  @impl Accrue.Auth
  def require_admin_plug do
    fn conn, _opts ->
      user = Pow.Plug.current_user(conn)

      if user && MyApp.Policy.admin?(user) do
        conn
      else
        conn
        |> send_resp(:forbidden, "forbidden")
        |> halt()
      end
    end
  end

  @impl Accrue.Auth
  def user_schema, do: User

  @impl Accrue.Auth
  def log_audit(user, event), do: MyApp.Audit.log(user, event)

  @impl Accrue.Auth
  def actor_id(%User{id: id}), do: to_string(id)
  def actor_id(_user), do: nil

  @impl Accrue.Auth
  def step_up_challenge(user, action), do: MyApp.Security.start_step_up(user, action)

  @impl Accrue.Auth
  def verify_step_up(user, params, action), do: MyApp.Security.verify_step_up(user, params, action)
end
```

## MyApp.Auth.Assent

Assent is often used behind a host-owned session pipeline. The adapter should read the already-loaded user from assigns or session-backed host helpers, not re-run OAuth inside Accrue.

```elixir
defmodule MyApp.Auth.Assent do
  @behaviour Accrue.Auth

  import Plug.Conn

  alias MyApp.Accounts
  alias MyApp.Accounts.User

  @impl Accrue.Auth
  def current_user(conn), do: conn.assigns[:current_user] || Accounts.current_user(conn)

  @impl Accrue.Auth
  def require_admin_plug do
    fn conn, _opts ->
      user = current_user(conn)

      if user && Accounts.admin?(user) do
        conn
      else
        conn
        |> send_resp(:forbidden, "forbidden")
        |> halt()
      end
    end
  end

  @impl Accrue.Auth
  def user_schema, do: User

  @impl Accrue.Auth
  def log_audit(user, event), do: Accounts.log_admin_audit(user, event)

  @impl Accrue.Auth
  def actor_id(%User{id: id}), do: to_string(id)
  def actor_id(_user), do: nil

  @impl Accrue.Auth
  def step_up_challenge(user, action), do: Accounts.start_step_up(user, action)

  @impl Accrue.Auth
  def verify_step_up(user, params, action), do: Accounts.verify_step_up(user, params, action)
end
```

## Sigra

When `:sigra` is present, the installer can wire the first-party adapter:

```elixir
config :accrue, :auth_adapter, Accrue.Integrations.Sigra
```

`Accrue.Integrations.Sigra` is conditionally compiled. In projects without Sigra, the module is not defined and Accrue stays on the configured fallback adapter.

## Default adapter warning

`Accrue.Auth.Default` is for local development and tests. It returns a dev admin user in `:dev` and `:test`, but it refuses to boot in `:prod` when it is still the configured adapter. Production installs must configure `MyApp.Auth.PhxGenAuth`, `MyApp.Auth.Pow`, `MyApp.Auth.Assent`, `Accrue.Integrations.Sigra`, or another host-owned adapter that protects admin routes and records audit actor ids.

## Router placement

Place the auth plug before mounting Accrue Admin:

```elixir
pipeline :admin do
  plug Accrue.Auth.require_admin_plug()
end

scope "/billing" do
  pipe_through [:browser, :admin]

  accrue_admin "/"
end
```

Keep the policy in the host app. Accrue only asks the adapter for the current user, admin boundary, user schema, audit sink, actor id, and step-up challenge behavior.