AuvalOffice.Policy behaviour (auval_office v0.1.0)

Use to make a policy like:

defmodule MyPolicy do
  use AuvalOffice.Policy
end

See the high-level docs in AuvalOffice to understand what's going on.

Link to this section Summary

Define a fetcher.

Define a rule.

Function generated in a module that uses this module.

authorization_result() ::
  {:ok, :atom, Keyword.t()} | {:error, :atom, Keyword.t()}

(macro)

Define a fetcher.

Takes an additional do block, or a do: expression.

id: An identifier to disambiguate this fetcher
attr: The attribute that will be set in the context. The fetcher will be skipped if there is already an attribute by this name in the context.

subject: A pattern to match against the subject being authorized
object: A pattern to match against the object being authorized
action: A pattern to match against the action being authorized
context: A pattern to match against the context built up so far
when: A guard. The fetcher will be skipped if this evaluates to false. Can refer to variables bound in the matchers. Will be evaluated in the context of an if block, so not limited to guard expressions.

(macro)

Define a rule.

Takes an additional do block, or a do: expression.

id: An identifier to identify and disambiguate the rule.
actions: An action or list of action that is authorized (or forbidden) by this rule. The action :all matches any action. This is not a pattern.
subject: A pattern matching the subject that this rule applies to. If the pattern does not match, the rule is skipped.
object: A pattern matching the object that this rule applies to. If the pattern does not match, the rule is skipped.
options: A keyword list of options as described below.

action: A pattern to bind the action to that is authorized. Only necessary for advanced matching or if you need to refer to the action in the body of the rule.
context: A pattern to match against the context of the authorization.
when: A guard expression. The rule is skipped if this expression evaluates to false. Can refer to any variable bound by the patterns passed to this macro. Will be evaluated in the context of an if, so not limited to guard expressions.

authorize(
  subject :: term(),
  object :: term(),
  action :: atom(),
  context :: map()
) :: authorization_result()

Function generated in a module that uses this module.

subject: The subject that should be authorized.
object: The object that would be acted upon by the subject.
action: The action taken by the subject upen the object.
context: A map of additional information necessary to make an authorization decision. Defaults to the empty map %{} if not given.

{:ok, deciding_rule, parameters}:
Returned when one rule returns a positive result. The rule that made the decision is identified by the second element, and any additional values returned by it are in the third element.
{:error, deciding_rule, parameters}:
Returned when one rule returns a negative result. The rule that made the decision is identified by the second element, and any additional values returned by it are in the third element. If no rule matched, the decision is considered negative, and the second element will be :default_deny.