# Sphinx

An authorization libriary for Phoenix application inspired by [CanCan](https://github.com/CanCanCommunity/cancancan),
[Canary](https://github.com/cpjk/canary), and others. It follows Convention over Configuration design, yet allowing full customizations.

[Read the docs](http://hexdocs.pm/sphinx)

## Installation

  0. Add `sphinx` to your list of dependencies in `mix.exs`:

    ```elixir
    def deps do
      [{:sphinx, "~> 0.1.0"}]
    end
    ```

  Then run `mix deps.get` to fetch the dependencies.

  1. Configure `:repo` in your `config.exs`:

    ```elixir
    config :sphinx, :repo, MyApp.Repo
    ```

## Usage

Say you want to authorize your `PostController`:

  0. Create `web/authorizers/post_authorizer.ex` and define `authorize?` functions for each action in controller like:

    ```elixir
    defmodule MyApp.PostAuthorizer do
      def authorize?(_, :index, Post), do: true

      def authorize?(_, :show, %Post{}), do: true

      def authorize?(%User{}, :create, Post), do: true

      def authorize?(%User{id: id}, action, %Post{author_id: id}) when action in [:update, :delete], do: true

      def authorize?(_, _, _), do: false
    end
    ```

  1. Call `plug :authorize` inside your `PostController`. You may want to `import Sphinx.Plugs` in your `web.ex`
    for controller scope.

  2. You can now access post in your controller actions like: `conn.assigns.resource` if authorization passes,
    and user gets 403 view if it fails.

  3. Profit!

  See [plug docs](https://hexdocs.pm/sphinx/Sphinx.Plugs.html#authorize/2) for more options.

## Ensuring authorization

If you want to make sure all your requests are authorized, add this in your pipelines:

```elixir
import Sphinx.Plugs

plug :ensure_authorization
```

Now, if any your requests is about to return without going through authorization, Sphinx would rise `Sphinx.AuthorizationNotPerformedError`.
You can skip authorization for some of your actions in controller like:

```elixir
plug :skip_authorization, only: [:index, :show]
```

## License

MIT License, Copyright (c) 2016 Almas Sapargali