defmodule Janus do
  @moduledoc """
  Authorization superpowers for applications using `Ecto`.

  Priorities:

    * Single source of truth - The same rules that authorize loaded data
      should be able to load authorized data.

    * Authentication-agnostic - Janus should not care about how users
      are modeled or authenticated.

    * Minimal library footprint - Expose a small but flexible API that
      can be used to create an optimal authorization interface for each
      application.

    * Escape hatches where necessary - Complex authorization rules and
      use-cases should be representable when Janus neglects to provide a
      short cut.

  Janus is split into two primary components:

    * `Janus.Policy` - functions and behaviour for defining _policy
    modules_, which describe the allowed actors, actions, and resources
    in your application. This is where you look if you're writing a
    policy module.

    * `Janus.Authorization` - functions and behaviour used by the rest
    of your application to authorize and load resources. This is where
    you look if you're using a policy module.

  Janus defines a Mix task to generate the basic policy module that will
  get you started:

      $ mix janus.gen.policy

  ## Policies

  Policy modules are created by invoking `use Janus`, which implements
  both the `Janus.Policy` and `Janus.Authorization` behaviours:

      defmodule Policy do
        use Janus

        @impl true
        def build_policy(policy, _user) do
          policy
        end
      end

  When you invoke `use Janus`, default implementations are injected for
  required callbacks, except for `c:Janus.Policy.build_policy/2`. This
  callback is your foundation, as it returns the authorization policy
  for an individual user of your application.

  The policy above is not very useful (it doesn't allow anyone to do
  anything) but that can be changed by using the `Janus.Policy` API to
  define actions, resources, and conditions that make up your
  authorization rules.

      def build_policy(policy, %User{role: :moderator} = mod) do
        policy
        |> allow(:read, Post)
        |> allow([:edit, :archive, :unarchive], Post, where: [user: [role: :member]])
        |> allow([:edit, :archive, :unarchive], Post, where: [user_id: mod.id])
        |> deny(:unarchive, Post, where: [archived_by: [role: :admin]])
      end

  See the `Janus.Policy` documentation for more on defining policies.

  ## Authorization

  With our policy module defined, it can now be used to load and
  authorize resources.

      iex> Policy.authorize(some_post, :archive, moderator)
      {:ok, some_post}

      iex> Policy.authorize(post_archived_by_admin, :unarchive, moderator)
      {:error, :not_authorized}

      iex> Policy.scope(Post, :read, moderator)
      %Ecto.Query{}

      iex> Policy.scope(Post, :read, moderator) |> Repo.all()
      [ ... posts the moderator can read ]

      iex> Policy.any_authorized?(Post, :edit, moderator)
      true # there are rules allowing moderators to edit posts

      iex> Policy.any_authorized?(Post, :delete, moderator)
      false # there are no rules that allow moderators to delete posts

  These functions make up the `Janus.Authorization` behaviour, and their
  definitions were injected by default when we invoked `use Janus`. This
  is the "public API" that the rest of your application will use to
  authorize resources.

  See the `Janus.Authorization` documentation for more.

  ## Integration with `Ecto.Query`

  The primary assumption that Janus makes is that your resources are
  backed by an `Ecto.Schema`. Using Ecto's schema reflection
  capabilities, Janus is able to use the same policy to authorize a
  single resource and to construct a composable Ecto query that is aware
  of field types and associations.

      # This query would result in the 5 latest posts that the current
      # user is authorized to see, preloaded with the user # who made
      # the post (but only if the current user is  allowed to see that
      # user).

      Post
      |> Policy.scope(:read, current_user,
        preload_authorized: :user
      )
      |> order_by(desc: :inserted_at)
      |> limit(5)

  This integration with Ecto queries is main reason Janus exists.

  ## Configuration

  Some defaults can be configured by passing them as options when
  invoking `use Janus`. Those are:

    * `:repo` - `Ecto.Repo` used to load associations when required by
      your authorization rules

    * `:load_associations` - Load associations when required by your
      authorization rules (requires `:repo` config option to be set or
      to be passed explicitly at the call site), defaults to `false`

  For example:

      defmodule MyApp.Policy do
          use Janus,
            repo: MyApp.Repo,
            load_associations: true

          # ...
      end

  These defaults will be referenced in the `Janus.Authorization`
  documentation where they are used.
  """

  require Ecto.Query

  @type action :: any()
  @type schema_module :: module()
  @type actor :: any()

  @doc """
  Sets up a module to implement the `Janus.Policy` and
  `Janus.Authorization` behaviours.

  Using `use Janus` does the following:

    * adds the `Janus.Policy` behaviour, imports functions used to
      define the required callback `c:Janus.Policy.build_policy/2`, and
      defines a `build_policy/1` helper

    * adds the `Janus.Authorization` behaviour and injects default
      (overridable) implementations for all callbacks

  ## Options

    * `:load_associations` - Load associations when required by your
      authorization rules (requires `:repo` config option to be set or
      to be passed explicitly at the call site), defaults to `false`

    * `:repo` - `Ecto.Repo` used to load associations when required by
      your authorization rules

  See "Configuration" section for details.

  ## Example

      defmodule MyApp.Policy do
        use Janus, repo: MyApp.Repo

        @impl true
        def build_policy(policy, _actor) do
          policy
          # |> allow(...)
        end
      end
  """
  defmacro __using__(opts \\ []) do
    quote location: :keep do
      @behaviour Janus.Authorization

      use Janus.Policy, unquote(opts)
      require Janus

      @impl Janus.Authorization
      def authorize(resource, action, actor, opts \\ []) do
        Janus.Authorization.authorize(resource, action, build_policy(actor), opts)
      end

      @impl Janus.Authorization
      def any_authorized?(schema, action, actor) do
        Janus.Authorization.any_authorized?(schema, action, build_policy(actor))
      end

      @impl Janus.Authorization
      def scope(query_or_schema, action, actor, opts \\ []) do
        Janus.Authorization.scope(query_or_schema, action, build_policy(actor), opts)
      end

      defoverridable authorize: 4, any_authorized?: 3, scope: 4
    end
  end
end