defmodule Permit do
@moduledoc ~S"""
Permit is an extensible, DSL-less library allowing the coder to define authorization rules in plain Elixir.
It can run on its own, but is also integrated with widely used Elixir libraries and frameworks.
## Libraries and repositories
The Permit library can run on its own as a standalone library, but it can also be used alongside Ecto and Phoenix integrations.
* [`Permit`](https://github.com/curiosum-dev/permit) - provides a syntax to define permissions to perform actions (defined as atoms) on objects (structs) by a specific user (subject) using functions or keyword lists, matching against an object's attributes.
* [`Permit.Ecto`](https://github.com/curiosum-dev/permit_ecto) - provides a resolver using Ecto to build and execute singular or collection Ecto queries based on defined permissions, also extending the syntax with a possibility to define more sophisticated permissions convertible to Ecto queries.
* [`Permit.Phoenix`](https://github.com/curiosum-dev/permit_phoenix) - uses `Permit` and `Permit.Ecto` to retrieve records via loader functions or queries generated by `Permit.Ecto` (if installed), based on data accessible in current context defined by a Plug `conn` or a LiveView `socket`.
## Paradigm and Extensibility
At the core of authorization resolution, there's always the question of:
* **What action** is being performed (for Phoenix, it's most likely a controller action)
* **What subject** performs the action (usually, the current user)
* **What object** the action is performed on
Once answers to these three questions are found, authorization or lack thereof is determined based on the set of permission definitions, defined as [expressions in disjunctive normal form (DNF)](https://en.wikipedia.org/wiki/Disjunctive_normal_form) expressions - that is, a set of sufficient conditions, with each condition defined as a conjunction of predicates, for example:
```text
Subject | Action | Object
--------------------------------------------
A **user** can | **update** | an **article**
...if user's ID = article author's ID AND the article is not published,
...if user's ID = article author's ID AND the article type is a live ticker,
...if user's role is editor-in-chief AND the article is not published,
...if user's role is editor-in-chief ID AND the article type is a live ticker,
...or if the use has a super-admin role.
```
Which, in Permit syntax, is translated to the following. Note the usage of pattern matching on the current user's (subject's) attributes, which allows to create function clauses for each user role. Permit does not enforce a specific structure of the `can/1` function, but as pattern matching usage is convenient in this case, it is naturally encouraged.
```elixir
def can(%User{role: :editor_in_chief} = _current_user) do
permit()
|> update(Article, state: {:not, :published})
|> update(Article, type: :live_ticker)
end
def can(%User{id: user_id} = _current_user) do
permit()
|> update(Article, author_id: user_id, state: {:not, :published})
|> update(Article, author_id: user_id, type: :live_ticker)
end
def can(%User{id: user_id, role: :super_admin} = _current_user) do
permit()
|> update(Article)
end
```
The library is written with extensibility in mind. Analogously to Phoenix interoperatbility, the developer may define their own integration with different frameworks.
For more details on interoperability, see `Permit.ResolverBase`.
## Configuration and usage
For more details on Ecto and Phoenix usage, visit [`permit_ecto`](https://hexdocs.pm/permit_ecto) and [`permit_phoenix`](https://hexdocs.pm/permit_phoenix) documentations, respectively.
### Configure & define your permissions
```elixir
defmodule MyApp.Authorization do
use Permit, permissions_module: MyApp.Permissions
end
defmodule MyApp.Permissions do
use Permit.Permissions, actions_module: Permit.Actions.CrudActions
def can(%{role: :admin} = user) do
permit()
|> all(MyApp.Blog.Article)
end
def can(%{id: user_id} = user) do
permit()
|> all(MyApp.Blog.Article, author_id: user_id)
|> read(MyApp.Blog.Article)
end
def can(user), do: permit()
end
```
Note that in the permission definitions module the `read` function is generated based on configuration provided as the `:actions_module` option - in this case, `CrudActions` generates `create`, `read`, `update` and `delete`. For more on this, see `Permit.Actions` and `Permit.Permissions`.
### Check a user's authorization to perform an action on a resource
```elixir
iex(1)> import MyApp.Authorization
iex(2)> can(%MyApp.User{id: 1}) |> read?(%MyApp.Article{author_id: 1})
true
iex(3)> can(%MyApp.User{id: 1}) |> read?(%MyApp.Article{author_id: 2})
true
iex(4)> can(%MyApp.User{id: 1}) |> update?(%MyApp.Article{author_id: 2})
false
iex(4)> can(%MyApp.User{role: :admin}) |> delete?(%MyApp.Article{author_id: 2})
true
```
Functions such as `MyApp.Authorization.read?/2`, `MyApp.Authorization.update?/2`, etc. are also generated based on the `:actions_module` option. See more in `Permit.Actions`.
"""
alias Permit.Permissions
alias Permit.SubjectMapping
alias Permit.Types
@callback resolver_module :: Types.resolver_module()
defmacro __using__(opts) do
alias Permit.Types
permissions_module = Keyword.fetch!(opts, :permissions_module)
predicates =
Macro.expand(permissions_module, __CALLER__).actions_module()
|> Permit.Actions.list_groups()
|> Enum.map(&add_predicate_name/1)
|> Enum.map(fn {predicate, name} ->
quote do
@spec unquote(predicate)(Permit.Context.t(), Types.object_or_resource_module()) ::
boolean()
def unquote(predicate)(authorization, resource) do
Permit.verify_record(authorization, resource, unquote(name))
end
end
end)
quote do
@behaviour Permit
def permissions_module do
unquote(permissions_module)
end
require unquote(permissions_module)
def actions_module,
do: unquote(permissions_module).actions_module()
@spec can(SubjectMapping.t()) :: Permit.Context.t()
def can(nil),
do: raise("Unable to create permit authorization for nil role/user")
def can(who) do
Permit.can(who, unquote(permissions_module))
end
@impl Permit
def resolver_module, do: Permit.Resolver
defoverridable resolver_module: 0
unquote(predicates)
end
end
@doc false
def can(who, permissions_module) do
who
|> SubjectMapping.subjects()
|> Stream.map(&permissions_module.can/1)
|> Enum.reduce(&Permissions.concatenate(&1, &2))
|> then(&%Permit.Context{subject: (is_struct(who) && who) || nil, permissions: &1})
end
@doc false
@spec verify_record(Permit.Context.t(), Types.object_or_resource_module(), Types.action_group()) ::
boolean()
def verify_record(
%{
permissions: permissions,
subject: subject
} = _authorization,
record,
action
) do
Permissions.granted?(permissions, action, record, subject)
end
defp add_predicate_name(atom),
do: {(Atom.to_string(atom) <> "?") |> String.to_atom(), atom}
end
