@spec action(atom() | [atom()], Macro.t()) :: Macro.t()

Defines an action that needs to be authorized.

Within the do-block, you can use the allow/1, deny/1 and pre_hooks/1 macros to define the checks to be run and the desc/1 macro to add a description.

This macro must be used within the do-block of object/2.

Each action block will be compiled to a rule. The rule name is an atom with the format {object}_{action}.

Example

object :article do
  action :create do
    allow role: :editor
    allow role: :writer
  end

  action :update do
    allow role: :editor
    allow [:own_resource, role: :writer]
  end
end

If you have multiple actions with the same allow and deny rules, you can also pass a list of action names as the first argument.

object :article do
  action [:create, :update, :delete] do
    allow role: :editor
    allow role: :writer
  end
end

@spec allow(LetMe.Rule.check() | [LetMe.Rule.check()]) :: Macro.t()

Defines the checks to be run to determine if an action is allowed.

The argument can be:

• a function name as an atom
• a tuple with the function name and an additional argument
• a list of function names or function/argument tuples
• true or false - Always allows or denies an action. Can be useful in combination with the deny/1 macro.

The function must be defined in the configured check module and take the subject (current user), object as arguments, and if given, the additional argument.

If a list is given as an argument, the checks are combined with a logical AND.

If the allow/1 macro is used multiple times within the same action/2 block, the checks of each macro call are combined with a logical OR.

Examples

Let's assume you defined the following checks:

defmodule MyApp.Policy.Checks do
  def role(%User{role: role}, _, role), do: true
  def role(_, _, _), do: false

  def own_resource(%User{id: id}, %{user_id: id}, _), do: true
  def own_resource(_, _, _), do: false
end

This would allow the :article_update action only if the current user has the role :admin:

object :article do
  action :update do
    allow role: :admin
  end
end

This is equivalent to:

object :article do
  action :update do
    allow {:role, :admin}
  end
end

This would allow the :article_update action if the user has the role :writer and the article belongs to the user:

object :article do
  action :update do
    allow [:own_resource, role: :writer]
  end
end

This is equivalent to:

object :article do
  action :update do
    allow [:own_resource, {:role, :writer}]
  end
end

This would allow the :article_update action if (the user has the role :admin or (the user has the role :writer and the article belongs to the user)):

object :article do
  action :update do
    allow role: :admin
    allow [:own_resource, role: :writer]
  end
end

@spec deny(LetMe.Rule.check() | [LetMe.Rule.check()]) :: Macro.t()

Defines the checks to be run to determine if an action is denied.

If any of the checks evaluates to true, the allow checks are overridden and the authorization request is automatically denied.

If a list is given as an argument, the checks are combined with a logical AND.

If the allow/1 macro is used multiple times within the same action/2 block, the checks of each macro call are combined with a logical OR.

Examples

Let's assume you defined the following checks:

defmodule MyApp.Policy.Checks do
  def role(%User{role: role}, _, role), do: true
  def role(_, _, _), do: false

  def own_resource(%User{id: id}, %{user_id: id}, _), do: true
  def own_resource(_, _, _), do: false

  def same_user(%User{id: id}, %User{id: id}, _), do: true
  def same_user(_, _, _), do: false
end

This would allow the :user_delete action by default, unless the object is the current user:

object :user do
  action :delete do
    allow true
    deny :same_user
  end
end

This would allow the :article_update action only if the current user has the role :admin, unless the object is the current user:

object :user do
  action :delete do
    allow role: :admin
    deny :same_user
  end
end

This would allow the :user_delete by default, unless the object is the current user and the current user is an admin:

object :user do
  action :delete do
    allow true
    deny [:same_user, role: :admin]
  end
end

This would allow the :user_delete by default, unless the object is the current user or the current user is a peasant:

object :user do
  action :delete do
    allow true
    deny :same_user
    deny role: :peasant
  end
end

@spec desc(String.t()) :: Macro.t()

Allows you to add a description to a rule.

The description can be accessed from the LetMe.Rule struct. You can use it to generate help texts or documentation.

Example

object :article do
  action :create do
    desc "allows a user to create a new article"
    allow role: :writer
  end
end

@spec metadata(atom(), term()) :: Macro.t()

Assigns metadata to the action in the form of a key value pair.

The metadata can be accessed from the LetMe.Rule struct. You can use it to extend the functionality of the library.

Example

