Behaviour for implementing email/password authentication.

This is the entry point for email-based authentication, equivalent to what OAuth providers (via Assent) do for OAuth flows. Your implementation verifies credentials and returns a raw user map that flows through the KeenAuth pipeline.

Pipeline Position

┌──────────────────────┐
│ EmailAuthHandler     │  ◀── YOU IMPLEMENT THIS
│ (credential verify)  │
└──────────┬───────────┘
           │ {:ok, raw_user}
           ▼
┌──────────────────────┐
│ Mapper               │  Normalize to KeenAuth.User
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ Processor            │  Business logic, DB ops
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ Storage              │  Persist session
└──────────────────────┘

Callbacks

• authenticate/2 - Verify credentials, return {:ok, user_map} or {:error, reason}
• handle_authenticated/2 - Called after successful auth (logging, side effects)
• handle_unauthenticated/3 - Handle failed auth (render error, redirect)

Example Implementation

defmodule MyApp.Auth.EmailHandler do
  @behaviour KeenAuth.EmailAuthenticationHandler
  import Plug.Conn
  import Phoenix.Controller

  @impl true
  def authenticate(_conn, %{"email" => email, "password" => password}) do
    with {:ok, user} <- MyApp.Accounts.get_user_by_email(email),
         :ok <- MyApp.Accounts.verify_password(user, password) do
      # Return raw user map - will be passed to Mapper
      {:ok, %{
        "sub" => to_string(user.id),
        "email" => user.email,
        "name" => user.display_name,
        "preferred_username" => user.username
      }}
    else
      _ -> {:error, :invalid_credentials}
    end
  end

  @impl true
  def handle_authenticated(conn, user) do
    # Optional: audit log, analytics, etc.
    Logger.info("User #{user.email} signed in via email")
    conn
  end

  @impl true
  def handle_unauthenticated(conn, params, {:error, :invalid_credentials}) do
    conn
    |> put_flash(:error, "Invalid email or password")
    |> redirect(to: params["redirect_to"] || "/login")
  end

  def handle_unauthenticated(conn, _params, _other_error) do
    conn
    |> put_flash(:error, "Authentication failed")
    |> redirect(to: "/login")
  end
end

Configuration

config :keen_auth,
  email_enabled: true,
  strategies: [
    email: [
      authentication_handler: MyApp.Auth.EmailHandler,
      mapper: KeenAuth.Mapper.Default,
      processor: MyApp.Auth.Processor
    ]
  ]