defmodule Ueberauth do
  @moduledoc """
  Ueberauth is a two-phase authentication framework that provides a clear API -
  allowing for many strategies to be created and shared within the community. It
  is heavily inspired by [Omniauth](https://github.com/intridea/omniauth). You
  could call it a port but it is significantly different in operation - but
  almost the same by concept. Huge hat tip to [Intridea](https://github.com/intridea).

  Ueberauth provides only the initial authentication challenge, (initial OAuth
  flow, collecting the information from a login form, etc). It does not
  authenticate each request, that's up to your application. You could issue a
  token or put the result into a session for your applications needs. Libraries
  like [Guardian](https://github.com/hassox/guardian) can help you with that
  aspect of authentication.

  The two phases are `request` and `callback`. These phases are implemented by
  Strategies.

  ### Strategies

  Strategies are plugs that decorate or intercept requests (or both).

  Strategies implement the two phases and then may allow the request to flow
  through to your downstream plugs. Implementing the request and callback phases
  is optional depending on the strategies requirements. If a strategy does not
  redirect, the request will be decorated with Ueberauth information and
  allowed to carry on through the pipeline.

  ### Request Phase

  The request phase is where you request information about the user. This could
  be a redirect to an OAuth2 authorization url or a form for collecting username
  and password. The request phase is concerned with only the collection of
  information. When a request comes in on the request phase url the relevant
  strategy will receive the `c:Ueberauth.Strategy.handle_request!/1` call.

  In some cases (default) the application using Ueberauth is responsible for
  implementing the request phase. That is, you should setup a route to receive
  the request phase and provide a form etc. In some cases, like OAuth, the
  request phase is used to redirect your user to a 3rd party site to fulfill
  the request.

  For example, an OAuth strategy for GitHub will receive the request phase url
  and stop the request, redirecting you to GitHub’s OAuth challenge url with
  some query parameters. Once you complete the GitHub OAuth flow, the user will
  be redirected back to the host site to the callback URL.

  Another example is simple email/password authentication. A request is made by
  the client to the request phase path and the host application displays a form.
  The strategy will likely not do anything with the incoming `c:Ueberauth.Strategy.handle_request!/1`
  request and simply pass through to the application. Once the form is completed,
  the POST should go to the callback url where it is handled (passwords checked,
  users created / authenticated).

  ### Callback Phase

  The callback phase is where the fun happens. Once a successful request phase
  has been completed, the request phase provider (OAuth provider or host site etc)
  should call the callback url. The strategy will intercept the request via the
  `c:Ueberauth.Strategy.handle_callback!/1`. If successful it should prepare the connection so the
  `Ueberauth.Auth` struct can be created, or set errors to indicate a failure.

  See `Ueberauth.Strategy` for more information on constructing the
  `Ueberauth.Auth` struct.

  ### Setup

  In your configuration file provide a list of the providers you intend to use.

  #### Example

      config :ueberauth, Ueberauth,
        providers: [
          facebook: {Ueberauth.Strategy.Facebook, [opt1: "value", opts2: "value"]},
          github: {Ueberauth.Strategy.Github, [opt1: "value", opts2: "value"]}
        ]

  This will define two providers for you. The general structure of the providers
  value is:

      config :ueberauth, Ueberauth,
        providers: [
          <provider name>: {<Strategy Module>, [<strategy options>]}
        ]

  We use the configuration options for defining these to allow for dependency
  injection in different environments. The provider name will be used to construct
  request and response paths (by default) but will also be returned in the
  `Ueberauth.Auth` struct as the `provider` field.

  Once you've setup your providers, in your router you need to configure the plug
  to run. The plug should run before your application routes.

  In phoenix, plug this module in your controller:

      defmodule MyApp.AuthController do
        use MyApp.Web, :controller
        plug Ueberauth

        ...
      end

  Its URL matching is done via pattern matching rather than explicit runtime
  checks so your strategies will only fire for relevant requests.

  Now that you have this, your strategies will intercept relevant requests for
  each strategy for both request and callback phases. The default URLs are (for
  our Facebook & GitHub example)

      # Request phase paths
      /auth/facebook
      /auth/github

      # Callback phase paths
      /auth/facebook/callback
      /auth/github/callback

  If you want to include only some of the providers with your plug
  you can specify a list of configured providers

      defmodule MyApp.Admin.AuthController do
        use MyApp.Web, :controller
        plug Ueberauth, providers: [:identity], base_path: "/admin/auth"
      end

  This will allow you to have different login points in your
  application selectively using some or all of the providers.

  #### Configuration of different Providers per OTP app

  If you wish to use Ueberauth in multiple OTP apps, and configure each instance of
  Ueberauth with a different list of Providers, you will need to do some things
  differently. When providing configuration for Ueberauth, you should set anything that
  differs by OTP app under the name of your OTP app, for example:

      config :my_app, Ueberauth,
        providers: [
          …
        ]

  Further, when using the Ueberauth plug, you should pass the `:otp_app` option,
  for example:

      defmodule MyApp.Admin.AuthController do
        use MyApp.Web, :controller
        plug Ueberauth,
          otp_app: :my_app,
          providers: [:identity],
          base_path: "/admin/auth"
      end

  This ensures that in addition to globally configured values under `:ueberauth`,
  values set under your own namespace are used with priority.

  #### Customizing Paths

  These paths can be configured on a per strategy basis by setting options on
  the provider.

  Note: These paths are absolute

  #### Example

      config :ueberauth, Ueberauth,
        base_path: "/login", # default is "/auth"
        providers: [
          identity: {Ueberauth.Strategies.Identity, [request_path: "/login/identity",
                                                     callback_path: "/login/identity/callback"]}
        ],
        json_library: Poison # or Jason

  #### Customizing Schemes

  By default, Ueberauth uses your `Plug.Conn` scheme.

  A custom scheme can be provided through the request header `X-Forwarded-Proto`.

  For example, in Nginx you can set it.

      proxy_set_header X-Forwarded-Proto $scheme;

  Another option is to override this via options to your strategy.

      providers: [
        identity: {Ueberauth.Strategies.Identity, [callback_scheme: "https"]}
      ]

  #### Customizing Ports

  By default, Ueberauth uses your `Plug.Conn` port.

  To override this via options to your strategy.

      providers: [
        identity: {Ueberauth.Strategies.Identity, [callback_port: 4000]}
      ]

  #### Http Methods

  By default, all callback URLs are only available via the `"GET"` method. You
  can override this via options to your strategy.

      providers: [
        identity: {Ueberauth.Strategies.Identity, [callback_methods: ["POST"]]}
      ]

  #### Strategy Options

  All options that are passed into your strategy are available at runtime to
  modify the behaviour of the strategy.
  """

  @behaviour Plug

  alias Ueberauth.Strategy

  defmodule NoProviderError do
    defexception [:message]

    @impl true
    def exception(provider) do
      msg = "Provider #{provider} was not found"
      %NoProviderError{message: msg}
    end
  end

  @doc """
  Fetch a successful auth from the `Plug.Conn`.

  This should only be called after the callback phase has run.
  """
  @spec auth(Plug.Conn.t()) :: Ueberauth.Auth.t()
  def auth(conn) do
    conn.assigns[:ueberauth_auth]
  end

  @doc """
  Fetch the configured JSON library.

  A JSON library is required for Ueberauth to operate.

  In config.exs your implicit or explicit configuration is:

      config :ueberauth, Ueberauth, json_library: Jason

  Or:

      config :ueberauth, json_library: Jason

  If you are using per-app configuration, you can also use:

      config :my_app, Ueberauth, json_library: Jason

  The JSON library defaults to Jason but can be configured to Poison.

  In mix.exs you will need something like:

      def deps() do
        [
          ...
          {:jason, "<version>"} # or {:poison, "<version>"}
        ]
      end

  This file will serve underlying Ueberauth libraries as a hook to grab the
  configured JSON library.
  """
  def json_library(otp_app \\ nil) do
    environment = get_env([:ueberauth, otp_app])
    Keyword.get(environment, :json_library, Application.get_env(:ueberauth, :json_library, Jason))
  end

  @type path :: String.t()
  @type method :: String.t()
  @type route :: {{path, method}, mfa()}
  @type routes :: [route]

  @doc """
  Implements `c:Plug.init/1`
  """
  @impl Plug
  def init(options \\ []) do
    environment = get_env([:ueberauth, Keyword.get(options, :otp_app)])
    providers = get_providers(environment, options)
    base_path = get_base_path(environment, options)
    Enum.flat_map(providers, &build_routes(base_path, &1))
  end

  @doc """
  Implements `c:Plug.call/2`
  """
  @impl Plug
  def call(conn, routes) do
    route_prefix = Path.join(["/" | conn.script_name])
    route_path = Path.relative_to(conn.request_path, route_prefix)
    route_key = {normalize_route_path(route_path), conn.method}

    case List.keyfind(routes, route_key, 0) do
      {_, route_mfa} ->
        run(conn, route_mfa)

      _ ->
        raise NoProviderError, route_path
    end
  end

  @doc """
  Request authentication against a provider.

  specified dynamically in arguments. For example, you can specify in a
  controller:

      def request(conn, %{"provider_name" => provider_name} = _params) do
        provider_config = case provider_name do
          "github" ->
            { Ueberauth.Strategy.Github, [
              default_scope: "user",
              request_path:  provider_auth_path(conn, :request, provider_name),
              callback_path: provider_auth_path(conn, :callback, provider_name),
            ]}
        end
        conn
        |> Ueberauth.run_request(provider_name, provider_config)
      end
  """
  def run_request(conn, provider_name, {provider, provider_options}, options \\ []) do
    environment = get_env([:ueberauth, Keyword.get(options, :otp_app)])
    base_path = get_base_path(environment, options)

    to_options = build_strategy_options(base_path, {provider_name, {provider, provider_options}})
    run(conn, {provider, :run_request, to_options})
  end

  @doc """
  Request authentication against a provider.

      def callback(conn, %{"provider_name" => provider_name} = _params) do
        provider_config = case provider_name do
          "github" ->
            { Ueberauth.Strategy.Github, [
              default_scope: "user",
              request_path:  provider_auth_path(conn, :request, provider_name),
              callback_path: provider_auth_path(conn, :callback, provider_name),
            ]}
        end
        conn
        |> Ueberauth.run_callback(provider_name, provider_config)
        |> handle_callback(params, provider)
      end
  """
  def run_callback(conn, provider_name, {provider, provider_options}, options \\ []) do
    environment = get_env([:ueberauth, Keyword.get(options, :otp_app)])
    base_path = get_base_path(environment, options)

    to_options = build_strategy_options(base_path, {provider_name, {provider, provider_options}})

    run(conn, {provider, :run_callback, to_options})
  end

  defp run(conn, {module, :run_request, options}) do
    route_base_path = Enum.map_join(conn.script_name, &"/#{&1}")

    to_request_path = Path.join(["/", route_base_path, options.request_path])
    to_callback_path = Path.join(["/", route_base_path, options.callback_path])
    to_options = %{options | request_path: to_request_path, callback_path: to_callback_path}

    conn
    |> Plug.Conn.put_private(:ueberauth_request_options, to_options)
    |> Strategy.run_request(module)
  end

  defp run(conn, {module, :run_callback, options}) do
    route_base_path = Enum.map_join(conn.script_name, &"/#{&1}")

    to_request_path = Path.join(["/", route_base_path, options.request_path])
    to_callback_path = Path.join(["/", route_base_path, options.callback_path])
    to_options = %{options | request_path: to_request_path, callback_path: to_callback_path}

    conn
    |> Plug.Conn.put_private(:ueberauth_request_options, to_options)
    |> Strategy.run_callback(module)
  end

  defp build_routes(base_path, strategy) do
    #
    # Given a Strategy (passed as providers in environment) and a base_path,
    # build a list of routes that can be used later on in `call/2`.
    # The request route must be GET, but there can be as many callback routes
    # as there are callback methods.

    {_, {module, _}} = strategy
    strategy_options = build_strategy_options(base_path, strategy)

    request_mfa = {module, :run_request, strategy_options}
    request_route = {{strategy_options.request_path, "GET"}, request_mfa}

    callback_mfa = {module, :run_callback, strategy_options}

    callback_routes =
      for callback_method <- strategy_options.callback_methods do
        {{strategy_options.callback_path, callback_method}, callback_mfa}
      end

    [request_route | callback_routes]
  end

  defp get_env(value) do
    #
    # Return the environment via `Application.get_env/3` with nil app names
    # yielding empty list, so the results can be used with `Keyword.merge/2`.

    case value do
      nil -> []
      name when is_atom(name) -> Application.get_env(name, __MODULE__, [])
      list when is_list(list) -> list |> Enum.map(&get_env/1) |> Enum.reduce(&Keyword.merge/2)
    end
  end

  # Used by `call/2`. Prefixes the route_path with a "/" only if there is not one already.
  defp normalize_route_path("/" <> _rest = route_path), do: route_path
  defp normalize_route_path(route_path), do: "/" <> route_path

  defp get_providers(environment, options) do
    #
    # Used within `init/1`. Return a filtered Keyword list of providers,
    # taking into account whether the providers have been filtered via options.

    {:ok, providers} = Keyword.fetch(environment, :providers)

    case Keyword.get(options, :providers, :all) do
      :all -> providers
      provider_names -> Keyword.take(providers, provider_names)
    end
  end

  defp get_base_path(environment, options) do
    #
    # Used within `init/1`. Form the base_path from configuration
    # in environment and options.

    Keyword.get(options, :base_path, Keyword.get(environment, :base_path, "/auth"))
  end

  defp build_strategy_options(base_path, strategy) do
    #
    # Used within `build_routes/2`. Form an internal struct which holds
    # specifics that are expected by downstream Strategies when they are run.

    {name, {module, options}} = strategy

    %{
      strategy: module,
      strategy_name: name,
      request_scheme: Keyword.get(options, :request_scheme),
      request_path: get_request_path(base_path, strategy),
      request_port: Keyword.get(options, :request_port),
      callback_scheme: Keyword.get(options, :callback_scheme),
      callback_path: get_callback_path(base_path, strategy),
      callback_port: Keyword.get(options, :callback_port),
      callback_methods: get_callback_methods(options),
      options: options,
      callback_url: Keyword.get(options, :callback_url),
      callback_params: Keyword.get(options, :callback_params)
    }
  end

  defp get_request_path(base_path, strategy) do
    #
    # Used within `build_strategy_options/2`. Form the Request Path
    # from the base path and name of the Strategy as specified in Providers.

    {name, {_, options}} = strategy
    default_path = Path.join(["/", base_path, to_string(name)])
    String.replace_trailing(Keyword.get(options, :request_path, default_path), "/", "")
  end

  defp get_callback_path(base_path, strategy) do
    #
    # Used within `build_strategy_options/2`. Form the Callback Path
    # from the base path and name of the Strategy as specified in Providers.

    {name, {_, options}} = strategy
    default_path = Path.join(["/", base_path, to_string(name), "callback"])
    Keyword.get(options, :callback_path, default_path)
  end

  defp get_callback_methods(options) do
    #
    # Used within `build_strategy_options/2`. Form the list of Callback Methods
    # from options provided.

    options
    |> Keyword.get(:callback_methods, ["GET"])
    |> Enum.map(&String.upcase(to_string(&1)))
  end
end