object :article do
  action :create do
    allow role: :writer

    desc "Allows a user to create a new article."
    metadata :desc_ja, "ユーザーが新しい記事を作成できるようにする"
  end
end

The LetMe.Rule struct returned by the introspection functions would look like this:

%LetMe.Rule{
  action: :create,
  allow: [[role: :writer]],
  deny: [],
  description: "Allows a user to create a new article.",
  name: :article_create,
  object: :article,
  pre_hooks: [],
  metadata: [
    desc_ja: "ユーザーが新しい記事を作成できるようにする"
  ]
}

It is also possible to use the metadata macro multiple times.

object :article do
  action :create do
    allow role: :writer

    desc "Allows a user to create a new article."
    metadata :desc_ja, "ユーザーが新しい記事を作成できるようにする"
    metadata :desc_es, "Permite al usuario crear un nuevo artículo."
  end
end

This would result in:

%LetMe.Rule{
  action: :create,
  allow: [[role: :writer]],
  deny: [],
  description: "Allows a user to create a new article.",
  name: :article_create,
  object: :article,
  pre_hooks: [],
  metadata: [
    desc_ja: "ユーザーが新しい記事を作成できるようにする",
    desc_es: "Permite al usuario crear un nuevo artículo."
  ]
}

@spec object(atom(), module() | nil, Macro.t()) :: Macro.t()

Defines an object on which actions can be performed.

Within the do-block, you can use the action/2 macro to define the actions and checks.

Examples

object :article do
  action :create do
    allow role: :writer
  end

  action :delete do
    allow role: :editor
  end
end

You can optionally pass the schema module as the second argument. The schema module should implement the LetMe.Schema behaviour.

object :article, MyApp.Blog.Article do
  action :create do
    allow role: :writer
  end
end

At the moment, this doesn't do much, except that you can find the schema module by passing the object name to get_schema/1, or find the object name by passing the schema module or struct to get_object_name/1 now. Also, you can now only pass the struct toc:MyApp.Policy.filter_allowed_actions/3, without explicitly passing the object name.

@spec pre_hooks(LetMe.Rule.hook() | [LetMe.Rule.hook()]) :: Macro.t()

Registers one or multiple functions to run in order to hydrate the subject and/or object of the request.

This is useful if you need to enhance the data for multiple checks in the same action by preloading associations, making external requests, or similar things. The configured hook functions will be called once before running the checks for an action.

The referenced functions must take the subject and object as arguments and return a 2-tuple with the updated subject and object.

The referenced functions may also take an optional third argument that are opts passed through the authorize functions. These opts are merged into any opts that are specified in the pre_hook definition.

Examples

Let's assume we defined these check and hook functions in our check module:

def MyApp.Policy.Checks do
  # Checks

  def min_age(%{age: age}, _, min_age), do: age >= min_age

  # Hooks

  def double_age(subject, object) do
    new_subject = %{subject | age: subject.age * 2}
    {new_subject, object}
  end

  def set_age(subject, object, age: age) do
    new_subject = %{subject | age: age}
    {new_subject, object}
  end
end

If an atom is passed, LetMe will try to find the function in the check module.

object :article do
  action :view do
    pre_hooks :double_age
    allow min_age: 50
  end
end

With this in place, the following authorization request will evaluate to true:

MyApp.Policy.authorize!(:article_view, %{age: 25})
# => true

If your hooks are defined in a different module, you can also pass a module/function tuple. The pre-hook configuration above is equivalent to:

object :article do
  action :view do
    pre_hooks {MyApp.Policy.Checks, :double_age}
    allow min_age: 50
  end
end

You can also pass options to a hook by using an MFA tuple:

object :article do
  action :view do
    pre_hooks {MyApp.Policy.Checks, :set_age, age: 50}
    allow min_age: 50
  end
end

MyApp.Policy.authorize!(:article_view, %{age: 10})
# => true

You can achieve the same functionality dynamically using the opts on authorize!:

object :article do
  action :view do
    pre_hooks {MyApp.Policy.Checks, :set_age}
    allow min_age: 50
  end
end

MyApp.Policy.authorize!(:article_view, %{age: 10}, age: 50)
# => true

And finally, you can also pass a list of hooks, which will be run in sequence:

alias MyApp.Policy.Checks

object :article do
  action :view do
    pre_hooks [{Checks, :set_age, 25}, :double_age]
    allow min_age: 50
  end
end

MyApp.Policy.authorize!(:article_view, %{age: 10})
# => true